slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: hledger, journal, csv: consistent use of pipe tables

Browse Source 
For consistency, ease of editing, and to fix unwanted content display
when cycling visibility in markdown-mode.

[ci skip]
This commit is contained in:
Simon Michael 2020-02-08 11:52:18 -08:00
parent ea4b69db32
commit 54e633e186
3 changed files with 109 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
hledger-lib/hledger_csv.m4.md
View File

@ -33,17 +33,17 @@ conditional rules for categorising transactions based on their
descriptions. Here's an overview of the CSV rules; descriptions. Here's an overview of the CSV rules;
these are described more fully below, after the examples: these are described more fully below, after the examples:
------------------------------------------- --------------------------------------------------- | | |
[**`skip`**](#skip) skip one or more header lines or matched CSV records |-------------------------------------------|---------------------------------------------------------|
[**`fields`**](#fields) name CSV fields, assign them to hledger fields | [**`skip`**](#skip) | skip one or more header lines or matched CSV records |
[**field assignment**](#field-assignment) assign a value to one hledger field, with interpolation | [**`fields`**](#fields) | name CSV fields, assign them to hledger fields |
[**`separator`**](#separator) a custom field separator | [**field assignment**](#field-assignment) | assign a value to one hledger field, with interpolation |
[**`if`**](#if) apply some rules to matched CSV records | [**`separator`**](#separator) | a custom field separator |
[**`end`**](#end) skip the remaining CSV records | [**`if`**](#if) | apply some rules to matched CSV records |
[**`date-format`**](#date-format) describe the format of CSV dates | [**`end`**](#end) | skip the remaining CSV records |
[**`newest-first`**](#newest-first) disambiguate record order when there's only one date | [**`date-format`**](#date-format) | describe the format of CSV dates |
[**`include`**](#include) inline another CSV rules file | [**`newest-first`**](#newest-first) | disambiguate record order when there's only one date |
------------------------------------------- --------------------------------------------------- | [**`include`**](#include) | inline another CSV rules file |
Note, for best error messages when reading CSV files, use a `.csv`, `.tsv` or `.ssv` Note, for best error messages when reading CSV files, use a `.csv`, `.tsv` or `.ssv`
file extension or file prefix - see [File Extension](#file-extension) below. file extension or file prefix - see [File Extension](#file-extension) below.

32
hledger-lib/hledger_journal.m4.md
View File

@ -205,11 +205,11 @@ can have a status mark, which is a single character before
the transaction description or posting account name, the transaction description or posting account name,
separated from it by a space, indicating one of three statuses: separated from it by a space, indicating one of three statuses:
mark   | status | mark   | status |
:-----------|:------------------- |--------|----------|
  | unmarked |   | unmarked |
`!` | pending | `!` | pending |
`*` | cleared | `*` | cleared |
When reporting, you can filter by status with When reporting, you can filter by status with
the `-U/--unmarked`, `-P/--pending`, and `-C/--cleared` flags; the `-U/--unmarked`, `-P/--pending`, and `-C/--cleared` flags;
@ -228,11 +228,11 @@ Eg in Emacs ledger-mode, you can toggle transaction status with C-c C-e, or post
What "uncleared", "pending", and "cleared" actually mean is up to you. What "uncleared", "pending", and "cleared" actually mean is up to you.
Here's one suggestion: Here's one suggestion:
status | meaning | status | meaning |
:---------|:------------------------------------------------------------ |-----------|--------------------------------------------------------------------|
uncleared | recorded but not yet reconciled; needs review | uncleared | recorded but not yet reconciled; needs review |
pending | tentatively reconciled (if needed, eg during a big reconciliation) | pending | tentatively reconciled (if needed, eg during a big reconciliation) |
cleared | complete, reconciled as far as possible, and considered correct | cleared | complete, reconciled as far as possible, and considered correct |
With this scheme, you would use With this scheme, you would use
`-PC` to see the current balance at your bank, `-PC` to see the current balance at your bank,
@ -771,7 +771,7 @@ so here is a table summarising the directives and their effects, with links to m
<!-- </style> --> <!-- </style> -->
| directive | end directive | subdirectives | purpose | can affect (as of 2018/06) | directive | end directive | subdirectives | purpose | can affect (as of 2018/06)
|:------------------|:--------------------|:----------------|:-------------------------------------------------------------------|:--------------------------------------------- |-------------------|---------------------|-----------------|--------------------------------------------------------------------|----------------------------------------------
| [`account`] | | any text | document account names, declare account types & display order | all entries in all files, before or after | [`account`] | | any text | document account names, declare account types & display order | all entries in all files, before or after
| [`alias`] | `end aliases` | | rewrite account names | following inline/included entries until end of current file or end directive | [`alias`] | `end aliases` | | rewrite account names | following inline/included entries until end of current file or end directive
| [`apply account`] | `end apply account` | | prepend a common parent to account names | following inline/included entries until end of current file or end directive | [`apply account`] | `end apply account` | | prepend a common parent to account names | following inline/included entries until end of current file or end directive
@ -795,11 +795,11 @@ so here is a table summarising the directives and their effects, with links to m
And some definitions: And some definitions:
| | | | | |
|:----------------|:-------------------------------------------------------------------------------------------------------------------- |-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| subdirective | optional indented directive line immediately following a parent directive | subdirective | optional indented directive line immediately following a parent directive |
| number notation | how to interpret numbers when parsing journal entries (the identity of the decimal separator character). (Currently each commodity can have its own notation, even in the same file.) | number notation | how to interpret numbers when parsing journal entries (the identity of the decimal separator character). (Currently each commodity can have its own notation, even in the same file.) |
| display style | how to display amounts of a commodity in reports (symbol side and spacing, digit groups, decimal separator, decimal places) | display style | how to display amounts of a commodity in reports (symbol side and spacing, digit groups, decimal separator, decimal places) |
| directive scope | which entries and (when there are multiple files) which files are affected by a directive | directive scope | which entries and (when there are multiple files) which files are affected by a directive |
<!-- | **entries affected:** | --> <!-- | **entries affected:** | -->
<!-- | following | subsequent entries in the file/parse stream --> <!-- | following | subsequent entries in the file/parse stream -->

163
hledger/hledger.m4.md
View File

@ -646,12 +646,12 @@ or:
If you asked why *four* slashes above, this may help: If you asked why *four* slashes above, this may help:
----------------- -------- | | |
unescaped: `$` |-----------------|---------|
escaped: `\$` | unescaped: | `$` |
double-escaped: `\\$` | escaped: | `\$` |
triple-escaped: `\\\\$` | double-escaped: | `\\$` |
----------------- -------- | triple-escaped: | `\\\\$` |
(The number of backslashes in fish shell is left as an exercise for the reader.) (The number of backslashes in fish shell is left as an exercise for the reader.)
@ -815,27 +815,27 @@ and can have less-significant date parts omitted (defaulting to 1).
Examples: Examples:
--------------------------------------------- ----------------------------------------------------------------------------- | | |
`2004/10/1`, `2004-01-01`, `2004.9.1` exact date, several separators allowed. Year is 4+ digits, month is 1-12, day is 1-31 |----------------------------------------------|---------------------------------------------------------------------------------------|
`2004` start of year | `2004/10/1`, `2004-01-01`, `2004.9.1` | exact date, several separators allowed. Year is 4+ digits, month is 1-12, day is 1-31 |
`2004/10` start of month | `2004` | start of year |
`10/1` month and day in current year | `2004/10` | start of month |
`21` day in current month | `10/1` | month and day in current year |
`october, oct` start of month in current year | `21` | day in current month |
`yesterday, today, tomorrow` -1, 0, 1 days from today | `october, oct` | start of month in current year |
`last/this/next day/week/month/quarter/year` -1, 0, 1 periods from the current period | `yesterday, today, tomorrow` | -1, 0, 1 days from today |
`20181201` 8 digit YYYYMMDD with valid year month and day | `last/this/next day/week/month/quarter/year` | -1, 0, 1 periods from the current period |
`201812` 6 digit YYYYMM with valid year and month | `20181201` | 8 digit YYYYMMDD with valid year month and day |
--------------------------------------------- ----------------------------------------------------------------------------- | `201812` | 6 digit YYYYMM with valid year and month |
Counterexamples - malformed digit sequences might give surprising results: Counterexamples - malformed digit sequences might give surprising results:
--------------------------------------------- ----------------------------------------------------------------------------- | | |
`201813` 6 digits with an invalid month is parsed as start of 6-digit year |-------------|-------------------------------------------------------------------|
`20181301` 8 digits with an invalid month is parsed as start of 8-digit year | `201813` | 6 digits with an invalid month is parsed as start of 6-digit year |
`20181232` 8 digits with an invalid day gives an error | `20181301` | 8 digits with an invalid month is parsed as start of 8-digit year |
`201801012` 9+ digits beginning with a valid YYYYMMDD gives an error | `20181232` | 8 digits with an invalid day gives an error |
--------------------------------------------- ----------------------------------------------------------------------------- | `201801012` | 9+ digits beginning with a valid YYYYMMDD gives an error |
## Report start & end date ## Report start & end date
@ -864,16 +864,16 @@ Some notes:
Examples: Examples:
----------------------------------- ------------------------------------------------------------------------------------------- | | |
`-b 2016/3/17` begin on St. Patrick's day 2016 |-------------------|---------------------------------------------------------------------------------------------|
`-e 12/1` end at the start of december 1st of the current year (11/30 will be the last date included) | `-b 2016/3/17` | begin on St. Patrick’s day 2016 |
`-b thismonth` all transactions on or after the 1st of the current month | `-e 12/1` | end at the start of december 1st of the current year (11/30 will be the last date included) |
`-p thismonth` all transactions in the current month | `-b thismonth` | all transactions on or after the 1st of the current month |
`date:2016/3/17-` the above written as queries instead | `-p thismonth` | all transactions in the current month |
`date:-12/1` | `date:2016/3/17-` | the above written as queries instead |
`date:thismonth-` | `date:-12/1` | |
`date:thismonth` | `date:thismonth-` | |
--- | `date:thismonth` | |
## Report intervals ## Report intervals
@ -900,39 +900,39 @@ Keywords like "from" and "to" are optional, and so are the spaces, as long
as you don't run two dates together. "to" can also be written as "-". as you don't run two dates together. "to" can also be written as "-".
These are equivalent to the above: These are equivalent to the above:
------------------------------ | |
`-p "2009/1/1 2009/4/1"` |--------------------------|
`-p2009/1/1to2009/4/1` | `-p "2009/1/1 2009/4/1"` |
`-p2009/1/1-2009/4/1` | `-p2009/1/1to2009/4/1` |
------------------------------ | `-p2009/1/1-2009/4/1` |
Dates are [smart dates](#smart-dates), so if the current year is 2009, the Dates are [smart dates](#smart-dates), so if the current year is 2009, the
above can also be written as: above can also be written as:
------------------------------ | |
`-p "1/1 4/1"` |-------------------------|
`-p "january-apr"` | `-p "1/1 4/1"` |
`-p "this year to 4/1"` | `-p "january-apr"` |
------------------------------ | `-p "this year to 4/1"` |
If you specify only one date, the missing start or end date will be the If you specify only one date, the missing start or end date will be the
earliest or latest transaction in your journal: earliest or latest transaction in your journal:
---------------------------- --------------------------------- | | |
`-p "from 2009/1/1"` everything after january 1, 2009 |----------------------|-----------------------------------|
`-p "from 2009/1"` the same | `-p "from 2009/1/1"` | everything after january 1, 2009 |
`-p "from 2009"` the same | `-p "from 2009/1"` | the same |
`-p "to 2009"` everything before january 1, 2009 | `-p "from 2009"` | the same |
---------------------------- --------------------------------- | `-p "to 2009"` | everything before january 1, 2009 |
A single date with no "from" or "to" defines both the start and end date A single date with no "from" or "to" defines both the start and end date
like so: like so:
--------------------- ------------------------------------------------------ | | |
`-p "2009"` the year 2009; equivalent to "2009/1/1 to 2010/1/1" |-----------------|--------------------------------------------------------|
`-p "2009/1"` the month of jan; equivalent to "2009/1/1 to 2009/2/1" | `-p "2009"` | the year 2009; equivalent to “2009/1/1 to 2010/1/1” |
`-p "2009/1/1"` just that day; equivalent to "2009/1/1 to 2009/1/2" | `-p "2009/1"` | the month of jan; equivalent to “2009/1/1 to 2009/2/1” |
--------------------- ------------------------------------------------------ | `-p "2009/1/1"` | just that day; equivalent to “2009/1/1 to 2009/1/2” |
The argument of `-p` can also begin with, or be, a [report interval](#report-intervals) expression. The argument of `-p` can also begin with, or be, a [report interval](#report-intervals) expression.
The basic report intervals are `daily`, `weekly`, `monthly`, `quarterly`, or `yearly`, The basic report intervals are `daily`, `weekly`, `monthly`, `quarterly`, or `yearly`,
@ -940,11 +940,11 @@ which have the same effect as the `-D`,`-W`,`-M`,`-Q`, or `-Y` flags.
Between report interval and start/end dates (if any), the word `in` is optional. Between report interval and start/end dates (if any), the word `in` is optional.
Examples: Examples:
------------------------------------------ | |
`-p "weekly from 2009/1/1 to 2009/4/1"` |-----------------------------------------|
`-p "monthly in 2008"` | `-p "weekly from 2009/1/1 to 2009/4/1"` |
`-p "quarterly"` | `-p "monthly in 2008"` |
------------------------------------------ | `-p "quarterly"` |
Note that `weekly`, `monthly`, `quarterly` and `yearly` intervals will Note that `weekly`, `monthly`, `quarterly` and `yearly` intervals will
always start on the first day on week, month, quarter or year always start on the first day on week, month, quarter or year
@ -953,12 +953,12 @@ associated period expression specifies different explicit start and end date.
For example: For example:
------------------------------------------ | | |
`-p "weekly from 2009/1/1 to 2009/4/1"` -- starts on 2008/12/29, closest preceding Monday |------------------------------------------------|------------------------------------------------------------------------------------|
`-p "monthly in 2008/11/25"` -- starts on 2018/11/01 | `-p "weekly from 2009/1/1 to 2009/4/1"` | starts on 2008/12/29, closest preceding Monday |
`-p "quarterly from 2009-05-05 to 2009-06-01"` - starts on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2 2009 | `-p "monthly in 2008/11/25"` | starts on 2018/11/01 |
`-p "yearly from 2009-12-29"` - starts on 2009/01/01, first day of 2009 | `-p "quarterly from 2009-05-05 to 2009-06-01"` | starts on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2 2009 |
------------------------------------------ | `-p "yearly from 2009-12-29"` | starts on 2009/01/01, first day of 2009 |
The following more complex report intervals are also supported: The following more complex report intervals are also supported:
`biweekly`, `biweekly`,
@ -971,11 +971,11 @@ All of these will start on the first day of the requested period and end on the
Examples: Examples:
------------------------------------------ | | |
`-p "bimonthly from 2008"` -- periods will have boundaries on 2008/01/01, 2008/03/01, ... |-----------------------------------|-------------------------------------------------------------|
`-p "every 2 weeks"` -- starts on closest preceding Monday | `-p "bimonthly from 2008"` | periods will have boundaries on 2008/01/01, 2008/03/01, ... |
`-p "every 5 month from 2009/03"` -- periods will have boundaries on 2009/03/01, 2009/08/01, ... | `-p "every 2 weeks"` | starts on closest preceding Monday |
------------------------------------------ | `-p "every 5 month from 2009/03"` | periods will have boundaries on 2009/03/01, 2009/08/01, ... |
If you want intervals that start on arbitrary day of your choosing and span a week, month or year, you need to use any of the following: If you want intervals that start on arbitrary day of your choosing and span a week, month or year, you need to use any of the following:
@ -989,16 +989,15 @@ If you want intervals that start on arbitrary day of your choosing and span a we
Examples: Examples:
------------------------------------------ | | |
`-p "every 2nd day of week"` -- periods will go from Tue to Tue |------------------------------|----------------------------------------------------------|
`-p "every Tue"` -- same | `-p "every 2nd day of week"` | periods will go from Tue to Tue |
`-p "every 15th day"` -- period boundaries will be on 15th of each month | `-p "every Tue"` | same |
`-p "every 2nd Monday"` -- period boundaries will be on second Monday of each month | `-p "every 15th day"` | period boundaries will be on 15th of each month |
`-p "every 11/05"` -- yearly periods with boundaries on 5th of Nov | `-p "every 2nd Monday"` | period boundaries will be on second Monday of each month |
`-p "every 5th Nov"` -- same | `-p "every 11/05"` | yearly periods with boundaries on 5th of Nov |
`-p "every Nov 5th"` -- same | `-p "every 5th Nov"` | same |
------------------------------------------ | `-p "every Nov 5th"` | same |
Show historical balances at end of 15th each month (N is exclusive end date): Show historical balances at end of 15th each month (N is exclusive end date):
@ -1305,7 +1304,7 @@ Related:
[#1083](https://github.com/simonmichael/hledger/issues/1083). [#1083](https://github.com/simonmichael/hledger/issues/1083).
| Report type | `-B`, `--value=cost` | `-V`, `-X` | `--value=end` | `--value=DATE`, `--value=now` | | Report type | `-B`, `--value=cost` | `-V`, `-X` | `--value=end` | `--value=DATE`, `--value=now` |
|:------------------------------------------------|:----------------------------------------------|:-------------------------------------------------|:---------------------------------------------------|:----------------------------------------| |-------------------------------------------------|-----------------------------------------------|--------------------------------------------------|----------------------------------------------------|-----------------------------------------|
| **print** | | | | | | **print** | | | | |
| posting amounts | cost | value at report end or today | value at report or journal end | value at DATE/today | | posting amounts | cost | value at report end or today | value at report or journal end | value at DATE/today |
| balance assertions / assignments | unchanged | unchanged | unchanged | unchanged | | balance assertions / assignments | unchanged | unchanged | unchanged | unchanged |