;doc: update manuals

hledger-lib/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{August 2022}})m4_dnl
+m4_define({{_monthyear_}}, {{September 2022}})m4_dnl

hledger-ui/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{August 2022}})m4_dnl
+m4_define({{_monthyear_}}, {{September 2022}})m4_dnl

hledger-ui/hledger-ui.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER-UI" "1" "August 2022" "hledger-ui-1.26.99 " "hledger User Manuals"
+.TH "HLEDGER-UI" "1" "September 2022" "hledger-ui-1.27 " "hledger User Manuals"
 
 
 
@@ -7,7 +7,7 @@
 .PP
 hledger-ui is a terminal interface (TUI) for the hledger accounting
 tool.
-This manual is for hledger-ui 1.26.99.
+This manual is for hledger-ui 1.27.
 .SH SYNOPSIS
 .PP
 \f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]

hledger-ui/hledger-ui.info

@@ -12,7 +12,7 @@ hledger-ui(1)
 *************
 
 hledger-ui is a terminal interface (TUI) for the hledger accounting
-tool.  This manual is for hledger-ui 1.26.99.
+tool.  This manual is for hledger-ui 1.27.
 
    'hledger-ui [OPTIONS] [QUERYARGS]'
 'hledger ui -- [OPTIONS] [QUERYARGS]'
@@ -640,34 +640,34 @@ program is restarted.
 
 Tag Table:
 Node: Top221
-Node: OPTIONS1657
+Node: OPTIONS1654
-Ref: #options1755
+Ref: #options1752
-Node: MOUSE6637
+Node: MOUSE6634
-Ref: #mouse6732
+Ref: #mouse6729
-Node: KEYS7014
+Node: KEYS7011
-Ref: #keys7107
+Ref: #keys7104
-Node: SCREENS11193
+Node: SCREENS11190
-Ref: #screens11291
+Ref: #screens11288
-Node: Accounts screen11381
+Node: Accounts screen11378
-Ref: #accounts-screen11509
+Ref: #accounts-screen11506
-Node: Register screen13848
+Node: Register screen13845
-Ref: #register-screen14003
+Ref: #register-screen14000
-Node: Transaction screen15987
+Node: Transaction screen15984
-Ref: #transaction-screen16145
+Ref: #transaction-screen16142
-Node: Error screen17015
+Node: Error screen17012
-Ref: #error-screen17137
+Ref: #error-screen17134
-Node: TIPS17381
+Node: TIPS17378
-Ref: #tips17480
+Ref: #tips17477
-Node: Watch mode17532
+Node: Watch mode17529
-Ref: #watch-mode17649
+Ref: #watch-mode17646
-Node: Watch mode limitations18399
+Node: Watch mode limitations18396
-Ref: #watch-mode-limitations18540
+Ref: #watch-mode-limitations18537
-Node: ENVIRONMENT19676
+Node: ENVIRONMENT19673
-Ref: #environment19787
+Ref: #environment19784
-Node: FILES21172
+Node: FILES21169
-Ref: #files21271
+Ref: #files21268
-Node: BUGS21484
+Node: BUGS21481
-Ref: #bugs21561
+Ref: #bugs21558
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -5,7 +5,7 @@ HLEDGER-UI(1)                hledger User Manuals                HLEDGER-UI(1)
 
 NAME
        hledger-ui  is  a  terminal  interface (TUI) for the hledger accounting
-       tool.  This manual is for hledger-ui 1.26.99.
+       tool.  This manual is for hledger-ui 1.27.
 
 SYNOPSIS
        hledger-ui [OPTIONS] [QUERYARGS]
@@ -549,4 +549,4 @@ SEE ALSO
 
 
 
-hledger-ui-1.26.99                August 2022                    HLEDGER-UI(1)
+hledger-ui-1.27                 September 2022                   HLEDGER-UI(1)

