;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_}}, {{March 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{April 2024}})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_}}, {{March 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{April 2024}})m4_dnl

hledger-ui/hledger-ui.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-UI" "1" "March 2024" "hledger-ui-1.32.99 " "hledger User Manuals"
+.TH "HLEDGER\-UI" "1" "April 2024" "hledger-ui-1.33.99 " "hledger User Manuals"
 
 
 
@@ -12,7 +12,7 @@ hledger\-ui \- robust, friendly plain text accounting (TUI version)
 .PD
 \f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R]
 .SH DESCRIPTION
-This manual is for hledger\[aq]s terminal interface, version 1.32.99.
+This manual is for hledger\[aq]s terminal interface, version 1.33.99.
 See also the hledger manual for common concepts and file formats.
 .PP
 hledger is a robust, user\-friendly, cross\-platform set of programs for

hledger-ui/hledger-ui.info

@@ -16,7 +16,7 @@ hledger-ui - robust, friendly plain text accounting (TUI version)
    'hledger-ui [OPTS] [QUERYARGS]'
 'hledger ui -- [OPTS] [QUERYARGS]'
 
-   This manual is for hledger's terminal interface, version 1.32.99.
+   This manual is for hledger's terminal interface, version 1.33.99.
 See also the hledger manual for common concepts and file formats.
 
    hledger is a robust, user-friendly, cross-platform set of programs

hledger-ui/hledger-ui.txt

@@ -9,7 +9,7 @@ SYNOPSIS
        hledger ui -- [OPTS] [QUERYARGS]
 
 DESCRIPTION
-       This  manual is for hledger's terminal interface, version 1.32.99.  See
+       This  manual is for hledger's terminal interface, version 1.33.99.  See
        also the hledger manual for common concepts and file formats.
 
        hledger is a robust, user-friendly, cross-platform set of programs  for
@@ -535,4 +535,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-ui-1.32.99                March 2024                     HLEDGER-UI(1)
+hledger-ui-1.33.99                April 2024                     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_}}, {{March 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{April 2024}})m4_dnl

hledger-web/hledger-web.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-WEB" "1" "March 2024" "hledger-web-1.32.99 " "hledger User Manuals"
+.TH "HLEDGER\-WEB" "1" "April 2024" "hledger-web-1.33.99 " "hledger User Manuals"
 
 
 
@@ -12,7 +12,7 @@ hledger\-web \- robust, friendly plain text accounting (Web version)
 .PD
 \f[CR]hledger web \-\- [\-\-serve|\-\-serve\-api] [OPTS] [ARGS]\f[R]
 .SH DESCRIPTION
-This manual is for hledger\[aq]s web interface, version 1.32.99.
+This manual is for hledger\[aq]s web interface, version 1.33.99.
 See also the hledger manual for common concepts and file formats.
 .PP
 hledger is a robust, user\-friendly, cross\-platform set of programs for

hledger-web/hledger-web.info

@@ -16,7 +16,7 @@ hledger-web - robust, friendly plain text accounting (Web version)
    'hledger-web [--serve|--serve-api] [OPTS] [ARGS]'
 'hledger web -- [--serve|--serve-api] [OPTS] [ARGS]'
 
-   This manual is for hledger's web interface, version 1.32.99.  See
+   This manual is for hledger's web interface, version 1.33.99.  See
 also the hledger manual for common concepts and file formats.
 
    hledger is a robust, user-friendly, cross-platform set of programs

hledger-web/hledger-web.txt

@@ -9,7 +9,7 @@ SYNOPSIS
        hledger web -- [--serve|--serve-api] [OPTS] [ARGS]
 
 DESCRIPTION
-       This  manual is for hledger's web interface, version 1.32.99.  See also
+       This  manual is for hledger's web interface, version 1.33.99.  See also
        the hledger manual for common concepts and file formats.
 
        hledger is a robust, user-friendly, cross-platform set of programs  for
@@ -558,4 +558,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-web-1.32.99               March 2024                    HLEDGER-WEB(1)
+hledger-web-1.33.99               April 2024                    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_}}, {{March 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{April 2024}})m4_dnl

hledger/hledger.1

@@ -1,6 +1,6 @@
 .\"t
 
-.TH "HLEDGER" "1" "March 2024" "hledger-1.32.99 " "hledger User Manuals"
+.TH "HLEDGER" "1" "April 2024" "hledger-1.33.99 " "hledger User Manuals"
 
 
 
@@ -24,7 +24,7 @@ hledger is inspired by and largely compatible with ledger(1), and
 largely interconvertible with beancount(1).
 .PP
 This manual is for hledger\[aq]s command line interface, version
-1.32.99.
+1.33.99.
 It also describes the common options, file formats and concepts used by
 all hledger programs.
 It might accidentally teach you some bookkeeping/accounting as well!
@@ -123,6 +123,9 @@ For more about how to do that on your system, see Common tasks > Setting
 LEDGER_FILE.
 .SS Text encoding
 Data files containing non\-ascii characters must use UTF\-8 encoding.
+An optional byte order mark (BOM) is allowed, at the beginning of the
+file (only).
+.PP
 Also, your system should be configured with a locale that can decode
 UTF\-8 text.
 On some unix systems, you may need set the \f[CR]LANG\f[R] environment
@@ -1823,20 +1826,17 @@ troubleshooting or for reading Ledger files.
 (Note: this flag currently does not disable balance assignments,
 described below).
 .SS Assertions and ordering
