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

hledger-ui/hledger-ui.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-UI" "1" "June 2024" "hledger-ui-1.34.99 " "hledger User Manuals"
+.TH "HLEDGER\-UI" "1" "September 2024" "hledger-ui-1.40.99 " "hledger User Manuals"
 
 
 
@@ -17,7 +17,7 @@ or
 .PD
 \f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R]
 .SH DESCRIPTION
-This manual is for hledger\[aq]s terminal interface, version 1.34.99.
+This manual is for hledger\[aq]s terminal interface, version 1.40.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
@@ -178,31 +178,10 @@ Emacs\-style
 (\f[CR]CTRL\-p\f[R]/\f[CR]CTRL\-n\f[R]/\f[CR]CTRL\-f\f[R]/\f[CR]CTRL\-b\f[R])
 and VI\-style (\f[CR]k\f[R],\f[CR]j\f[R],\f[CR]l\f[R],\f[CR]h\f[R])
 movement keys are also supported.
-A tip: movement speed is limited by your keyboard repeat rate, to move
+.PP
+(Tip: movement speed is limited by your keyboard repeat rate, to move
 faster you may want to adjust it.
-(If you\[aq]re on a mac, the karabiner app is one way to do that.)
+On a mac, the Karabiner app is one way to do that.)
-.PP
-With shift pressed, the cursor keys adjust the report period, limiting
-the transactions to be shown (by default, all are shown).
-\f[CR]SHIFT\-DOWN/UP\f[R] steps downward and upward through these
-standard report period durations: year, quarter, month, week, day.
-Then, \f[CR]SHIFT\-LEFT/RIGHT\f[R] moves to the previous/next period.
-\f[CR]T\f[R] sets the report period to today.
-With the \f[CR]\-w/\-\-watch\f[R] option, when viewing a
-\[dq]current\[dq] period (the current day, week, month, quarter, or
-year), the period will move automatically to track the current date.
-To set a non\-standard period, you can use \f[CR]/\f[R] and a
-\f[CR]date:\f[R] query.
-.PP
-(Mac users: SHIFT\-DOWN/UP keys do not work by default in Terminal, as
-of MacOS Monterey.
-You can configure them as follows: open Terminal, press CMD\-comma to
-open preferences, click Profiles, select your current terminal profile
-on the left, click Keyboard on the right, click + and add this for
-Shift\-Down: \f[CR]\[rs]033[1;2B\f[R], click + and add this for
-Shift\-Up: \f[CR]\[rs]033[1;2A\f[R].
-Press the Escape key to enter the \f[CR]\[rs]033\f[R] part, you
-can\[aq]t type it directly.)
 .PP
 \f[CR]/\f[R] lets you set a general filter query limiting the data
 shown, using the same query terms as in hledger and hledger\-web.
@@ -219,6 +198,31 @@ transactions generated by rule.
 \f[CR]F\f[R] toggles forecast mode, in which future/forecasted
 transactions are shown.
 .PP
+Pressing \f[CR]SHIFT\-DOWN\f[R] narrows the report period, and pressing
+\f[CR]SHIFT\-UP\f[R] expands it again.
+When narrowed, the current report period is displayed in the header
+line, pressing \f[CR]SHIFT\-LEFT\f[R] or \f[CR]SHIFT\-RIGHT\f[R] moves
+to the previous or next period, and pressing \f[CR]T\f[R] sets the
+period to \[dq]today\[dq].
+If you are using \f[CR]\-w/\-\-watch\f[R] and viewing a narrowed period
+containing today, the view will follow any changes in system date
+(moving to the period containing the new date).
+.PP
+You can also specify a non\-standard period with \f[CR]/\f[R] and a
+\f[CR]date:\f[R] query; in this case, the period is not movable with the
+arrow keys.
+.PP
+(Tip: arrow keys with Shift do not work out of the box in all terminal
+software.
+Eg in Apple\[aq]s Terminal, the SHIFT\-DOWN and SHIFT\-UP keys must be
+configured as follows: in Terminal\[aq]s preferences, click Profiles,
+select your current profile on the left, click Keyboard on the right,
+click + and add this for SHIFT\-DOWN: \f[CR]\[rs]033[1;2B\f[R], click +
+and add this for SHIFT\-UP: \f[CR]\[rs]033[1;2A\f[R].
+\ In other terminals (Windows Terminal ?)
+you might need to configure SHIFT\-RIGHT and SHIFT\-LEFT to emit
+\f[CR]\[rs]033[1;2C\f[R] and \f[CR]\[rs]033[1;2D\f[R] respectively.)
+.PP
 \f[CR]ESCAPE\f[R] resets the UI state and jumps back to the top screen,
 restoring the app\[aq]s initial state at startup.
 Or, it cancels minibuffer data entry or the help dialog.

hledger-ui/hledger-ui.info

@@ -18,7 +18,7 @@ plain text accounting app.
 or
 'hledger ui -- [OPTS] [QUERYARGS]'
 
-   This manual is for hledger's terminal interface, version 1.34.99.
+   This manual is for hledger's terminal interface, version 1.40.99.
 See also the hledger manual for common concepts and file formats.
 
    hledger is a robust, user-friendly, cross-platform set of programs
@@ -192,27 +192,11 @@ most screens:
 returns to the previous screen, 'UP'/'DOWN'/'PGUP'/'PGDN'/'HOME'/'END'
 move up and down through lists.  Emacs-style
 ('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b') and VI-style ('k','j','l','h')
-movement keys are also supported.  A tip: movement speed is limited by
+movement keys are also supported.
-your keyboard repeat rate, to move faster you may want to adjust it.
-(If you're on a mac, the karabiner app is one way to do that.)
 
-   With shift pressed, the cursor keys adjust the report period,
+   (Tip: movement speed is limited by your keyboard repeat rate, to move
-limiting the transactions to be shown (by default, all are shown).
+faster you may want to adjust it.  On a mac, the Karabiner app is one
-'SHIFT-DOWN/UP' steps downward and upward through these standard report
+way to do that.)
-period durations: year, quarter, month, week, day.  Then,
-'SHIFT-LEFT/RIGHT' moves to the previous/next period.  'T' sets the
-report period to today.  With the '-w/--watch' option, when viewing a
-"current" period (the current day, week, month, quarter, or year), the
-period will move automatically to track the current date.  To set a
-non-standard period, you can use '/' and a 'date:' query.
-
-   (Mac users: SHIFT-DOWN/UP keys do not work by default in Terminal, as
-of MacOS Monterey.  You can configure them as follows: open Terminal,
-press CMD-comma to open preferences, click Profiles, select your current
-terminal profile on the left, click Keyboard on the right, click + and
-add this for Shift-Down: '\033[1;2B', click + and add this for Shift-Up:
-'\033[1;2A'.  Press the Escape key to enter the '\033' part, you can't
-type it directly.)
 
    '/' lets you set a general filter query limiting the data shown,
 using the same query terms as in hledger and hledger-web.  While editing
@@ -227,6 +211,26 @@ both ordinary transactions recorded in the journal, and periodic
 transactions generated by rule.  'F' toggles forecast mode, in which
 future/forecasted transactions are shown.
 
+   Pressing 'SHIFT-DOWN' narrows the report period, and pressing
+'SHIFT-UP' expands it again.  When narrowed, the current report period
+is displayed in the header line, pressing 'SHIFT-LEFT' or 'SHIFT-RIGHT'
+moves to the previous or next period, and pressing 'T' sets the period
+to "today".  If you are using '-w/--watch' and viewing a narrowed period
+containing today, the view will follow any changes in system date
+(moving to the period containing the new date).
+
+   You can also specify a non-standard period with '/' and a 'date:'
+query; in this case, the period is not movable with the arrow keys.
+
+   (Tip: arrow keys with Shift do not work out of the box in all
+terminal software.  Eg in Apple's Terminal, the SHIFT-DOWN and SHIFT-UP
+keys must be configured as follows: in Terminal's preferences, click
+Profiles, select your current profile on the left, click Keyboard on the
+right, click + and add this for SHIFT-DOWN: '\033[1;2B', click + and add
+this for SHIFT-UP: '\033[1;2A'.  In other terminals (Windows Terminal ?)
+you might need to configure SHIFT-RIGHT and SHIFT-LEFT to emit
+'\033[1;2C' and '\033[1;2D' respectively.)
+
    'ESCAPE' resets the UI state and jumps back to the top screen,
 restoring the app's initial state at startup.  Or, it cancels minibuffer
 data entry or the help dialog.
@@ -537,30 +541,30 @@ Node: MOUSE8236
 Ref: #mouse8331
 Node: KEYS8568
 Ref: #keys8661
-Node: SCREENS13316
+Node: SCREENS13396
-Ref: #screens13420
+Ref: #screens13500
-Node: Menu screen14056
+Node: Menu screen14136
-Ref: #menu-screen14177
+Ref: #menu-screen14257
-Node: Cash accounts screen14372
+Node: Cash accounts screen14452
-Ref: #cash-accounts-screen14549
+Ref: #cash-accounts-screen14629
-Node: Balance sheet accounts screen14733
+Node: Balance sheet accounts screen14813
-Ref: #balance-sheet-accounts-screen14949
+Ref: #balance-sheet-accounts-screen15029
-Node: Income statement accounts screen15069
+Node: Income statement accounts screen15149
-Ref: #income-statement-accounts-screen15290
+Ref: #income-statement-accounts-screen15370
-Node: All accounts screen15454
+Node: All accounts screen15534
-Ref: #all-accounts-screen15635
+Ref: #all-accounts-screen15715
-Node: Register screen15817
+Node: Register screen15897
-Ref: #register-screen15976
+Ref: #register-screen16056
-Node: Transaction screen18260
+Node: Transaction screen18340
-Ref: #transaction-screen18418
+Ref: #transaction-screen18498
-Node: Error screen19835
+Node: Error screen19915
-Ref: #error-screen19957
+Ref: #error-screen20037
-Node: WATCH MODE20201
+Node: WATCH MODE20281
-Ref: #watch-mode20318
+Ref: #watch-mode20398
-Node: ENVIRONMENT21777
+Node: ENVIRONMENT21857
-Ref: #environment21893
+Ref: #environment21973
-Node: BUGS22084
+Node: BUGS22164
-Ref: #bugs22167
+Ref: #bugs22247
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -11,7 +11,7 @@ SYNOPSIS
        hledger ui -- [OPTS] [QUERYARGS]
 
 DESCRIPTION
-       This manual is for hledger's terminal interface, version 1.34.99.   See
+       This manual is for hledger's terminal interface, version 1.40.99.   See
        also the hledger manual for common concepts and file formats.
 
        hledger  is a robust, user-friendly, cross-platform set of programs for
@@ -161,28 +161,11 @@ KEYS
        The  cursor  keys navigate: RIGHT or ENTER goes deeper, LEFT returns to
        the  previous  screen,  UP/DOWN/PGUP/PGDN/HOME/END  move  up  and  down
        through  lists.  Emacs-style (CTRL-p/CTRL-n/CTRL-f/CTRL-b) and VI-style
-       (k,j,l,h) movement keys are also supported.  A tip: movement  speed  is
+       (k,j,l,h) movement keys are also supported.
-       limited  by  your  keyboard repeat rate, to move faster you may want to
-       adjust it.  (If you're on a mac, the karabiner app is  one  way  to  do
-       that.)
 
-       With  shift pressed, the cursor keys adjust the report period, limiting
+       (Tip: movement speed is limited by your keyboard repeat rate,  to  move
-       the  transactions  to  be  shown   (by   default,   all   are   shown).
+       faster  you  may want to adjust it.  On a mac, the Karabiner app is one
-       SHIFT-DOWN/UP  steps  downward and upward through these standard report
+       way to do that.)
-       period   durations:   year,   quarter,   month,   week,   day.    Then,
-       SHIFT-LEFT/RIGHT  moves to the previous/next period.  T sets the report
-       period to today.  With the -w/--watch option, when viewing a  "current"
-       period  (the  current  day,  week, month, quarter, or year), the period
-       will move automatically to track the current date.  To set a  non-stan-
-       dard period, you can use / and a date: query.
-
-       (Mac  users:  SHIFT-DOWN/UP keys do not work by default in Terminal, as
-       of MacOS Monterey.  You can configure them as follows:  open  Terminal,
-       press  CMD-comma  to open preferences, click Profiles, select your cur-
-       rent terminal profile on the left, click Keyboard on the right, click +
-       and add this for Shift-Down:  \033[1;2B,  click  +  and  add  this  for
-       Shift-Up:  \033[1;2A.  Press the Escape key to enter the \033 part, you
-       can't type it directly.)
 
        / lets you set a general filter query limiting the  data  shown,  using
        the  same query terms as in hledger and hledger-web.  While editing the
@@ -196,6 +179,26 @@ KEYS
        actions  generated  by  rule.   F  toggles  forecast mode, in which fu-
        ture/forecasted transactions are shown.
 
+       Pressing SHIFT-DOWN narrows the report period,  and  pressing  SHIFT-UP
+       expands  it  again.   When  narrowed, the current report period is dis-
+       played in the header line, pressing SHIFT-LEFT or SHIFT-RIGHT moves  to
+       the previous or next period, and pressing T sets the period to "today".
+       If  you  are  using -w/--watch and viewing a narrowed period containing
+       today, the view will follow any changes in system date (moving  to  the
+       period containing the new date).
+
+       You can also specify a non-standard period with / and a date: query; in
+       this case, the period is not movable with the arrow keys.
+
+       (Tip:  arrow keys with Shift do not work out of the box in all terminal
+       software.  Eg in Apple's Terminal, the  SHIFT-DOWN  and  SHIFT-UP  keys
+       must  be  configured  as follows: in Terminal's preferences, click Pro-
+       files, select your current profile on the left, click Keyboard  on  the
+       right,  click + and add this for SHIFT-DOWN: \033[1;2B, click + and add
+       this for SHIFT-UP: \033[1;2A.   In other terminals (Windows Terminal ?)
+       you  might  need  to  configure  SHIFT-RIGHT  and  SHIFT-LEFT  to  emit
+       \033[1;2C and \033[1;2D respectively.)
+
        ESCAPE  resets the UI state and jumps back to the top screen, restoring
        the app's initial state at startup.  Or, it cancels minibuffer data en-
        try or the help dialog.
@@ -441,4 +444,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-ui-1.34.99                 June 2024                     HLEDGER-UI(1)
+hledger-ui-1.40.99              September 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_}}, {{June 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{September 2024}})m4_dnl

hledger-web/hledger-web.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-WEB" "1" "June 2024" "hledger-web-1.34.99 " "hledger User Manuals"
+.TH "HLEDGER\-WEB" "1" "September 2024" "hledger-web-1.40.99 " "hledger User Manuals"
 
 
 
@@ -17,7 +17,7 @@ or
 .PD
 \f[CR]hledger web \-\- [OPTS] [QUERY]\f[R]
 .SH DESCRIPTION
-This manual is for hledger\[aq]s web interface, version 1.34.99.
+This manual is for hledger\[aq]s web interface, version 1.40.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

@@ -18,7 +18,7 @@ plain text accounting app.
 or
 'hledger web -- [OPTS] [QUERY]'
 
-   This manual is for hledger's web interface, version 1.34.99.  See
+   This manual is for hledger's web interface, version 1.40.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

@@ -11,7 +11,7 @@ SYNOPSIS
        hledger web -- [OPTS] [QUERY]
 
 DESCRIPTION
-       This manual is for hledger's web interface, version 1.34.99.  See  also
+       This manual is for hledger's web interface, version 1.40.99.  See  also
        the hledger manual for common concepts and file formats.
 
        hledger  is a robust, user-friendly, cross-platform set of programs for
@@ -474,4 +474,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-web-1.34.99                June 2024                    HLEDGER-WEB(1)
+hledger-web-1.40.99             September 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_}}, {{June 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{September 2024}})m4_dnl

hledger/hledger.1

@@ -1,6 +1,6 @@
 .\"t
 
-.TH "HLEDGER" "1" "June 2024" "hledger-1.34.99 " "hledger User Manuals"
+.TH "HLEDGER" "1" "September 2024" "hledger-1.40.99 " "hledger User Manuals"
 
 
 
@@ -33,7 +33,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.34.99.
+1.40.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!
@@ -112,7 +112,7 @@ hledger reads one or more data files, each time you run it.
 You can specify a file with \f[CR]\-f\f[R], like so
 .IP
 .EX
-$ hledger \-f FILE print
+$ hledger \-f FILE [\-f FILE2 ...] print
 .EE
 .PP
 Files are most often in hledger\[aq]s journal format, with the
@@ -731,32 +731,62 @@ quoting than you would at the command prompt.)
 .PP
 Argument files are now superseded by..
 .SS Config files
-hledger will read extra command line options from a
+As of hledger 1.40, you can optionally save command line options (or
-\f[CR]hledger.conf\f[R] config file.
+arguments) to be used when running hledger commands, in a config file.
-These will be inserted early in the command line, so your later options
+Here\[aq]s a small example:
-can override them if needed.
+.IP
-The config file can contain general options (which will be used with all
+.EX
-commands that support them), and command\-specific options (or
+\f[I]# General options are listed first, one or more per line.\f[R]
-arguments).
+\f[I]# These will be used with all hledger commands that support them.\f[R]
-hledger.conf.sample is an example, which you can install as
+\-\-pretty
-\f[CR]./hledger.conf\f[R] or \f[CR]$HOME/.hledger.conf\f[R].
+
+\f[I]# Options following a \[ga][COMMANDNAME]\[ga] heading are used with that hledger command only.\f[R]
+\f[B][print]\f[R]
+\-\-explicit \-\-show\-costs
+.EE
 .PP
-To be precise, hledger looks for \f[CR]hledger.conf\f[R] in the current
+To use a config file, specify it with the \f[CR]\-\-conf\f[R] option.
-directory or above, or in your home directory (with a dotted name,
+Its options will be inserted near the start of your command line (so you
-\f[CR]\[ti]/.hledger.conf\f[R]), or finally in your XDG config directory
+can override them if needed).
-(\f[CR]\[ti]/.config/hledger/hledger.conf\f[R]).
+Or, you can add a \f[CR]hledger \-\-conf\f[R] shebang line to a config
-Or you can select a particular config file by using the
+file and execute it like a script.
-\f[CR]\-\-conf\f[R] option, or by adding a \f[CR]hledger \-\-conf\f[R]
-shebang line to a config file and executing it like a script (see the
-example file).
-You can inspect the finding and processing of config files with
-\f[CR]\-\-debug\f[R] or \f[CR]\-\-debug=8\f[R].
 .PP
-If you want to run hledger without a config file, to ensure standard
+Or, you can set up an automatic config file that is used whenever you
-defaults and behaviour, use the \f[CR]\-n/\-\-no\-conf\f[R] flag.
+run hledger.
-This is useful when troubleshooting problems or sharing examples.
+This can be \f[CR]hledger.conf\f[R] in the current directory or above,
+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
-\f[I](Added in 1.40; experimental)\f[R]
+You can ignore config files by adding the \f[CR]\-n/\-\-no\-conf\f[R]
+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
+Automatic config files are convenient, but have a cost: it\[aq]s easy to
+change a report\[aq]s behaviour, or break scripts/applications which use
+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, here are some tips:
+.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
+This feature has been added in hledger 1.40 and is considered
+\f[I]experimental\f[R].
 .SH Output
 .SS Output destination
 hledger commands send their output to the terminal by default.
@@ -783,7 +813,7 @@ Here are those commands and the formats currently supported:
 .PP
 .TS
 tab(@);
-lw(16.1n) lw(14.5n) lw(14.5n) lw(16.1n) lw(4.8n) lw(4.0n).
+lw(13.6n) lw(12.2n) lw(12.2n) lw(12.2n) lw(12.2n) lw(4.1n) lw(3.4n).
 T{
 \-
 T}@T{
@@ -793,6 +823,8 @@ csv/tsv
 T}@T{
 html
 T}@T{
+fods
+T}@T{
 json
 T}@T{
 sql
@@ -807,6 +839,7 @@ Y
 T}@T{
 Y
 T}@T{
+T}@T{
 Y
 T}@T{
 T}
@@ -817,7 +850,9 @@ Y \f[I]1\f[R]
 T}@T{
 Y \f[I]1\f[R]
 T}@T{
-Y \f[I]1,2\f[R]
+Y \f[I]1\f[R]
+T}@T{
+Y \f[I]1\f[R]
 T}@T{
 Y
 T}@T{
@@ -831,6 +866,7 @@ Y \f[I]1\f[R]
 T}@T{
 Y \f[I]1\f[R]
 T}@T{
+T}@T{
 Y
 T}@T{
 T}
@@ -843,6 +879,7 @@ Y \f[I]1\f[R]
 T}@T{
 Y \f[I]1\f[R]
 T}@T{
+T}@T{
 Y
 T}@T{
 T}
@@ -855,6 +892,7 @@ Y \f[I]1\f[R]
 T}@T{
 Y \f[I]1\f[R]
 T}@T{
+T}@T{
 Y
 T}@T{
 T}
@@ -867,6 +905,7 @@ Y \f[I]1\f[R]
 T}@T{
 Y \f[I]1\f[R]
 T}@T{
+T}@T{
 Y
 T}@T{
 T}
@@ -878,6 +917,7 @@ T}@T{
 Y
 T}@T{
 T}@T{
+T}@T{
 Y
 T}@T{
 Y
@@ -890,6 +930,7 @@ T}@T{
 Y
 T}@T{
 T}@T{
+T}@T{
 Y
 T}@T{
 T}
@@ -897,9 +938,6 @@ T}
 .IP \[bu] 2
 \f[I]1 Also affected by the balance commands\[aq] \f[CI]\-\-layout\f[I]
 option.\f[R]
-.IP \[bu] 2
-\f[I]2 \f[CI]balance\f[I] does not support html output without a report
-interval or with \f[CI]\-\-budget\f[I].\f[R]
 .PP
 The output format is selected by the
 \f[CR]\-O/\-\-output\-format=FMT\f[R] option:
@@ -1104,7 +1142,7 @@ the add or web or import commands to create and update it.
 .PP
 Many users, though, edit the journal file with a text editor, and track
 changes with a version control system such as git.
-Editor addons such as ledger\-mode or hledger\-mode for Emacs,
+Editor add\-ons such as ledger\-mode or hledger\-mode for Emacs,
 vim\-ledger for Vim, and hledger\-vscode for Visual Studio Code, make
 this easier, adding colour, formatting, tab completion, and useful
 commands.
@@ -5329,11 +5367,17 @@ $ hledger \-f sample.timeclock register \-p weekly \-\-depth 1 \-\-empty  # time
 .PP
 To generate time logs, ie to clock in and clock out, you could:
 .IP \[bu] 2
-use emacs and the built\-in timeclock.el, or the extended
+use these shell aliases at the command line:
-timeclock\-x.el and perhaps the extras in ledgerutils.el
+.RS 2
+.IP
+.EX
+alias ti=\[aq]echo i \[ga]date \[dq]+%Y\-%m\-%d %H:%M:%S\[dq]\[ga] $* >>$TIMELOG\[aq]
+alias to=\[aq]echo o \[ga]date \[dq]+%Y\-%m\-%d %H:%M:%S\[dq]\[ga] >>$TIMELOG\[aq]
+.EE
+.RE
 .IP \[bu] 2
-at the command line, use these bash aliases:
+or Emacs\[aq]s built\-in timeclock.el, or the extended timeclock\-x.el,
-\f[CR]cli     alias ti=\[dq]echo i \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq]     alias to=\[dq]echo o \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R]
+and perhaps the extras in ledgerutils.el
 .IP \[bu] 2
 or use the old \f[CR]ti\f[R] and \f[CR]to\f[R] scripts in the ledger 2.x
 repository.
@@ -5687,26 +5731,62 @@ flags:
 .PP
 More complex intervals can be specified using \f[CR]\-p/\-\-period\f[R],
 described below.
-.SS Date adjustment
+.SS Date adjustments
-When there is a report interval (other than daily), report start/end
+.SS Start date adjustment
-dates which have been inferred, eg from the journal, are automatically
+If you let hledger infer a report\[aq]s start date, it will adjust the
-adjusted to natural period boundaries.
+date to the previous natural boundary of the report interval, for
-This is convenient for producing simple periodic reports.
+convenient periodic reports.
-More precisely:
+(If you don\[aq]t want that, specify a start date.)
-.IP \[bu] 2
-an inferred start date will be adjusted earlier if needed to fall on a
-natural period boundary
-.IP \[bu] 2
-an inferred end date will be adjusted later if needed to make the last
-period the same length as the others.
 .PP
-By contrast, start/end dates which have been specified explicitly, with
+For example, if the journal\[aq]s first transaction is on january 10th,
-\f[CR]\-b\f[R], \f[CR]\-e\f[R], \f[CR]\-p\f[R] or \f[CR]date:\f[R], will
+.IP \[bu] 2
-not be adjusted (since hledger 1.29).
+\f[CR]hledger register\f[R] (no report interval) will start the report
-This makes it possible to specify non\-standard report periods, but it
+on january 10th.
-also means that if you are specifying a start date, you should pick one
+.IP \[bu] 2
-that\[aq]s on a period boundary if you want to see simple report period
+\f[CR]hledger register \-\-monthly\f[R] will start the report on the
-headings.
+previous month boundary, january 1st.
+.IP \[bu] 2
+\f[CR]hledger register \-\-monthly \-\-begin 1/5\f[R] will start the
+report on january 5th [1].
+.PP
+Also if you are generating transactions or budget goals with periodic
+transaction rules, their start date may be adjusted in a similar way (in
+certain situations).
+.SS End date adjustment
+A report\[aq]s end date is always adjusted to include a whole number of
+intervals, so that the last subperiod has the same length as the others.
+.PP
+For example, if the journal\[aq]s last transaction is on february 20th,
+.IP \[bu] 2
+\f[CR]hledger register\f[R] will end the report on february 20th.
+.IP \[bu] 2
+\f[CR]hledger register \-\-monthly\f[R] will end the report at the end
+of february.
+.IP \[bu] 2
+\f[CR]hledger register \-\-monthly \-\-end 2/14\f[R] also will end the
+report at the end of february.
+.IP \[bu] 2
+\f[CR]hledger register \-\-monthly \-\-begin 1/5 \-\-end 2/14\f[R] will
+end the report on march 4th [1].
+.PP
+[1] Since hledger 1.29.
+.SS Period headings
+With non\-standard subperiods, hledger will show
+\[dq]STARTDATE..ENDDATE\[dq] headings.
+With standard subperiods (ie, starting on a natural interval boundary),
+you\[aq]ll see more compact headings, which are usually preferable.
+(Though month names will be in english, currently.)
+.PP
+So if you are specifying a start date and you want compact headings:
+choose a start of year for yearly reports, a start of quarter for
+quarterly reports, a start of month for monthly reports, etc.
+(Remember, you can write eg \f[CR]\-b 2024\f[R] or \f[CR]1/1\f[R] as a
+shortcut for a start of year, or \f[CR]2024\-04\f[R] or
+\f[CR]202404\f[R] or \f[CR]Apr\f[R] for a start of month or quarter.)
+.PP
+For weekly reports, choose a date that\[aq]s a Monday.
+(You can try different dates until you see the short headings, or write
+eg \f[CR]\-b \[aq]3 weeks ago\[aq]\f[R].)
 .SS Period expressions
 The \f[CR]\-p/\-\-period\f[R] option specifies a period expression,
 which is a compact way of expressing a start date, end date, and/or
@@ -5873,7 +5953,7 @@ adjusted to each month\[aq]s last day)
 .IP \[bu] 2
 \f[CR]every Nth WEEKDAYNAME [of month]\f[R]
 .PP
