;doc: update manuals
This commit is contained in:
Simon Michael
parent
d8205306dc
commit
c7cc1caca0
@ -6672,194 +6672,197 @@ $ hledger print --explicit
|
||||
.SS Directives
|
||||
.PP
|
||||
A directive is a line in the journal beginning with a special keyword,
|
||||
that influences how the journal is processed.
|
||||
hledger\[aq]s directives are based on a subset of Ledger\[aq]s, but
|
||||
there are many differences (and also some differences between hledger
|
||||
versions).
|
||||
that influences how the journal is processed, how things are displayed,
|
||||
and so on.
|
||||
hledger\[aq]s directives are based on (a subset of) Ledger\[aq]s, but
|
||||
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
|
||||
Directives\[aq] behaviour and interactions can get a little bit complex,
|
||||
so here is a table summarising the directives and their effects, with
|
||||
links to more detailed docs.
|
||||
Here are all the directives and their precise effects, with links to
|
||||
more detailed docs below:
|
||||
.PP
|
||||
.TS
|
||||
tab(@);
|
||||
lw(7.8n) lw(8.6n) lw(7.0n) lw(27.8n) lw(18.8n).
|
||||
lw(5.2n) lw(64.8n).
|
||||
T{
|
||||
directive
|
||||
T}@T{
|
||||
end directive
|
||||
T}@T{
|
||||
subdirectives
|
||||
T}@T{
|
||||
purpose
|
||||
T}@T{
|
||||
can affect (as of 2018/06)
|
||||
effects
|
||||
T}
|
||||
_
|
||||
T{
|
||||
\f[C]account\f[R]
|
||||
\f[B]\f[CB]account\f[B]\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
any text
|
||||
T}@T{
|
||||
document account names, declare account types & display order
|
||||
T}@T{
|
||||
all entries in all files, before or after
|
||||
Declare an account, for checking all entries in all files;and its
|
||||
display order and type, for reports.Subdirectives: any text, ignored.
|
||||
T}
|
||||
T{
|
||||
\f[C]alias\f[R]
|
||||
\f[B]\f[CB]alias\f[B]\f[R]
|
||||
T}@T{
|
||||
\f[C]end aliases\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
rewrite account names
|
||||
T}@T{
|
||||
following entries until end of current file or end directive
|
||||
Rewrites account names, in following entries until end of current file
|
||||
or \f[C]end aliases\f[R].
|
||||
T}
|
||||
T{
|
||||
\f[C]apply account\f[R]
|
||||
\f[B]\f[CB]apply account\f[B]\f[R]
|
||||
T}@T{
|
||||
\f[C]end apply account\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
prepend a common parent to account names
|
||||
T}@T{
|
||||
following entries until end of current file or end directive
|
||||
Prepends a common parent account to all account names, in following
|
||||
entries until end of current file or \f[C]end apply account\f[R].
|
||||
T}
|
||||
T{
|
||||
\f[C]comment\f[R]
|
||||
\f[B]\f[CB]comment\f[B]\f[R]
|
||||
T}@T{
|
||||
\f[C]end comment\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
ignore part of journal
|
||||
T}@T{
|
||||
following entries until end of current file or end directive
|
||||
Ignores part of the journal file, until end of current file or
|
||||
\f[C]end comment\f[R].
|
||||
T}
|
||||
T{
|
||||
\f[C]commodity\f[R]
|
||||
\f[B]\f[CB]commodity\f[B]\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
\f[C]format\f[R]
|
||||
T}@T{
|
||||
declare a commodity and its number notation & display style
|
||||
T}@T{
|
||||
number notation: following entries until end of current file; display
|
||||
style: amounts of that commodity in reports
|
||||
Declares a commodity, for checking all entries in all files;the 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 \f[C]D\f[R].Subdirectives: \f[C]format\f[R]
|
||||
(alternate syntax).
|
||||
T}
|
||||
T{
|
||||
\f[C]decimal-mark\f[R]
|
||||
\f[B]\f[CB]D\f[B]\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
T}@T{
|
||||
declare the decimal mark character for parsing this file
|
||||
T}@T{
|
||||
following entries until next decimal-mark or end of current file;
|
||||
included files can override
|
||||
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.
|
||||
T}
|
||||
T{
|
||||
\f[C]D\f[R]
|
||||
\f[B]\f[CB]decimal-mark\f[B]\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
T}@T{
|
||||
declare a commodity to be used for commodityless amounts, and its number
|
||||
notation & display style
|
||||
T}@T{
|
||||
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
|
||||
Declares the decimal mark, for parsing amounts of all commodities in
|
||||
following entries until next \f[C]decimal-mark\f[R] or end of current
|
||||
file.
|
||||
Included files can override.
|
||||
Takes precedence over \f[C]commodity\f[R] and \f[C]D\f[R].
|
||||
T}
|
||||
T{
|
||||
\f[C]include\f[R]
|
||||
\f[B]\f[CB]include\f[B]\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
T}@T{
|
||||
include entries/directives from another file
|
||||
T}@T{
|
||||
what the included directives affect
|
||||
Includes entries and directives from another file, as if they were
|
||||
written inline.
|
||||
T}
|
||||
T{
|
||||
\f[C]payee\f[R]
|
||||
\f[B]\f[CB]payee\f[B]\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
T}@T{
|
||||
declare a payee name
|
||||
T}@T{
|
||||
following entries until end of current file
|
||||
Declares a payee name, for checking all entries in all files.
|
||||
T}
|
||||
T{
|
||||
\f[C]P\f[R]
|
||||
\f[B]\f[CB]P\f[B]\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
T}@T{
|
||||
declare a market price for a commodity
|
||||
T}@T{
|
||||
amounts of that commodity in reports, when -V is used
|
||||
Declares a market price for a commodity on some date, for valuation
|
||||
reports.
|
||||
T}
|
||||
T{
|
||||
\f[C]Y\f[R]
|
||||
\f[B]\f[CB]Y\f[B]\f[R]
|
||||
T}@T{
|
||||
T}@T{
|
||||
T}@T{
|
||||
declare a year for yearless dates
|
||||
T}@T{
|
||||
following entries until end of current file
|
||||
Declares a year for yearless dates, for following entries until end of
|
||||
current file.
|
||||
T}
|
||||
T{
|
||||
\f[C]=\f[R]
|
||||
\f[B]\f[CB]\[ti]\f[B]\f[R] (tilde)
|
||||
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{
|
||||
declare an auto posting rule, adding postings to other transactions
|
||||
T}@T{
|
||||
all entries in parent/current/child files (but not sibling files, see
|
||||
#1212)
|
||||
Declares an auto posting rule that generates extra postings on matched
|
||||
transactions with \f[C]--auto\f[R], in current, parent, and child files
|
||||
(but not sibling files, see #1212).
|
||||
T}
|
||||
.TE
|
||||
.PP
|
||||
And some definitions:
|
||||
And here is an overview of which directives are useful for what:
|
||||
.PP
|
||||
.TS
|
||||
tab(@);
|
||||
lw(6.0n) lw(64.0n).
|
||||
lw(33.4n) lw(19.4n) lw(17.3n).
|
||||
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{
|
||||
optional indented directive line immediately following a parent
|
||||
directive
|
||||
T}
|
||||
T{
|
||||
number notation
|
||||
Modifying the journal file while parsing
|
||||
T}@T{
|
||||
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.)
|
||||
\f[C]alias\f[R], \f[C]apply account\f[R], \f[C]comment\f[R],
|
||||
\f[C]D\f[R], \f[C]Y\f[R]
|
||||
T}@T{
|
||||
\f[C]--alias\f[R]
|
||||
T}
|
||||
T{
|
||||
display style
|
||||
Inlining or concatenating extra data files
|
||||
T}@T{
|
||||
how to display amounts of a commodity in reports (symbol side and
|
||||
spacing, digit groups, decimal separator, decimal places)
|
||||
\f[C]include\f[R]
|
||||
T}@T{
|
||||
multiple \f[C]-f/--file\f[R]\[aq]s
|
||||
T}
|
||||
T{
|
||||
directive scope
|
||||
Generating extra transactions or budget goals
|
||||
T}@T{
|
||||
which entries and (when there are multiple files) which files are
|
||||
affected by a directive
|
||||
\f[C]\[ti]\f[R]
|
||||
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}
|
||||
.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
|
||||
.PP
|
||||
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.
|
||||
But note that directives which affect input (see above) typically last
|
||||
only until the end of the file in which they occur.
|
||||
But directives which affect input typically have effect only until the
|
||||
end of the file in which they occur (and on any included files in that
|
||||
region).
|
||||
.PP
|
||||
This may seem inconvenient, but it\[aq]s intentional; it makes reports
|
||||
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
|
||||
for parsing and display style for output).
|
||||
.PP
|
||||
The syntax is \f[C]D AMOUNT\f[R].
|
||||
As with \f[C]commodity\f[R], the amount must include a decimal mark
|
||||
(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:
|
||||
.IP
|
||||
.nf
|
||||
@ -7092,6 +7092,15 @@ D $1,000.00
|
||||
b
|
||||
\f[R]
|
||||
.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
|
||||
.PP
|
||||
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
|
||||
.SS \f[C]end aliases\f[R]
|
||||
.PP
|
||||
You can clear (forget) all currently defined aliases with the
|
||||
\f[C]end aliases\f[R] directive:
|
||||
You can clear (forget) all currently defined aliases (seen in the
|
||||
journal so far, or defined on the command line) with this directive:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
|
||||
5050
hledger/hledger.info
5050
hledger/hledger.info
File diff suppressed because it is too large
Load Diff
@ -4850,105 +4850,94 @@ JOURNAL FORMAT
|
||||
|
||||
Directives
|
||||
A directive is a line in the journal beginning with a special keyword,
|
||||
that influences how the journal is processed. hledger's directives are
|
||||
based on a subset of Ledger's, but there are many differences (and also
|
||||
some differences between hledger versions).
|
||||
that influences how the journal is processed, how things are displayed,
|
||||
and so on. hledger's directives are based on (a subset of) Ledger's,
|
||||
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
|
||||
here is a table summarising the directives and their effects, with
|
||||
links to more detailed docs.
|
||||
o subdirective - Some directives support subdirectives, written
|
||||
indented below the parent directive.
|
||||
|
||||
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
|
||||
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
|
||||
direc- effects
|
||||
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-
|
||||
nota- tity of the decimal separator character). (Currently each com-
|
||||
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.
|
||||
Defining commodity display styles commodity, D -c/--commodity-
|
||||
for output style
|
||||
|
||||
Directives and multiple files
|
||||
If you use multiple -f/--file options, or the include directive,
|
||||
hledger will process multiple input files. But note that directives
|
||||
which affect input (see above) typically last only until the end of the
|
||||
file in which they occur.
|
||||
hledger will process multiple input files. But directives which affect
|
||||
input typically have effect only until the end of the file in which
|
||||
they occur (and on any included files in that region).
|
||||
|
||||
This may seem inconvenient, but it's intentional; it makes reports sta-
|
||||
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
|
||||
style for output).
|
||||
|
||||
As with commodity, the amount must include a decimal mark (either
|
||||
period or comma). If both commodity and D directives are used for the
|
||||
same commodity, the commodity style takes precedence.
|
||||
|
||||
The syntax is D AMOUNT. Eg:
|
||||
The syntax is D AMOUNT. As with commodity, the amount must include a
|
||||
decimal mark (either period or comma). Eg:
|
||||
|
||||
; commodity-less amounts should be treated as dollars
|
||||
; (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
|
||||
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
|
||||
The P directive declares a market price, which is an exchange rate
|
||||
between two commodities on a certain date. (In Ledger, they are called
|
||||
@ -5486,8 +5479,8 @@ JOURNAL FORMAT
|
||||
include c.journal ; also affected
|
||||
|
||||
end aliases
|
||||
You can clear (forget) all currently defined aliases with the end
|
||||
aliases directive:
|
||||
You can clear (forget) all currently defined aliases (seen in the jour-
|
||||
nal so far, or defined on the command line) with this directive:
|
||||
|
||||
end aliases
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user