-hledger sorts an account\[aq]s postings and assertions first by date and
+hledger calculates and checks an account\[aq]s balance assertions in
-then (for postings on the same day) by parse order.
+date order (and when there are multiple assertions on the same day, in
-Note this is different from Ledger, which sorts assertions only by parse
+parse order).
-order.
+Note this is different from Ledger, which checks assertions always in
-(Also, Ledger assertions do not see the accumulated effect of repeated
+parse order, ignoring dates.
-postings to the same account within a transaction.)
 .PP
-So, hledger balance assertions keep working if you reorder
+This means in hledger you can freely reorder transactions, postings, or
-differently\-dated transactions within the journal.
+files, and balance assertions will usually keep working.
-But if you reorder same\-dated transactions or postings, assertions
+The exception is when you reorder multiple postings on the same day, to
-might break and require updating.
+the same account, which have balance assertions; those will likely need
-This order dependence does bring an advantage: precise control over the
+updating.
-order of postings and assertions within a day, so you can assert
-intra\-day balances.
 .SS Assertions and multiple included files
 Multiple files included with the \f[CR]include\f[R] directive are
 processed as if concatenated into one file, preserving their order and
@@ -1857,53 +1857,6 @@ disrupt valid assertions in later files.
 .PP
 If you do want assertions to see balance from earlier files, use
 \f[CR]include\f[R], or concatenate the files temporarily.
-.SS Assertions and commodities
-The asserted balance must be a simple single\-commodity amount, and in
-fact the assertion checks only this commodity\[aq]s balance within the
-(possibly multi\-commodity) account balance.
-This is how assertions work in Ledger also.
-We could call this a \[dq]partial\[dq] balance assertion.
-.PP
-To assert the balance of more than one commodity in an account, you can
-write multiple postings, each asserting one commodity\[aq]s balance.
-.PP
-You can make a stronger \[dq]total\[dq] balance assertion by writing a
-double equals sign (\f[CR]== EXPECTEDBALANCE\f[R]).
-This asserts that there are no other commodities in the account besides
-the asserted one (or at least, that their balance is 0).
-.IP
-.EX
-2013/1/1
-  a   $1
-  a    1€
-  b  $\-1
-  c   \-1€
-
-2013/1/2  ; These assertions succeed
-  a    0  =  $1
-  a    0  =   1€
-  b    0 == $\-1
-  c    0 ==  \-1€
-
-2013/1/3  ; This assertion fails as \[aq]a\[aq] also contains 1€
-  a    0 ==  $1
-.EE
-.PP
-It\[aq]s not yet possible to make a complete assertion about a balance
-that has multiple commodities.
-One workaround is to isolate each commodity into its own subaccount:
-.IP
-.EX
-2013/1/1
-  a:usd   $1
-  a:euro   1€
-  b
-
-2013/1/2
-  a        0 ==  0
-  a:usd    0 == $1
-  a:euro   0 ==  1€
-.EE
 .SS Assertions and costs
 Balance assertions ignore costs, and should normally be written without
 one:
@@ -1919,19 +1872,75 @@ passes or fails.
 This is for backward compatibility (hledger\[aq]s close command used to
 generate balance assertions with costs), and because balance
 \f[I]assignments\f[R] do use costs (see below).
+.SS Assertions and commodities
+The balance assertions described so far are \[dq]\f[B]single commodity
+balance assertions\f[R]\[dq]: they assert and check the balance in one
+commodity, ignoring any others that may be present.
+This is how balance assertions work in Ledger also.
+.PP
+If an account contains multiple commodities, you can assert their
+balances by writing multiple postings with balance assertions, one for
+each commodity:
+.IP
+.EX
+2013/1/1
+  usd   $\-1
+  eur   €\-1
+  both
+
+2013/1/2
+  both    0 = $1
+  both    0 = €1
+.EE
+.PP
+In hledger you can make a stronger \[dq]\f[B]sole commodity balance
+assertion\f[R]\[dq] by writing two equals signs
+(\f[CR]== EXPECTEDBALANCE\f[R]).
+This also asserts that there are no other commodities in the account
+besides the asserted one (or at least, that their current balance is
+zero):
+.IP
+.EX
+2013/1/1
+  usd   $\-1  == $\-1  ; these sole commodity assertions succeed
+  eur   €\-1  == €\-1
+  both      ;==  $1  ; this one would fail because \[aq]both\[aq] contains $ and €
+.EE
+.PP
+It\[aq]s less easy to make a \[dq]\f[B]sole commodities balance
+assertion\f[R]\[dq] (note the plural) \- ie, asserting that an account
+contains two or more specified commodities and no others.
+It can be done by
+.IP "1." 3
+isolating each commodity in a subaccount, and asserting those
+.IP "2." 3
+and also asserting there are no commodities in the parent account
+itself:
+.IP
+.EX
+2013/1/1
+  usd       $\-1
+  eur       €\-1
+  both        0 == 0   ; nothing up my sleeve
+  both:usd   $1 == $1  ; a dollar here
+  both:eur   €1 == €1  ; a euro there
+.EE
 .SS Assertions and subaccounts
-The balance assertions above (\f[CR]=\f[R] and \f[CR]==\f[R]) do not
+All of the balance assertions above (both \f[CR]=\f[R] and
-count the balance from subaccounts; they check the account\[aq]s
+\f[CR]==\f[R]) are \[dq]\f[B]subaccount\-exclusive balance
-exclusive balance only.
+assertions\f[R]\[dq]; they ignore any balances that exist in deeper
-You can assert the balance including subaccounts by writing
+subaccounts.
-\f[CR]=*\f[R] or \f[CR]==*\f[R], eg:
+.PP
+In hledger you can make \[dq]\f[B]subaccount\-inclusive balance
+assertions\f[R]\[dq] by adding a star after the equals (\f[CR]=*\f[R] or
+\f[CR]==*\f[R]):
 .IP
 .EX
 2019/1/1