-Yearly on a custom day:
+Yearly on a custom month and day:
 .IP \[bu] 2
 \f[CR]every MM/DD [of year]\f[R] (month number and day of month number)
 .IP \[bu] 2
@@ -6519,7 +6599,7 @@ $ hledger print \-\-forecast \-\-today=2023/4/21
 .EE
 .PP
 Here there are no ordinary transactions, so the forecasted transactions
-begin on the first occurence after today\[aq]s date.
+begin on the first occurrence after today\[aq]s date.
 (You won\[aq]t normally use \f[CR]\-\-today\f[R]; it\[aq]s just to make
 these examples reproducible.)
 .SS Forecast reports
@@ -7755,7 +7835,6 @@ T}
 \f[CR]\-\-cumulative\f[R] is omitted to save space, it works like
 \f[CR]\-H\f[R] but with a zero starting balance.
 .SH PART 4: COMMANDS
-\ 
 .PP
 Here are the standard commands, which you can list by running
 \f[CR]hledger\f[R].
@@ -7967,9 +8046,6 @@ payees/descriptions, dates (\f[CR]yesterday\f[R], \f[CR]today\f[R],
 \f[CR]tomorrow\f[R]).
 If the input area is empty, it will insert the default value.
 .IP \[bu] 2
-If the journal defines a default commodity, it will be added to any bare
-numbers entered.
-.IP \[bu] 2
 A parenthesised transaction code may be entered following a date.
 .IP \[bu] 2
 Comments and tags may be entered following a description or amount.