hledger-web/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{August 2022}})m4_dnl
+m4_define({{_monthyear_}}, {{September 2022}})m4_dnl

hledger-web/hledger-web.1

@@ -1,12 +1,12 @@
 
-.TH "HLEDGER-WEB" "1" "August 2022" "hledger-web-1.26.99 " "hledger User Manuals"
+.TH "HLEDGER-WEB" "1" "September 2022" "hledger-web-1.27 " "hledger User Manuals"
 
 
 
 .SH NAME
 .PP
 hledger-web is a web interface (WUI) for the hledger accounting tool.
-This manual is for hledger-web 1.26.99.
+This manual is for hledger-web 1.27.
 .SH SYNOPSIS
 .PP
 \f[C]hledger-web [OPTIONS]\f[R]

hledger-web/hledger-web.info

@@ -12,7 +12,7 @@ hledger-web(1)
 **************
 
 hledger-web is a web interface (WUI) for the hledger accounting tool.
-This manual is for hledger-web 1.26.99.
+This manual is for hledger-web 1.27.
 
    'hledger-web [OPTIONS]'
 'hledger web -- [OPTIONS]'
@@ -632,22 +632,22 @@ awkward.
 
 Tag Table:
 Node: Top223
-Node: OPTIONS1889
+Node: OPTIONS1886
-Ref: #options1994
+Ref: #options1991
-Node: PERMISSIONS9905
+Node: PERMISSIONS9902
-Ref: #permissions10044
+Ref: #permissions10041
-Node: EDITING UPLOADING DOWNLOADING11256
+Node: EDITING UPLOADING DOWNLOADING11253
-Ref: #editing-uploading-downloading11437
+Ref: #editing-uploading-downloading11434
-Node: RELOADING12271
+Node: RELOADING12268
-Ref: #reloading12405
+Ref: #reloading12402
-Node: JSON API12838
+Node: JSON API12835
-Ref: #json-api12952
+Ref: #json-api12949
-Node: ENVIRONMENT18442
+Node: ENVIRONMENT18439
-Ref: #environment18558
+Ref: #environment18555
-Node: FILES19869
+Node: FILES19866
-Ref: #files19969
+Ref: #files19966
-Node: BUGS20182
+Node: BUGS20179
-Ref: #bugs20260
+Ref: #bugs20257
 
 End Tag Table
 

hledger-web/hledger-web.txt

@@ -5,7 +5,7 @@ HLEDGER-WEB(1)               hledger User Manuals               HLEDGER-WEB(1)
 
 NAME
        hledger-web  is  a web interface (WUI) for the hledger accounting tool.
-       This manual is for hledger-web 1.26.99.
+       This manual is for hledger-web 1.27.
 
 SYNOPSIS
        hledger-web [OPTIONS]
@@ -586,4 +586,4 @@ SEE ALSO
 
 
 
-hledger-web-1.26.99               August 2022                   HLEDGER-WEB(1)
+hledger-web-1.27                September 2022                  HLEDGER-WEB(1)

hledger/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{August 2022}})m4_dnl
+m4_define({{_monthyear_}}, {{September 2022}})m4_dnl

hledger/hledger.1

@@ -1,6 +1,6 @@
 .\"t
 
-.TH "HLEDGER" "1" "August 2022" "hledger-1.26.99 " "hledger User Manuals"
+.TH "HLEDGER" "1" "September 2022" "hledger-1.27 " "hledger User Manuals"
 
 
 
@@ -9,7 +9,7 @@
 This is the command-line interface (CLI) for the hledger accounting
 tool.
 Here we also describe hledger\[aq]s concepts and file formats.
-This manual is for hledger 1.26.99.
+This manual is for hledger 1.27.
 .SH SYNOPSIS
 .PP
 \f[C]hledger\f[R]
@@ -1564,38 +1564,257 @@ not the old one, and \f[C]amt:\f[R] matches the new quantity, and not
 the old one.
 Note: this changed in hledger 1.22, previously it was the reverse, see
 the discussion at #1625.
