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

hledger-ui/hledger-ui.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-UI" "1" "September 2024" "hledger-ui-1.40.99 " "hledger User Manuals"
+.TH "HLEDGER\-UI" "1" "October 2024" "hledger-ui-1.40.99 " "hledger User Manuals"
 
 
 

hledger-ui/hledger-ui.info

@@ -1,4 +1,4 @@
-This is hledger-ui.info, produced by makeinfo version 7.1 from stdin.
+This is hledger-ui.info, produced by makeinfo version 7.1.1 from stdin.
 
 INFO-DIR-SECTION User Applications
 START-INFO-DIR-ENTRY
@@ -538,37 +538,22 @@ above).
 
 
 Tag Table:
-Node: Top221
+Node: Top223
-Node: OPTIONS1872
+Node: OPTIONS1874
-Ref: #options1970
+Node: MOUSE8391
-Node: MOUSE8389
+Node: KEYS8723
-Ref: #mouse8484
+Node: SCREENS13551
-Node: KEYS8721
+Node: Menu screen14291
-Ref: #keys8814
+Node: Cash accounts screen14607
-Node: SCREENS13549
+Node: Balance sheet accounts screen14968
-Ref: #screens13653
+Node: Income statement accounts screen15304
-Node: Menu screen14289
+Node: All accounts screen15689
-Ref: #menu-screen14410
+Node: Register screen16052
-Node: Cash accounts screen14605
+Node: Transaction screen18495
-Ref: #cash-accounts-screen14782
+Node: Error screen20070
-Node: Balance sheet accounts screen14966
+Node: WATCH MODE20436
-Ref: #balance-sheet-accounts-screen15182
+Node: ENVIRONMENT22012
-Node: Income statement accounts screen15302
+Node: BUGS22319
-Ref: #income-statement-accounts-screen15523
-Node: All accounts screen15687
-Ref: #all-accounts-screen15868
-Node: Register screen16050
-Ref: #register-screen16209
-Node: Transaction screen18493
-Ref: #transaction-screen18651
-Node: Error screen20068
-Ref: #error-screen20190
-Node: WATCH MODE20434
-Ref: #watch-mode20551
-Node: ENVIRONMENT22010
-Ref: #environment22126
-Node: BUGS22317
-Ref: #bugs22400
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -448,4 +448,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-ui-1.40.99              September 2024                   HLEDGER-UI(1)
+hledger-ui-1.40.99               October 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_}}, {{September 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{October 2024}})m4_dnl

hledger-web/hledger-web.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-WEB" "1" "September 2024" "hledger-web-1.40.99 " "hledger User Manuals"
+.TH "HLEDGER\-WEB" "1" "October 2024" "hledger-web-1.40.99 " "hledger User Manuals"
 
 
 

hledger-web/hledger-web.info

@@ -1,4 +1,4 @@
-This is hledger-web.info, produced by makeinfo version 7.1 from stdin.
+This is hledger-web.info, produced by makeinfo version 7.1.1 from stdin.
 
 INFO-DIR-SECTION User Applications
 START-INFO-DIR-ENTRY
@@ -526,25 +526,16 @@ http://bugs.hledger.org), or on the #hledger chat or hledger mail list
 
 
 Tag Table:
-Node: Top223
+Node: Top225
-Node: OPTIONS2569
+Node: OPTIONS2571
-Ref: #options2674
+Node: PERMISSIONS11103
-Node: PERMISSIONS11101
+Node: EDITING UPLOADING DOWNLOADING12454
-Ref: #permissions11240
+Node: RELOADING13469
-Node: EDITING UPLOADING DOWNLOADING12452
+Node: JSON API14036
-Ref: #editing-uploading-downloading12633
+Node: DEBUG OUTPUT19685
-Node: RELOADING13467
+Node: Debug output19837
-Ref: #reloading13601
+Node: ENVIRONMENT20355
-Node: JSON API14034
+Node: BUGS20591
-Ref: #json-api14149
-Node: DEBUG OUTPUT19683
-Ref: #debug-output19808
-Node: Debug output19835
-Ref: #debug-output-119936
-Node: ENVIRONMENT20353
-Ref: #environment20472
-Node: BUGS20589
-Ref: #bugs20673
 
 End Tag Table
 

hledger-web/hledger-web.txt

@@ -478,4 +478,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-web-1.40.99             September 2024                  HLEDGER-WEB(1)
+hledger-web-1.40.99              October 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_}}, {{September 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{October 2024}})m4_dnl

hledger/hledger.1

@@ -1,6 +1,6 @@
 .\"t
 
-.TH "HLEDGER" "1" "September 2024" "hledger-1.40.99 " "hledger User Manuals"
+.TH "HLEDGER" "1" "October 2024" "hledger-1.40.99 " "hledger User Manuals"
 
 
 
@@ -723,91 +723,99 @@ then reuse them by writing \f[CR]\[at]FILENAME\f[R] as a command line
 argument.
 Eg: \f[CR]hledger bal \[at]foo.args\f[R].
 .PP
-(Inside the argument file, each line should contain just one option or
+An argument file\[aq]s format is more restrictive than the command line.
-argument.
+Each line should contain just one option or argument.
 Don\[aq]t use spaces except inside quotes; write \f[CR]=\f[R] or nothing
 between a flag and its argument.
+If you use quotes, they must enclose the whole line.
 For the special characters mentioned above, use one less level of
-quoting than you would at the command prompt.)
+quoting than you would at the command line.
-.PP
-Argument files are now superseded by..
 .SS Config files