@@ -8827,6 +8903,9 @@ Flags:
                             description closest to DESC
   \-r \-\-related              show postings\[aq] siblings instead
      \-\-invert               display all amounts with reversed sign
+     \-\-sort=FIELDS          sort by: date, desc, account, amount, absamount,
+                            or a comma\-separated combination of these. For a
+                            descending sort, prefix with \-. (Default: date)
   \-w \-\-width=N              set output width (default: terminal width or
                             $COLUMNS). \-wN,M sets description width as well.
      \-\-align\-all            guarantee alignment across all lines (slower)
@@ -8894,6 +8973,16 @@ For example, it can be used on an income account where amounts are
 normally displayed as negative numbers.
 It\[aq]s also useful to show postings on the checking account together
 with the related account:
+.PP
+The \f[CR]\-\-sort=FIELDS\f[R] flag sorts by the fields given, which can
+be any of \f[CR]account\f[R], \f[CR]amount\f[R], \f[CR]absamount\f[R],
+\f[CR]date\f[R], or \f[CR]desc\f[R]/\f[CR]description\f[R], optionally
+separated by commas.
+For example, \f[CR]\-\-sort account,amount\f[R] will group all
+transactions in each account, sorted by transaction amount.
+Each field can be negated by a preceding \f[CR]\-\f[R], so
+\f[CR]\-\-sort \-amount\f[R] will show transactions ordered from
+smallest amount to largest amount.
 .IP
 .EX
 $ hledger register \-\-related \-\-invert assets:checking