-.SH CONVERSION & COST
+.SH COST
 .PP
-This section is about converting between commodities.
+This section is about recording the cost of things, in transactions
-Some definitions:
+where one commodity is exchanged for another.
+Eg an exchange of currency, or a stock purchase or sale.
+First, a quick glossary:
 .IP \[bu] 2
-A \[dq]commodity conversion\[dq] is an exchange of one currency or
+Conversion - an exchange of one currency or commodity for another.
-commodity for another.
 Eg a foreign currency exchange, or a purchase or sale of stock or
 cryptocurrency.
 .IP \[bu] 2
-A \[dq]conversion transaction\[dq] is a transaction involving one or
+Conversion transaction - a transaction involving one or more
-more such conversions.
+conversions.
 .IP \[bu] 2
-\[dq]Conversion rate\[dq] is the exchange rate in a conversion - the
+Conversion rate - the cost per unit of one commodity in the other, ie
-cost per unit of one commodity in the other.
+the exchange rate.
 .IP \[bu] 2
-\[dq]Cost\[dq] is how much of one commodity was paid to acquire the
+Cost - how much of one commodity was paid to acquire the other.
-other (when buying), or how much was received in exchange for the other
+And more generally, in hledger docs: the amount exchanged in the
-(when selling).
+\[dq]secondary\[dq] commodity (usually your base currency), whether in a
-We call both of these \[dq]cost\[dq] for convenience (after all, it is
+purchase or a sale, and whether expressed per unit or in total.
-cost for one party or the other).
+Or, the \[at]/\[at]\[at] notation used to represent this.
-.SS Recording conversions
+.IP \[bu] 2
+Transaction price - another name for the cost expressed with
+hledger\[aq]s cost notation.
+.SS -B: Convert to cost
 .PP
-As a concrete example, let\[aq]s assume 100 EUR was converted to 120
+As discussed a little further on in Transaction prices, when recording a
-USD.
+transaction you can also record the amount\[aq]s cost in another
-There are several ways to record this in the journal, each with pros and
+commodity, by adding \f[C]\[at] UNITPRICE\f[R] or
-cons which will be explained in more detail below.
+\f[C]\[at]\[at] TOTALPRICE\f[R].
-(Also, these examples use journal format which is properly explained
-much further below; sorry about that, you may want to read some of that
-first.)
-.SS Implicit conversion
 .PP
