summaryrefslogtreecommitdiff
path: root/hledger_journal.5
diff options
context:
space:
mode:
Diffstat (limited to 'hledger_journal.5')
-rw-r--r--hledger_journal.52153
1 files changed, 0 insertions, 2153 deletions
diff --git a/hledger_journal.5 b/hledger_journal.5
deleted file mode 100644
index c1b6c53..0000000
--- a/hledger_journal.5
+++ /dev/null
@@ -1,2153 +0,0 @@
-.\"t
-
-.TH "HLEDGER_JOURNAL" "5" "December 2020" "hledger-lib-1.20.4 " "hledger User Manuals"
-
-
-
-.SH NAME
-.PP
-hledger\[aq]s default file format, representing a General Journal.
-.SH DESCRIPTION
-.PP
-hledger\[aq]s usual data source is a plain text file containing journal
-entries in hledger journal format.
-This file represents a standard accounting general journal.
-I use file names ending in \f[C].journal\f[R], but that\[aq]s not
-required.
-The journal file contains a number of transaction entries, each
-describing a transfer of money (or any commodity) between two or more
-named accounts, in a simple format readable by both hledger and humans.
-.PP
-hledger\[aq]s journal format is a compatible subset, mostly, of
-ledger\[aq]s journal format, so hledger can work with compatible ledger
-journal files as well.
-It\[aq]s safe, and encouraged, to run both hledger and ledger on the
-same journal file, eg to validate the results you\[aq]re getting.
-.PP
-You can use hledger without learning any more about this file; just use
-the add or web or import commands to create and update it.
-.PP
-Many users, though, edit the journal file with a text editor, and track
-changes with a version control system such as git.
-Editor addons such as ledger-mode or hledger-mode for Emacs, vim-ledger
-for Vim, and hledger-vscode for Visual Studio Code, make this easier,
-adding colour, formatting, tab completion, and useful commands.
-See Editor configuration at hledger.org for the full list.
-.PP
-Here\[aq]s a description of each part of the file format (and
-hledger\[aq]s data model).
-These are mostly in the order you\[aq]ll use them, but in some cases
-related concepts have been grouped together for easy reference, or
-linked before they are introduced, so feel free to skip over anything
-that looks unnecessary right now.
-.SH TRANSACTIONS
-.PP
-Transactions are the main unit of information in a journal file.
-They represent events, typically a movement of some quantity of
-commodities between two or more named accounts.
-.PP
-Each transaction is recorded as a journal entry, beginning with a simple
-date in column 0.
-This can be followed by any of the following optional fields, separated
-by spaces:
-.IP \[bu] 2
-a status character (empty, \f[C]!\f[R], or \f[C]*\f[R])
-.IP \[bu] 2
-a code (any short number or text, enclosed in parentheses)
-.IP \[bu] 2
-a description (any remaining text until end of line or a semicolon)
-.IP \[bu] 2
-a comment (any remaining text following a semicolon until end of line,
-and any following indented lines beginning with a semicolon)
-.IP \[bu] 2
-0 or more indented \f[I]posting\f[R] lines, describing what was
-transferred and the accounts involved (indented comment lines are also
-allowed, but not blank lines or non-indented lines).
-.PP
-Here\[aq]s a simple journal file containing one transaction:
-.IP
-.nf
-\f[C]
-2008/01/01 income
- assets:bank:checking $1
- income:salary $-1
-\f[R]
-.fi
-.SH DATES
-.SS Simple dates
-.PP
-Dates in the journal file use \f[I]simple dates\f[R] format:
-\f[C]YYYY-MM-DD\f[R] or \f[C]YYYY/MM/DD\f[R] or \f[C]YYYY.MM.DD\f[R],
-with leading zeros optional.
-The year may be omitted, in which case it will be inferred from the
-context: the current transaction, the default year set with a default
-year directive, or the current date when the command is run.
-Some examples: \f[C]2010-01-31\f[R], \f[C]2010/01/31\f[R],
-\f[C]2010.1.31\f[R], \f[C]1/31\f[R].
-.PP
-(The UI also accepts simple dates, as well as the more flexible smart
-dates documented in the hledger manual.)
-.SS Secondary dates
-.PP
-Real-life transactions sometimes involve more than one date - eg the
-date you write a cheque, and the date it clears in your bank.
-When you want to model this, for more accurate daily balances, you can
-specify individual posting dates.
-.PP
-Or, you can use the older \f[I]secondary date\f[R] feature (Ledger calls
-it auxiliary date or effective date).
-Note: we support this for compatibility, but I usually recommend
-avoiding this feature; posting dates are almost always clearer and
-simpler.
-.PP
-A secondary date is written after the primary date, following an equals
-sign.
-If the year is omitted, the primary date\[aq]s year is assumed.
-When running reports, the primary (left) date is used by default, but
-with the \f[C]--date2\f[R] flag (or \f[C]--aux-date\f[R] or
-\f[C]--effective\f[R]), the secondary (right) date will be used instead.
-.PP
-The meaning of secondary dates is up to you, but it\[aq]s best to follow
-a consistent rule.
-Eg \[dq]primary = the bank\[aq]s clearing date, secondary = date the
-transaction was initiated, if different\[dq], as shown here:
-.IP
-.nf
-\f[C]
-2010/2/23=2/19 movie ticket
- expenses:cinema $10
- assets:checking
-\f[R]
-.fi
-.IP
-.nf
-\f[C]
-$ hledger register checking
-2010-02-23 movie ticket assets:checking $-10 $-10
-\f[R]
-.fi
-.IP
-.nf
-\f[C]
-$ hledger register checking --date2
-2010-02-19 movie ticket assets:checking $-10 $-10
-\f[R]
-.fi
-.SS Posting dates
-.PP
-You can give individual postings a different date from their parent
-transaction, by adding a posting comment containing a tag (see below)
-like \f[C]date:DATE\f[R].
-This is probably the best way to control posting dates precisely.
-Eg in this example the expense should appear in May reports, and the
-deduction from checking should be reported on 6/1 for easy bank
-reconciliation:
-.IP
-.nf
-\f[C]
-2015/5/30
- expenses:food $10 ; food purchased on saturday 5/30
- assets:checking ; bank cleared it on monday, date:6/1
-\f[R]
-.fi
-.IP
-.nf
-\f[C]
-$ hledger -f t.j register food
-2015-05-30 expenses:food $10 $10
-\f[R]
-.fi
-.IP
-.nf
-\f[C]
-$ hledger -f t.j register checking
-2015-06-01 assets:checking $-10 $-10
-\f[R]
-.fi
-.PP
-DATE should be a simple date; if the year is not specified it will use
-the year of the transaction\[aq]s date.
-You can set the secondary date similarly, with \f[C]date2:DATE2\f[R].
-The \f[C]date:\f[R] or \f[C]date2:\f[R] tags must have a valid simple
-date value if they are present, eg a \f[C]date:\f[R] tag with no value
-is not allowed.
-.PP
-Ledger\[aq]s earlier, more compact bracketed date syntax is also
-supported: \f[C][DATE]\f[R], \f[C][DATE=DATE2]\f[R] or
-\f[C][=DATE2]\f[R].
-hledger will attempt to parse any square-bracketed sequence of the
-\f[C]0123456789/-.=\f[R] characters in this way.
-With this syntax, DATE infers its year from the transaction and DATE2
-infers its year from DATE.
-.SH STATUS
-.PP
-Transactions, or individual postings within a transaction, 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:
-.PP
-.TS
-tab(@);
-l l.
-T{
-mark \
-T}@T{
-status
-T}
-_
-T{
-\
-T}@T{
-unmarked
-T}
-T{
-\f[C]!\f[R]
-T}@T{
-pending
-T}
-T{
-\f[C]*\f[R]
-T}@T{
-cleared
-T}
-.TE
-.PP
-When reporting, you can filter by status with the
-\f[C]-U/--unmarked\f[R], \f[C]-P/--pending\f[R], and
-\f[C]-C/--cleared\f[R] flags; or the \f[C]status:\f[R],
-\f[C]status:!\f[R], and \f[C]status:*\f[R] queries; or the U, P, C keys
-in hledger-ui.
-.PP
-Note, in Ledger and in older versions of hledger, the \[dq]unmarked\[dq]
-state is called \[dq]uncleared\[dq].
-As of hledger 1.3 we have renamed it to unmarked for clarity.
-.PP
-To replicate Ledger and old hledger\[aq]s behaviour of also matching
-pending, combine -U and -P.
-.PP
-Status marks are optional, but can be helpful eg for reconciling with
-real-world accounts.
-Some editor modes provide highlighting and shortcuts for working with
-status.
-Eg in Emacs ledger-mode, you can toggle transaction status with C-c C-e,
-or posting status with C-c C-c.
-.PP
-What \[dq]uncleared\[dq], \[dq]pending\[dq], and \[dq]cleared\[dq]
-actually mean is up to you.
-Here\[aq]s one suggestion:
-.PP
-.TS
-tab(@);
-lw(9.7n) lw(60.3n).
-T{
-status
-T}@T{
-meaning
-T}
-_
-T{
-uncleared
-T}@T{
-recorded but not yet reconciled; needs review
-T}
-T{
-pending
-T}@T{
-tentatively reconciled (if needed, eg during a big reconciliation)
-T}
-T{
-cleared
-T}@T{
-complete, reconciled as far as possible, and considered correct
-T}
-.TE
-.PP
-With this scheme, you would use \f[C]-PC\f[R] to see the current balance
-at your bank, \f[C]-U\f[R] to see things which will probably hit your
-bank soon (like uncashed checks), and no flags to see the most
-up-to-date state of your finances.
-.SH DESCRIPTION
-.PP
-A transaction\[aq]s description is the rest of the line following the
-date and status mark (or until a comment begins).
-Sometimes called the \[dq]narration\[dq] in traditional bookkeeping, it
-can be used for whatever you wish, or left blank.
-Transaction descriptions can be queried, unlike comments.
-.SS Payee and note
-.PP
-You can optionally include a \f[C]|\f[R] (pipe) character in
-descriptions to subdivide the description into separate fields for
-payee/payer name on the left (up to the first \f[C]|\f[R]) and an
-additional note field on the right (after the first \f[C]|\f[R]).
-This may be worthwhile if you need to do more precise querying and
-pivoting by payee or by note.
-.SH COMMENTS
-.PP
-Lines in the journal beginning with a semicolon (\f[C];\f[R]) or hash
-(\f[C]#\f[R]) or star (\f[C]*\f[R]) are comments, and will be ignored.
-(Star comments cause org-mode nodes to be ignored, allowing emacs users
-to fold and navigate their journals with org-mode or orgstruct-mode.)
-.PP
-You can attach comments to a transaction by writing them after the
-description and/or indented on the following lines (before the
-postings).
-Similarly, you can attach comments to an individual posting by writing
-them after the amount and/or indented on the following lines.
-Transaction and posting comments must begin with a semicolon
-(\f[C];\f[R]).
-.PP
-Some examples:
-.IP
-.nf
-\f[C]
-# a file comment
-; another file comment
-* also a file comment, useful in org/orgstruct mode
-
-comment
-A multiline file comment, which continues
-until a line containing just \[dq]end comment\[dq]
-(or end of file).
-end comment
-
-2012/5/14 something ; a transaction comment
- ; the transaction comment, continued
- posting1 1 ; a comment for posting 1
- posting2
- ; a comment for posting 2
- ; another comment line for posting 2
-; a file comment (because not indented)
-\f[R]
-.fi
-.PP
-You can also comment larger regions of a file using \f[C]comment\f[R]
-and \f[C]end comment\f[R] directives.
-.SH TAGS
-.PP
-Tags are a way to add extra labels or labelled data to postings and
-transactions, which you can then search or pivot on.
-.PP
-A simple tag is a word (which may contain hyphens) followed by a full
-colon, written inside a transaction or posting comment line:
-.IP
-.nf
-\f[C]
-2017/1/16 bought groceries ; sometag:
-\f[R]
-.fi
-.PP
-Tags can have a value, which is the text after the colon, up to the next
-comma or end of line, with leading/trailing whitespace removed:
-.IP
-.nf
-\f[C]
- expenses:food $10 ; a-posting-tag: the tag value
-\f[R]
-.fi
-.PP
-Note this means hledger\[aq]s tag values can not contain commas or
-newlines.
-Ending at commas means you can write multiple short tags on one line,
-comma separated:
-.IP
-.nf
-\f[C]
- assets:checking ; a comment containing tag1:, tag2: some value ...
-\f[R]
-.fi
-.PP
-Here,
-.IP \[bu] 2
-\[dq]\f[C]a comment containing\f[R]\[dq] is just comment text, not a tag
-.IP \[bu] 2
-\[dq]\f[C]tag1\f[R]\[dq] is a tag with no value
-.IP \[bu] 2
-\[dq]\f[C]tag2\f[R]\[dq] is another tag, whose value is
-\[dq]\f[C]some value ...\f[R]\[dq]
-.PP
-Tags in a transaction comment affect the transaction and all of its
-postings, while tags in a posting comment affect only that posting.
-For example, the following transaction has three tags (\f[C]A\f[R],
-\f[C]TAG2\f[R], \f[C]third-tag\f[R]) and the posting has four (those
-plus \f[C]posting-tag\f[R]):
-.IP
-.nf
-\f[C]
-1/1 a transaction ; A:, TAG2:
- ; third-tag: a third transaction tag, <- with a value
- (a) $1 ; posting-tag:
-\f[R]
-.fi
-.PP
-Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
-values are simple strings.
-.SH POSTINGS
-.PP
-A posting is an addition of some amount to, or removal of some amount
-from, an account.
-Each posting line begins with at least one space or tab (2 or 4 spaces
-is common), followed by:
-.IP \[bu] 2
-(optional) a status character (empty, \f[C]!\f[R], or \f[C]*\f[R]),
-followed by a space
-.IP \[bu] 2
-(required) an account name (any text, optionally containing \f[B]single
-spaces\f[R], until end of line or a double space)
-.IP \[bu] 2
-(optional) \f[B]two or more spaces\f[R] or tabs followed by an amount.
-.PP
-Positive amounts are being added to the account, negative amounts are
-being removed.
-.PP
-The amounts within a transaction must always sum up to zero.
-As a convenience, one amount may be left blank; it will be inferred so
-as to balance the transaction.
-.PP
-Be sure to note the unusual two-space delimiter between account name and
-amount.
-This makes it easy to write account names containing spaces.
-But if you accidentally leave only one space (or tab) before the amount,
-the amount will be considered part of the account name.
-.SS Virtual postings
-.PP
-A posting with a parenthesised account name is called a \f[I]virtual
-posting\f[R] or \f[I]unbalanced posting\f[R], which means it is exempt
-from the usual rule that a transaction\[aq]s postings must balance add
-up to zero.
-.PP
-This is not part of double entry accounting, so you might choose to
-avoid this feature.
-Or you can use it sparingly for certain special cases where it can be
-convenient.
-Eg, you could set opening balances without using a balancing equity
-account:
-.IP
-.nf
-\f[C]
-1/1 opening balances
- (assets:checking) $1000
- (assets:savings) $2000
-\f[R]
-.fi
-.PP
-A posting with a bracketed account name is called a \f[I]balanced
-virtual posting\f[R].
-The balanced virtual postings in a transaction must add up to zero
-(separately from other postings).
-Eg:
-.IP
-.nf
-\f[C]
-1/1 buy food with cash, update budget envelope subaccounts, & something else
- assets:cash $-10 ; <- these balance
- expenses:food $7 ; <-
- expenses:food $3 ; <-
- [assets:checking:budget:food] $-10 ; <- and these balance
- [assets:checking:available] $10 ; <-
- (something:else) $5 ; <- not required to balance
-\f[R]
-.fi
-.PP
-Ordinary non-parenthesised, non-bracketed postings are called \f[I]real
-postings\f[R].
-You can exclude virtual postings from reports with the
-\f[C]-R/--real\f[R] flag or \f[C]real:1\f[R] query.
-.SH ACCOUNT NAMES
-.PP
-Account names typically have several parts separated by a full colon,
-from which hledger derives a hierarchical chart of accounts.
-They can be anything you like, but in finance there are traditionally
-five top-level accounts: \f[C]assets\f[R], \f[C]liabilities\f[R],
-\f[C]income\f[R], \f[C]expenses\f[R], and \f[C]equity\f[R].
-.PP
-Account names may contain single spaces, eg:
-\f[C]assets:accounts receivable\f[R].
-Because of this, they must always be followed by \f[B]two or more
-spaces\f[R] (or newline).
-.PP
-Account names can be aliased.
-.SH AMOUNTS
-.PP
-After the account name, there is usually an amount.
-(Important: between account name and amount, there must be \f[B]two or
-more spaces\f[R].)
-.PP
-hledger\[aq]s amount format is flexible, supporting several
-international formats.
-Here are some examples.
-Amounts have a number (the \[dq]quantity\[dq]):
-.IP
-.nf
-\f[C]
-1
-\f[R]
-.fi
-.PP
-\&..and usually a currency or commodity name (the \[dq]commodity\[dq]).
-This is a symbol, word, or phrase, to the left or right of the quantity,
-with or without a separating space:
-.IP
-.nf
-\f[C]
-$1
-4000 AAPL
-\f[R]
-.fi
-.PP
-If the commodity name contains spaces, numbers, or punctuation, it must
-be enclosed in double quotes:
-.IP
-.nf
-\f[C]
-3 \[dq]no. 42 green apples\[dq]
-\f[R]
-.fi
-.PP
-Amounts can be preceded by a minus sign (or a plus sign, though plus is
-the default), The sign can be written before or after a left-side
-commodity symbol:
-.IP
-.nf
-\f[C]
--$1
-$-1
-\f[R]
-.fi
-.PP
-One or more spaces between the sign and the number are acceptable when
-parsing (but they won\[aq]t be displayed in output):
-.IP
-.nf
-\f[C]
-+ $1
-$- 1
-\f[R]
-.fi
-.PP
-Scientific E notation is allowed:
-.IP
-.nf
-\f[C]
-1E-6
-EUR 1E3
-\f[R]
-.fi
-.PP
-A decimal mark can be written as a period or a comma:
-.IP
-.nf
-\f[C]
-1.23
-1,23456780000009
-\f[R]
-.fi
-.SS Digit group marks
-.PP
-In the integer part of the quantity (left of the decimal mark), groups
-of digits can optionally be separated by a \[dq]digit group mark\[dq] -
-a space, comma, or period (different from the decimal mark):
-.IP
-.nf
-\f[C]
- $1,000,000.00
- EUR 2.000.000,00
-INR 9,99,99,999.00
- 1 000 000.9455
-\f[R]
-.fi
-.PP
-Note, a number containing a single group mark and no decimal mark is
-ambiguous.
-Are these group marks or decimal marks ?
-.IP
-.nf
-\f[C]
-1,000
-1.000
-\f[R]
-.fi
-.PP
-hledger will treat them both as decimal marks by default (cf #793).
-If you use digit group marks, to prevent confusion and undetected typos
-we recommend you write commodity directives at the top of the file to
-explicitly declare the decimal mark (and optionally a digit group mark).
-Note, these formats (\[dq]amount styles\[dq]) are specific to each
-commodity, so if your data uses multiple formats, hledger can handle it:
-.IP
-.nf
-\f[C]
-commodity $1,000.00
-commodity EUR 1.000,00
-commodity INR 9,99,99,999.00
-commodity 1 000 000.9455
-\f[R]
-.fi
-.PP
-.SS Commodity display style
-.PP
-For each commodity, hledger chooses a consistent style to use when
-displaying amounts.
-(Except price amounts, which are always displayed as written).
-The display style is chosen as follows:
-.IP \[bu] 2
-If there is a commodity directive (or default commodity directive) for
-the commodity, its style is used (see examples above).
-.IP \[bu] 2
-Otherwise the style is inferred from the amounts in that commodity seen
-in the journal.
-.IP \[bu] 2
-Or if there are no such amounts in the journal, a default style is used
-(like \f[C]$1000.00\f[R]).
-.PP
-A style is inferred from the journal amounts in a commodity as follows:
-.IP \[bu] 2
-Use the general style (decimal mark, symbol placement) of the first
-amount
-.IP \[bu] 2
-Use the first-seen digit group style (digit group mark, digit group
-sizes), if any
-.IP \[bu] 2
-Use the maximum number of decimal places of all.
-.PP
-Transaction price amounts don\[aq]t affect the commodity display style
-directly, but occasionally they can do so indirectly (eg when a
-posting\[aq]s amount is inferred using a transaction price).
-If you find this causing problems, use a commodity directive to fix the
-display style.
-.PP
-In summary, each commodity\[aq]s amounts will be normalised to
-.IP \[bu] 2
-the style declared by a \f[C]commodity\f[R] directive
-.IP \[bu] 2
-or, the style of the first posting amount in the journal, with the
-first-seen digit group style and the maximum-seen number of decimal
-places.
-.PP
-If reports are showing amounts in a way you don\[aq]t like (eg, with too
-many decimal places), use a commodity directive to set your preferred
-style.
-.SS Rounding
-.PP
-Amounts are stored internally as decimal numbers with up to 255 decimal
-places, and displayed with the number of decimal places specified by the
-commodity display style.
-Note, hledger uses banker\[aq]s rounding: it rounds to the nearest even
-number, eg 0.5 displayed with zero decimal places is \[dq]0\[dq]).
-(Guaranteed since hledger 1.17.1; in older versions this could vary if
-hledger was built with Decimal < 0.5.1.)
-.SH TRANSACTION PRICES
-.PP
-Within a transaction, you can note an amount\[aq]s price in another
-commodity.
-This can be used to document the cost (in a purchase) or selling price
-(in a sale).
-For example, transaction prices are useful to record purchases of a
-foreign currency.
-Note transaction prices are fixed at the time of the transaction, and do
-not change over time.
-See also market prices, which represent prevailing exchange rates on a
-certain date.
-.PP
-There are several ways to record a transaction price:
-.IP "1." 3
-Write the price per unit, as \f[C]\[at] UNITPRICE\f[R] after the amount:
-.RS 4
-.IP
-.nf
-\f[C]
-2009/1/1
- assets:euros \[Eu]100 \[at] $1.35 ; one hundred euros purchased at $1.35 each
- assets:dollars ; balancing amount is -$135.00
-\f[R]
-.fi
-.RE
-.IP "2." 3
-Write the total price, as \f[C]\[at]\[at] TOTALPRICE\f[R] after the
-amount:
-.RS 4
-.IP
-.nf
-\f[C]
-2009/1/1
- assets:euros \[Eu]100 \[at]\[at] $135 ; one hundred euros purchased at $135 for the lot
- assets:dollars
-\f[R]
-.fi
-.RE
-.IP "3." 3
-Specify amounts for all postings, using exactly two commodities, and let
-hledger infer the price that balances the transaction:
-.RS 4
-.IP
-.nf
-\f[C]
-2009/1/1
- assets:euros \[Eu]100 ; one hundred euros purchased
- assets:dollars $-135 ; for $135
-\f[R]
-.fi
-.RE
-.IP "4." 3
-Like 1, but the \f[C]\[at]\f[R] is parenthesised, i.e.
-\f[C](\[at])\f[R]; this is for compatibility with Ledger journals
-(Virtual posting costs), and is equivalent to 1 in hledger.
-.IP "5." 3
-Like 2, but as in 4 the \f[C]\[at]\[at]\f[R] is parenthesised, i.e.
-\f[C](\[at]\[at])\f[R]; in hledger, this is equivalent to 2.
-.PP
-Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction
-price\[aq]s commodity, if any.
-(mnemonic: \[dq]B\[dq] is from \[dq]cost Basis\[dq], as in Ledger).
-Eg here is how -B affects the balance report for the example above:
-.IP
-.nf
-\f[C]
-$ hledger bal -N --flat
- $-135 assets:dollars
- \[Eu]100 assets:euros
-$ hledger bal -N --flat -B
- $-135 assets:dollars
- $135 assets:euros # <- the euros\[aq] cost
-\f[R]
-.fi
-.PP
-Note -B is sensitive to the order of postings when a transaction price
-is inferred: the inferred price will be in the commodity of the last
-amount.
-So if example 3\[aq]s postings are reversed, while the transaction is
-equivalent, -B shows something different:
-.IP
-.nf
-\f[C]
-2009/1/1
- assets:dollars $-135 ; 135 dollars sold
- assets:euros \[Eu]100 ; for 100 euros
-\f[R]
-.fi
-.IP
-.nf
-\f[C]
-$ hledger bal -N --flat -B
- \[Eu]-100 assets:dollars # <- the dollars\[aq] selling price
- \[Eu]100 assets:euros
-\f[R]
-.fi
-.SH LOT PRICES, LOT DATES
-.PP
-Ledger allows another kind of price, lot price (four variants:
-\f[C]{UNITPRICE}\f[R], \f[C]{{TOTALPRICE}}\f[R],
-\f[C]{=FIXEDUNITPRICE}\f[R], \f[C]{{=FIXEDTOTALPRICE}}\f[R]), and/or a
-lot date (\f[C][DATE]\f[R]) to be specified.
-These are normally used to select a lot when selling investments.
-hledger will parse these, for compatibility with Ledger journals, but
-currently ignores them.
-A transaction price, lot price and/or lot date may appear in any order,
-after the posting amount and before the balance assertion if any.
-.SH BALANCE ASSERTIONS
-.PP
-hledger supports Ledger-style balance assertions in journal files.
-These look like, for example, \f[C]= EXPECTEDBALANCE\f[R] following a
-posting\[aq]s amount.
-Eg here we assert the expected dollar balance in accounts a and b after
-each posting:
-.IP
-.nf
-\f[C]
-2013/1/1
- a $1 =$1
- b =$-1
-
-2013/1/2
- a $1 =$2
- b $-1 =$-2
-\f[R]
-.fi
-.PP
-After reading a journal file, hledger will check all balance assertions
-and report an error if any of them fail.
-Balance assertions can protect you from, eg, inadvertently disrupting
-reconciled balances while cleaning up old entries.
-You can disable them temporarily with the
-\f[C]-I/--ignore-assertions\f[R] flag, which can be useful for
-troubleshooting or for reading Ledger files.
-(Note: this flag currently does not disable balance assignments, below).
-.SS Assertions and ordering
-.PP
-hledger sorts an account\[aq]s postings and assertions first by date and
-then (for postings on the same day) by parse order.
-Note this is different from Ledger, which sorts assertions only by parse
-order.
-(Also, Ledger assertions do not see the accumulated effect of repeated
-postings to the same account within a transaction.)
-.PP
-So, hledger balance assertions keep working if you reorder
-differently-dated transactions within the journal.
-But if you reorder same-dated transactions or postings, assertions might
-break and require updating.
-This order dependence does bring an advantage: precise control over the
-order of postings and assertions within a day, so you can assert
-intra-day balances.
-.SS Assertions and included files
-.PP
-With included files, things are a little more complicated.
-Including preserves the ordering of postings and assertions.
-If you have multiple postings to an account on the same day, split
-across different files, and you also want to assert the account\[aq]s
-balance on the same day, you\[aq]ll have to put the assertion in the
-right file.
-.SS Assertions and multiple -f options
-.PP
-Balance assertions don\[aq]t work well across files specified with
-multiple -f options.
-Use include or concatenate the files instead.
-.SS Assertions and commodities
-.PP
-The asserted balance must be a simple single-commodity amount, and in
-fact the assertion checks only this commodity\[aq]s balance within the
-(possibly multi-commodity) account balance.
-This is how assertions work in Ledger also.
-We could call this a \[dq]partial\[dq] balance assertion.
-.PP
-To assert the balance of more than one commodity in an account, you can
-write multiple postings, each asserting one commodity\[aq]s balance.
-.PP
-You can make a stronger \[dq]total\[dq] balance assertion by writing a
-double equals sign (\f[C]== EXPECTEDBALANCE\f[R]).
-This asserts that there are no other unasserted commodities in the
-account (or, that their balance is 0).
-.IP
-.nf
-\f[C]
-2013/1/1
- a $1
- a 1\[Eu]
- b $-1
- c -1\[Eu]
-
-2013/1/2 ; These assertions succeed
- a 0 = $1
- a 0 = 1\[Eu]
- b 0 == $-1
- c 0 == -1\[Eu]
-
-2013/1/3 ; This assertion fails as \[aq]a\[aq] also contains 1\[Eu]
- a 0 == $1
-\f[R]
-.fi
-.PP
-It\[aq]s not yet possible to make a complete assertion about a balance
-that has multiple commodities.
-One workaround is to isolate each commodity into its own subaccount:
-.IP
-.nf
-\f[C]
-2013/1/1
- a:usd $1
- a:euro 1\[Eu]
- b
-
-2013/1/2
- a 0 == 0
- a:usd 0 == $1
- a:euro 0 == 1\[Eu]
-\f[R]
-.fi
-.SS Assertions and prices
-.PP
-Balance assertions ignore transaction prices, and should normally be
-written without one:
-.IP
-.nf
-\f[C]
-2019/1/1
- (a) $1 \[at] \[Eu]1 = $1
-\f[R]
-.fi
-.PP
-We do allow prices to be written there, however, and print shows them,
-even though they don\[aq]t affect whether the assertion passes or fails.
-This is for backward compatibility (hledger\[aq]s close command used to
-generate balance assertions with prices), and because balance
-\f[I]assignments\f[R] do use them (see below).
-.SS Assertions and subaccounts
-.PP
-The balance assertions above (\f[C]=\f[R] and \f[C]==\f[R]) do not count
-the balance from subaccounts; they check the account\[aq]s exclusive
-balance only.
-You can assert the balance including subaccounts by writing \f[C]=*\f[R]
-or \f[C]==*\f[R], eg:
-.IP
-.nf
-\f[C]
-2019/1/1
- equity:opening balances
- checking:a 5
- checking:b 5
- checking 1 ==* 11
-\f[R]
-.fi
-.SS Assertions and virtual postings
-.PP
-Balance assertions are checked against all postings, both real and
-virtual.
-They are not affected by the \f[C]--real/-R\f[R] flag or \f[C]real:\f[R]
-query.
-.SS Assertions and precision
-.PP
-Balance assertions compare the exactly calculated amounts, which are not
-always what is shown by reports.
-Eg a commodity directive may limit the display precision, but this will
-not affect balance assertions.
-Balance assertion failure messages show exact amounts.
-.SH BALANCE ASSIGNMENTS
-.PP
-Ledger-style balance assignments are also supported.
-These are like balance assertions, but with no posting amount on the
-left side of the equals sign; instead it is calculated automatically so
-as to satisfy the assertion.
-This can be a convenience during data entry, eg when setting opening
-balances:
-.IP
-.nf
-\f[C]
-; starting a new journal, set asset account balances
-2016/1/1 opening balances
- assets:checking = $409.32
- assets:savings = $735.24
- assets:cash = $42
- equity:opening balances
-\f[R]
-.fi
-.PP
-or when adjusting a balance to reality:
-.IP
-.nf
-\f[C]
-; no cash left; update balance, record any untracked spending as a generic expense
-2016/1/15
- assets:cash = $0
- expenses:misc
-\f[R]
-.fi
-.PP
-The calculated amount depends on the account\[aq]s balance in the
-commodity at that point (which depends on the previously-dated postings
-of the commodity to that account since the last balance assertion or
-assignment).
-Note that using balance assignments makes your journal a little less
-explicit; to know the exact amount posted, you have to run hledger or do
-the calculations yourself, instead of just reading it.
-.SS Balance assignments and prices
-.PP
-A transaction price in a balance assignment will cause the calculated
-amount to have that price attached:
-.IP
-.nf
-\f[C]
-2019/1/1
- (a) = $1 \[at] \[Eu]2
-\f[R]
-.fi
-.IP
-.nf
-\f[C]
-$ hledger print --explicit
-2019-01-01
- (a) $1 \[at] \[Eu]2 = $1 \[at] \[Eu]2
-\f[R]
-.fi
-.SH 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).
-.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.
-Note part of this table is hidden when viewed in a web browser - scroll
-it sideways to see more.
-.PP
-.TS
-tab(@);
-lw(7.8n) lw(8.6n) lw(7.0n) lw(27.8n) lw(18.8n).
-T{
-directive
-T}@T{
-end directive
-T}@T{
-subdirectives
-T}@T{
-purpose
-T}@T{
-can affect (as of 2018/06)
-T}
-_
-T{
-\f[C]account\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
-T}
-T{
-\f[C]alias\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
-T}
-T{
-\f[C]apply account\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
-T}
-T{
-\f[C]comment\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
-T}
-T{
-\f[C]commodity\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 in that commodity in all files ;
-display style: amounts of that commodity in reports
-T}
-T{
-\f[C]D\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
-T}
-T{
-\f[C]include\f[R]
-T}@T{
-T}@T{
-T}@T{
-include entries/directives from another file
-T}@T{
-what the included directives affect
-T}
-T{
-\f[C]P\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
-T}
-T{
-\f[C]Y\f[R]
-T}@T{
-T}@T{
-T}@T{
-declare a year for yearless dates
-T}@T{
-following entries until end of current file
-T}
-T{
-\f[C]=\f[R]
-T}@T{
-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)
-T}
-.TE
-.PP
-And some definitions:
-.PP
-.TS
-tab(@);
-lw(6.0n) lw(64.0n).
-T{
-subdirective
-T}@T{
-optional indented directive line immediately following a parent
-directive
-T}
-T{
-number notation
-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.)
-T}
-T{
-display style
-T}@T{
-how to display amounts of a commodity in reports (symbol side and
-spacing, digit groups, decimal separator, decimal places)
-T}
-T{
-directive scope
-T}@T{
-which entries and (when there are multiple files) which files are
-affected by a directive
-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.
-.PP
-This may seem inconvenient, but it\[aq]s intentional; it makes reports
-stable and deterministic, independent of the order of input.
-Otherwise you could see different numbers if you happened to write -f
-options in a different order, or if you moved includes around while
-cleaning up your files.
-.PP
-It can be surprising though; for example, it means that \f[C]alias\f[R]
-directives do not affect parent or sibling files (see below).
-.SS Comment blocks
-.PP
-A line containing just \f[C]comment\f[R] starts a commented region of
-the file, and a line containing just \f[C]end comment\f[R] (or the end
-of the current file) ends it.
-See also comments.
-.SS Including other files
-.PP
-You can pull in the content of additional files by writing an include
-directive, like this:
-.IP
-.nf
-\f[C]
-include FILEPATH
-\f[R]
-.fi
-.PP
-Only journal files can include, and only journal, timeclock or timedot
-files can be included (not CSV files, currently).
-.PP
-If the file path does not begin with a slash, it is relative to the
-current file\[aq]s folder.
-.PP
-A tilde means home directory, eg: \f[C]include \[ti]/main.journal\f[R].
-.PP
-The path may contain glob patterns to match multiple files, eg:
-\f[C]include *.journal\f[R].
-.PP
-There is limited support for recursive wildcards: \f[C]**/\f[R] (the
-slash is required) matches 0 or more subdirectories.
-It\[aq]s not super convenient since you have to avoid include cycles and
-including directories, but this can be done, eg:
-\f[C]include */**/*.journal\f[R].
-.PP
-The path may also be prefixed to force a specific file format,
-overriding the file extension (as described in hledger.1 -> Input
-files): \f[C]include timedot:\[ti]/notes/2020*.md\f[R].
-.SS Default year
-.PP
-You can set a default year to be used for subsequent dates which
-don\[aq]t specify a year.
-This is a line beginning with \f[C]Y\f[R] followed by the year.
-Eg:
-.IP
-.nf
-\f[C]
-Y2009 ; set default year to 2009
-
-12/15 ; equivalent to 2009/12/15
- expenses 1
- assets
-
-Y2010 ; change default year to 2010
-
-2009/1/30 ; specifies the year, not affected
- expenses 1
- assets
-
-1/31 ; equivalent to 2010/1/31
- expenses 1
- assets
-\f[R]
-.fi
-.SS Declaring commodities
-.PP
-The \f[C]commodity\f[R] directive has several functions:
-.IP "1." 3
-It declares commodities which may be used in the journal.
-This is currently not enforced, but can serve as documentation.
-.IP "2." 3
-It declares what decimal mark character (period or comma) to expect when
-parsing input - useful to disambiguate international number formats in
-your data.
-(Without this, hledger will parse both \f[C]1,000\f[R] and
-\f[C]1.000\f[R] as 1).
-.IP "3." 3
-It declares a commodity\[aq]s display style in output - decimal and
-digit group marks, number of decimal places, symbol placement etc.
-.PP
-You are likely to run into one of the problems solved by commodity
-directives, sooner or later, so it\[aq]s a good idea to just always use
-them to declare your commodities.
-.PP
-A commodity directive is just the word \f[C]commodity\f[R] followed by
-an amount.
-It may be written on a single line, like this:
-.IP
-.nf
-\f[C]
-; commodity EXAMPLEAMOUNT
-
-; display AAAA amounts with the symbol on the right, space-separated,
-; using period as decimal point, with four decimal places, and
-; separating thousands with comma.
-commodity 1,000.0000 AAAA
-\f[R]
-.fi
-.PP
-or on multiple lines, using the \[dq]format\[dq] subdirective.
-(In this case the commodity symbol appears twice and should be the same
-in both places.):
-.IP
-.nf
-\f[C]
-; commodity SYMBOL
-; format EXAMPLEAMOUNT
-
-; display indian rupees with currency name on the left,
-; thousands, lakhs and crores comma-separated,
-; period as decimal point, and two decimal places.
-commodity INR
- format INR 1,00,00,000.00
-\f[R]
-.fi
-.PP
-The quantity of the amount does not matter; only the format is
-significant.
-The number must include a decimal mark: either a period or a comma,
-followed by 0 or more decimal digits.
-.PP
-Note hledger normally uses banker\[aq]s rounding, so 0.5 displayed with
-zero decimal digits is \[dq]0\[dq].
-(More at Commodity display style.)
-.SS Commodity error checking
-.PP
-In strict mode, enabled with the \f[C]-s\f[R]/\f[C]--strict\f[R] flag,
-hledger will report an error if a commodity symbol is used that has not
-been declared by a \f[C]commodity\f[R] directive.
-This works similarly to account error checking, see the notes there for
-more details.
-.SS Default commodity
-.PP
-The \f[C]D\f[R] directive sets a default commodity, to be used for
-amounts without a commodity symbol (ie, plain numbers).
-This commodity will be applied to all subsequent commodity-less amounts,
-or until the next \f[C]D\f[R] directive.
-(Note, this is different from Ledger\[aq]s \f[C]D\f[R].)
-.PP
-For compatibility/historical reasons, \f[C]D\f[R] also acts like a
-\f[C]commodity\f[R] directive, setting the commodity\[aq]s display style
-(for output) and decimal mark (for parsing input).
-As with \f[C]commodity\f[R], the amount must always be written with a
-decimal mark (period or comma).
-If both directives are used, \f[C]commodity\f[R]\[aq]s style takes
-precedence.
-.PP
-The syntax is \f[C]D AMOUNT\f[R].
-Eg:
-.IP
-.nf
-\f[C]
-; commodity-less amounts should be treated as dollars
-; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
-D $1,000.00
-
-1/1
- a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
- b
-\f[R]
-.fi
-.SS Declaring market prices
-.PP
-The \f[C]P\f[R] directive declares a market price, which is an exchange
-rate between two commodities on a certain date.
-(In Ledger, they are called \[dq]historical prices\[dq].) These are
-often obtained from a stock exchange, cryptocurrency exchange, or the
-foreign exchange market.
-.PP
-Here is the format:
-.IP
-.nf
-\f[C]
-P DATE COMMODITYA COMMODITYBAMOUNT
-\f[R]
-.fi
-.IP \[bu] 2
-DATE is a simple date
-.IP \[bu] 2
-COMMODITYA is the symbol of the commodity being priced
-.IP \[bu] 2
-COMMODITYBAMOUNT is an amount (symbol and quantity) in a second
-commodity, giving the price in commodity B of one unit of commodity A.
-.PP
-These two market price directives say that one euro was worth 1.35 US
-dollars during 2009, and $1.40 from 2010 onward:
-.IP
-.nf
-\f[C]
-P 2009/1/1 \[Eu] $1.35
-P 2010/1/1 \[Eu] $1.40
-\f[R]
-.fi
-.PP
-The \f[C]-V\f[R], \f[C]-X\f[R] and \f[C]--value\f[R] flags use these
-market prices to show amount values in another commodity.
-See Valuation.
-.SS Declaring accounts
-.PP
-\f[C]account\f[R] directives can be used to declare accounts (ie, the
-places that amounts are transferred from and to).
-Though not required, these declarations can provide several benefits:
-.IP \[bu] 2
-They can document your intended chart of accounts, providing a
-reference.
-.IP \[bu] 2
-They can help hledger know your accounts\[aq] types (asset, liability,
-equity, revenue, expense), useful for reports like balancesheet and
-incomestatement.
-.IP \[bu] 2
-They control account display order in reports, allowing non-alphabetic
-sorting (eg Revenues to appear above Expenses).
-.IP \[bu] 2
-They can store extra information about accounts (account numbers, notes,
-etc.)
-.IP \[bu] 2
-They help with account name completion in the add command, hledger-iadd,
-hledger-web, ledger-mode etc.
-.IP \[bu] 2
-In strict mode, they restrict which accounts may be posted to by
-transactions, which helps detect typos.
-.PP
-The simplest form is just the word \f[C]account\f[R] followed by a
-hledger-style account name, eg this account directive declares the
-\f[C]assets:bank:checking\f[R] account:
-.IP
-.nf
-\f[C]
-account assets:bank:checking
-\f[R]
-.fi
-.SS Account error checking
-.PP
-By default, accounts come into existence when a transaction references
-them by name.
-This is convenient, but it means hledger can\[aq]t warn you when you
-mis-spell an account name in the journal.
-Usually you\[aq]ll find the error later, as an extra account in balance
-reports, or an incorrect balance when reconciling.
-.PP
-In strict mode, enabled with the \f[C]-s\f[R]/\f[C]--strict\f[R] flag,
-hledger will report an error if any transaction uses an account name
-that has not been declared by an account directive.
-Some notes:
-.IP \[bu] 2
-The declaration is case-sensitive; transactions must use the correct
-account name capitalisation.
-.IP \[bu] 2
-The account directive\[aq]s scope is \[dq]whole file and below\[dq] (see
-directives).
-This means it affects all of the current file, and any files it
-includes, but not parent or sibling files.
-The position of account directives within the file does not matter,
-though it\[aq]s usual to put them at the top.
-.IP \[bu] 2
-Accounts can only be declared in \f[C]journal\f[R] files (but will
-affect included files in other formats).
-.IP \[bu] 2
-It\[aq]s currently not possible to declare \[dq]all possible
-subaccounts\[dq] with a wildcard; every account posted to must be
-declared.
-.SS Account comments
-.PP
-Comments, beginning with a semicolon, can be added:
-.IP \[bu] 2
-on the same line, \f[B]after two or more spaces\f[R] (because ; is
-allowed in account names)
-.IP \[bu] 2
-on the next lines, indented
-.PP
-An example of both:
-.IP
-.nf
-\f[C]
-account assets:bank:checking ; same-line comment, note 2+ spaces before ;
- ; next-line comment
- ; another with tag, acctno:12345 (not used yet)
-\f[R]
-.fi
-.PP
-Same-line comments are not supported by Ledger, or hledger <1.13.
-.SS Account subdirectives
-.PP
-We also allow (and ignore) Ledger-style indented subdirectives, just for
-compatibility.:
-.IP
-.nf
-\f[C]
-account assets:bank:checking
- format blah blah ; <- subdirective, ignored
-\f[R]
-.fi
-.PP
-Here is the full syntax of account directives:
-.IP
-.nf
-\f[C]
-account ACCTNAME [ACCTTYPE] [;COMMENT]
- [;COMMENTS]
- [LEDGER-STYLE SUBDIRECTIVES, IGNORED]
-\f[R]
-.fi
-.SS Account types
-.PP
-hledger recognises five main types of account, corresponding to the
-account classes in the accounting equation:
-.PP
-\f[C]Asset\f[R], \f[C]Liability\f[R], \f[C]Equity\f[R],
-\f[C]Revenue\f[R], \f[C]Expense\f[R].
-.PP
-These account types are important for controlling which accounts appear
-in the balancesheet, balancesheetequity, incomestatement reports (and
-probably for other things in future).
-.PP
-Additionally, we recognise the \f[C]Cash\f[R] type, which is also an
-\f[C]Asset\f[R], and which causes accounts to appear in the cashflow
-report.
-(\[dq]Cash\[dq] here means liquid assets, eg bank balances but typically
-not investments or receivables.)
-.SS Declaring account types
-.PP
-Generally, to make these reports work you should declare your top-level
-accounts and their types, using account directives with \f[C]type:\f[R]
-tags.
-.PP
-The tag\[aq]s value should be one of: \f[C]Asset\f[R],
-\f[C]Liability\f[R], \f[C]Equity\f[R], \f[C]Revenue\f[R],
-\f[C]Expense\f[R], \f[C]Cash\f[R], \f[C]A\f[R], \f[C]L\f[R],
-\f[C]E\f[R], \f[C]R\f[R], \f[C]X\f[R], \f[C]C\f[R] (all case
-insensitive).
-The type is inherited by all subaccounts except where they override it.
-Here\[aq]s a complete example:
-.IP
-.nf
-\f[C]
-account assets ; type: Asset
-account assets:bank ; type: Cash
-account assets:cash ; type: Cash
-account liabilities ; type: Liability
-account equity ; type: Equity
-account revenues ; type: Revenue
-account expenses ; type: Expense
-\f[R]
-.fi
-.SS Auto-detected account types
-.PP
-If you happen to use common english top-level account names, you may not
-need to declare account types, as they will be detected automatically
-using the following rules:
-.PP
-.TS
-tab(@);
-l l.
-T{
-If name matches regular expression:
-T}@T{
-account type is:
-T}
-_
-T{
-\f[C]\[ha]assets?(:|$)\f[R]
-T}@T{
-\f[C]Asset\f[R]
-T}
-T{
-\f[C]\[ha](debts?|liabilit(y|ies))(:|$)\f[R]
-T}@T{
-\f[C]Liability\f[R]
-T}
-T{
-\f[C]\[ha]equity(:|$)\f[R]
-T}@T{
-\f[C]Equity\f[R]
-T}
-T{
-\f[C]\[ha](income|revenue)s?(:|$)\f[R]
-T}@T{
-\f[C]Revenue\f[R]
-T}
-T{
-\f[C]\[ha]expenses?(:|$)\f[R]
-T}@T{
-\f[C]Expense\f[R]
-T}
-.TE
-.PP
-.TS
-tab(@);
-lw(56.9n) lw(13.1n).
-T{
-If account type is \f[C]Asset\f[R] and name does not contain regular
-expression:
-T}@T{
-account type is:
-T}
-_
-T{
-\f[C](investment|receivable|:A/R|:fixed)\f[R]
-T}@T{
-\f[C]Cash\f[R]
-T}
-.TE
-.PP
-Even so, explicit declarations may be a good idea, for clarity and
-predictability.
-.SS Interference from auto-detected account types
-.PP
-If you assign any account type, it\[aq]s a good idea to assign all of
-them, to prevent any confusion from mixing declared and auto-detected
-types.
-Although it\[aq]s unlikely to happen in real life, here\[aq]s an
-example: with the following journal, \f[C]balancesheetequity\f[R] shows
-\[dq]liabilities\[dq] in both Liabilities and Equity sections.
-Declaring another account as \f[C]type:Liability\f[R] would fix it:
-.IP
-.nf
-\f[C]
-account liabilities ; type:Equity
-
-2020-01-01
- assets 1
- liabilities 1
- equity -2
-\f[R]
-.fi
-.SS Old account type syntax
-.PP
-In some hledger journals you might instead see this old syntax (the
-letters ALERX, separated from the account name by two or more spaces);
-this is deprecated and may be removed soon:
-.IP
-.nf
-\f[C]
-account assets A
-account liabilities L
-account equity E
-account revenues R
-account expenses X
-\f[R]
-.fi
-.SS Account display order
-.PP
-Account directives also set the order in which accounts are displayed,
-eg in reports, the hledger-ui accounts screen, and the hledger-web
-sidebar.
-By default accounts are listed in alphabetical order.
-But if you have these account directives in the journal:
-.IP
-.nf
-\f[C]
-account assets
-account liabilities
-account equity
-account revenues
-account expenses
-\f[R]
-.fi
-.PP
-you\[aq]ll see those accounts displayed in declaration order, not
-alphabetically:
-.IP
-.nf
-\f[C]
-$ hledger accounts -1
-assets
-liabilities
-equity
-revenues
-expenses
-\f[R]
-.fi
-.PP
-Undeclared accounts, if any, are displayed last, in alphabetical order.
-.PP
-Note that sorting is done at each level of the account tree (within each
-group of sibling accounts under the same parent).
-And currently, this directive:
-.IP
-.nf
-\f[C]
-account other:zoo
-\f[R]
-.fi
-.PP
-would influence the position of \f[C]zoo\f[R] among
-\f[C]other\f[R]\[aq]s subaccounts, but not the position of
-\f[C]other\f[R] among the top-level accounts.
-This means:
-.IP \[bu] 2
-you will sometimes declare parent accounts (eg \f[C]account other\f[R]
-above) that you don\[aq]t intend to post to, just to customize their
-display order
-.IP \[bu] 2
-sibling accounts stay together (you couldn\[aq]t display \f[C]x:y\f[R]
-in between \f[C]a:b\f[R] and \f[C]a:c\f[R]).
-.SS Rewriting accounts
-.PP
-You can define account alias rules which rewrite your account names, or
-parts of them, before generating reports.
-This can be useful for:
-.IP \[bu] 2
-expanding shorthand account names to their full form, allowing easier
-data entry and a less verbose journal
-.IP \[bu] 2
-adapting old journals to your current chart of accounts
-.IP \[bu] 2
-experimenting with new account organisations, like a new hierarchy or
-combining two accounts into one
-.IP \[bu] 2
-customising reports
-.PP
-Account aliases also rewrite account names in account directives.
-They do not affect account names being entered via hledger add or
-hledger-web.
-.PP
-See also Rewrite account names.
-.SS Basic aliases
-.PP
-To set an account alias, use the \f[C]alias\f[R] directive in your
-journal file.
-This affects all subsequent journal entries in the current file or its
-included files.
-The spaces around the = are optional:
-.IP
-.nf
-\f[C]
-alias OLD = NEW
-\f[R]
-.fi
-.PP
-Or, you can use the \f[C]--alias \[aq]OLD=NEW\[aq]\f[R] option on the
-command line.
-This affects all entries.
-It\[aq]s useful for trying out aliases interactively.
-.PP
-OLD and NEW are case sensitive full account names.
-hledger will replace any occurrence of the old account name with the new
-one.
-Subaccounts are also affected.
-Eg:
-.IP
-.nf
-\f[C]
-alias checking = assets:bank:wells fargo:checking
-; rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq]
-\f[R]
-.fi
-.SS Regex aliases
-.PP
-There is also a more powerful variant that uses a regular expression,
-indicated by the forward slashes:
-.IP
-.nf
-\f[C]
-alias /REGEX/ = REPLACEMENT
-\f[R]
-.fi
-.PP
-or \f[C]--alias \[aq]/REGEX/=REPLACEMENT\[aq]\f[R].
-.PP
-REGEX is a case-insensitive regular expression.
-Anywhere it matches inside an account name, the matched part will be
-replaced by REPLACEMENT.
-If REGEX contains parenthesised match groups, these can be referenced by
-the usual numeric backreferences in REPLACEMENT.
-Eg:
-.IP
-.nf
-\f[C]
-alias /\[ha](.+):bank:([\[ha]:]+):(.*)/ = \[rs]1:\[rs]2 \[rs]3
-; rewrites \[dq]assets:bank:wells fargo:checking\[dq] to \[dq]assets:wells fargo checking\[dq]
-\f[R]
-.fi
-.PP
-Also note that REPLACEMENT continues to the end of line (or on command
-line, to end of option argument), so it can contain trailing whitespace.
-.SS Combining aliases
-.PP
-You can define as many aliases as you like, using journal directives
-and/or command line options.
-.PP
-Recursive aliases - where an account name is rewritten by one alias,
-then by another alias, and so on - are allowed.
-Each alias sees the effect of previously applied aliases.
-.PP
-In such cases it can be important to understand which aliases will be
-applied and in which order.
-For (each account name in) each journal entry, we apply:
-.IP "1." 3
-\f[C]alias\f[R] directives preceding the journal entry, most recently
-parsed first (ie, reading upward from the journal entry, bottom to top)
-.IP "2." 3
-\f[C]--alias\f[R] options, in the order they appeared on the command
-line (left to right).
-.PP
-In other words, for (an account name in) a given journal entry:
-.IP \[bu] 2
-the nearest alias declaration before/above the entry is applied first
-.IP \[bu] 2
-the next alias before/above that will be be applied next, and so on
-.IP \[bu] 2
-aliases defined after/below the entry do not affect it.
-.PP
-This gives nearby aliases precedence over distant ones, and helps
-provide semantic stability - aliases will keep working the same way
-independent of which files are being read and in which order.
-.PP
-In case of trouble, adding \f[C]--debug=6\f[R] to the command line will
-show which aliases are being applied when.
-.SS Aliases and multiple files
-.PP
-As explained at Directives and multiple files, \f[C]alias\f[R]
-directives do not affect parent or sibling files.
-Eg in this command,
-.IP
-.nf
-\f[C]
-hledger -f a.aliases -f b.journal
-\f[R]
-.fi
-.PP
-account aliases defined in a.aliases will not affect b.journal.
-Including the aliases doesn\[aq]t work either:
-.IP
-.nf
-\f[C]
-include a.aliases
-
-2020-01-01 ; not affected by a.aliases
- foo 1
- bar
-\f[R]
-.fi
-.PP
-This means that account aliases should usually be declared at the start
-of your top-most file, like this:
-.IP
-.nf
-\f[C]
-alias foo=Foo
-alias bar=Bar
-
-2020-01-01 ; affected by aliases above
- foo 1
- bar
-
-include c.journal ; also affected
-\f[R]
-.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:
-.IP
-.nf
-\f[C]
-end aliases
-\f[R]
-.fi
-.SS Default parent account
-.PP
-You can specify a parent account which will be prepended to all accounts
-within a section of the journal.
-Use the \f[C]apply account\f[R] and \f[C]end apply account\f[R]
-directives like so:
-.IP
-.nf
-\f[C]
-apply account home
-
-2010/1/1
- food $10
- cash
-
-end apply account
-\f[R]
-.fi
-.PP
-which is equivalent to:
-.IP
-.nf
-\f[C]
-2010/01/01
- home:food $10
- home:cash $-10
-\f[R]
-.fi
-.PP
-If \f[C]end apply account\f[R] is omitted, the effect lasts to the end
-of the file.
-Included files are also affected, eg:
-.IP
-.nf
-\f[C]
-apply account business
-include biz.journal
-end apply account
-apply account personal
-include personal.journal
-\f[R]
-.fi
-.PP
-Prior to hledger 1.0, legacy \f[C]account\f[R] and \f[C]end\f[R]
-spellings were also supported.
-.PP
-A default parent account also affects account directives.
-It does not affect account names being entered via hledger add or
-hledger-web.
-If account aliases are present, they are applied after the default
-parent account.
-.SH PERIODIC TRANSACTIONS
-.PP
-Periodic transaction rules describe transactions that recur.
-They allow hledger to generate temporary future transactions to help
-with forecasting, so you don\[aq]t have to write out each one in the
-journal, and it\[aq]s easy to try out different forecasts.
-.PP
-Periodic transactions can be a little tricky, so before you use them,
-read this whole section - or at least these tips:
-.IP "1." 3
-Two spaces accidentally added or omitted will cause you trouble - read
-about this below.
-.IP "2." 3
-For troubleshooting, show the generated transactions with
-\f[C]hledger print --forecast tag:generated\f[R] or
-\f[C]hledger register --forecast tag:generated\f[R].
-.IP "3." 3
-Forecasted transactions will begin only after the last non-forecasted
-transaction\[aq]s date.
-.IP "4." 3
-Forecasted transactions will end 6 months from today, by default.
-See below for the exact start/end rules.
-.IP "5." 3
-period expressions can be tricky.
-Their documentation needs improvement, but is worth studying.
-.IP "6." 3
-Some period expressions with a repeating interval must begin on a
-natural boundary of that interval.
-Eg in \f[C]weekly from DATE\f[R], DATE must be a monday.
-\f[C]\[ti] weekly from 2019/10/1\f[R] (a tuesday) will give an error.
-.IP "7." 3
-Other period expressions with an interval are automatically expanded to
-cover a whole number of that interval.
-(This is done to improve reports, but it also affects periodic
-transactions.
-Yes, it\[aq]s a bit inconsistent with the above.) Eg:
-\f[C]\[ti] every 10th day of month from 2020/01\f[R], which is
-equivalent to \f[C]\[ti] every 10th day of month from 2020/01/01\f[R],
-will be adjusted to start on 2019/12/10.
-.PP
-Periodic transaction rules also have a second meaning: they are used to
-define budget goals, shown in budget reports.
-.SS Periodic rule syntax
-.PP
-A periodic transaction rule looks like a normal journal entry, with the
-date replaced by a tilde (\f[C]\[ti]\f[R]) followed by a period
-expression (mnemonic: \f[C]\[ti]\f[R] looks like a recurring sine
-wave.):
-.IP
-.nf
-\f[C]
-\[ti] monthly
- expenses:rent $2000
- assets:bank:checking
-\f[R]
-.fi
-.PP
-There is an additional constraint on the period expression: the start
-date must fall on a natural boundary of the interval.
-Eg \f[C]monthly from 2018/1/1\f[R] is valid, but
-\f[C]monthly from 2018/1/15\f[R] is not.
-.PP
-Partial or relative dates (M/D, D, tomorrow, last week) in the period
-expression can work (useful or not).
-They will be relative to today\[aq]s date, unless a Y default year
-directive is in effect, in which case they will be relative to Y/1/1.
-.SS Two spaces between period expression and description!
-.PP
-If the period expression is followed by a transaction description, these
-must be separated by \f[B]two or more spaces\f[R].
-This helps hledger know where the period expression ends, so that
-descriptions can not accidentally alter their meaning, as in this
-example:
-.IP
-.nf
-\f[C]
-; 2 or more spaces needed here, so the period is not understood as \[dq]every 2 months in 2020\[dq]
-; ||
-; vv
-\[ti] every 2 months in 2020, we will review
- assets:bank:checking $1500
- income:acme inc
-\f[R]
-.fi
-.PP
-So,
-.IP \[bu] 2
-Do write two spaces between your period expression and your transaction
-description, if any.
-.IP \[bu] 2
-Don\[aq]t accidentally write two spaces in the middle of your period
-expression.
-.SS Forecasting with periodic transactions
-.PP
-The \f[C]--forecast\f[R] flag activates any periodic transaction rules
-in the journal.
-They will generate temporary recurring transactions, which are not saved
-in the journal, but will appear in all reports (eg print).
-This can be useful for estimating balances into the future, or
-experimenting with different scenarios.
-Or, it can be used as a data entry aid: describe recurring transactions,
-and every so often copy the output of \f[C]print --forecast\f[R] into
-the journal.
-.PP
-These transactions will have an extra tag indicating which periodic rule
-generated them: \f[C]generated-transaction:\[ti] PERIODICEXPR\f[R].
-And a similar, hidden tag (beginning with an underscore) which, because
-it\[aq]s never displayed by print, can be used to match transactions
-generated \[dq]just now\[dq]:
-\f[C]_generated-transaction:\[ti] PERIODICEXPR\f[R].
-.PP
-Periodic transactions are generated within some forecast period.
-By default, this
-.IP \[bu] 2
-begins on the later of
-.RS 2
-.IP \[bu] 2
-the report start date if specified with -b/-p/date:
-.IP \[bu] 2
-the day after the latest normal (non-periodic) transaction in the
-journal, or today if there are no normal transactions.
-.RE
-.IP \[bu] 2
-ends on the report end date if specified with -e/-p/date:, or 6 months
-(180 days) from today.
-.PP
-This means that periodic transactions will begin only after the latest
-recorded transaction.
-And a recorded transaction dated in the future can prevent generation of
-periodic transactions.
-(You can avoid that by writing the future transaction as a one-time
-periodic rule instead - put tilde before the date, eg
-\f[C]\[ti] YYYY-MM-DD ...\f[R]).
-.PP
-Or, you can set your own arbitrary \[dq]forecast period\[dq], which can
-overlap recorded transactions, and need not be in the future, by
-providing an option argument, like \f[C]--forecast=PERIODEXPR\f[R].
-Note the equals sign is required, a space won\[aq]t work.
-PERIODEXPR is a period expression, which can specify the start date, end
-date, or both, like in a \f[C]date:\f[R] query.
-(See also hledger.1 -> Report start & end date).
-Some examples: \f[C]--forecast=202001-202004\f[R],
-\f[C]--forecast=jan-\f[R], \f[C]--forecast=2020\f[R].
-.SS Budgeting with periodic transactions
-.PP
-With the \f[C]--budget\f[R] flag, currently supported by the balance
-command, each periodic transaction rule declares recurring budget goals
-for the specified accounts.
-Eg the first example above declares a goal of spending $2000 on rent
-(and also, a goal of depositing $2000 into checking) every month.
-Goals and actual performance can then be compared in budget reports.
-.PP
-See also: Budgeting and Forecasting.
-.PP
-.SH AUTO POSTINGS
-.PP
-\[dq]Automated postings\[dq] or \[dq]auto postings\[dq] are extra
-postings which get added automatically to transactions which match
-certain queries, defined by \[dq]auto posting rules\[dq], when you use
-the \f[C]--auto\f[R] flag.
-.PP
-An auto posting rule looks a bit like a transaction:
-.IP
-.nf
-\f[C]
-= QUERY
- ACCOUNT AMOUNT
- ...
- ACCOUNT [AMOUNT]
-\f[R]
-.fi
-.PP
-except the first line is an equals sign (mnemonic: \f[C]=\f[R] suggests
-matching), followed by a query (which matches existing postings), and
-each \[dq]posting\[dq] line describes a posting to be generated, and the
-posting amounts can be:
-.IP \[bu] 2
-a normal amount with a commodity symbol, eg \f[C]$2\f[R].
-This will be used as-is.
-.IP \[bu] 2
-a number, eg \f[C]2\f[R].
-The commodity symbol (if any) from the matched posting will be added to
-this.
-.IP \[bu] 2
-a numeric multiplier, eg \f[C]*2\f[R] (a star followed by a number N).
-The matched posting\[aq]s amount (and total price, if any) will be
-multiplied by N.
-.IP \[bu] 2
-a multiplier with a commodity symbol, eg \f[C]*$2\f[R] (a star, number
-N, and symbol S).
-The matched posting\[aq]s amount will be multiplied by N, and its
-commodity symbol will be replaced with S.
-.PP
-Any query term containing spaces must be enclosed in single or double
-quotes, as on the command line.
-Eg, note the quotes around the second query term below:
-.IP
-.nf
-\f[C]
-= expenses:groceries \[aq]expenses:dining out\[aq]
- (budget:funds:dining out) *-1
-\f[R]
-.fi
-.PP
-Some examples:
-.IP
-.nf
-\f[C]
-; every time I buy food, schedule a dollar donation
-= expenses:food
- (liabilities:charity) $-1
-
-; when I buy a gift, also deduct that amount from a budget envelope subaccount
-= expenses:gifts
- assets:checking:gifts *-1
- assets:checking *1
-
-2017/12/1
- expenses:food $10
- assets:checking
-
-2017/12/14
- expenses:gifts $20
- assets:checking
-\f[R]
-.fi
-.IP
-.nf
-\f[C]
-$ hledger print --auto
-2017-12-01
- expenses:food $10
- assets:checking
- (liabilities:charity) $-1
-
-2017-12-14
- expenses:gifts $20
- assets:checking
- assets:checking:gifts -$20
- assets:checking $20
-\f[R]
-.fi
-.SS Auto postings and multiple files
-.PP
-An auto posting rule can affect any transaction in the current file, or
-in any parent file or child file.
-Note, currently it will not affect sibling files (when multiple
-\f[C]-f\f[R]/\f[C]--file\f[R] are used - see #1212).
-.SS Auto postings and dates
-.PP
-A posting date (or secondary date) in the matched posting, or (taking
-precedence) a posting date in the auto posting rule itself, will also be
-used in the generated posting.
-.SS Auto postings and transaction balancing / inferred amounts / balance assertions
-.PP
-Currently, auto postings are added:
-.IP \[bu] 2
-after missing amounts are inferred, and transactions are checked for
-balancedness,
-.IP \[bu] 2
-but before balance assertions are checked.
-.PP
-Note this means that journal entries must be balanced both before and
-after auto postings are added.
-This changed in hledger 1.12+; see #893 for background.
-.SS Auto posting tags
-.PP
-Automated postings will have some extra tags:
-.IP \[bu] 2
-\f[C]generated-posting:= QUERY\f[R] - shows this was generated by an
-auto posting rule, and the query
-.IP \[bu] 2
-\f[C]_generated-posting:= QUERY\f[R] - a hidden tag, which does not
-appear in hledger\[aq]s output.
-This can be used to match postings generated \[dq]just now\[dq], rather
-than generated in the past and saved to the journal.
-.PP
-Also, any transaction that has been changed by auto posting rules will
-have these tags added:
-.IP \[bu] 2
-\f[C]modified:\f[R] - this transaction was modified
-.IP \[bu] 2
-\f[C]_modified:\f[R] - a hidden tag not appearing in the comment; this
-transaction was modified \[dq]just now\[dq].
-
-
-.SH "REPORTING BUGS"
-Report bugs at http://bugs.hledger.org
-(or on the #hledger IRC channel or hledger mail list)
-
-.SH AUTHORS
-Simon Michael <simon@joyful.com> and contributors
-
-.SH COPYRIGHT
-
-Copyright (C) 2007-2020 Simon Michael.
-.br
-Released under GNU GPL v3 or later.
-
-.SH SEE ALSO
-hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
-
-hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5)