-As of hledger 1.40, you can optionally save command line options (or
+With hledger 1.40+, you can save extra command line options and
-arguments) to be used when running hledger commands, in a config file.
+arguments in a more featureful hledger config file.
 Here\[aq]s a small example:
 .IP
 .EX
-\f[I]# General options are listed first, one or more per line.\f[R]
+\f[I]# General options are listed first, and used with hledger commands that support them.\f[R]
-\f[I]# These will be used with all hledger commands that support them.\f[R]
 \-\-pretty
 
-\f[I]# Options following a \[ga][COMMANDNAME]\[ga] heading are used with that hledger command only.\f[R]
+\f[I]# Options following a \[ga][COMMAND]\[ga] heading are used with that hledger command only.\f[R]
 \f[B][print]\f[R]
 \-\-explicit \-\-show\-costs
 .EE
 .PP
 To use a config file, specify it with the \f[CR]\-\-conf\f[R] option.
-Its options will be inserted near the start of your command line (so you
+Its options will be inserted near the start of your command line, so you
-can override them if needed).
+can override them with command line options if needed.
 .PP
 Or, you can set up an automatic config file that is used whenever you
-run hledger.
+run hledger, by creating \f[CR]hledger.conf\f[R] in the current
-This can be \f[CR]hledger.conf\f[R] in the current directory or above,
+directory or above, or \f[CR].hledger.conf\f[R] in your home directory
-or \f[CR].hledger.conf\f[R] in your home directory
 (\f[CR]\[ti]/.hledger.conf\f[R]), or \f[CR]hledger.conf\f[R] in your XDG
 config directory (\f[CR]\[ti]/.config/hledger/hledger.conf\f[R]).
 .PP
-You can ignore config files by adding the \f[CR]\-n/\-\-no\-conf\f[R]
+Here is another example config you could start with:
-flag.
-This is useful when using hledger in scripts, or when troubleshooting.
-(When both \f[CR]\-\-conf\f[R] and \f[CR]\-\-no\-conf\f[R] options are
-used, the right\-most wins.)
-To inspect the processing of config files, use \f[CR]\-\-debug\f[R] or
-\f[CR]\-\-debug=8\f[R].
-.PP
-Here is another example config file you could start with:
 https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
 .PP
-Tips:
+You can put not only options, but also arguments in a config file.
-.PP
+If the first word in a config file\[aq]s top (general) section does not
-Automatic config files are convenient, but have a cost: it\[aq]s easy to
+begin with a dash (eg: \f[CR]print\f[R]), it is treated as the command
-change a report\[aq]s behaviour, or break scripts/applications which use
+argument (overriding any argument on the command line).
-hledger, in unintended ways that will surprise you later.
-They change the nature of hledger somewhat, making it less transparent
-and predictable.
-If you decide to use one:
-.IP \[bu] 2
-Be conservative about what you put in it.
-Try to consider the effect on all your reports.
-.IP \[bu] 2
-Whenever a hledger command does not work as expected, try it again with
-\f[CR]\-n\f[R].
-.IP \[bu] 2
-If that helps, you can run it with \f[CR]\-\-debug\f[R] to see how a
-config file affected it.
 .PP
 On unix machines, you can add a shebang line at the top of a config
 file, set executable permission on the file, and use it like a script.
-Eg (some operating systems need the \f[CR]\-S\f[R], some don\[aq]t):
+Eg (the \f[CR]\-S\f[R] is needed on some operating systems):
 .IP
 .EX
 #!/usr/bin/env \-S hledger \-\-conf
 .EE
 .PP
-You can put not only options, but also arguments in a config file.
+You can ignore config files by adding the
-This is probably more useful in special\-purpose config files, not an
+\f[CR]\-n\f[R]/\f[CR]\-\-no\-conf\f[R] flag to the command line.
-automatic one.
+This is useful when using hledger in scripts, or when troubleshooting.
+When both \f[CR]\-\-conf\f[R] and \f[CR]\-\-no\-conf\f[R] options are
+used, the right\-most wins.
 .PP