+Then you can see a report with amounts converted to cost, by adding the
+\f[C]-B/--cost\f[R] flag.
+(Mnemonic: \[dq]B\[dq] from \[dq]cost Basis\[dq], as in Ledger).
+Eg:
+.IP
+.nf
+\f[C]
+2022-01-01
+  assets:dollars  $-135          ; 135 dollars is exchanged for..
+  assets:euros     \[Eu]100 \[at] $1.35  ; one hundred euros purchased at $1.35 each
+\f[R]
+.fi
+.IP
+.nf
+\f[C]
+$ hledger bal -N
+               $-135  assets:dollars
+                \[Eu]100  assets:euros
+$ hledger bal -N -B
+               $-135  assets:dollars
+                $135  assets:euros    # <- the euros\[aq] cost
+\f[R]
+.fi
+.PP
+Notes:
+.PP
+-B is sensitive to the order of postings when a transaction price is
+inferred: the inferred price will be in the commodity of the last
+amount.
+So if example 3\[aq]s postings are reversed, while the transaction is
+equivalent, -B shows something different:
+.IP
+.nf
+\f[C]
+2022-01-01
+  assets:dollars  $-135              ; 135 dollars sold
+  assets:euros     \[Eu]100              ; for 100 euros
+\f[R]
+.fi
+.IP
+.nf
+\f[C]
+$ hledger bal -N -B
+               \[Eu]-100  assets:dollars  # <- the dollars\[aq] selling price
+                \[Eu]100  assets:euros
+\f[R]
+.fi
+.PP
+The \[at]/\[at]\[at] cost notation is convenient, but has some
+drawbacks: it does not truly balance the transaction, so it disrupts the
+accounting equation and tends to causes a non-zero total in balance
+reports.
+.SS Equity conversion postings
+.PP
+By contrast, conventional double entry bookkeeping (DEB) uses a
+different notation: an extra pair of equity postings to balance
+conversion transactions.
+In this style, the above entry might be written:
+.IP
+.nf
+\f[C]
+2022-01-01 one hundred euros purchased at $1.35 each
+    assets:dollars      $-135
+    equity:conversion    $135
+    equity:conversion   \[Eu]-100
+    assets:euros         \[Eu]100
+\f[R]
+.fi
+.PP
+This style is more correct, but it\[aq]s also more verbose and makes
+cost reporting more difficult for PTA tools.
+.PP
+Happily, current hledger can read either notation, or convert one to the
+other when needed, so you can use the one you prefer.
+.SS Inferring equity postings from cost
+.PP
+With \f[C]--infer-equity\f[R], hledger detects transactions written with
+PTA cost notation and adds equity conversion postings to them (and
+temporarily permits the coexistence of equity conversion postings and
+cost notation, which normally would cause an unbalanced transaction
+error).
+Eg:
+.IP
+.nf
+\f[C]
+2022-01-01
+  assets:dollars  -$135
+  assets:euros     \[Eu]100 \[at] $1.35
+\f[R]
+.fi
+.IP
+.nf
+\f[C]
+$ hledger print --infer-equity
+2022-01-01
+    assets:dollars                    $-135
+    assets:euros               \[Eu]100 \[at] $1.35
+    equity:conversion:$-\[Eu]:\[Eu]           \[Eu]-100  ; generated-posting:
+    equity:conversion:$-\[Eu]:$         $135.00  ; generated-posting:
+\f[R]
+.fi
+.PP
+The conversion account names can be changed with the conversion account
+type declaration.
+.PP
+--infer-equity is useful when when transactions have been recorded using
+PTA cost notation, to help preserve the accounting equation and balance
+reports\[aq] zero total, or to produce more conventional journal entries
+for sharing with non-PTA-users.
+.PP
+\f[I]Experimental\f[R]
+.SS Inferring cost from equity postings
+.PP
+The reverse operation is possible using \f[C]--infer-costs\f[R], which
+detects transactions written with equity conversion postings and adds
+PTA cost notation to them (and temporarily permits the coexistence of
+equity conversion postings and cost notation).
+Eg:
+.IP
+.nf
+\f[C]
+2022-01-01
+    assets:dollars            $-135
+    equity:conversion          $135
+    equity:conversion         \[Eu]-100
+    assets:euros               \[Eu]100
+\f[R]
+.fi
+.IP
+.nf
+\f[C]
+$ hledger print --infer-costs
+2022-01-01
+    assets:dollars       $-135 \[at]\[at] \[Eu]100
+    equity:conversion             $135
+    equity:conversion            \[Eu]-100
+    assets:euros                  \[Eu]100
+\f[R]
+.fi
+.PP
+--infer-costs is useful when combined with -B/--cost, allowing cost
+reporting even when transactions have been recorded using equity
+postings:
+.IP
+.nf
+\f[C]
+$ hledger print --infer-costs -B
+2009-01-01
+    assets:dollars           \[Eu]-100
+    assets:euros              \[Eu]100
+\f[R]
+.fi
+.PP
+Notes:
+.PP
+Postings will be recognised as equity conversion postings if they are 1.
+to account(s) declared with type \f[C]V\f[R] (\f[C]Conversion\f[R]; or
+if no such accounts are declared, accounts named
+\f[C]equity:conversion\f[R], \f[C]equity:trade\f[R],
+\f[C]equity:trading\f[R], or subaccounts of these) 2.
+adjacent 3.
+and exactly matching the amounts of two non-conversion postings.
+.PP
+The total cost is appended to the first matching posting in the
+transaction.
+If you need to assign it to a different posting, or if you have several
+different sets of conversion postings in one transaction, you may need
+to write the costs explicitly yourself.
+Eg:
+.IP
+.nf
+\f[C]
+2022-01-01
+    assets:dollars                    $-135
+    equity:conversion                 \[Eu]-100
+    equity:conversion                  $135
+    assets:euros               \[Eu]100 \[at]\[at] $135
+\f[R]
+.fi
+.PP
+or:
+.IP
+.nf
+\f[C]
+2022-01-01
+    assets:dollars                    $-235
+    assets:euros               \[Eu]100 \[at] $1.35  ; 100 euros bought for $1.35 each
+    equity:conversion                 \[Eu]-100
+    equity:conversion                  $135
+    assets:pounds               \[Po]80 \[at]\[at] $100  ; 80 pounds bought for $100 total
+    equity:conversion                  \[Po]-80
+    equity:conversion                  $100
+\f[R]
+.fi
+.PP
+--infer-equity and --infer-costs can be used together, eg if you have a
+mixture of both notations.
+.PP
+\f[I]Experimental\f[R]
+.SS When to infer cost/equity
+.PP
+Inferring equity postings or costs is still fairly new, so not enabled
+by default.
+We\[aq]re not sure yet if that should change.
+Here are two suggestions to try, experience reports welcome:
+.IP "1." 3
+When you use -B, always use --infer-costs as well.
+Eg: \f[C]hledger bal -B --infer-costs\f[R]
+.IP "2." 3
+Always run hledger with both flags enabled.
+Eg: \f[C]alias hl=\[dq]hledger --infer-equity --infer-costs\[dq]\f[R]
+.SS How to record conversions
+.PP
+Essentially there are four ways to record a conversion transaction in
+hledger.
+Here are all of them, with pros and cons.
+.SS Conversion with implicit cost
+.PP
+Let\[aq]s assume 100 EUR is converted to 120 USD.
 You can just record the outflow (100 EUR) and inflow (120 USD) in the
 appropriate asset account:
 .IP