-  equity:opening balances
+  equity:start
-  checking:a       5
+  assets:checking  $10
-  checking:b       5
+  assets:savings   $10
-  checking         1  ==* 11
+  assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else
 .EE
 .SS Assertions and virtual postings
 Balance assertions always consider both real and virtual postings; they
@@ -3362,7 +3371,7 @@ This directive sets a default commodity, to be used for any subsequent
 commodityless amounts (ie, plain numbers) seen while parsing the
 journal.
 This effect lasts until the next \f[CR]D\f[R] directive, or the end of
-the journal.
+the current file.
 .PP
 For compatibility/historical reasons, \f[CR]D\f[R] also acts like a
 \f[CR]commodity\f[R] directive (setting the commodity\[aq]s decimal mark
@@ -3509,10 +3518,10 @@ Ledger allows a valuation function or value to be written in double
 parentheses after an amount.
 hledger ignores these.
 .SS Virtual postings
-A posting with parentheses around the account name
+A posting with parentheses around the account name, like
-(\f[CR](some:account)\f[R]) is called a \f[I]unbalanced virtual
+\f[CR](some:account)   10\f[R], is called an \f[I]unbalanced virtual
 posting\f[R].
-Such postings do not participate in transaction balancing.
+These postings do not participate in transaction balancing.
 (And if you write them without an amount, a zero amount is always
 inferred.)
 These can occasionally be convenient for special circumstances, but they
@@ -6460,34 +6469,45 @@ match all the other terms.
 .PP
 We also support more complex boolean queries with the \f[CR]expr:\f[R]
 prefix.
-This allows one to combine queries using \f[CR]AND\f[R], \f[CR]OR\f[R],
+This allows one to combine query terms using \f[CR]and\f[R],
-and \f[CR]NOT\f[R].
+\f[CR]or\f[R], \f[CR]not\f[R] keywords (case insensitive), and to group
-(\f[CR]NOT\f[R] is equivalent to the \f[CR]not:\f[R] prefix.)
+them by enclosing in parentheses.
+.PP
 Some examples:
 .IP \[bu] 2
-Match transactions with \[aq]cool\[aq] in the description AND with the
+Exclude account names containing \[aq]food\[aq]:
-\[aq]A\[aq] tag
 .RS 2
 .PP
-\f[CR]expr:\[dq]desc:cool AND tag:A\[dq]\f[R]
+\f[CR]expr:\[dq]not food\[dq]\f[R] (\f[CR]not:food\f[R] is equivalent)
 .RE
 .IP \[bu] 2
-Match transactions NOT to the \[aq]expenses:food\[aq] account OR with
+Match things which have \[aq]cool\[aq] in the description and the
-the \[aq]A\[aq] tag
+\[aq]A\[aq] tag:
 .RS 2
 .PP
-\f[CR]expr:\[dq]NOT expenses:food OR tag:A\[dq]\f[R]
+\f[CR]expr:\[dq]desc:cool and tag:A\[dq]\f[R]
+(\f[CR]expr:\[dq]desc:cool tag:A\[dq]\f[R] is equivalent)
 .RE
 .IP \[bu] 2
-Match transactions NOT involving the \[aq]expenses:food\[aq] account OR
+Match things which either do not reference the \[aq]expenses:food\[aq]
-with the \[aq]A\[aq] tag AND involving the \[aq]expenses:drink\[aq]
+account, or do have the \[aq]A\[aq] tag:
-account.
-(the AND is implicitly added by space\-separation, following the rules
-above)
 .RS 2
 .PP
-\f[CR]expr:\[dq]expenses:food OR (tag:A expenses:drink)\[dq]\f[R]
+\f[CR]expr:\[dq]not expenses:food or tag:A\[dq]\f[R]
 .RE
+.IP \[bu] 2
+Match things which either do not reference the \[aq]expenses:food\[aq]
+account, or which reference the \[aq]expenses:drink\[aq] account and
+also have the \[aq]A\[aq] tag:
+.RS 2
+.PP
+\f[CR]expr:\[dq]expenses:food or (expenses:drink and tag:A)\[dq]\f[R]
+.RE
+.PP
+\f[CR]expr:\f[R] has a restriction: \f[CR]date:\f[R] queries may not be
+used inside \f[CR]or\f[R] expressions.
+That would allow disjoint report periods or disjoint result sets, with
+unclear semantics for our reports.
 .SS Queries and command options
 Some queries can also be expressed as command\-line options:
 \f[CR]depth:2\f[R] is equivalent to \f[CR]\-\-depth 2\f[R],
@@ -9226,23 +9246,24 @@ Example:
 .IP
 .EX
 $ hledger balancesheet
-Balance Sheet
+Balance Sheet 2008\-12\-31
 
-Assets:
+                    || 2008\-12\-31 
-                 $\-1  assets
+====================++============
-                  $1    bank:saving
+ Assets             ||            
-                 $\-2    cash
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+ assets:bank:saving ||         $1 
-                 $\-1
+ assets:cash        ||        $\-2 
-
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
-Liabilities:
+                    ||        $\-1 
-                  $1  liabilities:debts
+====================++============
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+ Liabilities        ||            
-                  $1
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
-
+ liabilities:debts  ||        $\-1 
-Total:
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+                    ||        $\-1 
-                   0
+====================++============
+ Net:               ||          0 
 .EE
 .PP
 This command is a higher\-level variant of the \f[CR]balance\f[R]
@@ -9275,28 +9296,29 @@ Example:
 .IP
 .EX
 $ hledger balancesheetequity
-Balance Sheet With Equity
+Balance Sheet With Equity 2008\-12\-31
 
-Assets:
+                    || 2008\-12\-31 
-                 $\-2  assets
+====================++============
-                  $1    bank:saving
+ Assets             ||            
-                 $\-3    cash
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+ assets:bank:saving ||         $1 
-                 $\-2
+ assets:cash        ||        $\-2 
-
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
-Liabilities:
+                    ||        $\-1 
-                  $1  liabilities:debts
+====================++============
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+ Liabilities        ||            
-                  $1
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
-
+ liabilities:debts  ||        $\-1 
-Equity:
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
-          $1  equity:owner
+                    ||        $\-1 
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+====================++============
-          $1
+ Equity             ||            
-
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
-Total:
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+                    ||          0 
-                   0
+====================++============
+ Net:               ||          0 
 .EE
 .PP
 This command is a higher\-level variant of the \f[CR]balance\f[R]
@@ -9307,14 +9329,19 @@ It is similar to
 smarter account detection, and liabilities/equity displayed with their
 sign flipped.
 .PP
+This report is the easiest way to see if the accounting equation (A+L+E
+= 0) is satisfied (after you have done a \f[CR]close \-\-retain\f[R] to
+merge revenues and expenses with equity, and perhaps added
+\f[CR]\-\-infer\-equity\f[R] to balance your commodity conversions).
+.PP
 This command also supports the output destination and output format
 options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
 \f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R].
 .SS cashflow
 (cf)
 .PP
