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;
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
[**field assignment**](#field-assignment) assign a value to one hledger field, with interpolation
[**`separator`**](#separator) a custom field separator
[**`if`**](#if) apply some rules to matched CSV records
[**`end`**](#end) skip the remaining CSV records
[**`date-format`**](#date-format) describe the format of CSV dates
[**`newest-first`**](#newest-first) disambiguate record order when there's only one date
[**`include`**](#include) inline another CSV rules file
------------------------------------------- ---------------------------------------------------
| | |
|-------------------------------------------|---------------------------------------------------------|
| [**`skip`**](#skip) | skip one or more header lines or matched CSV records |
| [**`fields`**](#fields) | name CSV fields, assign them to hledger fields |
| [**field assignment**](#field-assignment) | assign a value to one hledger field, with interpolation |
| [**`separator`**](#separator) | a custom field separator |
| [**`if`**](#if) | apply some rules to matched CSV records |
| [**`end`**](#end) | skip the remaining CSV records |
| [**`date-format`**](#date-format) | describe the format of CSV dates |
| [**`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`
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,
separated from it by a space, indicating one of three statuses:
mark   | status
:-----------|:-------------------
  | unmarked
`!` | pending
`*` | cleared
| mark   | status |
|--------|----------|
|   | unmarked |
| `!` | pending |
| `*` | cleared |
When reporting, you can filter by status with
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.
Here's one suggestion:
status | meaning
:---------|:------------------------------------------------------------
uncleared | recorded but not yet reconciled; needs review
pending | tentatively reconciled (if needed, eg during a big reconciliation)
cleared | complete, reconciled as far as possible, and considered correct
| status | meaning |
|-----------|--------------------------------------------------------------------|
| uncleared | recorded but not yet reconciled; needs review |
| pending | tentatively reconciled (if needed, eg during a big reconciliation) |
| cleared | complete, reconciled as far as possible, and considered correct |
With this scheme, you would use
`-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> -->
| 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
| [`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
@ -795,11 +795,11 @@ so here is a table summarising the directives and their effects, with links to m
And some definitions:
| | |
|:----------------|:--------------------------------------------------------------------------------------------------------------------
| 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.)
| 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
|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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.) |
| 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 |
<!-- | **entries affected:** | -->
<!-- | 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:
----------------- --------
unescaped: `$`
escaped: `\$`
double-escaped: `\\$`
triple-escaped: `\\\\$`
----------------- --------
| | |
|-----------------|---------|
| unescaped: | `$` |
| escaped: | `\$` |
| double-escaped: | `\\$` |
| triple-escaped: | `\\\\$` |
(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:
--------------------------------------------- -----------------------------------------------------------------------------
`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` start of month
`10/1` month and day in current year
`21` day in current month
`october, oct` start of month in current year
`yesterday, today, tomorrow` -1, 0, 1 days from today
`last/this/next day/week/month/quarter/year` -1, 0, 1 periods from the current period
`20181201` 8 digit YYYYMMDD with valid year month and day
`201812` 6 digit YYYYMM with valid year and month
--------------------------------------------- -----------------------------------------------------------------------------
| | |
|----------------------------------------------|---------------------------------------------------------------------------------------|
| `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` | start of month |
| `10/1` | month and day in current year |
| `21` | day in current month |
| `october, oct` | start of month in current year |
| `yesterday, today, tomorrow` | -1, 0, 1 days from today |
| `last/this/next day/week/month/quarter/year` | -1, 0, 1 periods from the current period |
| `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:
--------------------------------------------- -----------------------------------------------------------------------------
`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
`20181232` 8 digits with an invalid day gives an error
`201801012` 9+ digits beginning with a valid YYYYMMDD gives an error
--------------------------------------------- -----------------------------------------------------------------------------
| | |
|-------------|-------------------------------------------------------------------|
| `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 |
| `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
@ -864,16 +864,16 @@ Some notes:
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 thismonth` all transactions on or after the 1st of the current month
`-p thismonth` all transactions in the current month
`date:2016/3/17-` the above written as queries instead
`date:-12/1`
`date:thismonth-`
`date:thismonth`
---
| | |
|-------------------|---------------------------------------------------------------------------------------------|
| `-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 thismonth` | all transactions on or after the 1st of the current month |
| `-p thismonth` | all transactions in the current month |
| `date:2016/3/17-` | the above written as queries instead |
| `date:-12/1` | |
| `date:thismonth-` | |
| `date:thismonth` | |
## 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 "-".
These are equivalent to the above:
------------------------------
`-p "2009/1/1 2009/4/1"`
`-p2009/1/1to2009/4/1`
`-p2009/1/1-2009/4/1`
------------------------------
| |
|--------------------------|
| `-p "2009/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
above can also be written as:
------------------------------
`-p "1/1 4/1"`
`-p "january-apr"`
`-p "this year to 4/1"`
------------------------------
| |
|-------------------------|
| `-p "1/1 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
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"` the same
`-p "to 2009"` everything before january 1, 2009
---------------------------- ---------------------------------
| | |
|----------------------|-----------------------------------|
| `-p "from 2009/1/1"` | everything after january 1, 2009 |
| `-p "from 2009/1"` | the same |
| `-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
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/1/1"` just that day; equivalent to "2009/1/1 to 2009/1/2"
--------------------- ------------------------------------------------------
| | |
|-----------------|--------------------------------------------------------|
| `-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/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 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.
Examples:
------------------------------------------
`-p "weekly from 2009/1/1 to 2009/4/1"`
`-p "monthly in 2008"`
`-p "quarterly"`
------------------------------------------
| |
|-----------------------------------------|
| `-p "weekly from 2009/1/1 to 2009/4/1"` |
| `-p "monthly in 2008"` |
| `-p "quarterly"` |
Note that `weekly`, `monthly`, `quarterly` and `yearly` intervals will
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:
------------------------------------------
`-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 "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
------------------------------------------
| | |
|------------------------------------------------|------------------------------------------------------------------------------------|
| `-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 "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:
`biweekly`,
@ -971,11 +971,11 @@ All of these will start on the first day of the requested period and end on the
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 "every 5 month from 2009/03"` -- periods will have boundaries on 2009/03/01, 2009/08/01, ...
------------------------------------------
| | |
|-----------------------------------|-------------------------------------------------------------|
| `-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 "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:
@ -989,16 +989,15 @@ If you want intervals that start on arbitrary day of your choosing and span a we
Examples:
------------------------------------------
`-p "every 2nd day of week"` -- periods will go from Tue to Tue
`-p "every Tue"` -- same
`-p "every 15th day"` -- period boundaries will be on 15th of each month
`-p "every 2nd Monday"` -- period boundaries will be on second Monday of each month
`-p "every 11/05"` -- yearly periods with boundaries on 5th of Nov
`-p "every 5th Nov"` -- same
`-p "every Nov 5th"` -- same
------------------------------------------
| | |
|------------------------------|----------------------------------------------------------|
| `-p "every 2nd day of week"` | periods will go from Tue to Tue |
| `-p "every Tue"` | same |
| `-p "every 15th day"` | period boundaries will be on 15th of each month |
| `-p "every 2nd Monday"` | period boundaries will be on second Monday of each month |
| `-p "every 11/05"` | yearly periods with boundaries on 5th of Nov |
| `-p "every 5th Nov"` | same |
| `-p "every Nov 5th"` | same |
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).
| Report type | `-B`, `--value=cost` | `-V`, `-X` | `--value=end` | `--value=DATE`, `--value=now` |
|:------------------------------------------------|:----------------------------------------------|:-------------------------------------------------|:---------------------------------------------------|:----------------------------------------|
|-------------------------------------------------|-----------------------------------------------|--------------------------------------------------|----------------------------------------------------|-----------------------------------------|
| **print** | | | | |
| 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 |