@@ -1613,25 +1832,24 @@ You can see the inferred rate by using \f[C]hledger print -x\f[R].
 .PP
 Pro:
 .IP \[bu] 2
-Easy, concise
+Concise, easy
-.IP \[bu] 2
-hledger can do cost reporting
 .PP
 Con:
 .IP \[bu] 2
 Less error checking - typos in amounts or commodity symbols may not be
 detected
 .IP \[bu] 2
-conversion rate is not clear
+Conversion rate is not clear
 .IP \[bu] 2
-disturbs the accounting equation
+Disturbs the accounting equation, unless you add the --infer-equity flag
 .PP
 You can prevent accidental implicit conversions due to a mistyped
 commodity symbol, by using \f[C]hledger check commodities\f[R].
+.PP
 You can prevent implicit conversions entirely, by using
 \f[C]hledger check balancednoautoconversion\f[R], or
 \f[C]-s/--strict\f[R].
-.SS Priced conversion
+.SS Conversion with explicit cost
 .PP
 You can add the conversion rate using \[at] notation:
 .IP
@@ -1650,16 +1868,14 @@ Pro:
 .IP \[bu] 2
 Still concise
 .IP \[bu] 2
-makes the conversion rate clear
+Makes the conversion rate clear
 .IP \[bu] 2
-provides some error checking
+Provides more error checking
-.IP \[bu] 2
-hledger can do cost reporting
 .PP
 Con:
 .IP \[bu] 2
-Disturbs the accounting equation without the --infer-equity flag
+Disturbs the accounting equation, unless you add the --infer-equity flag
-.SS Equity conversion
+.SS Conversion with equity postings
 .PP
 In strict double entry bookkeeping, the above transaction is not
 balanced in EUR or in USD, since some EUR disappears, and some USD
