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

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2022-07-25 03:32:30 +01:00
parent da2b8f5f34
commit 1c4f02cf03
3 changed files with 1675 additions and 1379 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

161
hledger/hledger.1
View File

@ -1656,7 +1656,7 @@ hledger can do cost reporting
.PP .PP
Con: Con:
.IP \[bu] 2 .IP \[bu] 2
Disturbs the accounting equation Disturbs the accounting equation without the --infer-equity flag
.SS Equity conversion .SS Equity conversion
.PP .PP
In strict double entry bookkeeping, the above transaction is not In strict double entry bookkeeping, the above transaction is not
@ -1685,6 +1685,9 @@ Preserves the accounting equation
keeps track of conversions and related gains/losses in one place keeps track of conversions and related gains/losses in one place
.IP \[bu] 2 .IP \[bu] 2
works in any double entry accounting system works in any double entry accounting system
.IP \[bu] 2
hledger can convert this to transaction prices using the --infer-costs
flag
.PP .PP
Con: Con:
.IP \[bu] 2 .IP \[bu] 2
@ -1692,11 +1695,11 @@ More verbose
.IP \[bu] 2 .IP \[bu] 2
conversion rate is not clear conversion rate is not clear
.IP \[bu] 2 .IP \[bu] 2
hledger can not do cost reporting depends on the order of postings
.SS Priced equity conversion .SS Priced equity conversion
.PP .PP
Another possible notation would be to record both the conversion rate Another notation is to record both the conversion rate and the equity
and the equity postings: postings:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1708,8 +1711,25 @@ and the equity postings:
\f[R] \f[R]
.fi .fi
.PP .PP
hledger currently does not allow this; instead, you can record the Pro:
conversion rate as a comment. .IP \[bu] 2
Preserves the accounting equation
.IP \[bu] 2
keeps track of conversions and related gains/losses in one place
.IP \[bu] 2
makes the conversion rate clear
.IP \[bu] 2
provides some error checking
.IP \[bu] 2
hledger can do cost reporting
.PP
Con:
.IP \[bu] 2
Most verbose
.IP \[bu] 2
Requires --infer-costs flag
.IP \[bu] 2
Not compatible with ledger
.SS Inferring missing conversion rates .SS Inferring missing conversion rates
.PP .PP
hledger will do this automatically for implicit conversions. hledger will do this automatically for implicit conversions.
@ -1717,8 +1737,12 @@ Currently it can not do this for equity conversions.
.SS Inferring missing equity postings .SS Inferring missing equity postings
.PP .PP
With the \f[C]--infer-equity\f[R] flag, hledger will add equity postings With the \f[C]--infer-equity\f[R] flag, hledger will add equity postings
to priced and implicit conversions (and move the conversion rate into a to priced and implicit conversions.
comment). .SS Inferring missing transaction prices from equity postings
.PP
With the \f[C]--infer-costs\f[R] flag, hledger will add transaction
prices from equity postings, and will be able to handle transaction
prices and equity postings together.
.SS Cost reporting .SS Cost reporting
.PP .PP
With the \f[C]-B/--cost\f[R] flag, hledger will convert the amounts in With the \f[C]-B/--cost\f[R] flag, hledger will convert the amounts in
@ -1730,7 +1754,8 @@ it disables \f[C]--infer-equity\f[R].
.PP .PP
These operations are transient, only affecting reports. These operations are transient, only affecting reports.
If you want to change the journal file permanently, you could pipe each If you want to change the journal file permanently, you could pipe each
entry through \f[C]hledger -f- -I print [-x] [--infer-equity] [-B]\f[R] entry through
\f[C]hledger -f- -I print [-x] [--infer-equity] [--infer-costs] [-B]\f[R]
.SS Conversion summary .SS Conversion summary
.IP \[bu] 2 .IP \[bu] 2
Recording the conversion rate is good because it makes that clear and Recording the conversion rate is good because it makes that clear and
@ -1739,9 +1764,8 @@ allows cost reporting.
Recording equity postings is good because it balances the accounting Recording equity postings is good because it balances the accounting
equation and is correct bookkeeping. equation and is correct bookkeeping.
.IP \[bu] 2 .IP \[bu] 2
Combining these is not yet supported, so you have to choose. Combining these is possible with the --infer-costs flag, but has certain
For now, priced conversions are a good compromise, so that: requirements for the order of postings.
.RS 2
.IP \[bu] 2 .IP \[bu] 2
When you want to see the cost (or sale proceeds) of things, use When you want to see the cost (or sale proceeds) of things, use
\f[C]-B/--cost\f[R]. \f[C]-B/--cost\f[R].
@ -1749,9 +1773,8 @@ When you want to see the cost (or sale proceeds) of things, use
When you want to see a balanced balance sheet or correct journal When you want to see a balanced balance sheet or correct journal
entries, use \f[C]--infer-equity\f[R]. entries, use \f[C]--infer-equity\f[R].
.IP \[bu] 2 .IP \[bu] 2
Combining these is not yet supported; \f[C]-B/--cost\f[R] will take \f[C]--cost\f[R] will remove any balancing equity posts, so as not to
precedence. disturb the accounting equation.
.RE
.IP \[bu] 2 .IP \[bu] 2
Conversion/cost operations are performed before valuation. Conversion/cost operations are performed before valuation.
.SH VALUATION .SH VALUATION
@ -2926,25 +2949,25 @@ tags - show tag names
.IP \[bu] 2 .IP \[bu] 2
test - run self tests test - run self tests
.PP .PP
.PP
\f[B]Add-on commands:\f[R] \f[B]Add-on commands:\f[R]
.PP .PP
Programs or scripts named \f[C]hledger-SOMETHING\f[R] in your PATH are Programs or scripts named \f[C]hledger-SOMETHING\f[R] in your PATH are
add-on commands; these appear in the commands list with a \f[C]+\f[R] add-on commands; these appear in the commands list with a \f[C]+\f[R]
mark. mark.
Two of these are maintained and released with hledger: The following add-on commands can be installed, eg by the
hledger-install script:
.IP \[bu] 2 .IP \[bu] 2
\f[B]ui\f[R] - an efficient terminal interface (TUI) for hledger \f[B]ui\f[R] - hledger\[aq]s official curses-style TUI
.IP \[bu] 2 .IP \[bu] 2
\f[B]web\f[R] - a simple web interface (WUI) for hledger \f[B]web\f[R] - hledger\[aq]s official web UI
.PP
And these add-ons are maintained separately:
.IP \[bu] 2 .IP \[bu] 2
iadd - a more interactive alternative for the add command iadd - a popular alternative to hledger\[aq]s \f[C]add\f[R] command.
.IP \[bu] 2 .IP \[bu] 2
interest - generates interest transactions according to various schemes interest - generates interest transactions
.IP \[bu] 2 .IP \[bu] 2
stockquotes - downloads market prices for your commodities from stockquotes - downloads market prices.
AlphaVantage \f[I](experimental)\f[R] \f[I](Alpha quality, needs your help.)\f[R]
.PP .PP
Next, the detailed command docs, in alphabetical order. Next, the detailed command docs, in alphabetical order.
.SS accounts .SS accounts
@ -6192,7 +6215,7 @@ $ hledger test -- -pData.Amount --color=never
.PP .PP
For help on these, see https://github.com/feuerbach/tasty#options For help on these, see https://github.com/feuerbach/tasty#options
(\f[C]-- --help\f[R] currently doesn\[aq]t show them). (\f[C]-- --help\f[R] currently doesn\[aq]t show them).
.SS About add-on commands .SS Add-on commands
.PP .PP
Add-on commands are programs or scripts in your PATH Add-on commands are programs or scripts in your PATH
.IP \[bu] 2 .IP \[bu] 2
@ -7031,6 +7054,94 @@ $ hledger bal -N --flat -B
\[Eu]100 assets:euros \[Eu]100 assets:euros
\f[R] \f[R]
.fi .fi
.SS Equity conversion postings
.PP
Transaction prices can be converted to and from equity conversion
postings using the \f[C]--infer-equity\f[R] and \f[C]--infer-costs\f[R]
flags.
.PP
With \f[C]--infer-equity\f[R], hledger will add equity postings to
balance out any transaction prices.
.IP
.nf
\f[C]
2009/1/1
assets:euros \[Eu]100 \[at] $1.35 ; 100 euros bought
assets:dollars -$135 ; for $135
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger print --infer-equity
2009-01-01
assets:euros \[Eu]100 \[at] $1.35 ; 100 euros bought
equity:conversion:$-\[Eu]:\[Eu] \[Eu]-100 ; 100 euros bought, generated-posting:
equity:conversion:$-\[Eu]:$ $135.00 ; 100 euros bought, generated-posting:
assets:dollars $-135 ; for $135
\f[R]
.fi
.PP
The reverse is possible using \f[C]--infer-costs\f[R], which will check
any equity conversion postings and generate a transaction price for the
\f[I]first\f[R] non-conversion posting which matches.
.IP
.nf
\f[C]
2009-01-01
assets:euros \[Eu]100 ; 100 euros bought
equity:conversion \[Eu]-100
equity:conversion $135
assets:dollars $-135 ; for $135
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger print --infer-costs
2009-01-01
assets:euros \[Eu]100 \[at]\[at] $135 ; 100 euros bought
equity:conversion \[Eu]-100
equity:conversion $135
assets:dollars $-135 ; for $135
\f[R]
.fi
.PP
Note that the above will assign the transaction price to the first
matching posting in the transaction.
If you want to assign it to a different posting, or if you have several
different sets of conversion postings which must match different
postings, you must manually specify the transaction price.
If you do this, equity conversion postings must occur in adjacent pairs
and must exactly match the amount of a non-conversion posting.
.IP
.nf
\f[C]
2009-01-01
assets:dollars $-135 ; $135 paid
equity:conversion \[Eu]-100
equity:conversion $135
assets:euros \[Eu]100 \[at]\[at] $135 ; to buy 100 euros
\f[R]
.fi
.IP
.nf
\f[C]
2009-01-01
assets:euros \[Eu]100 \[at] $1.35 ; 100 euros bought
equity:conversion \[Eu]-100
equity:conversion $135
assets:pounds \[Po]80 \[at]\[at] $100 ; 80 pounds bought
equity:conversion \[Po]-80
equity:conversion $100
assets:dollars $-235 ; for $235 total
\f[R]
.fi
.PP
The account names used for the conversion accounts can be changed with
the conversion account type declaration.
.SS Lot prices, lot dates .SS Lot prices, lot dates
.PP .PP
Ledger allows another kind of price, lot price (four variants: Ledger allows another kind of price, lot price (four variants:

1118
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

145
hledger/hledger.txt
View File

@ -1134,7 +1134,7 @@ CONVERSION & COST
Con: Con:
o Disturbs the accounting equation o Disturbs the accounting equation without the --infer-equity flag
Equity conversion Equity conversion
In strict double entry bookkeeping, the above transaction is not bal- In strict double entry bookkeeping, the above transaction is not bal-
@ -1159,17 +1159,20 @@ CONVERSION & COST
o works in any double entry accounting system o works in any double entry accounting system
o hledger can convert this to transaction prices using the --infer-
costs flag
Con: Con:
o More verbose o More verbose
o conversion rate is not clear o conversion rate is not clear
o hledger can not do cost reporting o depends on the order of postings
Priced equity conversion Priced equity conversion
Another possible notation would be to record both the conversion rate Another notation is to record both the conversion rate and the equity
and the equity postings: postings:
2021-01-01 2021-01-01
assets:cash -100 EUR @ 1.20 USD assets:cash -100 EUR @ 1.20 USD
@ -1177,8 +1180,25 @@ CONVERSION & COST
equity:conversion -120 USD equity:conversion -120 USD
assets:cash 120 USD assets:cash 120 USD
hledger currently does not allow this; instead, you can record the con- Pro:
version rate as a comment.
o Preserves the accounting equation
o keeps track of conversions and related gains/losses in one place
o makes the conversion rate clear
o provides some error checking
o hledger can do cost reporting
Con:
o Most verbose
o Requires --infer-costs flag
o Not compatible with ledger
Inferring missing conversion rates Inferring missing conversion rates
hledger will do this automatically for implicit conversions. Currently hledger will do this automatically for implicit conversions. Currently
@ -1186,8 +1206,12 @@ CONVERSION & COST
Inferring missing equity postings Inferring missing equity postings
With the --infer-equity flag, hledger will add equity postings to With the --infer-equity flag, hledger will add equity postings to
priced and implicit conversions (and move the conversion rate into a priced and implicit conversions.
comment).
Inferring missing transaction prices from equity postings
With the --infer-costs flag, hledger will add transaction prices from
equity postings, and will be able to handle transaction prices and
equity postings together.
Cost reporting Cost reporting
With the -B/--cost flag, hledger will convert the amounts in priced and With the -B/--cost flag, hledger will convert the amounts in priced and
@ -1198,7 +1222,7 @@ CONVERSION & COST
These operations are transient, only affecting reports. If you want to These operations are transient, only affecting reports. If you want to
change the journal file permanently, you could pipe each entry through change the journal file permanently, you could pipe each entry through
hledger -f- -I print [-x] [--infer-equity] [-B] hledger -f- -I print [-x] [--infer-equity] [--infer-costs] [-B]
Conversion summary Conversion summary
o Recording the conversion rate is good because it makes that clear and o Recording the conversion rate is good because it makes that clear and
@ -1207,8 +1231,8 @@ CONVERSION & COST
o Recording equity postings is good because it balances the accounting o Recording equity postings is good because it balances the accounting
equation and is correct bookkeeping. equation and is correct bookkeeping.
o Combining these is not yet supported, so you have to choose. For o Combining these is possible with the --infer-costs flag, but has cer-
now, priced conversions are a good compromise, so that: tain requirements for the order of postings.
o When you want to see the cost (or sale proceeds) of things, use o When you want to see the cost (or sale proceeds) of things, use
-B/--cost. -B/--cost.
@ -1216,8 +1240,8 @@ CONVERSION & COST
o When you want to see a balanced balance sheet or correct journal o When you want to see a balanced balance sheet or correct journal
entries, use --infer-equity. entries, use --infer-equity.
o Combining these is not yet supported; -B/--cost will take prece- o --cost will remove any balancing equity posts, so as not to disturb
dence. the accounting equation.
o Conversion/cost operations are performed before valuation. o Conversion/cost operations are performed before valuation.
@ -1563,6 +1587,9 @@ VALUATION
posting cost value at value at posting value at value at posting cost value at value at posting value at value at
amounts report end date report or DATE/today amounts report end date report or DATE/today
or today journal end or today journal end
balance unchanged unchanged unchanged unchanged unchanged balance unchanged unchanged unchanged unchanged unchanged
asser- asser-
tions/assign- tions/assign-
@ -1602,8 +1629,6 @@ VALUATION
played val- played val- valued played val- played values played val- played val- valued played val- played values
ues ues ues ues ues ues
balance (bs, balance (bs,
bse, cf, is) bse, cf, is)
with report with report
@ -1633,6 +1658,8 @@ VALUATION
row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis- row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis-
(-T, -A) played val- played val- played val- played values (-T, -A) played val- played val- played val- played values
ues ues ues ues ues ues
column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis-
played val- played val- values played val- played values played val- played val- values played val- played values
ues ues ues ues ues ues
@ -1771,6 +1798,8 @@ OUTPUT
balance Y 1 Y 1 Y 1,2 Y balance Y 1 Y 1 Y 1,2 Y
bal- Y 1 Y 1 Y 1 Y bal- Y 1 Y 1 Y 1 Y
ancesheet ancesheet
bal- Y 1 Y 1 Y 1 Y bal- Y 1 Y 1 Y 1 Y
ancesheete- ancesheete-
quity quity
@ -1935,25 +1964,23 @@ COMMANDS
o test - run self tests o test - run self tests
Add-on commands: Add-on commands:
Programs or scripts named hledger-SOMETHING in your PATH are add-on Programs or scripts named hledger-SOMETHING in your PATH are add-on
commands; these appear in the commands list with a + mark. Two of commands; these appear in the commands list with a + mark. The follow-
these are maintained and released with hledger: ing add-on commands can be installed, eg by the hledger-install script:
o ui - an efficient terminal interface (TUI) for hledger o ui - hledger's official curses-style TUI
o web - a simple web interface (WUI) for hledger o web - hledger's official web UI
And these add-ons are maintained separately: o iadd - a popular alternative to hledger's add command.
o iadd - a more interactive alternative for the add command o interest - generates interest transactions
o interest - generates interest transactions according to various o stockquotes - downloads market prices. (Alpha quality, needs your
schemes help.)
o stockquotes - downloads market prices for your commodities from
AlphaVantage (experimental)
Next, the detailed command docs, in alphabetical order. Next, the detailed command docs, in alphabetical order.
@ -2708,7 +2735,6 @@ COMMANDS
tion show: tion show:
Valua- no valuation --value= then --value= end --value= YYYY- Valua- no valuation --value= then --value= end --value= YYYY-
tion: MM-DD /now tion: MM-DD /now
>Accumu- >Accumu-
@ -4424,7 +4450,7 @@ COMMANDS
For help on these, see https://github.com/feuerbach/tasty#options (-- For help on these, see https://github.com/feuerbach/tasty#options (--
--help currently doesn't show them). --help currently doesn't show them).
About add-on commands Add-on commands
Add-on commands are programs or scripts in your PATH Add-on commands are programs or scripts in your PATH
o whose name starts with hledger- o whose name starts with hledger-
@ -5031,6 +5057,69 @@ JOURNAL FORMAT
EUR-100 assets:dollars # <- the dollars' selling price EUR-100 assets:dollars # <- the dollars' selling price
EUR100 assets:euros EUR100 assets:euros
Equity conversion postings
Transaction prices can be converted to and from equity conversion post-
ings using the --infer-equity and --infer-costs flags.
With --infer-equity, hledger will add equity postings to balance out
any transaction prices.
2009/1/1
assets:euros EUR100 @ $1.35 ; 100 euros bought
assets:dollars -$135 ; for $135
$ hledger print --infer-equity
2009-01-01
assets:euros EUR100 @ $1.35 ; 100 euros bought
equity:conversion:$-EUR:EUR EUR-100 ; 100 euros bought, generated-posting:
equity:conversion:$-EUR:$ $135.00 ; 100 euros bought, generated-posting:
assets:dollars $-135 ; for $135
The reverse is possible using --infer-costs, which will check any
equity conversion postings and generate a transaction price for the
first non-conversion posting which matches.
2009-01-01
assets:euros EUR100 ; 100 euros bought
equity:conversion EUR-100
equity:conversion $135
assets:dollars $-135 ; for $135
$ hledger print --infer-costs
2009-01-01
assets:euros EUR100 @@ $135 ; 100 euros bought
equity:conversion EUR-100
equity:conversion $135
assets:dollars $-135 ; for $135
Note that the above will assign the transaction price to the first
matching posting in the transaction. If you want to assign it to a
different posting, or if you have several different sets of conversion
postings which must match different postings, you must manually specify
the transaction price. If you do this, equity conversion postings must
occur in adjacent pairs and must exactly match the amount of a non-con-
version posting.
2009-01-01
assets:dollars $-135 ; $135 paid
equity:conversion EUR-100
equity:conversion $135
assets:euros EUR100 @@ $135 ; to buy 100 euros
2009-01-01
assets:euros EUR100 @ $1.35 ; 100 euros bought
equity:conversion EUR-100
equity:conversion $135
assets:pounds 80 @@ $100 ; 80 pounds bought
equity:conversion -80
equity:conversion $100
assets:dollars $-235 ; for $235 total
The account names used for the conversion accounts can be changed with
the conversion account type declaration.
Lot prices, lot dates Lot prices, lot dates
Ledger allows another kind of price, lot price (four variants: {UNIT- Ledger allows another kind of price, lot price (four variants: {UNIT-
PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}), PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}),