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
Con:
.IP \[bu] 2
Disturbs the accounting equation
Disturbs the accounting equation without the --infer-equity flag
.SS Equity conversion
.PP
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
.IP \[bu] 2
works in any double entry accounting system
.IP \[bu] 2
hledger can convert this to transaction prices using the --infer-costs
flag
.PP
Con:
.IP \[bu] 2
@ -1692,11 +1695,11 @@ More verbose
.IP \[bu] 2
conversion rate is not clear
.IP \[bu] 2
hledger can not do cost reporting
depends on the order of postings
.SS Priced equity conversion
.PP
Another possible notation would be to record both the conversion rate
and the equity postings:
Another notation is to record both the conversion rate and the equity
postings:
.IP
.nf
\f[C]
@ -1708,8 +1711,25 @@ and the equity postings:
\f[R]
.fi
.PP
hledger currently does not allow this; instead, you can record the
conversion rate as a comment.
Pro:
.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
.PP
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
.PP
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
comment).
to priced and implicit conversions.
.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
.PP
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
These operations are transient, only affecting reports.
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
.IP \[bu] 2
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
equation and is correct bookkeeping.
.IP \[bu] 2
Combining these is not yet supported, so you have to choose.
For now, priced conversions are a good compromise, so that:
.RS 2
Combining these is possible with the --infer-costs flag, but has certain
requirements for the order of postings.
.IP \[bu] 2
When you want to see the cost (or sale proceeds) of things, use
\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
entries, use \f[C]--infer-equity\f[R].
.IP \[bu] 2
Combining these is not yet supported; \f[C]-B/--cost\f[R] will take
precedence.
.RE
\f[C]--cost\f[R] will remove any balancing equity posts, so as not to
disturb the accounting equation.
.IP \[bu] 2
Conversion/cost operations are performed before valuation.
.SH VALUATION
@ -2926,25 +2949,25 @@ tags - show tag names
.IP \[bu] 2
test - run self tests
.PP
.PP
\f[B]Add-on commands:\f[R]
.PP
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]
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
\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
\f[B]web\f[R] - a simple web interface (WUI) for hledger
.PP
And these add-ons are maintained separately:
\f[B]web\f[R] - hledger\[aq]s official web UI
.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
interest - generates interest transactions according to various schemes
interest - generates interest transactions
.IP \[bu] 2
stockquotes - downloads market prices for your commodities from
AlphaVantage \f[I](experimental)\f[R]
stockquotes - downloads market prices.
\f[I](Alpha quality, needs your help.)\f[R]
.PP
Next, the detailed command docs, in alphabetical order.
.SS accounts
@ -6192,7 +6215,7 @@ $ hledger test -- -pData.Amount --color=never
.PP
For help on these, see https://github.com/feuerbach/tasty#options
(\f[C]-- --help\f[R] currently doesn\[aq]t show them).
.SS About add-on commands
.SS Add-on commands
.PP
Add-on commands are programs or scripts in your PATH
.IP \[bu] 2
@ -7031,6 +7054,94 @@ $ hledger bal -N --flat -B
\[Eu]100 assets:euros
\f[R]
.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
.PP
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:
o Disturbs the accounting equation
o Disturbs the accounting equation without the --infer-equity flag
Equity conversion
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 hledger can convert this to transaction prices using the --infer-
costs flag
Con:
o More verbose
o conversion rate is not clear
o hledger can not do cost reporting
o depends on the order of postings
Priced equity conversion
Another possible notation would be to record both the conversion rate
and the equity postings:
Another notation is to record both the conversion rate and the equity
postings:
2021-01-01
assets:cash -100 EUR @ 1.20 USD
@ -1177,8 +1180,25 @@ CONVERSION & COST
equity:conversion -120 USD
assets:cash 120 USD
hledger currently does not allow this; instead, you can record the con-
version rate as a comment.
Pro:
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
hledger will do this automatically for implicit conversions. Currently
@ -1186,8 +1206,12 @@ CONVERSION & COST
Inferring missing equity postings
With the --infer-equity flag, hledger will add equity postings to
priced and implicit conversions (and move the conversion rate into a
comment).
priced and implicit conversions.
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
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
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
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
equation and is correct bookkeeping.
o Combining these is not yet supported, so you have to choose. For
now, priced conversions are a good compromise, so that:
o Combining these is possible with the --infer-costs flag, but has cer-
tain requirements for the order of postings.
o When you want to see the cost (or sale proceeds) of things, use
-B/--cost.
@ -1216,8 +1240,8 @@ CONVERSION & COST
o When you want to see a balanced balance sheet or correct journal
entries, use --infer-equity.
o Combining these is not yet supported; -B/--cost will take prece-
dence.
o --cost will remove any balancing equity posts, so as not to disturb
the accounting equation.
o Conversion/cost operations are performed before valuation.
@ -1563,6 +1587,9 @@ VALUATION
posting cost value at value at posting value at value at
amounts report end date report or DATE/today
or today journal end
balance unchanged unchanged unchanged unchanged unchanged
asser-
tions/assign-
@ -1602,8 +1629,6 @@ VALUATION
played val- played val- valued played val- played values
ues ues ues
balance (bs,
bse, cf, is)
with report
@ -1633,6 +1658,8 @@ VALUATION
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
ues ues ues
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
ues ues ues
@ -1771,6 +1798,8 @@ OUTPUT
balance Y 1 Y 1 Y 1,2 Y
bal- Y 1 Y 1 Y 1 Y
ancesheet
bal- Y 1 Y 1 Y 1 Y
ancesheete-
quity
@ -1935,25 +1964,23 @@ COMMANDS
o test - run self tests
Add-on commands:
Programs or scripts named hledger-SOMETHING in your PATH are add-on
commands; these appear in the commands list with a + mark. Two of
these are maintained and released with hledger:
commands; these appear in the commands list with a + mark. The follow-
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
schemes
o stockquotes - downloads market prices for your commodities from
AlphaVantage (experimental)
o stockquotes - downloads market prices. (Alpha quality, needs your
help.)
Next, the detailed command docs, in alphabetical order.
@ -2708,7 +2735,6 @@ COMMANDS
tion show:
Valua- no valuation --value= then --value= end --value= YYYY-
tion: MM-DD /now
>Accumu-
@ -4424,7 +4450,7 @@ COMMANDS
For help on these, see https://github.com/feuerbach/tasty#options (--
--help currently doesn't show them).
About add-on commands
Add-on commands
Add-on commands are programs or scripts in your PATH
o whose name starts with hledger-
@ -5031,6 +5057,69 @@ JOURNAL FORMAT
EUR-100 assets:dollars # <- the dollars' selling price
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
Ledger allows another kind of price, lot price (four variants: {UNIT-
PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}),