-There\[aq]s an exception to this: a config file can\[aq]t provide the
+To inspect the processing of config files, use \f[CR]\-\-debug\f[R] or
-command argument, currently (#2231).
+\f[CR]\-\-debug=8\f[R].
-If you need that, you can do it in the shebang line instead.
-Eg:
-.IP
-.EX
-#!/usr/bin/env \-S hledger balance \-\-conf
-.EE
 .PP
-The config file feature has been added in hledger 1.40 and is considered
+\f[B]Warning!\f[R]
+.PP
+There aren\[aq]t many hledger features that need a warning, but this is
+one!
+.PP
+Automatic config files, while convenient, also make hledger less
+predictable and dependable.
+It\[aq]s easy to make a config file that changes a report\[aq]s
+behaviour, or breaks your hledger\-using scripts/applications, in ways
+that will surprise you later.
+.PP
+If you don\[aq]t want this,
+.IP "1." 3
+Just don\[aq]t create a hledger.conf file on your machine.
+.IP "2." 3
+Also be alert to downloaded directories which may contain a hledger.conf
+file.
+.IP "3." 3
+Also if you are sharing scripts or examples or support, consider that
+others may have a hledger.conf file.
+.PP
+Conversely, once you decide to use this feature, try to remember:
+.IP "1." 3
+Whenever a hledger command does not work as expected, try it again with
+\f[CR]\-n\f[R] (\f[CR]\-\-no\-conf\f[R]) to see if a config file was to
+blame.
+.IP "2." 3
+Whenever you call hledger from a script, consider whether that call
+should use \f[CR]\-n\f[R] or not.
+.IP "3." 3
+Be conservative about what you put in your config file; try to consider
+the effect on all your reports.
+.IP "4." 3
+To troubleshoot the effect of config files, run with
+\f[CR]\-\-debug\f[R] or \f[CR]\-\-debug 8\f[R].
+.PP
+The config file feature was added in hledger 1.40 and is considered
 \f[I]experimental\f[R].
 .SS Shell completions
 If you use the bash shell, you can optionally set up context\-sensitive
@@ -829,8 +837,8 @@ $ hledger print > foo.txt
 .EE
 .PP
 Some commands (print, register, stats, the balance commands) also
-provide the \f[CR]\-o/\-\-output\-file\f[R] option, which does the same
+provide the \f[CR]\-o\f[R]/\f[CR]\-\-output\-file\f[R] option, which
-thing without needing the shell.
+does the same thing without needing the shell.
 Eg:
 .IP
 .EX
@@ -844,21 +852,23 @@ Here are those commands and the formats currently supported:
 .PP
 .TS
 tab(@);
-lw(13.6n) lw(12.2n) lw(12.2n) lw(12.2n) lw(12.2n) lw(4.1n) lw(3.4n).
+lw(20.6n) lw(5.1n) lw(6.2n) lw(9.3n) lw(6.2n) lw(11.3n) lw(5.1n) lw(6.2n).
 T{
-\-
+command
 T}@T{
 txt
 T}@T{
-csv/tsv
-T}@T{
 html
 T}@T{
+csv/tsv
+T}@T{
 fods
 T}@T{
-json
+beancount
 T}@T{
 sql
+T}@T{
+json
 T}
 _
 T{
@@ -871,83 +881,91 @@ T}@T{
 Y
 T}@T{
 T}@T{
-Y
 T}@T{
+T}@T{
+Y
 T}
 T{
 balance
 T}@T{
-Y \f[I]1\f[R]
+Y
-T}@T{
-Y \f[I]1\f[R]
-T}@T{
-Y \f[I]1\f[R]
-T}@T{
-Y \f[I]1\f[R]
 T}@T{
 Y
 T}@T{
+Y
+T}@T{
+Y
+T}@T{
+T}@T{
+T}@T{
+Y
 T}
 T{
 balancesheet
 T}@T{
-Y \f[I]1\f[R]
+Y
-T}@T{
-Y \f[I]1\f[R]
-T}@T{
-Y \f[I]1\f[R]
-T}@T{
 T}@T{
 Y
 T}@T{
+Y
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+Y
 T}
 T{
 balancesheetequity
 T}@T{
-Y \f[I]1\f[R]
+Y
-T}@T{
-Y \f[I]1\f[R]
-T}@T{
-Y \f[I]1\f[R]
-T}@T{
 T}@T{
 Y
 T}@T{
+Y
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+Y
 T}
 T{
 cashflow
 T}@T{
-Y \f[I]1\f[R]
+Y
-T}@T{
-Y \f[I]1\f[R]
-T}@T{
-Y \f[I]1\f[R]
-T}@T{
 T}@T{
 Y
 T}@T{
+Y
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+Y
 T}
 T{
 incomestatement
 T}@T{
-Y \f[I]1\f[R]
+Y
-T}@T{
-Y \f[I]1\f[R]
-T}@T{
-Y \f[I]1\f[R]
-T}@T{
 T}@T{
 Y
 T}@T{
+Y
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+Y
 T}
 T{
 print
 T}@T{
 Y
 T}@T{
+T}@T{
 Y
 T}@T{
 T}@T{
+Y
 T}@T{
 Y
 T}@T{
@@ -958,27 +976,25 @@ register
 T}@T{
 Y
 T}@T{
+T}@T{
 Y
 T}@T{
 T}@T{
 T}@T{
+T}@T{
 Y
-T}@T{
 T}
 .TE
-.IP \[bu] 2
-\f[I]1 Also affected by the balance commands\[aq] \f[CI]\-\-layout\f[I]
-option.\f[R]
 .PP
 The output format is selected by the
-\f[CR]\-O/\-\-output\-format=FMT\f[R] option:
+\f[CR]\-O\f[R]/\f[CR]\-\-output\-format=FMT\f[R] option:
 .IP
 .EX
 $ hledger print \-O csv    # print CSV on stdout
 .EE
 .PP
 or by the filename extension of an output file specified with the
-\f[CR]\-o/\-\-output\-file=FILE.FMT\f[R] option:
+\f[CR]\-o\f[R]/\f[CR]\-\-output\-file=FILE.FMT\f[R] option:
 .IP
 .EX
 $ hledger balancesheet \-o foo.csv    # write CSV to foo.csv
@@ -991,11 +1007,10 @@ override the file extension, if needed:
 $ hledger balancesheet \-o foo.txt \-O csv    # write CSV to foo.txt
 .EE
 .PP
-Some notes about the various output formats:
+Here are some notes about the various output formats.
-.SS CSV output
+.SS Text output
-.IP \[bu] 2
+This is the default: human readable, plain text report output, suitable
-In CSV output, digit group marks (such as thousands separators) are
+for a terminal.
-disabled automatically.
 .SS HTML output
 .IP \[bu] 2
 HTML output can be styled by an optional \f[CR]hledger.css\f[R] file in
@@ -1006,28 +1021,74 @@ If your web browser is showing junk characters, you may need to change
 its text encoding to UTF\-8.
 Eg in Safari, see View \-> Text Encoding and Settings \-> Advanced \->
 Default Encoding.
-.SS JSON output
+.SS CSV / TSV output
 .IP \[bu] 2
-This is not yet much used; real\-world feedback is welcome.
+In CSV or TSV output, digit group marks (such as thousands separators)
-.IP \[bu] 2
+are disabled automatically.
-Our JSON is rather large and verbose, since it is a faithful
+.SS FODS output
-representation of hledger\[aq]s internal data types.
+FODS is the OpenDocument spreadsheet format used by LibreOffice and
-To understand the JSON, read the Haskell type definitions, which are
+OpenOffice.
-mostly in
+It is a good format to use if you are exporting to their spreadsheet
-https://github.com/simonmichael/hledger/blob/master/hledger\-lib/Hledger/Data/Types.hs.
+app.
-hledger\-web\[aq]s OpenAPI specification may also be relevant.
+.SS Beancount output
-.IP \[bu] 2
+This is Beancount\[aq]s journal format.
-hledger represents quantities as Decimal values storing up to 255
+You can use this to export your hledger data to Beancount, perhaps to
-significant digits, eg for repeating decimals.
+query it with Beancount Query Language or with the Fava web app.
-Such numbers can arise in practice (from automatically\-calculated
+hledger will try to adjust your data to suit Beancount.
-transaction prices), and would break most JSON consumers.
+If you plan to export often, you may want to follow Beancount\[aq]s
-So in JSON, we show quantities as simple Numbers with at most 10 decimal
+conventions in your hledger data, to ease conversion.
-places.
+Eg use Beancount\-friendly account names, currency codes instead of
-We don\[aq]t limit the number of integer digits, but that part is under
+currency symbols, and avoid virtual postings, redundant cost notation,
-your control.
+etc.
-We hope this approach will not cause problems in practice; if you find
+.PP
-otherwise, please let us know.
+Here are more details, included here for now (see also \[dq]hledger and
-(Cf #1195)
+Beancount\[dq] https://hledger.org/beancount.html).
+.SS Beancount account names
+hledger will try adjust your account names, if needed, to Beancount
+account names, by capitalising, replacing unsupported characters with
+\f[CR]\-\f[R], and prepending \f[CR]B\f[R] to parts which don\[aq]t
+begin with a letter or digit.
+(It\[aq]s possible for this to convert distinct hledger account names to
+the same beancount name.
+Eg, hledger\[aq]s automatic equity conversion accounts can have currency
+symbols in their name, so \f[CR]equity:conversion:$\-€\f[R] becomes
+\f[CR]equity:conversion:B\-\-\-\f[R].)
+.PP
+In addition, you must ensure that the top level account names are
+\f[CR]Assets\f[R], \f[CR]Liabilities\f[R], \f[CR]Equity\f[R],
+\f[CR]Income\f[R], and \f[CR]Expenses\f[R], which Beancount requires.
+If yours are named differently, you can use account aliases, usually in
+the form of \f[CR]\-\-alias\f[R] options, possibly stored in a config
+file.
+(An example: hledger2beancount.conf)
+.SS Beancount commodity names
+hledger will adjust your commodity names, if needed, to Beancount
+commodity/currency names, which must be 2\-24 uppercase letters, digits,
+or \f[CR]\[aq]\f[R], \f[CR].\f[R], \f[CR]_\f[R], \f[CR]\-\f[R],
+beginning with a letter and ending with a letter or digit.
+hledger will convert known currency symbols to ISO 4217 currency codes.
+Otherwise, it will capitalise letters, replace unsupported characters
+with a dash (\-), and prepend/append a \[dq]B\[dq] when needed.
+(It\[aq]s possible for this to generate unreadable commodity names, or
+to convert distinct hledger commodity names to the same beancount name.)
+.SS Beancount virtual postings
+Beancount doesn\[aq]t allow unbalanced/virtual postings, so you will
+need to comment those, or use \f[CR]\-\-real\f[R] to exclude
+transactions that use them.
+(If you have transactions which are a mixture of balanced and unbalanced
+postings, you\[aq]ll have to do something more.)
+.SS Beancount costs
+Beancount doesn\[aq]t allow redundant cost notation as hledger does.
+If you have entries like this, you will need to comment out either the
+costs or the equity postings.
+.SS Beancount operating currency
+Declaring an operating currency improves Beancount and Fava reports.
+You can do this manually by adding a line like this to the beancount
+journal:
+.IP
+.EX
+option \[dq]operating_currency\[dq] \[dq]USD\[dq]
+.EE
 .SS SQL output
 .IP \[bu] 2
 This is not yet much used; real\-world feedback is welcome.
@@ -1050,6 +1111,28 @@ If you already have tables created via SQL output of hledger, you would
 probably want to either clear tables of existing data (via
 \f[CR]delete\f[R] or \f[CR]truncate\f[R] SQL statements) or drop tables
 completely as otherwise your postings will be duped.
+.SS JSON output
+.IP \[bu] 2
+This is not yet much used; real\-world feedback is welcome.
+.IP \[bu] 2
+Our JSON is rather large and verbose, since it is a faithful
+representation of hledger\[aq]s internal data types.
+To understand the JSON, read the Haskell type definitions, which are
+mostly in
+https://github.com/simonmichael/hledger/blob/master/hledger\-lib/Hledger/Data/Types.hs.
+hledger\-web\[aq]s OpenAPI specification may also be relevant.
+.IP \[bu] 2
+hledger represents quantities as Decimal values storing up to 255
+significant digits, eg for repeating decimals.
+Such numbers can arise in practice (from automatically\-calculated
+transaction prices), and would break most JSON consumers.
+So in JSON, we show quantities as simple Numbers with at most 10 decimal
+places.
+We don\[aq]t limit the number of integer digits, but that part is under
+your control.
+We hope this approach will not cause problems in practice; if you find
+otherwise, please let us know.
+(Cf #1195)
 .SS Commodity styles
 When displaying amounts, hledger infers a standard display style for
 each commodity/currency, as described below in Commodity display style.
@@ -2156,16 +2239,18 @@ Tags hledger adds to indicate generated data:
  generated\-transaction  \-\- appears on generated periodic txns (with \-\-verbose\-tags)
  generated\-posting      \-\- appears on generated auto postings (with \-\-verbose\-tags)
  modified               \-\- appears on txns which have had auto postings added (with \-\-verbose\-tags)
+
 Not displayed, but queryable:
  _generated\-transaction \-\- exists on generated periodic txns (always)
  _generated\-posting     \-\- exists on generated auto postings (always)
  _modified              \-\- exists on txns which have had auto postings added (always)
 .EE
 .PP
-Tags hledger uses internally:
+Other tags hledger uses internally:
 .IP
 .EX
- _conversion\-matched    \-\- exists on postings which have been matched with a nearby \[at]/\[at]\[at] cost annotation
+ _cost\-matched          \-\- marks postings with a cost which have been matched with a nearby pair of equity conversion postings
+ _conversion\-matched    \-\- marks equity conversion postings which have been matched with a nearby posting with a cost
 .EE
 .SS Tag values
 Tags can have a value, which is any text after the colon up until a
@@ -2510,8 +2595,9 @@ Usually you\[aq]ll find that error later, as an extra account in balance
 reports, or an incorrect balance when reconciling.
 .PP
 In strict mode, enabled with the \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R]
-flag, hledger will report an error if any transaction uses an account
+flag, or when you run \f[CR]hledger check accounts\f[R], hledger will
-name that has not been declared by an account directive.
+report an error if any transaction uses an account name that has not
+been declared by an account directive.
 Some notes:
 .IP \[bu] 2
 The declaration is case\-sensitive; transactions must use the correct
@@ -2530,6 +2616,9 @@ affect included files of all types.
 It\[aq]s currently not possible to declare \[dq]all possible
 subaccounts\[dq] with a wildcard; every account posted to must be
 declared.
+.IP \[bu] 2
+If you use the \-\-infer\-equity flag, you will also need declarations
+for the account names it generates.
 .SS Account display order
 Account directives also cause hledger to display accounts in a
 particular order, not just alphabetically.
@@ -7073,6 +7162,10 @@ The equity account names will be \[dq]equity:conversion:A\-B:A\[dq] and
 commodity symbol.
 You can customise the \[dq]equity:conversion\[dq] part by declaring an
 account with the \f[CR]V\f[R]/\f[CR]Conversion\f[R] account type.
+.PP
+Note you will need to add account declarations for these to your
+journal, if you use \f[CR]check accounts\f[R] or
+\f[CR]check \-\-strict\f[R].
 .SS Combining costs and equity conversion postings
 Finally, you can use both the \[at]/\[at]\[at] cost notation and equity
 postings at the same time.
@@ -10439,10 +10532,10 @@ uses all periodic rules; or with an argument
 T}
 .TE
 .SS Balance report layout
-The \f[CR]\-\-layout\f[R] option affects how balance reports show
+The \f[CR]\-\-layout\f[R] option affects how \f[CR]balance\f[R] and the
-multi\-commodity amounts and commodity symbols, which can improve
+other balance\-like commands show multi\-commodity amounts and commodity
-readability.
+symbols.
-It can also normalise the data for easy consumption by other programs.
+It can improve readability, for humans and/or machines (other software).
 It has four possible values:
 .IP \[bu] 2
 \f[CR]\-\-layout=wide[,WIDTH]\f[R]: commodities are shown on a single
@@ -10454,7 +10547,9 @@ line, optionally elided to WIDTH
 amounts are bare numbers
 .IP \[bu] 2
 \f[CR]\-\-layout=tidy\f[R]: data is normalised to easily\-consumed
-\[dq]tidy\[dq] form, with one row per data value
+\[dq]tidy\[dq] form, with one row per data value.
+(This one is currently supported only by the \f[CR]balance\f[R]
+command.)
 .PP
 Here are the \f[CR]\-\-layout\f[R] modes supported by each output format
 Only CSV output supports all of them:
@@ -10658,10 +10753,9 @@ You can also produce relative links, like
 \f[CR]\-\-base\-url=\[dq]some/path\[dq]\f[R] or
 \f[CR]\-\-base\-url=\[dq]\[dq]\f[R].)
 .PP
-The balance reports\[aq] HTML output currently does not display tree
+The balance reports\[aq] HTML output currently does not indent tree mode
-mode reports properly (#1846).
+reports properly (#1846).
-For now, if generating HTML you should probabBly use the default
+So in HTML balance reports, use list mode for now (it is the default).
-\f[CR]\-\-flat\f[R] mode.
 .SS Some useful balance reports
 Some frequently used \f[CR]balance\f[R] options/reports are:
 .IP \[bu] 2

hledger/hledger.txt

@@ -559,80 +559,92 @@ Options
        then  reuse  them by writing @FILENAME as a command line argument.  Eg:
        hledger bal @foo.args.
 
-       (Inside the argument file, each line should contain just one option  or
+       An argument file's format is more restrictive than  the  command  line.
-       argument.   Don't  use  spaces except inside quotes; write = or nothing
+       Each line should contain just one option or argument.  Don't use spaces
-       between a flag and its argument.  For the special characters  mentioned
+       except  inside  quotes; write = or nothing between a flag and its argu-
-       above,  use  one  less  level  of quoting than you would at the command
+       ment.  If you use quotes, they must enclose the whole  line.   For  the
-       prompt.)
+       special  characters mentioned above, use one less level of quoting than
-
+       you would at the command line.
-       Argument files are now superseded by..
 
    Config files
-       As of hledger 1.40, you can optionally save command  line  options  (or
+       With hledger 1.40+, you can save extra command line options  and  argu-
-       arguments)  to be used when running hledger commands, in a config file.
+       ments  in  a more featureful hledger config file.  Here's a small exam-
-       Here's a small example:
+       ple:
 
-              # General options are listed first, one or more per line.
+              # General options are listed first, and used with hledger commands that support them.
-              # These will be used with all hledger commands that support them.
               --pretty
 
-              # Options following a `[COMMANDNAME]` heading are used with that hledger command only.
+              # Options following a `[COMMAND]` heading are used with that hledger command only.
               [print]
               --explicit --show-costs
 
        To use a config file, specify it with the --conf option.   Its  options
-       will  be inserted near the start of your command line (so you can over-
+       will  be inserted near the start of your command line, so you can over-
-       ride them if needed).
+       ride them with command line options if needed.
 
        Or, you can set up an automatic config file that is used  whenever  you
-       run  hledger.   This  can  be  hledger.conf in the current directory or
+       run  hledger,  by  creating  hledger.conf  in  the current directory or
        above, or .hledger.conf in your home  directory  (~/.hledger.conf),  or
        hledger.conf     in     your     XDG    config    directory    (~/.con-
        fig/hledger/hledger.conf).
 
-       You can ignore config files by adding the -n/--no-conf flag.   This  is
+       Here   is   another   example   config   you    could    start    with:
-       useful  when  using hledger in scripts, or when troubleshooting.  (When
-       both --conf and --no-conf options are used, the right-most  wins.)   To
-       inspect the processing of config files, use --debug or --debug=8.
-
-       Here   is   another   example   config   file  you  could  start  with:
        https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
 
-       Tips:
+       You  can put not only options, but also arguments in a config file.  If
-
+       the first word in a config file's top (general) section does not  begin
-       Automatic config files are convenient, but have a cost:  it's  easy  to
+       with  a  dash (eg: print), it is treated as the command argument (over-
-       change  a  report's  behaviour, or break scripts/applications which use
+       riding any argument on the command line).
-       hledger, in unintended ways that will surprise you later.  They  change
-       the  nature  of  hledger  somewhat, making it less transparent and pre-
-       dictable.  If you decide to use one:
-
-       o Be conservative about what you put in it.  Try to consider the effect
-         on all your reports.
-
-       o Whenever a hledger command does not work as expected,  try  it  again
-         with -n.
-
-       o If  that  helps, you can run it with --debug to see how a config file
-         affected it.
 
        On unix machines, you can add a shebang line at the  top  of  a  config
        file,  set executable permission on the file, and use it like a script.
-       Eg (some operating systems need the -S, some don't):
+       Eg (the -S is needed on some operating systems):
 
               #!/usr/bin/env -S hledger --conf
 
-       You can put not only options, but also  arguments  in  a  config  file.
+       You can ignore config files by adding the -n/--no-conf flag to the com-
-       This  is  probably  more useful in special-purpose config files, not an
+       mand line.  This is useful when using hledger in scripts, or when trou-
-       automatic one.
+       bleshooting.  When both --conf and  --no-conf  options  are  used,  the
+       right-most wins.
 
-       There's an exception to this: a config file can't provide  the  command
+       To inspect the processing of config files, use --debug or --debug=8.
-       argument,  currently  (#2231).   If you need that, you can do it in the
-       shebang line instead.  Eg:
 
-              #!/usr/bin/env -S hledger balance --conf
+       Warning!
 
-       The config file feature has been added in hledger 1.40 and  is  consid-
+       There  aren't  many  hledger  features that need a warning, but this is
-       ered experimental.
+       one!
+
+       Automatic config files, while convenient, also make hledger  less  pre-
+       dictable  and dependable.  It's easy to make a config file that changes
+       a report's behaviour, or  breaks  your  hledger-using  scripts/applica-
+       tions, in ways that will surprise you later.
+
+       If you don't want this,
+
+       1. Just don't create a hledger.conf file on your machine.
+
+       2. Also  be  alert  to  downloaded  directories  which  may  contain  a
+          hledger.conf file.
+
+       3. Also if you are sharing scripts or  examples  or  support,  consider
+          that others may have a hledger.conf file.
+
+       Conversely, once you decide to use this feature, try to remember:
+
+       1. Whenever  a  hledger command does not work as expected, try it again
+          with -n (--no-conf) to see if a config file was to blame.
+
+       2. Whenever you call hledger from a script, consider whether that  call
+          should use -n or not.
+
+       3. Be  conservative about what you put in your config file; try to con-
+          sider the effect on all your reports.
+
+       4. To troubleshoot the effect of config  files,  run  with  --debug  or
+          --debug 8.
+
+       The config file feature was added in hledger 1.40 and is considered ex-
+       perimental.
 
    Shell completions
        If  you use the bash shell, you can optionally set up context-sensitive
@@ -660,21 +672,17 @@ Output
        Some commands offer other kinds of output, not just text on the  termi-
        nal.  Here are those commands and the formats currently supported:
 
-       -                txt            csv/tsv        html           fods            json   sql
+       command                 txt     html     csv/tsv     fods     beancount      sql     json
-       -----------------------------------------------------------------------------------------
+       --------------------------------------------------------------------------------------------
        aregister               Y       Y        Y                                           Y
-       balance          Y 1            Y 1            Y 1            Y 1             Y
+       balance                 Y       Y        Y           Y                               Y
-       balancesheet     Y 1            Y 1            Y 1                            Y
+       balancesheet            Y       Y        Y                                           Y
-       balancesheete-   Y 1            Y 1            Y 1                            Y
+       balancesheetequity      Y       Y        Y                                           Y
-       quity
+       cashflow                Y       Y        Y                                           Y
-       cashflow         Y 1            Y 1            Y 1                            Y
+       incomestatement         Y       Y        Y                                           Y
-       incomestate-     Y 1            Y 1            Y 1                            Y
+       print                   Y                Y                    Y              Y       Y
-       ment
-       print            Y              Y                                             Y      Y
        register                Y                Y                                           Y
 
-       o 1 Also affected by the balance commands' --layout option.
-
        The output format is selected by the -O/--output-format=FMT option:
 
               $ hledger print -O csv    # print CSV on stdout
@@ -689,11 +697,11 @@ Output
 
               $ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt
 
-       Some notes about the various output formats:
+       Here are some notes about the various output formats.
 
-   CSV output
+   Text output
-       o In  CSV  output, digit group marks (such as thousands separators) are
+       This is the default: human readable, plain text report output, suitable
-         disabled automatically.
+       for a terminal.
 
    HTML output
        o HTML output can be styled by an optional hledger.css file in the same
@@ -704,6 +712,88 @@ Output
          Eg  in  Safari, see View -> Text Encoding and Settings -> Advanced ->
          Default Encoding.
 
+   CSV / TSV output
+       o In CSV or TSV output, digit group marks (such  as  thousands  separa-
+         tors) are disabled automatically.
+
+   FODS output
+       FODS  is  the  OpenDocument  spreadsheet format used by LibreOffice and
+       OpenOffice.  It is a good format to use if you are exporting  to  their
+       spreadsheet app.
+
+   Beancount output
+       This  is  Beancount's  journal format.  You can use this to export your
+       hledger data to Beancount, perhaps to query  it  with  Beancount  Query
+       Language  or  with  the  Fava web app.  hledger will try to adjust your
+       data to suit Beancount.  If you plan to export often, you may  want  to
+       follow  Beancount's  conventions  in your hledger data, to ease conver-
+       sion.  Eg use Beancount-friendly account names, currency codes  instead
+       of  currency  symbols, and avoid virtual postings, redundant cost nota-
+       tion, etc.
+
+       Here are more details, included here for now  (see  also  "hledger  and
+       Beancount" https://hledger.org/beancount.html).
+
+   Beancount account names
+       hledger will try adjust your account names, if needed, to Beancount ac-
+       count  names, by capitalising, replacing unsupported characters with -,
+       and prepending B to parts which don't begin with  a  letter  or  digit.
+       (It's  possible  for  this to convert distinct hledger account names to
+       the same beancount name.  Eg, hledger's automatic equity conversion ac-
+       counts can have currency symbols in their name, so equity:conversion:$-
+       becomes equity:conversion:B---.)
+
+       In addition, you must ensure that the top level account names  are  As-
+       sets,  Liabilities,  Equity,  Income, and Expenses, which Beancount re-
+       quires.  If yours are named differently, you can use  account  aliases,
+       usually  in  the  form  of --alias options, possibly stored in a config
+       file.  (An example: hledger2beancount.conf)
+
+   Beancount commodity names
+       hledger will adjust your commodity names, if needed, to Beancount  com-
+       modity/currency names, which must be 2-24 uppercase letters, digits, or
+       ',  ., _, -, beginning with a letter and ending with a letter or digit.
+       hledger will convert known currency symbols to ISO 4217 currency codes.
+       Otherwise, it will capitalise letters, replace  unsupported  characters
+       with  a dash (-), and prepend/append a "B" when needed.  (It's possible
+       for this to generate unreadable commodity names, or to convert distinct
+       hledger commodity names to the same beancount name.)
+
+   Beancount virtual postings
+       Beancount doesn't allow unbalanced/virtual postings, so you  will  need
+       to  comment those, or use --real to exclude transactions that use them.
+       (If you have transactions which are a mixture of  balanced  and  unbal-
+       anced postings, you'll have to do something more.)
+
+   Beancount costs
+       Beancount  doesn't  allow  redundant cost notation as hledger does.  If
+       you have entries like this, you will need to  comment  out  either  the
+       costs or the equity postings.
+
+   Beancount operating currency
+       Declaring  an  operating  currency improves Beancount and Fava reports.
+       You can do this manually by adding a line like this  to  the  beancount
+       journal:
+
+              option "operating_currency" "USD"
+
+   SQL output
+       o This is not yet much used; real-world feedback is welcome.
+
+       o SQL  output is expected to work at least with SQLite, MySQL and Post-
+         gres.
+
+       o For SQLite, it will be more useful if you  modify  the  generated  id
+         field to be a PRIMARY KEY.  Eg:
+
+                $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...
+
+       o SQL  output  is structured with the expectations that statements will
+         be executed in the empty database.  If you already have  tables  cre-
+         ated  via  SQL  output  of hledger, you would probably want to either
+         clear tables of existing data (via delete or truncate SQL statements)
+         or drop tables completely as otherwise your postings will be duped.
+
    JSON output
        o This is not yet much used; real-world feedback is welcome.
 
@@ -723,23 +813,6 @@ Output
          hope this approach will not cause problems in practice; if  you  find
          otherwise, please let us know.  (Cf #1195)
 
-   SQL output
-       o This is not yet much used; real-world feedback is welcome.
-
-       o SQL output is expected to work at least with SQLite, MySQL and  Post-
-         gres.
-
-       o For  SQLite,  it  will  be more useful if you modify the generated id
-         field to be a PRIMARY KEY.  Eg:
-
-                $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...
-
-       o SQL output is structured with the expectations that  statements  will
-         be  executed  in the empty database.  If you already have tables cre-
-         ated via SQL output of hledger, you would  probably  want  to  either
-         clear tables of existing data (via delete or truncate SQL statements)
-         or drop tables completely as otherwise your postings will be duped.
-
    Commodity styles
        When  displaying  amounts,  hledger infers a standard display style for
        each commodity/currency, as described below in Commodity display style.
@@ -1675,14 +1748,16 @@ Journal
                generated-transaction  -- appears on generated periodic txns (with --verbose-tags)
                generated-posting      -- appears on generated auto postings (with --verbose-tags)
                modified               -- appears on txns which have had auto postings added (with --verbose-tags)
+
               Not displayed, but queryable:
                _generated-transaction -- exists on generated periodic txns (always)
                _generated-posting     -- exists on generated auto postings (always)
                _modified              -- exists on txns which have had auto postings added (always)
 
-       Tags hledger uses internally:
+       Other tags hledger uses internally:
 
-               _conversion-matched    -- exists on postings which have been matched with a nearby @/@@ cost annotation
+               _cost-matched          -- marks postings with a cost which have been matched with a nearby pair of equity conversion postings
+               _conversion-matched    -- marks equity conversion postings which have been matched with a nearby posting with a cost
 
    Tag values
        Tags can have a value, which is any text after the  colon  up  until  a
@@ -1859,9 +1934,10 @@ Journal
        nal.  Usually you'll find that error later, as an extra account in bal-
        ance reports, or an incorrect balance when reconciling.
 
-       In strict mode, enabled with the -s/--strict flag, hledger will  report
+       In strict mode, enabled with the -s/--strict  flag,  or  when  you  run
-       an  error if any transaction uses an account name that has not been de-
+       hledger check accounts, hledger will report an error if any transaction
-       clared by an account directive.  Some notes:
+       uses  an  account  name that has not been declared by an account direc-
+       tive.  Some notes:
 
        o The declaration is case-sensitive; transactions must use the  correct
          account name capitalisation.
@@ -1878,6 +1954,9 @@ Journal
        o It's  currently  not  possible  to declare "all possible subaccounts"
          with a wildcard; every account posted to must be declared.
 
+       o If you use the --infer-equity flag, you will also  need  declarations
+         for the account names it generates.
+
    Account display order
        Account directives also cause hledger to display accounts in a particu-
        lar  order, not just alphabetically.  Eg, here is a conventional order-
@@ -5542,6 +5621,9 @@ Cost reporting
        symbol.  You can customise the "equity:conversion" part by declaring an
        account with the V/Conversion account type.
 
+       Note you will need to add account declarations for these to your  jour-
+       nal, if you use check accounts or check --strict.
+
    Combining costs and equity conversion postings
        Finally, you can use both the @/@@ cost notation and equity postings at
        the  same time.  This in theory gives the best of all worlds - preserv-
@@ -8336,9 +8418,9 @@ Advanced report commands
                                                 DESCPAT
 
    Balance report layout
-       The  --layout  option  affects how balance reports show multi-commodity
+       The --layout option affects how balance and the other balance-like com-
-       amounts and commodity symbols, which can improve readability.   It  can
+       mands  show  multi-commodity amounts and commodity symbols.  It can im-
-       also normalise the data for easy consumption by other programs.  It has
+       prove readability, for humans and/or machines (other software).  It has
        four possible values:
 
        o --layout=wide[,WIDTH]: commodities are shown on a  single  line,  op-
@@ -8350,7 +8432,8 @@ Advanced report commands
          bare numbers
 
        o --layout=tidy:  data  is  normalised  to easily-consumed "tidy" form,
-         with one row per data value
+         with one row per data value.  (This one is currently  supported  only
+         by the balance command.)
 
        Here  are  the  --layout modes supported by each output format Only CSV
        output supports all of them:
@@ -8488,9 +8571,9 @@ Advanced report commands
        host:5000.     You    can    also    produce   relative   links,   like
        --base-url="some/path" or --base-url="".)
 
-       The balance reports' HTML output currently does not display  tree  mode
+       The balance reports' HTML output currently does not  indent  tree  mode
-       reports properly (#1846).  For now, if generating HTML you should prob-
+       reports  properly  (#1846).   So in HTML balance reports, use list mode
-       abBly use the default --flat mode.
+       for now (it is the default).
 
    Some useful balance reports
        Some frequently used balance options/reports are:
@@ -9739,4 +9822,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-1.40.99                 September 2024                      HLEDGER(1)
+hledger-1.40.99                  October 2024                       HLEDGER(1)