@@ -1684,24 +1900,22 @@ Pro:
 .IP \[bu] 2
 Preserves the accounting equation
 .IP \[bu] 2
-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
-works in any double entry accounting system
+Standard, 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
 More verbose
 .IP \[bu] 2
-conversion rate is not clear
+Conversion rate is not obvious
 .IP \[bu] 2
-depends on the order of postings
+Cost reporting requires adding the --infer-costs flag
-.SS Priced equity conversion
+.SS Conversion with equity postings and explicit cost
 .PP
-Another notation is to record both the conversion rate and the equity
+Here both equity postings and \[at] notation are used together.
-postings:
+hledger will usually complain about this redundancy, but when using the
+--infer-costs flag it is accepted.
 .IP
 .nf
 \f[C]
@@ -1717,68 +1931,39 @@ Pro:
 .IP \[bu] 2
 Preserves the accounting equation
 .IP \[bu] 2
-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
-makes the conversion rate clear
+Makes the conversion rate clear
 .IP \[bu] 2
-provides some error checking
+Provides more error checking
-.IP \[bu] 2
-hledger can do cost reporting
 .PP
 Con:
 .IP \[bu] 2
 Most verbose
 .IP \[bu] 2
-Requires --infer-costs flag
+Requires the --infer-costs flag
 .IP \[bu] 2
 Not compatible with ledger
-.SS Inferring missing conversion rates
+.SS Cost tips
-.PP
-hledger will do this automatically for implicit conversions.
-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.
-.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
-priced and implicit conversions to their cost in the other commodity.
-This is useful to see a report of what you paid for things (or how much
-you sold things for).
-Currently \f[C]-B/--cost\f[R] does not work on equity conversions, and
-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] [--infer-costs] [-B]\f[R]
-.SS Conversion summary
 .IP \[bu] 2
-Recording the conversion rate is good because it makes that clear and
+Recording the conversion rate explicitly is good because it makes that
-allows cost reporting.
+clear and helps detect errors.
 .IP \[bu] 2
-Recording equity postings is good because it balances the accounting
+Recording equity postings is good because it is correct bookkeeping and
-equation and is correct bookkeeping.
+preserves the accounting equation.
 .IP \[bu] 2
-Combining these is possible with the --infer-costs flag, but has certain
+Combining these is possible by using the --infer-costs flag (which
-requirements for the order of postings.
+requires well-ordered postings).
 .IP \[bu] 2
 When you want to see the cost (or sale proceeds) of things, use
-\f[C]-B/--cost\f[R].
+\f[C]-B\f[R] (or \f[C]--cost\f[R]).
+If you use equity conversion postings notation, use
+\f[C]-B --infer-costs\f[R].
 .IP \[bu] 2
-When you want to see a balanced balance sheet or correct journal
+If you use PTA cost notation, and you want to see a balanced balance
-entries, use \f[C]--infer-equity\f[R].
+sheet or print correct journal entries, use \f[C]--infer-equity\f[R].
 .IP \[bu] 2
-\f[C]--cost\f[R] will remove any balancing equity posts, so as not to
+Conversion to cost is performed before valuation (described next).
-disturb the accounting equation.
-.IP \[bu] 2
-Conversion/cost operations are performed before valuation.
 .SH VALUATION
 .PP
 Instead of reporting amounts in their original commodity, hledger can
@@ -6988,18 +7173,30 @@ number, eg 0.5 displayed with zero decimal places is \[dq]0\[dq]).
 hledger was built with Decimal < 0.5.1.)
 .SS Transaction prices
 .PP
-Within a transaction, you can note an amount\[aq]s price in another
+(AKA Costs)
-commodity.
-This can be used to document the cost (in a purchase) or selling price
-(in a sale).
-For example, transaction prices are useful to record purchases of a
-foreign currency.
-Note transaction prices are fixed at the time of the transaction, and do
-not change over time.
-See also market prices, which represent prevailing exchange rates on a
-certain date.
 .PP