-This command displays a cashflow statement, showing the inflows and
+This command displays a (simple) cashflow statement, showing the inflows
-outflows affecting \[dq]cash\[dq] (ie, liquid, easily convertible)
+and outflows affecting \[dq]cash\[dq] (ie, liquid, easily convertible)
 assets.
 Amounts are shown with normal positive sign, as in conventional
 financial statements.
@@ -9340,18 +9367,16 @@ An example cashflow report:
 .IP
 .EX
 $ hledger cashflow
-Cashflow Statement
+Cashflow Statement 2008
 
-Cash flows:
+                    || 2008 
-                 $\-1  assets
+====================++======
-                  $1    bank:saving
+ Cash flows         ||      
-                 $\-2    cash
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+ assets:bank:saving ||   $1 
-                 $\-1
+ assets:cash        ||  $\-2 
-
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
-Total:
+                    ||  $\-1 
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-                 $\-1
 .EE
 .PP
 This command is a higher\-level variant of the \f[CR]balance\f[R]
@@ -9866,18 +9891,18 @@ files to your main journal, you will run
 .PP
 Note you can import from any file format, though CSV files are the most
 common import source, and these docs focus on that case.
-.SS Skipping
+.SS Deduplication
 \f[CR]import\f[R] tries to import only the transactions which are new
-since the last import, \[dq]skipping over\[dq] any that it saw last
+since the last import, ignoring any that it has seen in previous runs.
-time.
 So if your bank\[aq]s CSV includes the last three months of data, you
 can download and \f[CR]import\f[R] it every month (or week, or day) and
 only the new transactions will be imported each time.
 .PP
 It works as follows.
-For each imported \f[CR]FILE\f[R]:
+For each imported \f[CR]FILE\f[R] (usually CSV, but they could be any of
+hledger\[aq]s input formats):
 .IP \[bu] 2
-It tries to find the latest date seen previously, by reading it from a
+It tries to recall the latest date seen previously, reading it from a
 hidden \f[CR].latest.FILE\f[R] in the same directory.
 .IP \[bu] 2
 Then it processes \f[CR]FILE\f[R], ignoring any transactions on or
@@ -9886,36 +9911,44 @@ before the \[dq]latest seen\[dq] date.
 And after a successful import, it updates the \f[CR].latest.FILE\f[R](s)
 for next time (unless \f[CR]\-\-dry\-run\f[R] was used).
 .PP
-This is simple system that works fairly well for transaction data
+This is a limited kind of deduplication, let\[aq]s call it \[dq]date
-(usually CSV, but it could be any of hledger\[aq]s input formats).
+skipping\[dq].
-It assumes:
+Within each input file, it avoids reprocessing the same dates across
+successive runs.
+This is a simple system that works for most real\-world CSV files; it
+assumes these are true, or true enough:
 .IP "1." 3
 new items always have the newest dates
 .IP "2." 3
-item dates are stable across successive CSV downloads
+item dates are stable across successive downloads
 .IP "3." 3
-the order of same\-date items is stable across CSV downloads
+the order of same\-date items is stable across downloads
+.IP "4." 3
+the name of the input file is stable across downloads
 .PP
-These are true of most CSV files representing transactions, or true
+If you have a bank whose CSV dates or ordering occasionally change, you
-enough.
-If you have a bank whose CSV dates or ordering occasionally changes, you
 can reduce the chance of this happening in new transactions by importing
-more often (and in old transactions it doesn\[aq]t matter).
+more often, and in old transactions it doesn\[aq]t matter.
+And remember you can use CSV rules files as input, which is one way to
+ensure a stable file name.
 .PP
