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

doc: bring embedded help files up to date

Browse Source
This commit is contained in:
Simon Michael 2016-05-28 12:58:30 -07:00
parent abf1bcbf36
commit bd3212654c
18 changed files with 1065 additions and 906 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

280
hledger-lib/doc/hledger_journal.5
View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger_journal" "5" "April 2016" "" "hledger User Manuals"
.TH "hledger_journal" "5" "May 2016" "" "hledger User Manuals"
@ -85,25 +85,29 @@ inferred.
.SS Simple dates
.PP
Within a journal file, transaction dates use Y/M/D (or Y\-M\-D or Y.M.D)
Leading zeroes are optional.
The year may be omitted, in which case it defaults to the current year,
or you can set the default year with a default year directive.
.PP
Leading zeros are 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[], \f[C]1/31\f[],
\f[C]2010\-01\-31\f[], \f[C]2010.1.31\f[].
.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, eg for more accurate balances, write both
dates separated by an equals sign.
The \f[I]primary date\f[], on the left, is used by default; the
\f[I]secondary date\f[], on the right, is used when the
\f[C]\-\-date2\f[] flag is specified (For Ledger compatibility,
\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work.)
When you want to model this, eg for more accurate balances, you can
specify individual #posting\-dates, which I recommend.
Or, you can use the secondary dates (aka auxiliary/effective dates)
feature, supported for compatibility with Ledger.
.PP
Their meaning is up to you, but it\[aq]s best to follow a consistent
rule.
A secondary date can be written after the primary date, separated by an
equals sign.
The primary date, on the left, is used by default; the secondary date,
on the right, is used when the \f[C]\-\-date2\f[] flag is specified
(\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work).
.PP
The meaning of secondary dates is up to you, but it\[aq]s best to follow
a consistent rule.
Eg write the bank\[aq]s clearing date as primary, and when needed, the
date the transaction was initiated as secondary.
.PP
@ -133,15 +137,16 @@ $\ hledger\ register\ checking\ \-\-date2
\f[]
.fi
.PP
Secondary dates require some effort: you must use them consistently in
Secondary dates require some effort; you must use them consistently in
your journal entries and remember whether to use or not use the
\f[C]\-\-date2\f[] flag for your reports.
Arguably they are now obsolete, superseded by...
They are included in hledger for Ledger compatibility, but posting dates
are a more powerful and less confusing alternative.
.SS Posting dates
.PP
You can give individual postings a different date from their parent
transaction, by adding a posting tag (see below) like
\f[C]date:DATE\f[], where DATE is a simple date.
transaction, by adding a posting comment containing a tag (see below)
like \f[C]date:DATE\f[].
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
@ -157,28 +162,31 @@ reconciliation:
.IP
.nf
\f[C]
$\ hledger\ \-f\ tt.j\ register\ food
$\ hledger\ \-f\ t.j\ register\ food
2015/05/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ \ \ \ \ \ \ \ \ \ $10
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ \-f\ tt.j\ register\ checking
$\ hledger\ \-f\ t.j\ register\ checking
2015/06/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ $\-10
\f[]
.fi
.PP
A posting date will use the year of the transaction date if unspecified.
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[].
The \f[C]date:\f[] or \f[C]date2:\f[] tags must have a valid simple date
value if they are present, eg a \f[C]date:\f[] tag with no value is not
allowed.
.PP
You can also set the secondary date, with \f[C]date2:DATE2\f[].
For compatibility, Ledger\[aq]s older posting date syntax is also
supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[]
in a posting comment.
.PP
When using any of these forms, be sure to provide a valid simple date or
you\[aq]ll get a parse error.
Eg a \f[C]date:\f[] tag with no value is not allowed.
Ledger\[aq]s earlier, more compact bracketed date syntax is also
supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[].
hledger will attempt to parse any square\-bracketed sequence of the
\f[C]0123456789/\-.=\f[] characters in this way.
With this syntax, DATE infers its year from the transaction and DATE2
infers its year from DATE.
.SS Account names
.PP
Account names typically have several parts separated by a full colon,
@ -189,67 +197,87 @@ five top\-level accounts: \f[C]assets\f[], \f[C]liabilities\f[],
.PP
Account names may contain single spaces, eg:
\f[C]assets:accounts\ receivable\f[].
Because of this, they must always be followed by at least two spaces (or
newline).
Because of this, they must always be followed by \f[B]two or more
spaces\f[] (or newline).
.PP
Account names can be aliased.
.SS 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\f[] spaces.
more spaces\f[].
.PP
The amount is a number, optionally with a currency symbol or commodity
name on either the left or right.
Negative amounts may have the minus sign either before or after the
currency symbol (\f[C]\-$1\f[] or \f[C]$\-1\f[]).
Commodity names which contain more than just letters should be enclosed
in double quotes (\f[C]1\ "person\ hours"\f[]).
.SS Decimal points and digit groups
Amounts consist of a number and (usually) a currency symbol or commodity
name.
Some examples:
.PP
hledger supports flexible decimal point and digit group separator
styles, to support international variations.
Numbers can use either a period (\f[C]\&.\f[]) or a comma (\f[C],\f[])
as decimal point.
They can also have digit group separators at any position (eg thousands
separators) which can be comma or period \- whichever one you did not
use as a decimal point.
If you use digit group separators, you must also include a decimal point
in at least one number in the same commodity, so that hledger knows
which character is which.
Eg, write \f[C]$1,000.00\f[] or \f[C]$1.000,00\f[].
.SS Amount display styles
\f[C]2.00001\f[]
.PD 0
.P
.PD
\f[C]$1\f[]
.PD 0
.P
.PD
\f[C]4000\ AAPL\f[]
.PD 0
.P
.PD
\f[C]3\ "green\ apples"\f[]
.PD 0
.P
.PD
\f[C]\-$1,000,000.00\f[]
.PD 0
.P
.PD
\f[C]INR\ 9,99,99,999.00\f[]
.PD 0
.P
.PD
\f[C]EUR\ \-2.000.000,00\f[]
.PP
Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in that
As you can see, the amount format is somewhat flexible:
.IP \[bu] 2
amounts are a number (the "quantity") and optionally a currency
symbol/commodity name (the "commodity").
.IP \[bu] 2
the commodity is a symbol, word, or double\-quoted phrase, on the left
or right, with or without a separating space
.IP \[bu] 2
negative amounts with a commodity on the left can have the minus sign
before or after it
.IP \[bu] 2
digit groups (thousands, or any other grouping) can be separated by
commas (in which case period is used for decimal point) or periods (in
which case comma is used for decimal point)
.PP
You can use any of these variations when recording data, but when
hledger displays amounts, it will choose a consistent format for each
commodity.
Amount styles include:
(Except for price amounts, which are always formatted as written).
The display format is chosen as follows:
.IP \[bu] 2
the position (left or right) and spacing (space or no separator) of the
commodity symbol
if there is a commodity directive specifying the format, that is used
.IP \[bu] 2
the digit group separator character (comma or period) and digit group
sizes, if any
otherwise the format is inferred from the first posting amount in that
commodity in the journal, and the precision (number of decimal places)
will be the maximum from all posting amounts in that commmodity
.IP \[bu] 2
the decimal point character (period or comma)
.IP \[bu] 2
the display precision (number of decimal places displayed)
or if there are no such amounts in the journal, a default format is used
(like \f[C]$1000.00\f[]).
.PP
The canonical style is generally the style of the first posting amount
seen in a commodity.
However the display precision will be the highest precision seen in all
posting amounts in that commmodity.
.PP
The precisions used in a price amount, or a D directive, don\[aq]t
affect the canonical display precision directly, but they can affect it
indirectly, eg when D\[aq]s default commodity is applied to a
commodity\-less amount or when an amountless posting is balanced using a
price\[aq]s commodity (actually this last case does not influence the
canonical display precision but probably should).
Price amounts and amounts in D directives usually don\[aq]t affect
amount format inference, but in some situations they can do so
indirectly.
(Eg when D\[aq]s default commodity is applied to a commodity\-less
amount, or when an amountless posting is balanced using a price\[aq]s
commodity, or when \-V is used.) If you find this causing problems, set
the desired format with a commodity directive.
.SS Virtual Postings
.PP
When you parenthesise the account name in a posting, that posting is
considered \f[I]virtual\f[], which means:
When you parenthesise the account name in a posting, we call that a
\f[I]virtual posting\f[], which means:
.IP \[bu] 2
it is ignored when checking that the transaction is balanced
.IP \[bu] 2
@ -265,20 +293,28 @@ needing to use the \f[C]equity:opening\ balances\f[] account:
\ \ (assets:checking)\ \ \ $1000
\f[]
.fi
.SS Balanced Virtual Postings
.PP
When the account name is bracketed, the posting is \f[I]balanced
virtual\f[], which is just like a virtual posting except the balanced
virtual postings in a transaction must balance to 0, like the real
postings (but separately from them).
When the account name is bracketed, we call it a \f[I]balanced virtual
posting\f[].
This is like an ordinary virtual posting except the balanced virtual
postings in a transaction must balance to 0, like the real postings (but
separately from them).
Balanced virtual postings are also excluded by \f[C]\-\-real/\-R\f[] or
\f[C]real:1\f[].
.IP
.nf
\f[C]
1/1\ buy\ food\ with\ cash,\ and\ update\ some\ budget\-tracking\ subaccounts\ elsewhere
\ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10
\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10
\ \ [assets:checking:available]\ \ \ \ \ $10
\ \ [assets:checking:budget:food]\ \ $\-10
\f[]
.fi
.PP
Virtual postings are a feature inherited from Ledger can can
occasionally be useful, but they can be a crutch and you should think
twice or three times before using them.
You can almost always find an equivalent journal entry using two or more
real postings that will be more correct and more error\-proof.
Virtual postings have some legitimate uses, but those are few.
You can usually find an equivalent journal entry using real postings,
which is more correct and provides better error checking.
.SS Balance Assertions
.PP
hledger supports ledger\-style balance assertions in journal files.
@ -547,7 +583,7 @@ posting\-tag):
.fi
.PP
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
values are always simple strings.
values are simple strings.
.SS Directives
.SS Account aliases
.PP
@ -721,46 +757,50 @@ spellings were also supported.
A line containing just \f[C]comment\f[] starts a multi\-line comment,
and a line containing just \f[C]end\ comment\f[] ends it.
See comments.
.SS commodity directive
.PP
The \f[C]commodity\f[] directive predefines commodities (currently this
is just informational), and also it may define the display format for
amounts in this commodity (overriding the automatically inferred
format).
.PP
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[]
.fi
.PP
or on multiple lines, using the "format" 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\ 9,99,99,999.00
\f[]
.fi
.SS Default commodity
.PP
You can set a default commodity, to be used for amounts without one.
Use the D directive with a sample amount.
The commodity (and the sample amount\[aq]s display style) will be
The commodity (and the sample amount\[aq]s display format) will be
applied to all subsequent commodity\-less amounts, up to the next D
directive.
(Note this is different from Ledger\[aq]s default commodity directive.)
.PP
Also note the directive itself does not influence the commodity\[aq]s
default display style, but the amount it is applied to might.
Here\[aq]s an example:
.IP
.nf
\f[C]
;\ set\ £\ as\ the\ default\ commodity
D\ £1,000.00
2010/1/1
\ \ a\ \ 2340
\ \ b
2014/1/1
\ \ c\ \ £1000
\ \ d
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ print
2010/01/01
\ \ \ \ a\ \ \ \ \ £2,340.00
\ \ \ \ b\ \ \ \ £\-2,340.00
2014/01/01
\ \ \ \ c\ \ \ \ \ £1,000.00
\ \ \ \ d\ \ \ \ £\-1,000.00
\f[]
.fi
.SS Default year
.PP
You can set a default year to be used for subsequent dates which
@ -800,12 +840,10 @@ include\ path/to/file.journal
.PP
If the path does not begin with a slash, it is relative to the current
file.
.PP
Glob patterns (\f[C]*\f[]) are not currently supported.
.PP
The \f[C]include\f[] directive may only be used in journal files, and
currently it may only include other journal files (eg, not CSV or
timeclock files.)
The \f[C]include\f[] directive can only be used in journal files.
It can include journal, timeclock or timedot files, but not CSV files.
.SH EDITOR SUPPORT
.PP
Add\-on modes exist for various text editors, to make working with

