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

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2021-11-21 22:41:52 -10:00
parent d8205306dc
commit c7cc1caca0
3 changed files with 2650 additions and 3188 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
hledger/hledger.1
View File

@ -6672,194 +6672,197 @@ $ hledger print --explicit
.SS Directives .SS Directives
.PP .PP
A directive is a line in the journal beginning with a special keyword, A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. that influences how the journal is processed, how things are displayed,
hledger\[aq]s directives are based on a subset of Ledger\[aq]s, but and so on.
there are many differences (and also some differences between hledger hledger\[aq]s directives are based on (a subset of) Ledger\[aq]s, but
versions). there are many differences, and also some differences between hledger
versions.
Here are some more definitions:
.IP \[bu] 2
\f[I]subdirective\f[R] - Some directives support subdirectives, written
indented below the parent directive.
.IP \[bu] 2
\f[I]decimal mark\f[R] - The character to interpret as a decimal mark
(period or comma) when parsing amounts of a commodity.
.IP \[bu] 2
\f[I]display style\f[R] - How to display amounts of a commodity in
output: symbol side and spacing, digit groups, decimal mark, and number
of decimal places.
.PP .PP
Directives\[aq] behaviour and interactions can get a little bit complex, Here are all the directives and their precise effects, with links to
so here is a table summarising the directives and their effects, with more detailed docs below:
links to more detailed docs.
.PP .PP
.TS .TS
tab(@); tab(@);
lw(7.8n) lw(8.6n) lw(7.0n) lw(27.8n) lw(18.8n). lw(5.2n) lw(64.8n).
T{ T{
directive directive
T}@T{ T}@T{
end directive effects
T}@T{
subdirectives
T}@T{
purpose
T}@T{
can affect (as of 2018/06)
T} T}
_ _
T{ T{
\f[C]account\f[R] \f[B]\f[CB]account\f[B]\f[R]
T}@T{ T}@T{
T}@T{ Declare an account, for checking all entries in all files;and its
any text display order and type, for reports.Subdirectives: any text, ignored.
T}@T{
document account names, declare account types & display order
T}@T{
all entries in all files, before or after
T} T}
T{ T{
\f[C]alias\f[R] \f[B]\f[CB]alias\f[B]\f[R]
T}@T{ T}@T{
\f[C]end aliases\f[R] Rewrites account names, in following entries until end of current file
T}@T{ or \f[C]end aliases\f[R].
T}@T{
rewrite account names
T}@T{
following entries until end of current file or end directive
T} T}
T{ T{
\f[C]apply account\f[R] \f[B]\f[CB]apply account\f[B]\f[R]
T}@T{ T}@T{
\f[C]end apply account\f[R] Prepends a common parent account to all account names, in following
T}@T{ entries until end of current file or \f[C]end apply account\f[R].
T}@T{
prepend a common parent to account names
T}@T{
following entries until end of current file or end directive
T} T}
T{ T{
\f[C]comment\f[R] \f[B]\f[CB]comment\f[B]\f[R]
T}@T{ T}@T{
\f[C]end comment\f[R] Ignores part of the journal file, until end of current file or
T}@T{ \f[C]end comment\f[R].
T}@T{
ignore part of journal
T}@T{
following entries until end of current file or end directive
T} T}
T{ T{
\f[C]commodity\f[R] \f[B]\f[CB]commodity\f[B]\f[R]
T}@T{ T}@T{
T}@T{ Declares a commodity, for checking all entries in all files;the decimal
\f[C]format\f[R] mark for parsing amounts of this commodity, for following entries until
T}@T{ end of current file;and its display style, for reports.
declare a commodity and its number notation & display style Takes precedence over \f[C]D\f[R].Subdirectives: \f[C]format\f[R]
T}@T{ (alternate syntax).
number notation: following entries until end of current file; display
style: amounts of that commodity in reports
T} T}
T{ T{
\f[C]decimal-mark\f[R] \f[B]\f[CB]D\f[B]\f[R]
T}@T{ T}@T{
T}@T{ Sets a default commodity to use for no-symbol amounts,and its decimal
T}@T{ mark for parsing amounts of this commodity in following entries until
declare the decimal mark character for parsing this file end of current file;and its display style, for reports.
T}@T{
following entries until next decimal-mark or end of current file;
included files can override
T} T}
T{ T{
\f[C]D\f[R] \f[B]\f[CB]decimal-mark\f[B]\f[R]
T}@T{ T}@T{
T}@T{ Declares the decimal mark, for parsing amounts of all commodities in
T}@T{ following entries until next \f[C]decimal-mark\f[R] or end of current
declare a commodity to be used for commodityless amounts, and its number file.
notation & display style Included files can override.
T}@T{ Takes precedence over \f[C]commodity\f[R] and \f[C]D\f[R].
default commodity: following commodityless entries until end of current
file; number notation: following entries in that commodity until end of
current file; display style: amounts of that commodity in reports
T} T}
T{ T{
\f[C]include\f[R] \f[B]\f[CB]include\f[B]\f[R]
T}@T{ T}@T{
T}@T{ Includes entries and directives from another file, as if they were
T}@T{ written inline.
include entries/directives from another file
T}@T{
what the included directives affect
T} T}
T{ T{
\f[C]payee\f[R] \f[B]\f[CB]payee\f[B]\f[R]
T}@T{ T}@T{
T}@T{ Declares a payee name, for checking all entries in all files.
T}@T{
declare a payee name
T}@T{
following entries until end of current file
T} T}
T{ T{
\f[C]P\f[R] \f[B]\f[CB]P\f[B]\f[R]
T}@T{ T}@T{
T}@T{ Declares a market price for a commodity on some date, for valuation
T}@T{ reports.
declare a market price for a commodity
T}@T{
amounts of that commodity in reports, when -V is used
T} T}
T{ T{
\f[C]Y\f[R] \f[B]\f[CB]Y\f[B]\f[R]
T}@T{ T}@T{
T}@T{ Declares a year for yearless dates, for following entries until end of
T}@T{ current file.
declare a year for yearless dates
T}@T{
following entries until end of current file
T} T}
T{ T{
\f[C]=\f[R] \f[B]\f[CB]\[ti]\f[B]\f[R] (tilde)
T}@T{ T}@T{
Declares a periodic transaction rule that generates future transactions
with \f[C]--forecast\f[R] and budget goals with
\f[C]balance --budget\f[R].
T}
T{
\f[B]\f[CB]=\f[B]\f[R] (equals)
T}@T{ T}@T{
T}@T{ Declares an auto posting rule that generates extra postings on matched
declare an auto posting rule, adding postings to other transactions transactions with \f[C]--auto\f[R], in current, parent, and child files
T}@T{ (but not sibling files, see #1212).
all entries in parent/current/child files (but not sibling files, see
#1212)
T} T}
.TE .TE
.PP .PP
And some definitions: And here is an overview of which directives are useful for what:
.PP .PP
.TS .TS
tab(@); tab(@);
lw(6.0n) lw(64.0n). lw(33.4n) lw(19.4n) lw(17.3n).
T{ T{
subdirective purpose
T}@T{
directives
T}@T{
command line options with similar effect
T}
_
T{
Declaring a commodity\[aq]s or file\[aq]s decimal mark to help parse
amounts accurately
T}@T{
\f[C]commodity\f[R], \f[C]D\f[R], \f[C]decimal-mark\f[R]
T}@T{ T}@T{
optional indented directive line immediately following a parent
directive
T} T}
T{ T{
number notation Modifying the journal file while parsing
T}@T{ T}@T{
how to interpret numbers when parsing journal entries (the identity of \f[C]alias\f[R], \f[C]apply account\f[R], \f[C]comment\f[R],
the decimal separator character). \f[C]D\f[R], \f[C]Y\f[R]
(Currently each commodity can have its own notation, even in the same T}@T{
file.) \f[C]--alias\f[R]
T} T}
T{ T{
display style Inlining or concatenating extra data files
T}@T{ T}@T{
how to display amounts of a commodity in reports (symbol side and \f[C]include\f[R]
spacing, digit groups, decimal separator, decimal places) T}@T{
multiple \f[C]-f/--file\f[R]\[aq]s
T} T}
T{ T{
directive scope Generating extra transactions or budget goals
T}@T{ T}@T{
which entries and (when there are multiple files) which files are \f[C]\[ti]\f[R]
affected by a directive T}@T{
T}
T{
Generating extra postings
T}@T{
\f[C]=\f[R]
T}@T{
T}
T{
Defining entities to help with error checking
T}@T{
\f[C]account\f[R], \f[C]commodity\f[R], \f[C]payee\f[R]
T}@T{
T}
T{
Defining accounts\[aq] display order and accounting type
T}@T{
\f[C]account\f[R]
T}@T{
T}
T{
Defining commodity display styles for output
T}@T{
\f[C]commodity\f[R], \f[C]D\f[R]
T}@T{
\f[C]-c/--commodity-style\f[R]
T} T}
.TE .TE
.PP
As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output
(reports).
Some directives have multiple effects.
.SS Directives and multiple files .SS Directives and multiple files
.PP .PP
If you use multiple \f[C]-f\f[R]/\f[C]--file\f[R] options, or the If you use multiple \f[C]-f\f[R]/\f[C]--file\f[R] options, or the
\f[C]include\f[R] directive, hledger will process multiple input files. \f[C]include\f[R] directive, hledger will process multiple input files.
But note that directives which affect input (see above) typically last But directives which affect input typically have effect only until the
only until the end of the file in which they occur. end of the file in which they occur (and on any included files in that
region).
.PP .PP
This may seem inconvenient, but it\[aq]s intentional; it makes reports This may seem inconvenient, but it\[aq]s intentional; it makes reports
stable and deterministic, independent of the order of input. stable and deterministic, independent of the order of input.
@ -7073,12 +7076,9 @@ For compatibility/historical reasons, \f[C]D\f[R] also acts like a
\f[C]commodity\f[R] directive (setting the commodity\[aq]s decimal mark \f[C]commodity\f[R] directive (setting the commodity\[aq]s decimal mark
for parsing and display style for output). for parsing and display style for output).
.PP .PP
The syntax is \f[C]D AMOUNT\f[R].
As with \f[C]commodity\f[R], the amount must include a decimal mark As with \f[C]commodity\f[R], the amount must include a decimal mark
(either period or comma). (either period or comma).
If both \f[C]commodity\f[R] and \f[C]D\f[R] directives are used for the
same commodity, the \f[C]commodity\f[R] style takes precedence.
.PP
The syntax is \f[C]D AMOUNT\f[R].
Eg: Eg:
.IP .IP
.nf .nf
@ -7092,6 +7092,15 @@ D $1,000.00
b b
\f[R] \f[R]
.fi .fi
.PP
If both \f[C]commodity\f[R] and \f[C]D\f[R] directives are found for a
commodity, \f[C]commodity\f[R] takes precedence for setting decimal mark
and display style.
.PP
If you are using \f[C]D\f[R] and also checking commodities, you will
need to add a \f[C]commodity\f[R] directive similar to the \f[C]D\f[R].
(The \f[C]hledger check commodities\f[R] command expects
\f[C]commodity\f[R] directives, and ignores \f[C]D\f[R]).
.SS Declaring market prices .SS Declaring market prices
.PP .PP
The \f[C]P\f[R] directive declares a market price, which is an exchange The \f[C]P\f[R] directive declares a market price, which is an exchange
@ -7553,8 +7562,8 @@ include c.journal ; also affected
.fi .fi
.SS \f[C]end aliases\f[R] .SS \f[C]end aliases\f[R]
.PP .PP
You can clear (forget) all currently defined aliases with the You can clear (forget) all currently defined aliases (seen in the
\f[C]end aliases\f[R] directive: journal so far, or defined on the command line) with this directive:
.IP .IP
.nf .nf
\f[C] \f[C]

5050
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

185
hledger/hledger.txt
View File

@ -4850,105 +4850,94 @@ JOURNAL FORMAT
Directives Directives
A directive is a line in the journal beginning with a special keyword, A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. hledger's directives are that influences how the journal is processed, how things are displayed,
based on a subset of Ledger's, but there are many differences (and also and so on. hledger's directives are based on (a subset of) Ledger's,
some differences between hledger versions). but there are many differences, and also some differences between
hledger versions. Here are some more definitions:
Directives' behaviour and interactions can get a little bit complex, so o subdirective - Some directives support subdirectives, written
here is a table summarising the directives and their effects, with indented below the parent directive.
links to more detailed docs.
o decimal mark - The character to interpret as a decimal mark (period
or comma) when parsing amounts of a commodity.
o display style - How to display amounts of a commodity in output: sym-
bol side and spacing, digit groups, decimal mark, and number of deci-
mal places.
Here are all the directives and their precise effects, with links to
more detailed docs below:
direc- end subdi- purpose can affect (as of direc- effects
tive directive rec- 2018/06)
tives
------------------------------------------------------------------------------------
account any document account names, all entries in all
text declare account types & dis- files, before or
play order after
alias end rewrite account names following entries
aliases until end of cur-
rent file or end
directive
apply end apply prepend a common parent to following entries
account account account names until end of cur-
rent file or end
directive
comment end com- ignore part of journal following entries
ment until end of cur-
rent file or end
directive
commod- format declare a commodity and its number notation:
ity number notation & display following entries
style until end of cur-
rent file; display
style: amounts of
that commodity in
reports
decimal- declare the decimal mark following entries
mark character for parsing this until next decimal-
file mark or end of cur-
rent file; included
files can override
D declare a commodity to be default commodity:
used for commodityless following commod-
amounts, and its number ityless entries
notation & display style until end of cur-
rent file; number
notation: following
entries in that
commodity until end
of current file;
display style:
amounts of that
commodity in
reports
include include entries/directives what the included
from another file directives affect
payee declare a payee name following entries
until end of cur-
rent file
P declare a market price for a amounts of that
commodity commodity in
reports, when -V is
used
Y declare a year for yearless following entries
dates until end of cur-
rent file
= declare an auto posting all entries in par-
rule, adding postings to ent/current/child
other transactions files (but not sib-
ling files, see
#1212)
And some definitions:
subdi- optional indented directive line immediately following a parent
rec- directive
tive tive
-----------------------------------------------------------------------------
account Declare an account, for checking all entries in all files;and its
display order and type, for reports.Subdirectives: any text,
ignored.
alias Rewrites account names, in following entries until end of current
file or end aliases.
apply Prepends a common parent account to all account names, in follow-
account ing entries until end of current file or end apply account.
comment Ignores part of the journal file, until end of current file or
end comment.
commod- Declares a commodity, for checking all entries in all files;the
ity decimal mark for parsing amounts of this commodity, for following
entries until end of current file;and its display style, for
reports. Takes precedence over D.Subdirectives: format (alter-
nate syntax).
D Sets a default commodity to use for no-symbol amounts,and its
decimal mark for parsing amounts of this commodity in following
entries until end of current file;and its display style, for
reports.
deci- Declares the decimal mark, for parsing amounts of all commodities
mal- in following entries until next decimal-mark or end of current
mark file. Included files can override. Takes precedence over com-
modity and D.
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 valua-
tion reports.
Y Declares a year for yearless dates, for following entries until
end of current file.
~ Declares a periodic transaction rule that generates future trans-
(tilde) actions with --forecast and budget goals with balance --budget.
= Declares an auto posting rule that generates extra postings on
(equals) matched transactions with --auto, in current, parent, and child
files (but not sibling files, see #1212).
And here is an overview of which directives are useful for what:
purpose directives command line
options with sim-
ilar effect
-----------------------------------------------------------------------------
Declaring a commodity's or file's commodity, D, deci-
decimal mark to help parse mal-mark
amounts accurately
Modifying the journal file while alias, apply --alias
parsing account, comment,
D, Y
Inlining or concatenating extra include multiple
data files -f/--file's
Generating extra transactions or ~
budget goals
Generating extra postings =
Defining entities to help with account, commodity,
error checking payee
Defining accounts' display order account
and accounting type
number how to interpret numbers when parsing journal entries (the iden- Defining commodity display styles commodity, D -c/--commodity-
nota- tity of the decimal separator character). (Currently each com- for output style
tion modity can have its own notation, even in the same file.)
dis- how to display amounts of a commodity in reports (symbol side
play and spacing, digit groups, decimal separator, decimal places)
style
direc- which entries and (when there are multiple files) which files
tive are affected by a directive
scope
As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output
(reports). Some directives have multiple effects.
Directives and multiple files Directives and multiple files
If you use multiple -f/--file options, or the include directive, If you use multiple -f/--file options, or the include directive,
hledger will process multiple input files. But note that directives hledger will process multiple input files. But directives which affect
which affect input (see above) typically last only until the end of the input typically have effect only until the end of the file in which
file in which they occur. they occur (and on any included files in that region).
This may seem inconvenient, but it's intentional; it makes reports sta- This may seem inconvenient, but it's intentional; it makes reports sta-
ble and deterministic, independent of the order of input. Otherwise ble and deterministic, independent of the order of input. Otherwise
@ -5117,11 +5106,8 @@ JOURNAL FORMAT
directive (setting the commodity's decimal mark for parsing and display directive (setting the commodity's decimal mark for parsing and display
style for output). style for output).
As with commodity, the amount must include a decimal mark (either The syntax is D AMOUNT. As with commodity, the amount must include a
period or comma). If both commodity and D directives are used for the decimal mark (either period or comma). Eg:
same commodity, the commodity style takes precedence.
The syntax is D AMOUNT. Eg:
; commodity-less amounts should be treated as dollars ; commodity-less amounts should be treated as dollars
; (and displayed with the dollar sign on the left, thousands separators and two decimal places) ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
@ -5131,6 +5117,13 @@ JOURNAL FORMAT
a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
b b
If both commodity and D directives are found for a commodity, commodity
takes precedence for setting decimal mark and display style.
If you are using D and also checking commodities, you will need to add
a commodity directive similar to the D. (The hledger check commodities
command expects commodity directives, and ignores D).
Declaring market prices Declaring market prices
The P directive declares a market price, which is an exchange rate The P directive declares a market price, which is an exchange rate
between two commodities on a certain date. (In Ledger, they are called between two commodities on a certain date. (In Ledger, they are called
@ -5486,8 +5479,8 @@ JOURNAL FORMAT
include c.journal ; also affected include c.journal ; also affected
end aliases end aliases
You can clear (forget) all currently defined aliases with the end You can clear (forget) all currently defined aliases (seen in the jour-
aliases directive: nal so far, or defined on the command line) with this directive:
end aliases end aliases