-Note, \f[CR]import\f[R] avoids reprocessing the same dates across
+\f[CR]import\f[R] doesn\[aq]t detect other kinds of duplication, such as
-successive runs, but it does not detect transactions that are duplicated
+duplicate transactions within a single run.
-within a single run.
+(In part, because legitimate duplicate transactions can easily occur in
-I\[aq]ll call these \[dq]skipping\[dq] and \[dq]deduplication\[dq].
+real\-world data.)
-.PP
+So, say you downloaded but forgot to import \f[CR]bank.1.csv\f[R], and a
-So for example, say you downloaded but did not import
+week later you downloaded \f[CR]bank.2.csv\f[R] with overlapping data.
-\f[CR]bank.1.csv\f[R], and later downloaded \f[CR]bank.2.csv\f[R] with
+Now you should not import both of these at once
-overlapping data.
+(\f[CR]hledger import bank.1.csv bank.2.csv\f[R]); the overlapping
-Then you should not import both of them at once
+transactions which appear twice would not be deduplicated since this is
-(\f[CR]hledger import bank.1.csv bank.2.csv\f[R]), as the overlapping
+considered a single import.
-data would appear twice and not be deduplicated.
+Instead, import these files one at a time, and also use the same
-Instead, import them one at a time
+filename each time for a common \[dq]latest seen\[dq] state:
-(\f[CR]hledger import bank.1.csv; hledger import bank.2.csv\f[R]), and
+.IP
-the second import will skip the overlapping data.
+.EX
+$ mv bank.1.csv bank.csv; hledger import bank.csv
+$ mv bank.2.csv bank.csv; hledger import bank.csv
+.EE
 .PP
 Normally you can ignore the \f[CR].latest.*\f[R] files, but if needed,
 you can delete them (to make all transactions unseen), or
@@ -9925,8 +9958,8 @@ possibly repeated on multiple lines.
 It means \[dq]I have seen transactions up to this date, and this many of
 them occurring on that date\[dq].
 .PP
-(\f[CR]hledger print \-\-new\f[R] also uses and updates these
+\f[CR]hledger print \-\-new\f[R] also uses and updates these
-\f[CR].latest.*\f[R] files, but it is less often used.)
+\f[CR].latest.*\f[R] files, but it is less often used.
 .PP
 Related: CSV > Working with CSV > Deduplicating, importing.
 .SS Import testing
@@ -9991,25 +10024,25 @@ Example:
 .IP
 .EX
 $ hledger incomestatement
-Income Statement
+Income Statement 2008
 
-Revenues:
+                   || 2008 
-                 $\-2  income
+===================++======
-                 $\-1    gifts
+ Revenues          ||      
-                 $\-1    salary
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+ income:gifts      ||   $1 
-                 $\-2
+ income:salary     ||   $1 
-
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
-Expenses:
+                   ||   $2 
-                  $2  expenses
+===================++======
-                  $1    food
+ Expenses          ||      
-                  $1    supplies
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+ expenses:food     ||   $1 
-                  $2
+ expenses:supplies ||   $1 
-
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
-Total:
+                   ||   $2 
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+===================++======
-                   0
+ Net:              ||    0 
 .EE
 .PP
 This command is a higher\-level variant of the \f[CR]balance\f[R]

hledger/hledger.txt

@@ -16,7 +16,7 @@ DESCRIPTION
        and largely compatible with  ledger(1),  and  largely  interconvertible
        with beancount(1).
 
-       This  manual  is for hledger's command line interface, version 1.32.99.
+       This  manual  is for hledger's command line interface, version 1.33.99.
        It also describes the common options, file formats and concepts used by
        all hledger programs.  It might accidentally teach you  some  bookkeep-
        ing/accounting  as  well!  You don't need to know everything in here to
@@ -96,7 +96,10 @@ Input
        Common tasks > Setting LEDGER_FILE.
 
    Text encoding
-       Data files containing non-ascii characters  must  use  UTF-8  encoding.
+       Data files containing non-ascii characters must use UTF-8 encoding.  An
+       optional byte order mark (BOM) is allowed, at the beginning of the file
+       (only).
+
        Also, your system should be configured with a locale  that  can  decode
        UTF-8  text.   On some unix systems, you may need set the LANG environ-
        ment variable, eg.  You can read more about this in Unicode characters,
@@ -1410,18 +1413,15 @@ Journal
        balance assignments, described below).
 
    Assertions and ordering
-       hledger sorts an account's postings and assertions first  by  date  and
+       hledger  calculates  and checks an account's balance assertions in date
-       then  (for postings on the same day) by parse order.  Note this is dif-
+       order (and when there are multiple assertions on the same day, in parse
-       ferent from Ledger, which sorts assertions only by parse order.  (Also,
+       order).  Note this is different from Ledger,  which  checks  assertions
-       Ledger assertions do not see the accumulated effect of  repeated  post-
+       always in parse order, ignoring dates.
-       ings to the same account within a transaction.)
 
-       So,  hledger  balance  assertions  keep  working if you reorder differ-
+       This means in hledger you can freely reorder transactions, postings, or
-       ently-dated transactions  within  the  journal.   But  if  you  reorder
+       files, and balance assertions will usually keep working.  The exception
-       same-dated transactions or postings, assertions might break and require
+       is  when you reorder multiple postings on the same day, to the same ac-
-       updating.   This order dependence does bring an advantage: precise con-
+       count, which have balance assertions; those will likely need updating.
-       trol over the order of postings and assertions within a day, so you can
-       assert intra-day balances.
 
    Assertions and multiple included files
        Multiple files included with the include directive are processed as  if
@@ -1443,49 +1443,6 @@ Journal
        If  you  do  want assertions to see balance from earlier files, use in-
        clude, or concatenate the files temporarily.
 