403
hledger-lib/doc/hledger_journal.5.info
View File

@ -119,11 +119,11 @@ File: hledger_journal.5.info, Node: Simple dates, Next: Secondary dates, Up:
------------------
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
Leading zeroes are optional. The year may be omitted, in which case it
defaults to the current year, or you can set the default year with a
default year directive.
Some examples: `2010/01/31', `1/31', `2010-01-31', `2010.1.31'.
Leading zeros are 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: `2010/01/31', `1/31', `2010-01-31',
`2010.1.31'.

File: hledger_journal.5.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates
@ -133,15 +133,19 @@ File: hledger_journal.5.info, Node: Secondary dates, Next: Posting dates, Pre
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, eg for more accurate balances, write both dates
separated by an equals sign. The _primary date_, on the left, is used
by default; the _secondary date_, on the right, is used when the
`--date2' flag is specified (For Ledger compatibility, `--aux-date' or
`--effective' also work.)
want to model this, eg for more accurate balances, you can specify
individual #posting-dates, which I recommend. Or, you can use the
secondary dates (aka auxiliary/effective dates) feature, supported for
compatibility with Ledger.
Their meaning is up to you, but it's best to follow a consistent
rule. Eg write the bank's clearing date as primary, and when needed,
the date the transaction was initiated as secondary.
A secondary date can be written after the primary date, separated by
an equals sign. The primary date, on the left, is used by default; the
secondary date, on the right, is used when the `--date2' flag is
specified (`--aux-date' or `--effective' also work).
The meaning of secondary dates is up to you, but it's best to follow
a consistent rule. Eg write the bank's clearing date as primary, and
when needed, the date the transaction was initiated as secondary.
Here's an example. Note that a secondary date will use the year of
the primary date if unspecified.
@ -159,10 +163,11 @@ $ hledger register checking
$ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10
Secondary dates require some effort: you must use them consistently
Secondary dates require some effort; you must use them consistently
in your journal entries and remember whether to use or not use the
`--date2' flag for your reports. Arguably they are now obsolete,
superseded by...
`--date2' flag for your reports. They are included in hledger for
Ledger compatibility, but posting dates are a more powerful and less
confusing alternative.

File: hledger_journal.5.info, Node: Posting dates, Prev: Secondary dates, Up: Dates
@ -171,11 +176,11 @@ File: hledger_journal.5.info, Node: Posting dates, Prev: Secondary dates, Up:
-------------------
You can give individual postings a different date from their parent
transaction, by adding a posting tag (see below) like `date:DATE',
where DATE is a simple date. 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:
transaction, by adding a posting comment containing a tag (see below)
like `date:DATE'. 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:
2015/5/30
@ -183,23 +188,24 @@ for easy bank reconciliation:
assets:checking ; bank cleared it on monday, date:6/1
$ hledger -f tt.j register food
$ hledger -f t.j register food
2015/05/30 expenses:food $10 $10
$ hledger -f tt.j register checking
$ hledger -f t.j register checking
2015/06/01 assets:checking $-10 $-10
A posting date will use the year of the transaction date if
unspecified.
DATE should be a simple date; if the year is not specified it will
use the year of the transaction's date. You can set the secondary date
similarly, with `date2:DATE2'. The `date:' or `date2:' tags must have a
valid simple date value if they are present, eg a `date:' tag with no
value is not allowed.
You can also set the secondary date, with `date2:DATE2'. For
compatibility, Ledger's older posting date syntax is also supported:
`[DATE]', `[DATE=DATE2]' or `[=DATE2]' in a posting comment.
When using any of these forms, be sure to provide a valid simple
date or you'll get a parse error. Eg a `date:' tag with no value is not
allowed.
Ledger's earlier, more compact bracketed date syntax is also
supported: `[DATE]', `[DATE=DATE2]' or `[=DATE2]'. hledger will attempt
to parse any square-bracketed sequence of the `0123456789/-.='
characters in this way. With this syntax, DATE infers its year from the
transaction and DATE2 infers its year from DATE.

File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Dates, Up: FILE FORMAT
@ -213,8 +219,8 @@ anything you like, but in finance there are traditionally five top-level
accounts: `assets', `liabilities', `income', `expenses', and `equity'.
Account names may contain single spaces, eg: `assets:accounts
receivable'. Because of this, they must always be followed by at least
two spaces (or newline).
receivable'. Because of this, they must always be followed by *two or
more spaces* (or newline).
Account names can be aliased.
@ -225,65 +231,56 @@ File: hledger_journal.5.info, Node: Amounts, Next: Virtual Postings, Prev: Ac
===========
After the account name, there is usually an amount. Important: between
account name and amount, there must be *two or more* spaces.
account name and amount, there must be *two or more spaces*.
The amount is a number, optionally with a currency symbol or
commodity name on either the left or right. Negative amounts may have
the minus sign either before or after the currency symbol (`-$1' or
`$-1'). Commodity names which contain more than just letters should be
enclosed in double quotes (`1 "person hours"').
Amounts consist of a number and (usually) a currency symbol or
commodity name. Some examples:
* Menu:
`2.00001'
`$1'
`4000 AAPL'
`3 "green apples"'
`-$1,000,000.00'
`INR 9,99,99,999.00'
`EUR -2.000.000,00'
* Decimal points and digit groups::
* Amount display styles::
As you can see, the amount format is somewhat flexible:

File: hledger_journal.5.info, Node: Decimal points and digit groups, Next: Amount display styles, Up: Amounts
* amounts are a number (the "quantity") and optionally a currency
symbol/commodity name (the "commodity").
1.4.1 Decimal points and digit groups
-------------------------------------
* the commodity is a symbol, word, or double-quoted phrase, on the
left or right, with or without a separating space
hledger supports flexible decimal point and digit group separator
styles, to support international variations. Numbers can use either a
period (`.') or a comma (`,') as decimal point. They can also have
digit group separators at any position (eg thousands separators) which
can be comma or period - whichever one you did not use as a decimal
point. If you use digit group separators, you must also include a
decimal point in at least one number in the same commodity, so that
hledger knows which character is which. Eg, write `$1,000.00' or
`$1.000,00'.
* negative amounts with a commodity on the left can have the minus
sign before or after it