@@ -9450,7 +9539,7 @@ Flags:
                             \[aq]bare\[aq]        : commodity symbols in one column
                             \[aq]tidy\[aq]        : every attribute in its own column
   \-O \-\-output\-format=FMT    select the output format. Supported formats:
-                            txt, html, csv, tsv, json.
+                            txt, html, csv, tsv, json, fods.
   \-o \-\-output\-file=FILE     write output to FILE. A file extension matching
                             one of the above formats selects that format.
 .EE
@@ -9543,7 +9632,7 @@ commodities displayed on the same line or multiple lines
 This command supports the output destination and output format options,
 with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R]
 (\f[I]Added in 1.32\f[R]), \f[CR]json\f[R], and (multi\-period reports
-only:) \f[CR]html\f[R].
+only:) \f[CR]html\f[R], \f[CR]fods\f[R] (\f[I]Added in 1.40\f[R]).
 In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative
 amounts are shown in red.
 .SS Simple balance report

hledger/hledger.txt

@@ -19,7 +19,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.34.99.
+       This manual is for hledger's command line interface,  version  1.40.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
@@ -83,7 +83,7 @@ Input
        hledger reads one or more data files, each time you run  it.   You  can
        specify a file with -f, like so
 
-              $ hledger -f FILE print
+              $ hledger -f FILE [-f FILE2 ...] print
 
        Files  are  most  often  in hledger's journal format, with the .journal
        file extension (.hledger or .j also work); these files describe  trans-