-   Assertions and commodities
-       The asserted balance must be a simple single-commodity amount,  and  in
-       fact  the  assertion  checks  only  this commodity's balance within the
-       (possibly multi-commodity) account balance.   This  is  how  assertions
-       work in Ledger also.  We could call this a "partial" balance assertion.
-
-       To assert the balance of more than one commodity in an account, you can
-       write multiple postings, each asserting one commodity's balance.
-
-       You  can  make a stronger "total" balance assertion by writing a double
-       equals sign (== EXPECTEDBALANCE).  This asserts that there are no other
-       commodities in the account besides the asserted one (or at least,  that
-       their balance is 0).
-
-              2013/1/1
-                a   $1
-                a    1
-                b  $-1
-                c   -1
-
-              2013/1/2  ; These assertions succeed
-                a    0  =  $1
-                a    0  =   1
-                b    0 == $-1
-                c    0 ==  -1
-
-              2013/1/3  ; This assertion fails as 'a' also contains 1
-                a    0 ==  $1
-
-       It's not yet possible to make a complete assertion about a balance that
-       has  multiple commodities.  One workaround is to isolate each commodity
-       into its own subaccount:
-
-              2013/1/1
-                a:usd   $1
-                a:euro   1
-                b
-
-              2013/1/2
-                a        0 ==  0
-                a:usd    0 == $1
-                a:euro   0 ==  1
-
    Assertions and costs
        Balance assertions ignore costs, and should normally be written without
        one:
@@ -1499,16 +1456,64 @@ Journal
        command  used  to  generate balance assertions with costs), and because
        balance assignments do use costs (see below).
 
+   Assertions and commodities
+       The balance assertions described so far are "single  commodity  balance
+       assertions": they assert and check the balance in one commodity, ignor-
+       ing  any  others  that  may be present.  This is how balance assertions
+       work in Ledger also.
+
+       If an account contains multiple commodities, you can assert their  bal-
+       ances  by  writing  multiple  postings with balance assertions, one for
+       each commodity:
+
+              2013/1/1
+                usd   $-1
+                eur   -1
+                both
+
+              2013/1/2
+                both    0 = $1
+                both    0 = 1
+
+       In hledger you can make a stronger "sole commodity  balance  assertion"
+       by  writing  two  equals signs (== EXPECTEDBALANCE).  This also asserts
+       that there are no other commodities in the account besides the asserted
+       one (or at least, that their current balance is zero):
+
+              2013/1/1
+                usd   $-1  == $-1  ; these sole commodity assertions succeed
+                eur   -1  == -1
+                both      ;==  $1  ; this one would fail because 'both' contains $ and
+
+       It's less easy to make a "sole commodities balance assertion" (note the
+       plural) - ie, asserting that an account contains two or more  specified
+       commodities and no others.  It can be done by
+
+       1. isolating each commodity in a subaccount, and asserting those
+
+       2. and  also  asserting  there are no commodities in the parent account
+          itself:
+
+          2013/1/1
+            usd       $-1
+            eur       -1
+            both        0 == 0   ; nothing up my sleeve
+            both:usd   $1 == $1  ; a dollar here
+            both:eur   1 == 1  ; a euro there
+
    Assertions and subaccounts
-       The balance assertions above (= and ==) do not count the  balance  from
+       All of the balance assertions above (both = and ==) are "subaccount-ex-
-       subaccounts;  they check the account's exclusive balance only.  You can
+       clusive balance assertions"; they ignore any  balances  that  exist  in
-       assert the balance including subaccounts by writing =* or ==*, eg:
+       deeper subaccounts.
+
+       In  hledger  you  can make "subaccount-inclusive balance assertions" by
+       adding a star after the equals (=* or ==*):
 
               2019/1/1
-                equity:opening balances
+                equity:start
-                checking:a       5
+                assets:checking  $10
-                checking:b       5
+                assets:savings   $10
-                checking         1  ==* 11
+                assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else
 
    Assertions and virtual postings
        Balance assertions always consider both real and virtual postings; they
@@ -2641,7 +2646,7 @@ Journal
        This  directive sets a default commodity, to be used for any subsequent
        commodityless amounts (ie, plain numbers) seen while parsing the  jour-
        nal.   This  effect lasts until the next D directive, or the end of the