File: hledger_journal.5.info, Node: Amount display styles, Prev: Decimal points and digit groups, Up: Amounts
* digit groups (thousands, or any other grouping) can be separated by
commas (in which case period is used for decimal point) or periods
(in which case comma is used for decimal point)
1.4.2 Amount display styles
---------------------------
You can use any of these variations when recording data, but when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
written). The display format is chosen as follows:
Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in that
commodity. Amount styles include:
* if there is a commodity directive specifying the format, that is
used
* the position (left or right) and spacing (space or no separator)
of the commodity symbol
* otherwise the format is inferred from the first posting amount in
that commodity in the journal, and the precision (number of
decimal places) will be the maximum from all posting amounts in
that commmodity
* the digit group separator character (comma or period) and digit
group sizes, if any
* or if there are no such amounts in the journal, a default format
is used (like `$1000.00').
* the decimal point character (period or comma)
* the display precision (number of decimal places displayed)
The canonical style is generally the style of the first posting
amount seen in a commodity. However the display precision will be the
highest precision seen in all posting amounts in that commmodity.
The precisions used in a price amount, or a D directive, don't affect
the canonical display precision directly, but they can affect it
indirectly, eg when D's default commodity is applied to a commodity-less
amount or when an amountless posting is balanced using a price's
commodity (actually this last case does not influence the canonical
display precision but probably should).
Price amounts and amounts in D directives usually don't affect amount
format inference, but in some situations they can do so indirectly. (Eg
when D's default commodity is applied to a commodity-less amount, or
when an amountless posting is balanced using a price's commodity, or
when -V is used.) If you find this causing problems, set the desired
format with a commodity directive.

File: hledger_journal.5.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT
@ -291,8 +288,8 @@ File: hledger_journal.5.info, Node: Virtual Postings, Next: Balance Assertions
1.5 Virtual Postings
====================
When you parenthesise the account name in a posting, that posting is
considered _virtual_, which means:
When you parenthesise the account name in a posting, we call that a
_virtual posting_, which means:
* it is ignored when checking that the transaction is balanced
@ -306,27 +303,22 @@ needing to use the `equity:opening balances' account:
1/1 special unbalanced posting to set initial balance
(assets:checking) $1000
* Menu:
When the account name is bracketed, we call it a _balanced virtual
posting_. This is like an ordinary virtual posting except the balanced
virtual postings in a transaction must balance to 0, like the real
postings (but separately from them). Balanced virtual postings are also
excluded by `--real/-R' or `real:1'.
* Balanced Virtual Postings::

File: hledger_journal.5.info, Node: Balanced Virtual Postings, Up: Virtual Postings
1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere
expenses:food $10
assets:cash $-10
[assets:checking:available] $10
[assets:checking:budget:food] $-10
1.5.1 Balanced Virtual Postings
-------------------------------
When the account name is bracketed, the posting is _balanced virtual_,
which is just like a virtual posting except the balanced virtual
postings in a transaction must balance to 0, like the real postings
(but separately from them). Balanced virtual postings are also excluded
by `--real/-R' or `real:1'.
Virtual postings are a feature inherited from Ledger can can
occasionally be useful, but they can be a crutch and you should think
twice or three times before using them. You can almost always find an
equivalent journal entry using two or more real postings that will be
more correct and more error-proof.
Virtual postings have some legitimate uses, but those are few. You
can usually find an equivalent journal entry using real postings, which
is more correct and provides better error checking.

File: hledger_journal.5.info, Node: Balance Assertions, Next: Prices, Prev: Virtual Postings, Up: FILE FORMAT
@ -602,7 +594,7 @@ and the posting has four (A, TAG2, third-tag, posting-tag):
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
are always simple strings.
are simple strings.

File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
@ -616,6 +608,7 @@ File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
* account directive::
* apply account directive::
* Multi-line comments::
* commodity directive::
* Default commodity::
* Default year::
* Including other files::
@ -791,7 +784,7 @@ include personal.journal
also supported.

File: hledger_journal.5.info, Node: Multi-line comments, Next: Default commodity, Prev: apply account directive, Up: Directives
File: hledger_journal.5.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives
1.10.4 Multi-line comments
--------------------------
@ -800,47 +793,56 @@ A line containing just `comment' starts a multi-line comment, and a
line containing just `end comment' ends it. See comments.

File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: Multi-line comments, Up: Directives
File: hledger_journal.5.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives
1.10.5 Default commodity
1.10.5 commodity directive
--------------------------
The `commodity' directive predefines commodities (currently this is
just informational), and also it may define the display format for
amounts in this commodity (overriding the automatically inferred
format).
It may be written on a single line, like this:
; 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
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
places:
; 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 9,99,99,999.00

File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
1.10.6 Default commodity
------------------------
You can set a default commodity, to be used for amounts without one. Use
the D directive with a sample amount. The commodity (and the sample
amount's display style) will be applied to all subsequent commodity-less
amounts, up to the next D directive. (Note this is different from
Ledger's default commodity directive.)
Also note the directive itself does not influence the commodity's
default display style, but the amount it is applied to might. Here's an
example:
; set £ as the default commodity
D £1,000.00
2010/1/1
a 2340
b
2014/1/1
c £1000
d
$ hledger print
2010/01/01
a £2,340.00
b £-2,340.00
2014/01/01
c £1,000.00
d £-1,000.00
amount's display format) will be applied to all subsequent
commodity-less amounts, up to the next D directive. (Note this is
different from Ledger's default commodity directive.)

File: hledger_journal.5.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
1.10.6 Default year
1.10.7 Default year
-------------------
You can set a default year to be used for subsequent dates which don't
@ -867,7 +869,7 @@ Y2010 ; change default year to 2010

File: hledger_journal.5.info, Node: Including other files, Prev: Default year, Up: Directives
1.10.7 Including other files
1.10.8 Including other files
----------------------------
You can pull in the content of additional journal files by writing an
@ -877,13 +879,10 @@ include directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the
current file.
current file. Glob patterns (`*') are not currently supported.
Glob patterns (`*') are not currently supported.
The `include' directive may only be used in journal files, and
currently it may only include other journal files (eg, not CSV or
timeclock files.)
The `include' directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.

File: hledger_journal.5.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
@ -917,67 +916,63 @@ Node: Dates3351
Ref: #dates3479
Node: Simple dates3544
Ref: #simple-dates3672
Node: Secondary dates3976
Ref: #secondary-dates4132
Node: Posting dates5408
Ref: #posting-dates5539
Node: Account names6715
Ref: #account-names6854
Node: Amounts7338
Ref: #amounts7476
Node: Decimal points and digit groups8003
Ref: #decimal-points-and-digit-groups8196
Node: Amount display styles8751
Ref: #amount-display-styles8924
Node: Virtual Postings10003
Ref: #virtual-postings10164
Node: Balanced Virtual Postings10683
Ref: #balanced-virtual-postings10837
Node: Balance Assertions11452
Ref: #balance-assertions11616
Node: Assertions and ordering12438
Ref: #assertions-and-ordering12623
Node: Assertions and commodities13654
Ref: #assertions-and-commodities13880
Node: Assertions and subaccounts14572
Ref: #assertions-and-subaccounts14806
Node: Assertions and virtual postings15328
Ref: #assertions-and-virtual-postings15537
Node: Prices15678
Ref: #prices15810
Node: Transaction prices15861
Ref: #transaction-prices16006
Node: Market prices17613
Ref: #market-prices17748
Node: Comments18636
Ref: #comments18758
Node: Tags19870
Ref: #tags19988
Node: Directives20918
Ref: #directives21033
Node: Account aliases21202
Ref: #account-aliases21348
Node: Basic aliases21950
Ref: #basic-aliases22095
Node: Regex aliases22783
Ref: #regex-aliases22953
Node: Multiple aliases23723
Ref: #multiple-aliases23897
Node: end aliases24393
Ref: #end-aliases24535
Node: account directive24637
Ref: #account-directive24819
Node: apply account directive25115
Ref: #apply-account-directive25313
Node: Multi-line comments25974
Ref: #multi-line-comments26164
Node: Default commodity26291
Ref: #default-commodity26466
Node: Default year27161
Ref: #default-year27328
Node: Including other files27751
Ref: #including-other-files27910
Node: EDITOR SUPPORT28327
Ref: #editor-support28447
Node: Secondary dates4036
Ref: #secondary-dates4192
Node: Posting dates5753
Ref: #posting-dates5884
Node: Account names7255
Ref: #account-names7394
Node: Amounts7879
Ref: #amounts8017
Node: Virtual Postings10015
Ref: #virtual-postings10176
Node: Balance Assertions11396
Ref: #balance-assertions11560
Node: Assertions and ordering12382
Ref: #assertions-and-ordering12567
Node: Assertions and commodities13598
Ref: #assertions-and-commodities13824
Node: Assertions and subaccounts14516
Ref: #assertions-and-subaccounts14750
Node: Assertions and virtual postings15272
Ref: #assertions-and-virtual-postings15481
Node: Prices15622
Ref: #prices15754
Node: Transaction prices15805
Ref: #transaction-prices15950
Node: Market prices17557
Ref: #market-prices17692
Node: Comments18580
Ref: #comments18702
Node: Tags19814
Ref: #tags19932
Node: Directives20855
Ref: #directives20970
Node: Account aliases21163
Ref: #account-aliases21309
Node: Basic aliases21911
Ref: #basic-aliases22056
Node: Regex aliases22744
Ref: #regex-aliases22914
Node: Multiple aliases23684
Ref: #multiple-aliases23858
Node: end aliases24354
Ref: #end-aliases24496
Node: account directive24598
Ref: #account-directive24780
Node: apply account directive25076
Ref: #apply-account-directive25274
Node: Multi-line comments25935
Ref: #multi-line-comments26127
Node: commodity directive26254
Ref: #commodity-directive26440
Node: Default commodity27313
Ref: #default-commodity27488
Node: Default year27809
Ref: #default-year27976
Node: Including other files28399
Ref: #including-other-files28558
Node: EDITOR SUPPORT28954
Ref: #editor-support29074

End Tag Table

243
hledger-lib/doc/hledger_journal.5.txt
View File

@ -75,24 +75,28 @@ FFIILLEE FFOORRMMAATT
DDaatteess
SSiimmppllee ddaatteess
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
Leading zeroes are optional. The year may be omitted, in which case it
defaults to the current year, or you can set the default year with a
default year directive.
Some examples: 2010/01/31, 1/31, 2010-01-31, 2010.1.31.
Leading zeros are 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: 2010/01/31, 1/31, 2010-01-31,
2010.1.31.
SSeeccoonnddaarryy ddaatteess
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, eg for more accurate balances, write both dates
separated by an equals sign. The _p_r_i_m_a_r_y _d_a_t_e, on the left, is used by
default; the _s_e_c_o_n_d_a_r_y _d_a_t_e, on the right, is used when the --date2
flag is specified (For Ledger compatibility, --aux-date or --effective
also work.)
want to model this, eg for more accurate balances, you can specify
individual #posting-dates, which I recommend. Or, you can use the sec-
ondary dates (aka auxiliary/effective dates) feature, supported for
compatibility with Ledger.
Their meaning is up to you, but it's best to follow a consistent rule.
Eg write the bank's clearing date as primary, and when needed, the date
the transaction was initiated as secondary.
A secondary date can be written after the primary date, separated by an
equals sign. The primary date, on the left, is used by default; the
secondary date, on the right, is used when the --date2 flag is speci-
fied (--aux-date or --effective also work).
The meaning of secondary dates is up to you, but it's best to follow a
consistent rule. Eg write the bank's clearing date as primary, and
when needed, the date the transaction was initiated as secondary.
Here's an example. Note that a secondary date will use the year of the
primary date if unspecified.
@ -107,39 +111,41 @@ FFIILLEE FFOORRMMAATT
$ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10
Secondary dates require some effort: you must use them consistently in
Secondary dates require some effort; you must use them consistently in
your journal entries and remember whether to use or not use the --date2
flag for your reports. Arguably they are now obsolete, superseded
by...
flag for your reports. They are included in hledger for Ledger compat-
ibility, but posting dates are a more powerful and less confusing
alternative.
PPoossttiinngg ddaatteess
You can give individual postings a different date from their parent
transaction, by adding a posting tag (see below) like date:DATE, where
DATE is a simple date. This is probably the best way to control post-
ing 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:
transaction, by adding a posting comment containing a tag (see below)
like date:DATE. 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:
2015/5/30
expenses:food $10 ; food purchased on saturday 5/30
assets:checking ; bank cleared it on monday, date:6/1
$ hledger -f tt.j register food
$ hledger -f t.j register food
2015/05/30 expenses:food $10 $10
$ hledger -f tt.j register checking
$ hledger -f t.j register checking
2015/06/01 assets:checking $-10 $-10
A posting date will use the year of the transaction date if unspeci-
fied.
DATE should be a simple date; if the year is not specified it will use
the year of the transaction's date. You can set the secondary date
similarly, with date2:DATE2. The date: or date2: tags must have a
valid simple date value if they are present, eg a date: tag with no
value is not allowed.
You can also set the secondary date, with date2:DATE2. For compatibil-
ity, Ledger's older posting date syntax is also supported: [DATE],
[DATE=DATE2] or [=DATE2] in a posting comment.
When using any of these forms, be sure to provide a valid simple date
or you'll get a parse error. Eg a date: tag with no value is not
allowed.
Ledger's earlier, more compact bracketed date syntax is also supported:
[DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any
square-bracketed sequence of the 0123456789/-.= characters in this way.
With this syntax, DATE infers its year from the transaction and DATE2
infers its year from DATE.
AAccccoouunntt nnaammeess
Account names typically have several parts separated by a full colon,
@ -148,60 +154,66 @@ FFIILLEE FFOORRMMAATT
top-level accounts: assets, liabilities, income, expenses, and equity.
Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by at least two
spaces (or newline).
able. Because of this, they must always be followed by ttwwoo oorr mmoorree
ssppaacceess (or newline).
Account names can be aliased.
AAmmoouunnttss
After the account name, there is usually an amount. Important: between
account name and amount, there must be ttwwoo oorr mmoorree spaces.
account name and amount, there must be ttwwoo oorr mmoorree ssppaacceess.
The amount is a number, optionally with a currency symbol or commodity
name on either the left or right. Negative amounts may have the minus
sign either before or after the currency symbol (-$1 or $-1). Commod-
ity names which contain more than just letters should be enclosed in
double quotes (1 "person hours").
Amounts consist of a number and (usually) a currency symbol or commod-
ity name. Some examples:
DDeecciimmaall ppooiinnttss aanndd ddiiggiitt ggrroouuppss
hledger supports flexible decimal point and digit group separator
styles, to support international variations. Numbers can use either a
period (.) or a comma (,) as decimal point. They can also have digit
group separators at any position (eg thousands separators) which can be
comma or period - whichever one you did not use as a decimal point. If
you use digit group separators, you must also include a decimal point
in at least one number in the same commodity, so that hledger knows
which character is which. Eg, write $1,000.00 or $1.000,00.
2.00001
$1
4000 AAPL
3 "green apples"
-$1,000,000.00
INR 9,99,99,999.00
EUR -2.000.000,00
AAmmoouunntt ddiissppllaayy ssttyylleess
Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in
that commodity. Amount styles include:
As you can see, the amount format is somewhat flexible:
+o the position (left or right) and spacing (space or no separator) of
the commodity symbol
+o amounts are a number (the "quantity") and optionally a currency sym-
bol/commodity name (the "commodity").
+o the digit group separator character (comma or period) and digit group
sizes, if any
+o the commodity is a symbol, word, or double-quoted phrase, on the left
or right, with or without a separating space
+o the decimal point character (period or comma)
+o negative amounts with a commodity on the left can have the minus sign
before or after it
+o the display precision (number of decimal places displayed)
+o digit groups (thousands, or any other grouping) can be separated by
commas (in which case period is used for decimal point) or periods
(in which case comma is used for decimal point)
The canonical style is generally the style of the first posting amount
seen in a commodity. However the display precision will be the highest
precision seen in all posting amounts in that commmodity.
You can use any of these variations when recording data, but when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
written). The display format is chosen as follows:
The precisions used in a price amount, or a D directive, don't affect
the canonical display precision directly, but they can affect it indi-
rectly, eg when D's default commodity is applied to a commodity-less
amount or when an amountless posting is balanced using a price's com-
modity (actually this last case does not influence the canonical dis-
play precision but probably should).
+o if there is a commodity directive specifying the format, that is used
+o otherwise the format is inferred from the first posting amount in
that commodity in the journal, and the precision (number of decimal
places) will be the maximum from all posting amounts in that commmod-
ity
+o or if there are no such amounts in the journal, a default format is
used (like $1000.00).
Price amounts and amounts in D directives usually don't affect amount
format inference, but in some situations they can do so indirectly.
(Eg when D's default commodity is applied to a commodity-less amount,
or when an amountless posting is balanced using a price's commodity, or
when -V is used.) If you find this causing problems, set the desired
format with a commodity directive.
VViirrttuuaall PPoossttiinnggss
When you parenthesise the account name in a posting, that posting is
considered _v_i_r_t_u_a_l, which means:
When you parenthesise the account name in a posting, we call that a
_v_i_r_t_u_a_l _p_o_s_t_i_n_g, which means:
+o it is ignored when checking that the transaction is balanced
@ -214,18 +226,21 @@ FFIILLEE FFOORRMMAATT
1/1 special unbalanced posting to set initial balance
(assets:checking) $1000
BBaallaanncceedd VViirrttuuaall PPoossttiinnggss
When the account name is bracketed, the posting is _b_a_l_a_n_c_e_d _v_i_r_t_u_a_l,
which is just like a virtual posting except the balanced virtual post-
ings in a transaction must balance to 0, like the real postings (but
separately from them). Balanced virtual postings are also excluded by
--real/-R or real:1.
When the account name is bracketed, we call it a _b_a_l_a_n_c_e_d _v_i_r_t_u_a_l _p_o_s_t_-
_i_n_g. This is like an ordinary virtual posting except the balanced vir-
tual postings in a transaction must balance to 0, like the real post-
ings (but separately from them). Balanced virtual postings are also
excluded by --real/-R or real:1.
Virtual postings are a feature inherited from Ledger can can occasion-
ally be useful, but they can be a crutch and you should think twice or
three times before using them. You can almost always find an equiva-
lent journal entry using two or more real postings that will be more
correct and more error-proof.
1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere
expenses:food $10
assets:cash $-10
[assets:checking:available] $10
[assets:checking:budget:food] $-10
Virtual postings have some legitimate uses, but those are few. You can
usually find an equivalent journal entry using real postings, which is
more correct and provides better error checking.
BBaallaannccee AAsssseerrttiioonnss
hledger supports ledger-style balance assertions in journal files.
@ -429,7 +444,7 @@ FFIILLEE FFOORRMMAATT
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
are always simple strings.
are simple strings.
DDiirreeccttiivveess
AAccccoouunntt aalliiaasseess
@ -554,37 +569,40 @@ FFIILLEE FFOORRMMAATT
A line containing just comment starts a multi-line comment, and a line
containing just end comment ends it. See comments.
ccoommmmooddiittyy ddiirreeccttiivvee
The commodity directive predefines commodities (currently this is just
informational), and also it may define the display format for amounts
in this commodity (overriding the automatically inferred format).
It may be written on a single line, like this:
; 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
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
places:
; 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 9,99,99,999.00
DDeeffaauulltt ccoommmmooddiittyy
You can set a default commodity, to be used for amounts without one.
Use the D directive with a sample amount. The commodity (and the sam-
ple amount's display style) will be applied to all subsequent commod-
ple amount's display format) will be applied to all subsequent commod-
ity-less amounts, up to the next D directive. (Note this is different
from Ledger's default commodity directive.)
Also note the directive itself does not influence the commodity's
default display style, but the amount it is applied to might. Here's
an example:
; set ^A-L as the default commodity
D ^A-L1,000.00
2010/1/1
a 2340
b
2014/1/1
c ^A-L1000
d
$ hledger print
2010/01/01
a ^A-L2,340.00
b ^A-L-2,340.00
2014/01/01
c ^A-L1,000.00
d ^A-L-1,000.00
DDeeffaauulltt yyeeaarr
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
@ -613,13 +631,10 @@ FFIILLEE FFOORRMMAATT
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file.
file. Glob patterns (*) are not currently supported.
Glob patterns (*) are not currently supported.
The include directive may only be used in journal files, and currently
it may only include other journal files (eg, not CSV or timeclock
files.)
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
EEDDIITTOORR SSUUPPPPOORRTT
Add-on modes exist for various text editors, to make working with jour-
@ -665,4 +680,4 @@ SSEEEE AALLSSOO
April 2016 hledger_journal(5)
May 2016 hledger_journal(5)

2
hledger-lib/doc/hledger_timeclock.5
View File

@ -11,7 +11,7 @@ Timeclock \- the time logging format of timeclock.el, as read by hledger
hledger can read timeclock files.
As with Ledger, these are (a subset of) timeclock.el\[aq]s format,
containing clock\-in and clock\-out entries as in the example below.
The date is a simple date (also, default year directives work).
The date is a simple date.
The time format is HH:MM[:SS][+\-ZZZZ].
Seconds and timezone are optional.
The timezone, if present, must be four digits and is ignored (currently

8
hledger-lib/doc/hledger_timeclock.5.info
View File

@ -9,10 +9,10 @@ hledger_timeclock(5)
hledger can read timeclock files. As with Ledger, these are (a subset
of) timeclock.el's format, containing clock-in and clock-out entries as
in the example below. The date is a simple date (also, default year
directives work). The time format is HH:MM[:SS][+-ZZZZ]. Seconds and
timezone are optional. The timezone, if present, must be four digits and
is ignored (currently the time is always interpreted as a local time).
in the example below. The date is a simple date. The time format is
HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone, if
present, must be four digits and is ignored (currently the time is
always interpreted as a local time).
i 2015/03/30 09:00:00 some:account name optional description after two spaces

9
hledger-lib/doc/hledger_timeclock.5.txt
View File

@ -9,11 +9,10 @@ NNAAMMEE
DDEESSCCRRIIPPTTIIOONN
hledger can read timeclock files. As with Ledger, these are (a subset
of) timeclock.el's format, containing clock-in and clock-out entries as
in the example below. The date is a simple date (also, default year
directives work). The time format is HH:MM[:SS][+-ZZZZ]. Seconds and
timezone are optional. The timezone, if present, must be four digits
and is ignored (currently the time is always interpreted as a local
time).
in the example below. The date is a simple date. The time format is
HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone,
if present, must be four digits and is ignored (currently the time is
always interpreted as a local time).
i 2015/03/30 09:00:00 some:account name optional description after two spaces
o 2015/03/30 09:20:00

2
hledger-lib/doc/hledger_timedot.5
View File

@ -120,8 +120,6 @@ $\ hledger\ \-f\ t.timedot\ \-\-alias\ /\\\\./=:\ bal\ date:2016/2/4
\f[]
.fi
.PP
default year directives may be used.
.PP
Here is a sample.timedot.

2
hledger-lib/doc/hledger_timedot.5.info
View File

@ -109,8 +109,6 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4
--------------------
4.50
default year directives may be used.
Here is a sample.timedot.

2
hledger-lib/doc/hledger_timedot.5.txt
View File

@ -93,8 +93,6 @@ FFIILLEE FFOORRMMAATT
--------------------
4.50
default year directives may be used.
Here is a sample.timedot.

4
hledger-ui/doc/hledger-ui.1
View File

@ -139,8 +139,8 @@ set start date, end date, and/or reporting interval all at once
.RS
.RE
.TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[]
use postings/txns\[aq] secondary dates instead
.B \f[C]\-\-date2\f[]
show, and match with \-b/\-e/\-p/date:, secondary dates instead
.RS
.RE
.TP

28
hledger-ui/doc/hledger-ui.1.info
View File

@ -106,8 +106,8 @@ The following common hledger options should also work:
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
`--date2 --aux-date'
use postings/txns' secondary dates instead
`--date2'
show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared'
include only cleared postings/txns
@ -273,17 +273,17 @@ Node: OPTIONS682
Ref: #options781
Node: hledger options1547
Ref: #hledger-options1653
Node: KEYS2829
Ref: #keys2926
Node: SCREENS3323
Ref: #screens3410
Node: Accounts screen3500
Ref: #accounts-screen3630
Node: Register screen4475
Ref: #register-screen4632
Node: Transaction screen6014
Ref: #transaction-screen6174
Node: Error screen7041
Ref: #error-screen7165
Node: KEYS2836
Ref: #keys2933
Node: SCREENS3330
Ref: #screens3417
Node: Accounts screen3507
Ref: #accounts-screen3637
Node: Register screen4482
Ref: #register-screen4639
Node: Transaction screen6021
Ref: #transaction-screen6181
Node: Error screen7048
Ref: #error-screen7172

End Tag Table

4
hledger-ui/doc/hledger-ui.1.txt
View File

@ -94,8 +94,8 @@ OOPPTTIIOONNSS
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
----ddaattee22 ----aauuxx--ddaattee
use postings/txns' secondary dates instead
----ddaattee22
show, and match with -b/-e/-p/date:, secondary dates instead
--CC ----cclleeaarreedd
include only cleared postings/txns

12
hledger-web/doc/hledger-web.1
View File

@ -73,8 +73,14 @@ Note there is no built\-in access control, so you will need to hide
hledger\-web behind an authenticating proxy (such as apache or nginx) if
you want to restrict who can see and add entries to your journal.
.PP
Command\-line options and arguments may be used to set an initial filter
on the data.
This is not shown in the web UI, but it will be applied in addition to
any search query entered there.
.PP
With journal and timeclock files (but not CSV files, currently) the web
app detects changes and will show the new data on the next request.
app detects changes made by other means and will show the new data on
the next request.
If a change makes the file unparseable, hledger\-web will show an error
until the file has been fixed.
.SH OPTIONS
@ -178,8 +184,8 @@ set start date, end date, and/or reporting interval all at once
.RS
.RE
.TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[]
use postings/txns\[aq] secondary dates instead
.B \f[C]\-\-date2\f[]
show, and match with \-b/\-e/\-p/date:, secondary dates instead
.RS
.RE
.TP

22
hledger-web/doc/hledger-web.1.info
View File

@ -51,10 +51,14 @@ the PORT in the base url.
hledger-web behind an authenticating proxy (such as apache or nginx) if
you want to restrict who can see and add entries to your journal.
Command-line options and arguments may be used to set an initial
filter on the data. This is not shown in the web UI, but it will be
applied in addition to any search query entered there.
With journal and timeclock files (but not CSV files, currently) the
web app detects changes and will show the new data on the next request.
If a change makes the file unparseable, hledger-web will show an error
until the file has been fixed.
web app detects changes made by other means and will show the new data
on the next request. If a change makes the file unparseable, hledger-web
will show an error until the file has been fixed.
* Menu:
@ -139,8 +143,8 @@ The following common hledger options should also work:
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
`--date2 --aux-date'
use postings/txns' secondary dates instead
`--date2'
show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared'
include only cleared postings/txns
@ -167,9 +171,9 @@ The following common hledger options should also work:

Tag Table:
Node: Top90
Node: OPTIONS2622
Ref: #options2709
Node: hledger options3572
Ref: #hledger-options3679
Node: OPTIONS2834
Ref: #options2921
Node: hledger options3784
Ref: #hledger-options3891

End Tag Table

14
hledger-web/doc/hledger-web.1.txt
View File

@ -61,10 +61,14 @@ DDEESSCCRRIIPPTTIIOONN
hledger-web behind an authenticating proxy (such as apache or nginx) if
you want to restrict who can see and add entries to your journal.
Command-line options and arguments may be used to set an initial filter
on the data. This is not shown in the web UI, but it will be applied
in addition to any search query entered there.
With journal and timeclock files (but not CSV files, currently) the web
app detects changes and will show the new data on the next request. If
a change makes the file unparseable, hledger-web will show an error
until the file has been fixed.
app detects changes made by other means and will show the new data on
the next request. If a change makes the file unparseable, hledger-web
will show an error until the file has been fixed.
OOPPTTIIOONNSS
Note: if invoking hledger-web as a hledger subcommand, write -- before
@ -128,8 +132,8 @@ OOPPTTIIOONNSS
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
----ddaattee22 ----aauuxx--ddaattee
use postings/txns' secondary dates instead
----ddaattee22
show, and match with -b/-e/-p/date:, secondary dates instead
--CC ----cclleeaarreedd
include only cleared postings/txns

69
hledger/doc/hledger.1
View File

@ -142,6 +142,27 @@ $\ hledger\ print\ desc:shop\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transacti
$\ hledger\ activity\ \-W\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transaction\ counts\ per\ week\ as\ a\ bar\ chart
\f[]
.fi
.PP
With the journal
.IP
.nf
\f[C]
2016/02/16\ Member\ Fee\ Payment\ John\ Doe
\ \ \ \ assets:bank\ account\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR
\ \ \ \ income:member\ fees\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR
\ \ \ \ \ \ ;\ member:\ John\ Doe
\f[]
.fi
.PP
the \-\-pivot comand will output the following:
.IP
.nf
\f[C]
$\ hledger\ bal\ \-\-pivot\ member
\ \ \ \ 2\ EUR\ \ assets:bank\ account
\ \ \ \-2\ EUR\ \ member:John\ Doe
\f[]
.fi
.SH OPTIONS
.PP
To see general usage and the command list: \f[C]hledger\ \-h\f[] or just
@ -269,8 +290,8 @@ set start date, end date, and/or reporting interval all at once
.RS
.RE
.TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[]
use postings/txns\[aq] secondary dates instead
.B \f[C]\-\-date2\f[]
show, and match with \-b/\-e/\-p/date:, secondary dates instead
.RS
.RE
.TP
@ -308,12 +329,27 @@ show empty/zero things which are normally omitted
show amounts in their cost price\[aq]s commodity
.RS
.RE
.TP
.B `\-\-pivot TAG
will transform the journal before any other processing by replacing the
account name of every posting having the tag TAG with content VALUE by
the account name "TAG:VALUE".
.RS
.RE
The TAG will only match if it is a full\-length match.
The pivot will only happen if the TAG is on a posting, not if it is on
the transaction.
If the tag value is a multi:level:account:name the new account name will
be "TAG:multi:level:account:name".
.RS
.RE
.SS Multiple files
.PP
One may specify the \f[C]\-\-file\ FILE\f[] option multiple times.
This is equivalent to concatenating the files to standard input and
passing \f[C]\-\-file\ \-\f[], except that the add command functions
normally and adds entries to the first specified file.
You can specify multiple \f[C]\-f/\-\-file\ FILE\f[] options.
This is like combining all the files into one, except they can have
different formats.
Also directives and aliases in one file do not affect subsequent files
(if you need that, use the include directive instead).
.SS Repeated options
.PP
Otherwise, if a reporting option is repeated, the last one takes
@ -657,13 +693,16 @@ match transaction descriptions
.RE
.TP
.B \f[B]\f[C]date:PERIODEXPR\f[]\f[]
match dates within the specified period (which should not include a
reporting interval
match dates within the specified period.
PERIODEXPR should not include a reporting interval.
The command\-line \f[C]\-\-date2\f[] flag makes this match secondary
dates instead (like the \f[C]\-b\f[]/\f[C]\-e\f[]/\f[C]\-p\f[] options).
.RS
.RE
.TP
.B \f[B]\f[C]date2:PERIODEXPR\f[]\f[]
as above, but match secondary dates
match secondary dates within the specified period.
PERIODEXPR should not include a reporting interval.
.RS
.RE
.TP
@ -695,8 +734,6 @@ transaction.
before any of the above negates the match.
.RS
.RE
.PP
* * * * *
.PP
Some of these can also be expressed as command\-line options (eg
\f[C]depth:2\f[] is equivalent to \f[C]\-\-depth\ 2\f[]).
@ -827,8 +864,9 @@ Many hledger users edit their journals directly with a text editor, or
generate them from CSV.
For more interactive data entry, there is the \f[C]add\f[] command,
which prompts interactively on the console for new transactions, and
appends them to the journal file (existing transactions are not
changed).
appends them to the journal file (if there are multiple
\f[C]\-f\ FILE\f[] options, the first file is used.) Existing
transactions are not changed.
This is the only hledger command that writes to the journal file.
.PP
To use it, just run \f[C]hledger\ add\f[] and follow the prompts.
@ -2103,6 +2141,11 @@ $\ LEDGER_FILE=unique.journal\ hledger\ print\-unique
.PP
Prints all journal entries, adding specified custom postings to matched
entries.
.PP
hledger\-rewrite.hs, in hledger\[aq]s extra directory (compilation
optional), adds postings to existing transactions, optionally with an
amount based on the existing transaction\[aq]s first amount.
See the script for more details.
.IP
.nf
\f[C]

242
hledger/doc/hledger.1.info
View File

@ -114,6 +114,21 @@ $ hledger reg 'assets:some bank:checking' # show postings to/from this checking
$ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart
With the journal
2016/02/16 Member Fee Payment John Doe
assets:bank account 2 EUR
income:member fees -2 EUR
; member: John Doe
the -pivot comand will output the following:
$ hledger bal --pivot member
2 EUR assets:bank account
-2 EUR member:John Doe

File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
@ -204,8 +219,8 @@ command name.
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
`--date2 --aux-date'
use postings/txns' secondary dates instead
`--date2'
show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared'
include only cleared postings/txns
@ -228,6 +243,15 @@ command name.
`-B --cost'
show amounts in their cost price's commodity
`-pivot TAG
will transform the journal before any other processing by
replacing the account name of every posting having the tag TAG
with content VALUE by the account name "TAG:VALUE". The TAG will
only match if it is a full-length match. The pivot will only
happen if the TAG is on a posting, not if it is on the transaction.
If the tag value is a multi:level:account:name the new account
name will be "TAG:multi:level:account:name".
* Menu:
* Multiple files::
@ -244,10 +268,10 @@ File: hledger.1.info, Node: Multiple files, Next: Repeated options, Up: OPTIO
2.1 Multiple files
==================
One may specify the `--file FILE' option multiple times. This is
equivalent to concatenating the files to standard input and passing
`--file -', except that the add command functions normally and adds
entries to the first specified file.
You can specify multiple `-f/--file FILE' options. This is like
combining all the files into one, except they can have different
formats. Also directives and aliases in one file do not affect
subsequent files (if you need that, use the include directive instead).

File: hledger.1.info, Node: Repeated options, Next: Depth limiting, Prev: Multiple files, Up: OPTIONS
@ -480,11 +504,14 @@ match (or negatively match)
match transaction descriptions
*`date:PERIODEXPR'*
match dates within the specified period (which should not include a
reporting interval
match dates within the specified period. PERIODEXPR should not
include a reporting interval. The command-line `--date2' flag
makes this match secondary dates instead (like the `-b'/`-e'/`-p'
options).
*`date2:PERIODEXPR'*
as above, but match secondary dates
match secondary dates within the specified period. PERIODEXPR
should not include a reporting interval.
*`depth:N'*
match (or display, depending on command) accounts at or above this
@ -506,8 +533,7 @@ match (or negatively match)
*`not:'*
before any of the above negates the match.
-----------------------------------------------------------------------
Some of these can also be expressed as command-line options (eg
Some of these can also be expressed as command-line options (eg
`depth:2' is equivalent to `--depth 2'). Generally you can mix options
and query arguments, and the resulting query will be their intersection
(perhaps excluding the `-p/--period' option).
@ -648,8 +674,9 @@ Prompt for transactions and add them to the journal.
Many hledger users edit their journals directly with a text editor,
or generate them from CSV. For more interactive data entry, there is the
`add' command, which prompts interactively on the console for new
transactions, and appends them to the journal file (existing
transactions are not changed). This is the only hledger command that
transactions, and appends them to the journal file (if there are
multiple `-f FILE' options, the first file is used.) Existing
transactions are not changed. This is the only hledger command that
writes to the journal file.
To use it, just run `hledger add' and follow the prompts. You can
@ -1877,6 +1904,11 @@ File: hledger.1.info, Node: rewrite, Next: ui, Prev: print-unique, Up: ADD-O
Prints all journal entries, adding specified custom postings to matched
entries.
hledger-rewrite.hs, in hledger's extra directory (compilation
optional), adds postings to existing transactions, optionally with an
amount based on the existing transaction's first amount. See the script
for more details.
$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
@ -2009,97 +2041,97 @@ Tag Table:
Node: Top82
Node: EXAMPLES1754
Ref: #examples1856
Node: OPTIONS3508
Ref: #options3612
Node: Multiple files6386
Ref: #multiple-files6511
Node: Repeated options6750
Ref: #repeated-options6902
Node: Depth limiting7022
Ref: #depth-limiting7167
Node: Smart dates7368
Ref: #smart-dates7509
Node: Reporting interval8506
Ref: #reporting-interval8665
Node: Period expressions9008
Ref: #period-expressions9175
Node: Regular Expressions11221
Ref: #regular-expressions11363
Node: QUERIES12846
Ref: #queries12950
Node: COMMANDS16125
Ref: #commands16239
Node: accounts16912
Ref: #accounts17012
Node: activity17994
Ref: #activity18106
Node: add18465
Ref: #add18566
Node: balance21160
Ref: #balance21273
Node: Flat mode23989
Ref: #flat-mode24116
Node: Depth limited balance reports24535
Ref: #depth-limited-balance-reports24738
Node: Multicolumn balance reports25159
Ref: #multicolumn-balance-reports25361
Node: Market value30010
Ref: #market-value30174
Node: Custom balance output30667
Ref: #custom-balance-output30840
Node: Output destination32944
Ref: #output-destination33109
Node: CSV output33379
Ref: #csv-output33498
Node: balancesheet33895
Ref: #balancesheet34023
Node: cashflow34675
Ref: #cashflow34792
Node: help35482
Ref: #help35594
Node: incomestatement36431
Ref: #incomestatement36561
Node: info37288
Ref: #info37395
Node: man37757
Ref: #man37854
Node: print38257
Ref: #print38362
Node: register39713
Ref: #register39826
Node: Custom register output44167
Ref: #custom-register-output44298
Node: stats45595
Ref: #stats45701
Node: test46582
Ref: #test46669
Node: ADD-ON COMMANDS47036
Ref: #add-on-commands47172
Node: api48460
Ref: #api48552
Node: autosync48586
Ref: #autosync48701
Node: diff51016
Ref: #diff51126
Node: equity51790
Ref: #equity51904
Node: interest53232
Ref: #interest53349
Node: irr56433
Ref: #irr56546
Node: print-unique58921
Ref: #print-unique59051
Node: rewrite59309
Ref: #rewrite59428
Node: ui59731
Ref: #ui59831
Node: web59872
Ref: #web59960
Node: TROUBLESHOOTING59993
Ref: #troubleshooting60112
Node: Run-time problems60166
Ref: #run-time-problems60309
Node: Known limitations62253
Ref: #known-limitations62396
Node: OPTIONS3860
Ref: #options3964
Node: Multiple files7217
Ref: #multiple-files7342
Node: Repeated options7607
Ref: #repeated-options7759
Node: Depth limiting7879
Ref: #depth-limiting8024
Node: Smart dates8225
Ref: #smart-dates8366
Node: Reporting interval9363
Ref: #reporting-interval9522
Node: Period expressions9865
Ref: #period-expressions10032
Node: Regular Expressions12078
Ref: #regular-expressions12220
Node: QUERIES13703
Ref: #queries13807
Node: COMMANDS17109
Ref: #commands17223
Node: accounts17896
Ref: #accounts17996
Node: activity18978
Ref: #activity19090
Node: add19449
Ref: #add19550
Node: balance22209
Ref: #balance22322
Node: Flat mode25038
Ref: #flat-mode25165
Node: Depth limited balance reports25584
Ref: #depth-limited-balance-reports25787
Node: Multicolumn balance reports26208
Ref: #multicolumn-balance-reports26410
Node: Market value31059
Ref: #market-value31223
Node: Custom balance output31716
Ref: #custom-balance-output31889
Node: Output destination33993
Ref: #output-destination34158
Node: CSV output34428
Ref: #csv-output34547
Node: balancesheet34944
Ref: #balancesheet35072
Node: cashflow35724
Ref: #cashflow35841
Node: help36531
Ref: #help36643
Node: incomestatement37480
Ref: #incomestatement37610
Node: info38337
Ref: #info38444
Node: man38806
Ref: #man38903
Node: print39306
Ref: #print39411
Node: register40762
Ref: #register40875
Node: Custom register output45216
Ref: #custom-register-output45347
Node: stats46644
Ref: #stats46750
Node: test47631
Ref: #test47718
Node: ADD-ON COMMANDS48085
Ref: #add-on-commands48221
Node: api49509
Ref: #api49601
Node: autosync49635
Ref: #autosync49750
Node: diff52065
Ref: #diff52175
Node: equity52839
Ref: #equity52953
Node: interest54281
Ref: #interest54398
Node: irr57482
Ref: #irr57595
Node: print-unique59970
Ref: #print-unique60100
Node: rewrite60358
Ref: #rewrite60477
Node: ui61006
Ref: #ui61106
Node: web61147
Ref: #web61235
Node: TROUBLESHOOTING61268
Ref: #troubleshooting61387
Node: Run-time problems61441
Ref: #run-time-problems61584
Node: Known limitations63528
Ref: #known-limitations63671

End Tag Table

57
hledger/doc/hledger.1.txt
View File

@ -103,6 +103,19 @@ EEXXAAMMPPLLEESS
$ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart
With the journal
2016/02/16 Member Fee Payment John Doe
assets:bank account 2 EUR
income:member fees -2 EUR
; member: John Doe
the --pivot comand will output the following:
$ hledger bal --pivot member
2 EUR assets:bank account
-2 EUR member:John Doe
OOPPTTIIOONNSS
To see general usage and the command list: hledger -h or just hledger
@ -181,8 +194,8 @@ OOPPTTIIOONNSS
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
----ddaattee22 ----aauuxx--ddaattee
use postings/txns' secondary dates instead
----ddaattee22
show, and match with -b/-e/-p/date:, secondary dates instead
--CC ----cclleeaarreedd
include only cleared postings/txns
@ -205,11 +218,20 @@ OOPPTTIIOONNSS
--BB ----ccoosstt
show amounts in their cost price's commodity
``----ppiivvoott TTAAGG
will transform the journal before any other processing by
replacing the account name of every posting having the tag TAG
with content VALUE by the account name "TAG:VALUE".
The TAG will only match if it is a full-length match. The pivot will
only happen if the TAG is on a posting, not if it is on the transac-
tion. If the tag value is a multi:level:account:name the new account
name will be "TAG:multi:level:account:name".
MMuullttiippllee ffiilleess
One may specify the --file FILE option multiple times. This is equiva-
lent to concatenating the files to standard input and passing --file -,
except that the add command functions normally and adds entries to the
first specified file.
You can specify multiple -f/--file FILE options. This is like combin-
ing all the files into one, except they can have different formats.
Also directives and aliases in one file do not affect subsequent files
(if you need that, use the include directive instead).
RReeppeeaatteedd ooppttiioonnss
Otherwise, if a reporting option is repeated, the last one takes prece-
@ -404,11 +426,14 @@ QQUUEERRIIEESS
match transaction descriptions
ddaattee::PPEERRIIOODDEEXXPPRR
match dates within the specified period (which should not
include a reporting interval
match dates within the specified period. PERIODEXPR should not
include a reporting interval. The command-line --date2 flag
makes this match secondary dates instead (like the -b/-e/-p
options).
ddaattee22::PPEERRIIOODDEEXXPPRR
as above, but match secondary dates
match secondary dates within the specified period. PERIODEXPR
should not include a reporting interval.
ddeepptthh::NN
match (or display, depending on command) accounts at or above
@ -429,8 +454,6 @@ QQUUEERRIIEESS
nnoott:: before any of the above negates the match.
* * * * *
Some of these can also be expressed as command-line options (eg depth:2
is equivalent to --depth 2). Generally you can mix options and query
arguments, and the resulting query will be their intersection (perhaps
@ -529,9 +552,10 @@ CCOOMMMMAANNDDSS
Many hledger users edit their journals directly with a text editor, or
generate them from CSV. For more interactive data entry, there is the
add command, which prompts interactively on the console for new trans-
actions, and appends them to the journal file (existing transactions
are not changed). This is the only hledger command that writes to the
journal file.
actions, and appends them to the journal file (if there are multiple
-f FILE options, the first file is used.) Existing transactions are not
changed. This is the only hledger command that writes to the journal
file.
To use it, just run hledger add and follow the prompts. You can add as
many transactions as you like; when you are finished, enter . or press
@ -1539,6 +1563,11 @@ AADDDD--OONN CCOOMMMMAANNDDSS
Prints all journal entries, adding specified custom postings to matched
entries.
hledger-rewrite.hs, in hledger's extra directory (compilation
optional), adds postings to existing transactions, optionally with an
amount based on the existing transaction's first amount. See the
script for more details.
$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'