@@ -568,28 +568,54 @@ Options
        Argument files are now superseded by..
 
    Config files
-       hledger will read extra command line options from a hledger.conf config
+       As  of  hledger  1.40, you can optionally save command line options (or
-       file.   These will be inserted early in the command line, so your later
+       arguments) to be used when running hledger commands, in a config  file.
-       options can override them if needed.  The config file can contain  gen-
+       Here's a small example:
-       eral  options (which will be used with all commands that support them),
-       and command-specific options (or arguments).  hledger.conf.sample is an
-       example,   which    you    can    install    as    ./hledger.conf    or
-       $HOME/.hledger.conf.
 
-       To  be precise, hledger looks for hledger.conf in the current directory
+              # General options are listed first, one or more per line.
-       or  above,  or  in  your  home   directory   (with   a   dotted   name,
+              # These will be used with all hledger commands that support them.
-       ~/.hledger.conf),  or  finally  in  your  XDG config directory (~/.con-
+              --pretty
-       fig/hledger/hledger.conf).  Or you can select a particular config  file
-       by  using the --conf option, or by adding a hledger --conf shebang line
-       to a config file and executing it like a script (see the example file).
-       You can inspect the finding and processing of config files with --debug
-       or --debug=8.
 
-       If you want to run hledger without a config file,  to  ensure  standard
+              # Options following a `[COMMANDNAME]` heading are used with that hledger command only.
-       defaults and behaviour, use the -n/--no-conf flag.  This is useful when
+              [print]
-       troubleshooting problems or sharing examples.
+              --explicit --show-costs
 