-There are several ways to record a transaction price:
+After a posting amount, you can note its cost or selling price in
+another commodity, by writing either \f[C]\[at] UNITPRICE\f[R] or
+\f[C]\[at]\[at] TOTALPRICE\f[R] after it.
+This indicates a conversion transaction, where one commodity is
+exchanged for another.
+.PP
+hledger docs have historically called this a \[dq]transaction price\[dq]
+because it is specific to one transaction, unlike market prices which
+are not.
+\[dq]Cost\[dq] is shorter and might be preferable; just remember this
+feature can represent either a buyer\[aq]s cost, or a seller\[aq]s
+price.
+.PP
+Costs are usually written explicitly with \f[C]\[at]\f[R] or
+\f[C]\[at]\[at]\f[R], but can also be inferred automatically for simple
+multi-commodity transactions.
+.PD 0
+.P
+.PD
+As an example, here are several ways to record purchases of a foreign
+currency in hledger, using the cost notation either explicitly or
+implicitly:
 .IP "1." 3
 Write the price per unit, as \f[C]\[at] UNITPRICE\f[R] after the amount:
 .RS 4
@@ -7046,131 +7243,8 @@ Like 1, but the \f[C]\[at]\f[R] is parenthesised, i.e.
 Like 2, but as in 4 the \f[C]\[at]\[at]\f[R] is parenthesised, i.e.
 \f[C](\[at]\[at])\f[R]; in hledger, this is equivalent to 2.
 .PP
-Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction
+Amounts can be converted to cost at report time using the
-price\[aq]s commodity, if any.
+\f[C]-B/--cost\f[R] flag; this is discussed more in the COST section.
-(mnemonic: \[dq]B\[dq] is from \[dq]cost Basis\[dq], as in Ledger).
-Eg here is how -B affects the balance report for the example above:
-.IP
-.nf
-\f[C]
-$ hledger bal -N --flat
-               $-135  assets:dollars
-                \[Eu]100  assets:euros
-$ hledger bal -N --flat -B
-               $-135  assets:dollars
-                $135  assets:euros    # <- the euros\[aq] cost
-\f[R]
-.fi
-.PP
-Note -B is sensitive to the order of postings when a transaction price
-is inferred: the inferred price will be in the commodity of the last
-amount.
-So if example 3\[aq]s postings are reversed, while the transaction is
-equivalent, -B shows something different:
-.IP
-.nf
-\f[C]
-2009/1/1
-  assets:dollars  $-135              ; 135 dollars sold
-  assets:euros     \[Eu]100              ; for 100 euros
-\f[R]
-.fi
-.IP
-.nf
-\f[C]
-$ hledger bal -N --flat -B
-               \[Eu]-100  assets:dollars  # <- the dollars\[aq] selling price
-                \[Eu]100  assets:euros
-\f[R]
-.fi
-.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:
@@ -8113,7 +8187,7 @@ or, it can be (these are used less often):
 assets for the cashflow report)
 .IP \[bu] 2
 \f[C]V\f[R] or \f[C]Conversion\f[R] (a subtype of Equity, for
-conversions (see CONVERSION & COST).)
+conversions (see COST).)
 .PP
 Here is a typical set of account type declarations:
 .IP
@@ -10933,7 +11007,7 @@ Show only asset and liability balances, as a flat list, limited to depth
 .IP
 .nf
 \f[C]
-$ hledger bal assets liabilities --flat -2
+$ hledger bal assets liabilities -2
                $4000  assets:bank
                 $105  assets:cash
                 $-50  liabilities:creditcard
@@ -10947,7 +11021,7 @@ balance sheet:
 .IP
 .nf
 \f[C]
-$ hledger bs --flat -2
+$ hledger bs -2
 Balance Sheet 2020-01-16
 
                         || 2020-01-16