;doc: cli: improve Directives summaries
This commit is contained in:
Simon Michael
parent
9004372e3c
commit
331b419c97
@ -1684,47 +1684,49 @@ Here are some more definitions:
|
||||
symbol side and spacing, digit groups, decimal mark, and number of
|
||||
decimal places.
|
||||
|
||||
Directives are not required when starting out with hledger, but you
|
||||
will probably add some as your needs grow.
|
||||
Here is an overview of directives by purpose:
|
||||
Directives are not required when starting out with hledger,
|
||||
but you will probably want to add some as your needs grow.
|
||||
Here are the directives organised by use case:
|
||||
|
||||
| purpose | directives | command line options with similar effect |
|
||||
|-------------------------------------------------------------------------------|---------------------------------------------------------|---------------------------------------------|
|
||||
| **READING/GENERATING DATA:** | | |
|
||||
| Declare a commodity's or file's decimal mark to help parse amounts accurately | [`commodity`], [`D`], [`decimal-mark`] | |
|
||||
| Apply changes to the data while parsing | [`alias`], [`apply account`], [`comment`], [`D`], [`Y`] | [`--alias`] |
|
||||
| Inline extra data files | [`include`] | [multiple `-f/--file`'s](#multiple-files) |
|
||||
| Generate extra transactions or budget goals | [`~`] | |
|
||||
| Generate extra postings | [`=`] | |
|
||||
| **CHECKING FOR ERRORS:** | | |
|
||||
| Define valid entities to allow stricter error checking | [`account`], [`commodity`], [`payee`] | |
|
||||
| **DISPLAYING REPORTS:** | | |
|
||||
| Declare accounts' display order and accounting type | [`account`] | |
|
||||
| Declare commodity display styles | [`commodity`], [`D`] | [`-c/--commodity-style`](#commodity-styles) |
|
||||
| Declare market prices | [`P`] | |
|
||||
| purpose | directives |
|
||||
|-------------------------------------------------------------------------------|---------------------------------------------------------|
|
||||
| **READING/GENERATING DATA:** | |
|
||||
| Declare a commodity's or file's decimal mark to help parse amounts accurately | [`commodity`], [`D`], [`decimal-mark`] |
|
||||
| Apply changes to the data while parsing | [`alias`], [`apply account`], [`comment`], [`D`], [`Y`] |
|
||||
| Inline extra data files | [`include`] |
|
||||
| Generate extra transactions or budget goals | [`~`] |
|
||||
| Generate extra postings | [`=`] |
|
||||
| **CHECKING FOR ERRORS:** | |
|
||||
| Define valid entities to allow stricter error checking | [`account`], [`commodity`], [`payee`] |
|
||||
| **DISPLAYING REPORTS:** | |
|
||||
| Declare accounts' display order and accounting type | [`account`] |
|
||||
| Declare commodity display styles | [`commodity`], [`D`] |
|
||||
| Declare market prices | [`P`] |
|
||||
|
||||
And here are all the directives and their precise effects:
|
||||
### Directive effects
|
||||
|
||||
And here is what each directive does, and which files and journal entries (transactions) it affects:
|
||||
|
||||
<!-- <style> -->
|
||||
<!-- table a code { white-space:nowrap; } -->
|
||||
<!-- h1,h2,h3,h4,h5,h6 { color:red; } -->
|
||||
<!-- </style> -->
|
||||
|
||||
| directive | effects | ends at file end? |
|
||||
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|
|
||||
| **[`account`]** | Declares an account, for [checking](#check) all entries in all files; <br>and its [display order](#account-display-order) and [type](#declaring-account-types), for reports. <br>Subdirectives: any text, ignored. | |
|
||||
| **[`alias`]** | Rewrites account names, in following entries until end of current file or [`end aliases`]. | Y |
|
||||
| **[`apply account`]** | Prepends a common parent account to all account names, in following entries until end of current file or `end apply account`. | Y |
|
||||
| **[`comment`]** | Ignores part of the journal file, until end of current file or `end comment`. | Y |
|
||||
| **[`commodity`]** | Declares a commodity, for checking all entries in all files; <br>the decimal mark for parsing amounts of this commodity, for following entries until end of current file; <br>and its display style, for reports. Takes precedence over `D`. <br>Subdirectives: `format` (alternate syntax). | N, <br>Y<br><br> |
|
||||
| **[`D`]** | Sets a default commodity to use for no-symbol amounts, <br>and its decimal mark for parsing amounts of this commodity in following entries until end of current file; <br>and its display style, for reports. | Y |
|
||||
| **[`decimal-mark`]** | Declares the decimal mark, for parsing amounts of all commodities in following entries until next `decimal-mark` or end of current file. Included files can override. Takes precedence over `commodity` and `D`. | Y |
|
||||
| **[`include`]** | Includes entries and directives from another file, as if they were written inline. | |
|
||||
| **[`payee`]** | Declares a payee name, for checking all entries in all files. | |
|
||||
| **[`P`]** | Declares a market price for a commodity on some date, for [valuation](#valuation) reports. | |
|
||||
| **[`Y`]** | Declares a year for yearless dates, for following entries until end of current file. | Y |
|
||||
| **[`~`]** (tilde) | Declares a periodic transaction rule that generates future transactions with `--forecast` and budget goals with `balance --budget`. | |
|
||||
| **[`=`]** (equals) | Declares an auto posting rule that generates extra postings on matched transactions with `--auto`, in current, parent, and child files (but not sibling files, see [#1212](https://github.com/simonmichael/hledger/issues/1212)). | partly |
|
||||
| directive | what it does | ends at file end? |
|
||||
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|
|
||||
| **[`account`]** | Declares an account, for [checking](#check) all entries in all files; <br>and its [display order](#account-display-order) and [type](#declaring-account-types). <br>Subdirectives: any text, ignored. | N |
|
||||
| **[`alias`]** | Rewrites account names, in following entries until end of current file or [`end aliases`]. <br>Command line equivalent: [`--alias`] | Y |
|
||||
| **[`apply account`]** | Prepends a common parent account to all account names, in following entries until end of current file or `end apply account`. | Y |
|
||||
| **[`comment`]** | Ignores part of the journal file, until end of current file or `end comment`. | Y |
|
||||
| **[`commodity`]** | Declares up to four things: <br>1. a commodity symbol, for checking all amounts in all files <br>2. the decimal mark for parsing amounts of this commodity, in the following entries until end of current file (if there is no `decimal-mark` directive) <br>3. and the display style for amounts of this commodity <br>4. which is also the precision to use for balanced-transaction checking in this commodity.<br> Takes precedence over `D`. <br>Subdirectives: `format` (Ledger-compatible syntax). <br>Command line equivalent: [`-c/--commodity-style`](#commodity-styles) | N,<br>Y,<br>N,<br>N |
|
||||
| **[`D`]** | Sets a default commodity to use for no-symbol amounts;<br>and, if there is no `commodity` directive for this commodity: its decimal mark, balancing precision, and display style, as above. | Y,<br>Y,<br>N,<br>N |
|
||||
| **[`decimal-mark`]** | Declares the decimal mark, for parsing amounts of all commodities in following entries until next `decimal-mark` or end of current file. Included files can override. Takes precedence over `commodity` and `D`. | Y |
|
||||
| **[`include`]** | Includes entries and directives from another file, as if they were written inline. <br>Command line alternative: multiple [`-f/--file`](#multiple-files) | N |
|
||||
| **[`payee`]** | Declares a payee name, for checking all entries in all files. | N |
|
||||
| **[`P`]** | Declares the market price of a commodity on some date, for [value reports](#valuation). | N |
|
||||
| **[`Y`]** | Sets a default year to use for any yearless dates, in following entries until end of current file. | Y |
|
||||
| **[`~`]** (tilde) | Declares a periodic transaction rule that generates future transactions with `--forecast` and budget goals with `balance --budget`. | N |
|
||||
| **[`=`]** (equals) | Declares an auto posting rule that generates extra postings on matched transactions with `--auto`, in current, parent, and child files (but not sibling files, see [#1212](https://github.com/simonmichael/hledger/issues/1212)). | partly |
|
||||
|
||||
[`=`]: #auto-postings
|
||||
[`D`]: #default-commodity
|
||||
|
||||
Loading…
Reference in New Issue
Block a user