-       (Added in 1.40; experimental)
+       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-
+       ride them if needed).  Or, you can add a hledger --conf shebang line to
+       a config file and execute it like a script.
+
+       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
+       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
+       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
+
+       Automatic  config  files  are convenient, but have a cost: it's easy to
+       change a report's behaviour, or break  scripts/applications  which  use
+       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, here are some tips:
+
+       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.
+
+       This  feature  has been added in hledger 1.40 and is considered experi-
+       mental.
 
 Output
    Output destination
@@ -609,23 +635,21 @@ 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               json    sql
+       -                txt            csv/tsv        html           fods            json   sql
-       --------------------------------------------------------------------------------------
+       -----------------------------------------------------------------------------------------
        aregister        Y              Y              Y                              Y
-       balance            Y 1               Y 1              Y 1,2              Y
+       balance          Y 1            Y 1            Y 1            Y 1             Y
        balancesheet     Y 1            Y 1            Y 1                            Y
        balancesheete-   Y 1            Y 1            Y 1                            Y
        quity
        cashflow         Y 1            Y 1            Y 1                            Y
-       incomestatement    Y 1               Y 1              Y 1                Y
+       incomestate-     Y 1            Y 1            Y 1                            Y
+       ment
        print            Y              Y                                             Y      Y
        register         Y              Y                                             Y
 
        o 1 Also affected by the balance commands' --layout option.
 