-       journal.
+       current file.
 
        For compatibility/historical reasons, D also acts like a commodity  di-
        rective  (setting  the commodity's decimal mark for parsing and display
@@ -2770,13 +2775,13 @@ Journal
        parentheses after an amount.  hledger ignores these.
 
    Virtual postings
-       A posting with parentheses around the account name ((some:account))  is
+       A posting with parentheses around the account name, like (some:account)
-       called  a unbalanced virtual posting.  Such postings do not participate
+       10, is called an unbalanced virtual posting.   These  postings  do  not
-       in transaction balancing.  (And if you write them without an amount,  a
+       participate  in  transaction balancing.  (And if you write them without
-       zero  amount is always inferred.)  These can occasionally be convenient
+       an amount, a zero amount is always inferred.)  These  can  occasionally
-       for special circumstances, but they violate  double  entry  bookkeeping
+       be  convenient for special circumstances, but they violate double entry
-       and  make  your  data less portable across applications, so many people
+       bookkeeping and make your data less portable  across  applications,  so
-       avoid using them at all.
+       many people avoid using them at all.
 
        A  posting  with  brackets  around the account name ([some:account]) is
        called a balanced virtual posting.  The balanced virtual postings in  a
@@ -4953,24 +4958,33 @@ Queries
        o match all the other terms.
 
        We  also  support  more  complex boolean queries with the expr: prefix.
-       This  allows  one  to  combine queries using AND, OR, and NOT.  (NOT is
+       This allows one to combine query terms  using  and,  or,  not  keywords
-       equivalent to the not: prefix.)  Some examples:
+       (case insensitive), and to group them by enclosing in parentheses.
 
-       o Match transactions with 'cool' in the description AND  with  the  'A'
+       Some examples:
-         tag
 
-         expr:"desc:cool AND tag:A"
+       o Exclude account names containing 'food':
 
-       o Match transactions NOT to the 'expenses:food' account OR with the 'A'
+         expr:"not food" (not:food is equivalent)
-         tag
 
-         expr:"NOT expenses:food OR tag:A"
+       o Match things which have 'cool' in the description and the 'A' tag:
 
-       o Match  transactions NOT involving the 'expenses:food' account OR with
+         expr:"desc:cool and tag:A" (expr:"desc:cool tag:A" is equivalent)
-         the 'A' tag AND involving the 'expenses:drink' account.  (the AND  is
-         implicitly added by space-separation, following the rules above)
 
-         expr:"expenses:food OR (tag:A expenses:drink)"
+       o Match  things  which  either do not reference the 'expenses:food' ac-
+         count, or do have the 'A' tag:
+
+         expr:"not expenses:food or tag:A"
+
+       o Match things which either do not reference  the  'expenses:food'  ac-
+         count,  or which reference the 'expenses:drink' account and also have
+         the 'A' tag:
+
+         expr:"expenses:food or (expenses:drink and tag:A)"
+
+       expr: has a restriction: date: queries may not be used  inside  or  ex-
+       pressions.  That would allow disjoint report periods or disjoint result
+       sets, with unclear semantics for our reports.
 
    Queries and command options
        Some  queries can also be expressed as command-line options: depth:2 is
@@ -7148,23 +7162,24 @@ PART 4: COMMANDS
        Example:
 
               $ hledger balancesheet
-              Balance Sheet
+              Balance Sheet 2008-12-31
 
-              Assets:
+                                  || 2008-12-31
-                               $-1  assets
+              ====================++============
-                                $1    bank:saving
+               Assets             ||
-                               $-2    cash
+              --------------------++------------
-              --------------------
+               assets:bank:saving ||         $1
-                               $-1
+               assets:cash        ||        $-2
-
+              --------------------++------------
-              Liabilities:
+                                  ||        $-1
-                                $1  liabilities:debts
+              ====================++============
-              --------------------
+               Liabilities        ||
-                                $1
+              --------------------++------------
-
+               liabilities:debts  ||        $-1
-              Total:
+              --------------------++------------
-              --------------------
+                                  ||        $-1
-                                 0
+              ====================++============
+               Net:               ||          0
 
        This command is a higher-level variant of the balance command, and sup-
        ports  many  of  that command's features, such as multi-period reports.
@@ -7191,28 +7206,29 @@ PART 4: COMMANDS
        Example:
 
               $ hledger balancesheetequity
-              Balance Sheet With Equity
+              Balance Sheet With Equity 2008-12-31
 
-              Assets:
+                                  || 2008-12-31
-                               $-2  assets
+              ====================++============
-                                $1    bank:saving
+               Assets             ||
-                               $-3    cash
+              --------------------++------------
-              --------------------
+               assets:bank:saving ||         $1
-                               $-2
+               assets:cash        ||        $-2
-
+              --------------------++------------
-              Liabilities:
+                                  ||        $-1
-                                $1  liabilities:debts
+              ====================++============
-              --------------------
+               Liabilities        ||
-                                $1
+              --------------------++------------
-
+               liabilities:debts  ||        $-1
-              Equity:
+              --------------------++------------
-                        $1  equity:owner
+                                  ||        $-1
-              --------------------
+              ====================++============
-                        $1
+               Equity             ||
-
+              --------------------++------------
-              Total:
+              --------------------++------------
-              --------------------
+                                  ||          0
-                                 0
+              ====================++============
+               Net:               ||          0
 
        This command is a higher-level variant of the balance command, and sup-
        ports many of that command's features, such  as  multi-period  reports.
@@ -7220,16 +7236,21 @@ PART 4: COMMANDS
        smarter  account detection, and liabilities/equity displayed with their
        sign flipped.
 
+       This report is the easiest way to see if the accounting equation (A+L+E
+       = 0) is satisfied (after you have done a close --retain to  merge  rev-
+       enues  and  expenses  with  equity, and perhaps added --infer-equity to
+       balance your commodity conversions).
+
        This command also supports the output destination and output format op-
        tions The output formats supported are txt, csv, tsv, html, and json.
 
    cashflow
        (cf)
 
-       This command displays a cashflow statement,  showing  the  inflows  and
+       This command displays a (simple) cashflow statement,  showing  the  in-
-       outflows  affecting  "cash"  (ie,  liquid,  easily convertible) assets.
+       flows  and  outflows  affecting "cash" (ie, liquid, easily convertible)
-       Amounts are shown with normal positive sign, as in conventional  finan-
+       assets.  Amounts are shown with normal positive  sign,  as  in  conven-
-       cial statements.
+       tional financial statements.
 
        This  report  shows  accounts  declared with the Cash type (see account
        types).  Or if no such accounts are declared, it shows accounts
@@ -7249,18 +7270,16 @@ PART 4: COMMANDS
        An example cashflow report:
 
               $ hledger cashflow
-              Cashflow Statement
+              Cashflow Statement 2008
 
-              Cash flows:
+                                  || 2008
-                               $-1  assets
+              ====================++======
-                                $1    bank:saving
+               Cash flows         ||
-                               $-2    cash
+              --------------------++------
-              --------------------
+               assets:bank:saving ||   $1
-                               $-1
+               assets:cash        ||  $-2
-
+              --------------------++------
-              Total:
+                                  ||  $-1
-              --------------------
-                               $-1
 
        This command is a higher-level variant of the balance command, and sup-
        ports  many  of  that command's features, such as multi-period reports.
@@ -7719,17 +7738,18 @@ PART 4: COMMANDS
        Note you can import from any file format, though CSV files are the most
        common import source, and these docs focus on that case.
 
-   Skipping
+   Deduplication
        import  tries  to  import only the transactions which are new since the
-       last import, "skipping over" any that it saw last  time.   So  if  your
+       last import, ignoring any that it has seen in  previous  runs.   So  if
-       bank's CSV includes the last three months of data, you can download and
+       your  bank's  CSV includes the last three months of data, you can down-
-       import  it  every month (or week, or day) and only the new transactions
+       load and import it every month (or week,  or  day)  and  only  the  new
-       will be imported each time.
+       transactions will be imported each time.
 
-       It works as follows.  For each imported FILE:
+       It  works  as  follows.   For each imported FILE (usually CSV, but they
+       could be any of hledger's input formats):
 
-       o It tries to find the latest date seen previously, by reading it  from
+       o It tries to recall the latest date seen previously, reading it from a
-         a hidden .latest.FILE in the same directory.
+         hidden .latest.FILE in the same directory.
 
        o Then it processes FILE, ignoring any transactions on  or  before  the
          "latest seen" date.
@@ -7737,32 +7757,38 @@ PART 4: COMMANDS
        And  after a successful import, it updates the .latest.FILE(s) for next
        time (unless --dry-run was used).
 
-       This is simple system that works fairly well for transaction data (usu-
+       This is a limited kind of deduplication, let's call it "date skipping".
-       ally CSV, but it could be any of hledger's input formats).  It assumes:
+       Within each input file, it avoids reprocessing the  same  dates  across
+       successive  runs.   This  is  a  simple  system  that  works  for  most
+       real-world CSV files; it assumes these are true, or true enough:
 
        1. new items always have the newest dates
 
-       2. item dates are stable across successive CSV downloads
+       2. item dates are stable across successive downloads
 
-       3. the order of same-date items is stable across CSV downloads
+       3. the order of same-date items is stable across downloads
 
-       These  are  true  of  most CSV files representing transactions, or true
+       4. the name of the input file is stable across downloads
-       enough.  If you have a bank whose CSV dates  or  ordering  occasionally
-       changes,  you  can  reduce the chance of this happening in new transac-
-       tions by importing more often (and in old transactions it doesn't  mat-
-       ter).
 
-       Note, import avoids reprocessing the same dates across successive runs,
+       If you have a bank whose CSV dates or ordering occasionally change, you
-       but it does not detect transactions that are duplicated within a single
+       can reduce the chance of this happening in new transactions by  import-
-       run.  I'll call these "skipping" and "deduplication".
+       ing  more often, and in old transactions it doesn't matter.  And remem-
+       ber you can use CSV rules files as input, which is one way to ensure  a
+       stable file name.
 
-       So  for  example, say you downloaded but did not import bank.1.csv, and
+       import  doesn't  detect  other  kinds of duplication, such as duplicate
-       later downloaded bank.2.csv with overlapping data.  Then you should not
+       transactions within a single run.  (In part, because legitimate  dupli-
-       import both of them at once (hledger import bank.1.csv bank.2.csv),  as
+       cate  transactions  can  easily occur in real-world data.)  So, say you
-       the  overlapping  data would appear twice and not be deduplicated.  In-
+       downloaded but forgot to import bank.1.csv, and a week later you  down-
-       stead, import them one at a time (hledger  import  bank.1.csv;  hledger
+       loaded  bank.2.csv  with  overlapping  data.  Now you should not import
-       import  bank.2.csv),  and  the  second import will skip the overlapping
+       both of these at once (hledger import bank.1.csv bank.2.csv); the over-
-       data.
+       lapping transactions which appear twice would not be deduplicated since
+       this is considered a single import.  Instead, import these files one at
+       a time, and also use the same filename each time for a  common  "latest
+       seen" state:
+
+              $ mv bank.1.csv bank.csv; hledger import bank.csv
+              $ mv bank.2.csv bank.csv; hledger import bank.csv
 
        Normally  you  can  ignore  the .latest.* files, but if needed, you can
        delete them (to make all transactions unseen), or construct/modify them
@@ -7771,8 +7797,8 @@ PART 4: COMMANDS
        "I have seen transactions up to this date, and this many of them occur-
        ring on that date".
 
-       (hledger  print  --new also uses and updates these .latest.* files, but
+       hledger print --new also uses and updates these .latest.* files, but it
-       it is less often used.)
+       is less often used.
 
        Related: CSV > Working with CSV > Deduplicating, importing.
 
@@ -7828,25 +7854,25 @@ PART 4: COMMANDS
        Example:
 
               $ hledger incomestatement
-              Income Statement
+              Income Statement 2008
 
-              Revenues:
+                                 || 2008
-                               $-2  income
+              ===================++======
-                               $-1    gifts
+               Revenues          ||
-                               $-1    salary
+              -------------------++------
-              --------------------
+               income:gifts      ||   $1
-                               $-2
+               income:salary     ||   $1
-
+              -------------------++------
-              Expenses:
+                                 ||   $2
-                                $2  expenses
+              ===================++======
-                                $1    food
+               Expenses          ||
-                                $1    supplies
+              -------------------++------
-              --------------------
+               expenses:food     ||   $1
-                                $2
+               expenses:supplies ||   $1
-
+              -------------------++------
-              Total:
+                                 ||   $2
-              --------------------
+              ===================++======
-                                 0
+               Net:              ||    0
 
        This command is a higher-level variant of the balance command, and sup-
        ports  many  of  that command's features, such as multi-period reports.
@@ -9090,4 +9116,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-1.32.99                   March 2024                        HLEDGER(1)
+hledger-1.33.99                   April 2024                        HLEDGER(1)