-       o 2 balance does not support html output without a report  interval  or
-         with --budget.
-
        The output format is selected by the -O/--output-format=FMT option:
 
               $ hledger print -O csv    # print CSV on stdout
@@ -797,7 +821,7 @@ Journal
        the add or web or import commands to create and update it.
 
        Many users, though, edit the journal file with a text editor, and track
-       changes  with a version control system such as git.  Editor addons such
+       changes with a version control system such as git.  Editor add-ons such
        as  ledger-mode  or  hledger-mode  for  Emacs,  vim-ledger for Vim, and
        hledger-vscode for Visual Studio Code, make this easier, adding colour,
        formatting, tab completion, and useful commands.  See Editor configura-
@@ -4221,12 +4245,13 @@ Timeclock
 
        To generate time logs, ie to clock in and clock out, you could:
 
-       o use emacs and  the  built-in  timeclock.el,  or  the  extended  time-
+       o use these shell aliases at the command line:
-         clock-x.el and perhaps the extras in ledgerutils.el
 
-       o at the command line, use these bash aliases: cli     alias ti="echo i
+                alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG'
-         `date  '+%Y-%m-%d  %H:%M:%S'`  \$*  >>$TIMELOG"      alias to="echo o
+                alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG'
-         `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
+
+       o or Emacs's built-in timeclock.el, or the extended timeclock-x.el, and
+         perhaps the extras in ledgerutils.el
 
        o or use the old ti and to scripts in the ledger 2.x repository.  These
          rely  on  a "timeclock" executable which I think is just the ledger 2
@@ -4531,24 +4556,61 @@ Time periods
        More  complex  intervals  can be specified using -p/--period, described
        below.
 
-   Date adjustment
+   Date adjustments
-       When  there  is  a report interval (other than daily), report start/end
+   Start date adjustment
-       dates which have been inferred, eg from the journal, are  automatically
+       If you let hledger infer a report's start date, it will adjust the date
-       adjusted  to natural period boundaries.  This is convenient for produc-
+       to the previous natural boundary of the report interval, for convenient
-       ing simple periodic reports.  More precisely:
+       periodic reports.  (If you don't want that, specify a start date.)
 
-       o an inferred start date will be adjusted earlier if needed to fall  on
+       For example, if the journal's first transaction is on january 10th,
-         a natural period boundary
 
-       o an  inferred  end  date  will be adjusted later if needed to make the
+       o hledger register (no report interval) will start the report on  janu-
-         last period the same length as the others.
+         ary 10th.
 
-       By contrast, start/end dates which have been specified explicitly, with
+       o hledger  register  --monthly  will  start  the report on the previous
-       -b, -e, -p or date:, will not be adjusted (since hledger  1.29).   This
+         month boundary, january 1st.
-       makes  it  possible to specify non-standard report periods, but it also
+
-       means that if you are specifying a start  date,  you  should  pick  one
+       o hledger register --monthly --begin 1/5 will start the report on janu-
-       that's  on  a  period  boundary if you want to see simple report period
+         ary 5th [1].
-       headings.
+
+       Also if you are generating transactions or budget goals  with  periodic
+       transaction  rules,  their  start date may be adjusted in a similar way
+       (in certain situations).
+
+   End date adjustment
+       A report's end date is always adjusted to include a whole number of in-
+       tervals, so that the last subperiod has the same length as the others.
+
+       For example, if the journal's last transaction is on february 20th,
+
+       o hledger register will end the report on february 20th.
+
+       o hledger register --monthly will end the report at the end  of  febru-
+         ary.
+
+       o hledger register --monthly --end 2/14 also will end the report at the
+         end of february.
+
+       o hledger register --monthly --begin 1/5 --end 2/14 will end the report
+         on march 4th [1].
+
+       [1] Since hledger 1.29.
+
+   Period headings
+       With  non-standard  subperiods,  hledger will show "STARTDATE..ENDDATE"
+       headings.  With standard subperiods (ie, starting on a natural interval
+       boundary), you'll see more compact headings, which are usually  prefer-
+       able.  (Though month names will be in english, currently.)
+
+       So  if  you  are specifying a start date and you want compact headings:
+       choose a start of year for yearly reports, a start of quarter for quar-
+       terly reports, a start of month for monthly reports,  etc.   (Remember,
+       you  can  write eg -b 2024 or 1/1 as a shortcut for a start of year, or
+       2024-04 or 202404 or Apr for a start of month or quarter.)
+
+       For weekly reports, choose a date that's a Monday.  (You can  try  dif-
+       ferent  dates until you see the short headings, or write eg -b '3 weeks
+       ago'.)
 
    Period expressions
        The -p/--period option specifies a period expression, which is  a  com-
@@ -4637,7 +4699,7 @@ Time periods
 
        o every Nth WEEKDAYNAME [of month]
 
-       Yearly on a custom day:
+       Yearly on a custom month and day:
 
        o every MM/DD [of year] (month number and day of month number)
 
@@ -5065,7 +5127,7 @@ Forecasting
                   expenses:rent                  $1000
 
        Here there are no ordinary transactions, so the forecasted transactions
-       begin on the first occurence after today's date.  (You  won't  normally
+       begin on the first occurrence after today's date.  (You won't  normally
        use --today; it's just to make these examples reproducible.)
 
    Forecast reports
@@ -5981,8 +6043,6 @@ Value reporting
        starting balance.
 
 PART 4: COMMANDS
-
-
        Here  are the standard commands, which you can list by running hledger.
        If you have installed more add-on commands, they also will be listed.
 
@@ -6174,9 +6234,6 @@ Data entry commands
          ees/descriptions,  dates  (yesterday, today, tomorrow).  If the input
          area is empty, it will insert the default value.
 
-       o If the journal defines a default commodity, it will be added  to  any
-         bare numbers entered.
-
        o A parenthesised transaction code may be entered following a date.
 
        o Comments and tags may be entered following a description or amount.
@@ -6935,6 +6992,9 @@ Standard report commands
                                           description closest to DESC
                 -r --related              show postings' siblings instead
                    --invert               display all amounts with reversed sign
+                   --sort=FIELDS          sort by: date, desc, account, amount, absamount,
+                                          or a comma-separated combination of these. For a
+                                          descending sort, prefix with -. (Default: date)
                 -w --width=N              set output width (default: terminal width or
                                           $COLUMNS). -wN,M sets description width as well.
                    --align-all            guarantee alignment across all lines (slower)
@@ -6993,6 +7053,13 @@ Standard report commands
        bers.   It's  also  useful to show postings on the checking account to-
        gether with the related account:
 
+       The --sort=FIELDS flag sorts by the fields given, which can be  any  of
+       account, amount, absamount, date, or desc/description, optionally sepa-
+       rated  by  commas.   For  example, --sort account,amount will group all
+       transactions in each account, sorted by transaction amount.  Each field
+       can be negated by a preceding -, so --sort -amount will  show  transac-
+       tions ordered from smallest amount to largest amount.
+
               $ hledger register --related --invert assets:checking
 
        With a reporting interval, register shows summary postings, one per in-
@@ -7498,7 +7565,7 @@ Advanced report commands
                                           'bare'        : commodity symbols in one column
                                           'tidy'        : every attribute in its own column
                 -O --output-format=FMT    select the output format. Supported formats:
-                                          txt, html, csv, tsv, json.
+                                          txt, html, csv, tsv, json, fods.
                 -o --output-file=FILE     write output to FILE. A file extension matching
                                           one of the above formats selects that format.
 
@@ -7582,8 +7649,8 @@ Advanced report commands
 
        This command supports the output destination and output format options,
        with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe-
-       riod reports only:) html.  In txt output in a colour-supporting  termi-
+       riod reports only:) html, fods (Added in 1.40).  In  txt  output  in  a
-       nal, negative amounts are shown in red.
+       colour-supporting terminal, negative amounts are shown in red.
 
    Simple balance report
        With  no  arguments,  balance  shows  a  list of all accounts and their
@@ -9598,4 +9665,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-1.34.99                    June 2024                        HLEDGER(1)
+hledger-1.40.99                 September 2024                      HLEDGER(1)