slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2024-06-01 13:30:47 -10:00
parent d18c00e1ec
commit 3f3672e999
13 changed files with 1803 additions and 1870 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-lib/.date.m4
View File

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

2
hledger-ui/.date.m4
View File

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

83
hledger-ui/hledger-ui.1
View File

@ -1,5 +1,5 @@
.TH "HLEDGER\-UI" "1" "May 2024" "hledger-ui-1.33.99 " "hledger User Manuals"
.TH "HLEDGER\-UI" "1" "June 2024" "hledger-ui-1.34.99 " "hledger User Manuals"
@ -11,9 +11,13 @@ robust, friendly plain text accounting app.
.PD 0
.P
.PD
or
.PD 0
.P
.PD
\f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R]
.SH DESCRIPTION
This manual is for hledger\[aq]s terminal interface, version 1.33.99.
This manual is for hledger\[aq]s terminal interface, version 1.34.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
@ -42,47 +46,27 @@ They can be revealed, along with any rule\-generated periodic
transactions, by pressing the F key (or starting with \-\-forecast) to
enable \[dq]forecast mode\[dq].
.SH OPTIONS
Any QUERYARGS are interpreted as a hledger search query which filters
the data.
.PP
Any arguments are interpreted as a hledger query which filters the data.
hledger\-ui provides the following options:
.TP
\f[CR]\-w \-\-watch\f[R]
watch for data and date changes and reload automatically
.TP
\f[CR]\-\-theme=default|terminal|greenterm|dark\f[R]
use this custom display theme
.TP
\f[CR]\-\-menu\f[R]
start in the menu screen
.TP
\f[CR]\-\-cash\f[R]
start in the cash accounts screen
.TP
\f[CR]\-\-bs\f[R]
start in the balance sheet accounts screen
.TP
\f[CR]\-\-is\f[R]
start in the income statement accounts screen
.TP
\f[CR]\-\-all\f[R]
start in the all accounts screen
.TP
\f[CR]\-\-register=ACCTREGEX\f[R]
start in the (first) matched account\[aq]s register screen
.TP
\f[CR]\-\-change\f[R]
show period balances (changes) at startup instead of historical balances
.TP
\f[CR]\-l \-\-flat\f[R]
show accounts as a flat list (default)
.TP
\f[CR]\-t \-\-tree\f[R]
show accounts as a tree
.IP
.EX
Flags:
\-w \-\-watch watch for data and date changes and reload
automatically
\-\-theme=THEME use this custom display theme (default,
greenterm, terminal, dark)
\-\-cash start in the cash accounts screen
\-\-bs start in the balance sheet accounts screen
\-\-is start in the income statement accounts screen
\-\-all start in the all accounts screen
\-\-register=ACCTREGEX start in the (first matched) account\[aq]s register
\-\-change show period balances (changes) at startup instead
of historical balances
\-l \-\-flat show accounts as a flat list (default)
\-t \-\-tree show accounts as a tree
.EE
.PP
hledger\-ui also supports many of hledger\[aq]s general options (and the
hledger manual\[aq]s command line tips also apply here):
.SS General options
and also supports many of hledger\[aq]s general options:
.IP
.EX
General input/data transformation flags:
@ -151,7 +135,6 @@ General output/reporting flags (supported by some commands):
Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
\-\-color=YN \-\-colour Use ANSI color codes in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].
(A NO_COLOR environment variable overrides this.)
\-\-pretty[=YN] Use box\-drawing characters in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
If YN is specified, the equals is required.
@ -160,10 +143,13 @@ General output/reporting flags (supported by some commands):
General help flags:
\-h \-\-help show command line help
\-\-tldr show command examples with tldr
\-\-info show the hledger manual with info
\-\-man show the hledger manual with man
\-\-info show the manual with info
\-\-man show the manual with man
\-\-version show version information
.EE
.PP
With hledger\-ui, the \f[CR]\-\-debug\f[R] option sends debug output to
a \f[CR]hledger\-ui.log\f[R] file in the current directory.
.SH MOUSE
In most modern terminals, you can navigate through the screens with a
mouse or touchpad:
@ -417,8 +403,7 @@ when you press g to reload.
Once you have fixed the problem, press g again to reload and resume
normal operation.
(Or, you can press escape to cancel the reload attempt.)
.SH TIPS
.SS Watch mode
.SH WATCH MODE
One of hledger\-ui\[aq]s best features is the auto\-reloading
\f[CR]\-w/\-\-watch\f[R] mode.
With this flag, it will update the display automatically whenever
@ -458,12 +443,6 @@ know.)
.PP
If you are viewing files mounted from another machine, the system clocks
on both machines should be roughly in agreement.
.SS Debug output
You can add \f[CR]\-\-debug[=N]\f[R] to the command line to log debug
output.
This will be logged to the file \f[CR]hledger\-ui.log\f[R] in the
current directory.
N ranges from 1 (least output, the default) to 9 (maximum output).
.SH ENVIRONMENT
\f[B]COLUMNS\f[R] The screen width to use.
Default: the full terminal width.

175
hledger-ui/hledger-ui.info
View File

@ -15,9 +15,10 @@ hledger-ui - terminal interface (TUI) for 'hledger', a robust, friendly
plain text accounting app.
'hledger-ui [OPTS] [QUERYARGS]'
or
'hledger ui -- [OPTS] [QUERYARGS]'
This manual is for hledger's terminal interface, version 1.33.99.
This manual is for hledger's terminal interface, version 1.34.99.
See also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs
@ -49,7 +50,7 @@ enable "forecast mode".
* MOUSE::
* KEYS::
* SCREENS::
* TIPS::
* WATCH MODE::
* ENVIRONMENT::
* BUGS::
@ -59,58 +60,25 @@ File: hledger-ui.info, Node: OPTIONS, Next: MOUSE, Prev: Top, Up: Top
1 OPTIONS
*********
Any QUERYARGS are interpreted as a hledger search query which filters
the data.
Any arguments are interpreted as a hledger query which filters the data.
hledger-ui provides the following options:
'-w --watch'
Flags:
-w --watch watch for data and date changes and reload
automatically
--theme=THEME use this custom display theme (default,
greenterm, terminal, dark)
--cash start in the cash accounts screen
--bs start in the balance sheet accounts screen
--is start in the income statement accounts screen
--all start in the all accounts screen
--register=ACCTREGEX start in the (first matched) account's register
--change show period balances (changes) at startup instead
of historical balances
-l --flat show accounts as a flat list (default)
-t --tree show accounts as a tree
watch for data and date changes and reload automatically
'--theme=default|terminal|greenterm|dark'
use this custom display theme
'--menu'
start in the menu screen
'--cash'
start in the cash accounts screen
'--bs'
start in the balance sheet accounts screen
'--is'
start in the income statement accounts screen
'--all'
start in the all accounts screen
'--register=ACCTREGEX'
start in the (first) matched account's register screen
'--change'
show period balances (changes) at startup instead of historical
balances
'-l --flat'
show accounts as a flat list (default)
'-t --tree'
show accounts as a tree
hledger-ui also supports many of hledger's general options (and the
hledger manual's command line tips also apply here):
* Menu:
* General options::

File: hledger-ui.info, Node: General options, Up: OPTIONS
1.1 General options
===================
and also supports many of hledger's general options:
General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be
@ -178,7 +146,6 @@ General output/reporting flags (supported by some commands):
Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
(A NO_COLOR environment variable overrides this.)
--pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required.
@ -187,10 +154,13 @@ General output/reporting flags (supported by some commands):
General help flags:
-h --help show command line help
--tldr show command examples with tldr
--info show the hledger manual with info
--man show the hledger manual with man
--info show the manual with info
--man show the manual with man
--version show version information
With hledger-ui, the '--debug' option sends debug output to a
'hledger-ui.log' file in the current directory.

File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top
@ -309,7 +279,7 @@ amount values.
Additional screen-specific keys are described below.

File: hledger-ui.info, Node: SCREENS, Next: TIPS, Prev: KEYS, Up: Top
File: hledger-ui.info, Node: SCREENS, Next: WATCH MODE, Prev: KEYS, Up: Top
4 SCREENS
*********
@ -485,21 +455,10 @@ again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.)

File: hledger-ui.info, Node: TIPS, Next: ENVIRONMENT, Prev: SCREENS, Up: Top
File: hledger-ui.info, Node: WATCH MODE, Next: ENVIRONMENT, Prev: SCREENS, Up: Top
5 TIPS
******
* Menu:
* Watch mode::
* Debug output::

File: hledger-ui.info, Node: Watch mode, Next: Debug output, Up: TIPS
5.1 Watch mode
==============
5 WATCH MODE
************
One of hledger-ui's best features is the auto-reloading '-w/--watch'
mode. With this flag, it will update the display automatically whenever
@ -536,17 +495,7 @@ work around, press 'g' to reload manually, or try #1617's
clocks on both machines should be roughly in agreement.

File: hledger-ui.info, Node: Debug output, Prev: Watch mode, Up: TIPS
5.2 Debug output
================
You can add '--debug[=N]' to the command line to log debug output. This
will be logged to the file 'hledger-ui.log' in the current directory. N
ranges from 1 (least output, the default) to 9 (maximum output).

File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: TIPS, Up: Top
File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: WATCH MODE, Up: Top
6 ENVIRONMENT
*************
@ -581,42 +530,36 @@ above).

Tag Table:
Node: Top221
Node: OPTIONS1863
Ref: #options1961
Node: General options2928
Ref: #general-options3032
Node: MOUSE8182
Ref: #mouse8277
Node: KEYS8514
Ref: #keys8607
Node: SCREENS13262
Ref: #screens13360
Node: Menu screen13996
Ref: #menu-screen14117
Node: Cash accounts screen14312
Ref: #cash-accounts-screen14489
Node: Balance sheet accounts screen14673
Ref: #balance-sheet-accounts-screen14889
Node: Income statement accounts screen15009
Ref: #income-statement-accounts-screen15230
Node: All accounts screen15394
Ref: #all-accounts-screen15575
Node: Register screen15757
Ref: #register-screen15916
Node: Transaction screen18200
Ref: #transaction-screen18358
Node: Error screen19775
Ref: #error-screen19897
Node: TIPS20141
Ref: #tips20240
Node: Watch mode20282
Ref: #watch-mode20389
Node: Debug output21848
Ref: #debug-output21959
Node: ENVIRONMENT22171
Ref: #environment22281
Node: BUGS22472
Ref: #bugs22555
Node: OPTIONS1872
Ref: #options1970
Node: MOUSE8150
Ref: #mouse8245
Node: KEYS8482
Ref: #keys8575
Node: SCREENS13230
Ref: #screens13334
Node: Menu screen13970
Ref: #menu-screen14091
Node: Cash accounts screen14286
Ref: #cash-accounts-screen14463
Node: Balance sheet accounts screen14647
Ref: #balance-sheet-accounts-screen14863
Node: Income statement accounts screen14983
Ref: #income-statement-accounts-screen15204
Node: All accounts screen15368
Ref: #all-accounts-screen15549
Node: Register screen15731
Ref: #register-screen15890
Node: Transaction screen18174
Ref: #transaction-screen18332
Node: Error screen19749
Ref: #error-screen19871
Node: WATCH MODE20115
Ref: #watch-mode20232
Node: ENVIRONMENT21691
Ref: #environment21807
Node: BUGS21998
Ref: #bugs22081

End Tag Table

65
hledger-ui/hledger-ui.txt
View File

@ -7,10 +7,11 @@ NAME
SYNOPSIS
hledger-ui [OPTS] [QUERYARGS]
or
hledger ui -- [OPTS] [QUERYARGS]
DESCRIPTION
This manual is for hledger's terminal interface, version 1.33.99. See
This manual is for hledger's terminal interface, version 1.34.99. See
also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs for
@ -37,44 +38,26 @@ DESCRIPTION
enable "forecast mode".
OPTIONS
Any QUERYARGS are interpreted as a hledger search query which filters
the data.
hledger-ui provides the following options:
-w --watch
watch for data and date changes and reload automatically
--theme=default|terminal|greenterm|dark
use this custom display theme
--menu start in the menu screen
Any arguments are interpreted as a hledger query which filters the
data. hledger-ui provides the following options:
Flags:
-w --watch watch for data and date changes and reload
automatically
--theme=THEME use this custom display theme (default,
greenterm, terminal, dark)
--cash start in the cash accounts screen
--bs start in the balance sheet accounts screen
--is start in the income statement accounts screen
--all start in the all accounts screen
--register=ACCTREGEX start in the (first matched) account's register
--change show period balances (changes) at startup instead
of historical balances
-l --flat show accounts as a flat list (default)
-t --tree show accounts as a tree
--register=ACCTREGEX
start in the (first) matched account's register screen
and also supports many of hledger's general options:
--change
show period balances (changes) at startup instead of historical
balances
-l --flat
show accounts as a flat list (default)
-t --tree
show accounts as a tree
hledger-ui also supports many of hledger's general options (and the
hledger manual's command line tips also apply here):
General options
General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be
specified more than once. If not specified, reads
@ -141,7 +124,6 @@ OPTIONS
Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
(A NO_COLOR environment variable overrides this.)
--pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required.
@ -150,10 +132,13 @@ OPTIONS
General help flags:
-h --help show command line help
--tldr show command examples with tldr
--info show the hledger manual with info
--man show the hledger manual with man
--info show the manual with info
--man show the manual with man
--version show version information
With hledger-ui, the --debug option sends debug output to a
hledger-ui.log file in the current directory.
MOUSE
In most modern terminals, you can navigate through the screens with a
mouse or touchpad:
@ -379,8 +364,7 @@ SCREENS
again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.)
TIPS
Watch mode
WATCH MODE
One of hledger-ui's best features is the auto-reloading -w/--watch
mode. With this flag, it will update the display automatically when-
ever changes are saved to the data files.
@ -415,11 +399,6 @@ TIPS
If you are viewing files mounted from another machine, the system
clocks on both machines should be roughly in agreement.
Debug output
You can add --debug[=N] to the command line to log debug output. This
will be logged to the file hledger-ui.log in the current directory. N
ranges from 1 (least output, the default) to 9 (maximum output).
ENVIRONMENT
COLUMNS The screen width to use. Default: the full terminal width.
@ -461,4 +440,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-ui-1.33.99 May 2024 HLEDGER-UI(1)
hledger-ui-1.34.99 June 2024 HLEDGER-UI(1)

2
hledger-web/.date.m4
View File

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

115
hledger-web/hledger-web.1
View File

@ -1,5 +1,5 @@
.TH "HLEDGER\-WEB" "1" "May 2024" "hledger-web-1.33.99 " "hledger User Manuals"
.TH "HLEDGER\-WEB" "1" "June 2024" "hledger-web-1.34.99 " "hledger User Manuals"
@ -7,13 +7,17 @@
hledger\-web \- web interface and API for \f[CR]hledger\f[R], a robust,
friendly plain text accounting app.
.SH SYNOPSIS
\f[CR]hledger\-web [\-\-serve|\-\-serve\-api] [OPTS] [ARGS]\f[R]
\f[CR]hledger\-web [OPTS] [QUERY]\f[R]
.PD 0
.P
.PD
\f[CR]hledger web \-\- [\-\-serve|\-\-serve\-api] [OPTS] [ARGS]\f[R]
or
.PD 0
.P
.PD
\f[CR]hledger web \-\- [OPTS] [QUERY]\f[R]
.SH DESCRIPTION
This manual is for hledger\[aq]s web interface, version 1.33.99.
This manual is for hledger\[aq]s web interface, version 1.34.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
@ -61,45 +65,41 @@ In all cases hledger\-web runs as a foreground process, logging requests
to stdout.
.SH OPTIONS
hledger\-web provides the following options:
.TP
\f[CR]\-\-serve\f[R]
serve and log requests, don\[aq]t browse or auto\-exit after timeout
.TP
\f[CR]\-\-serve\-api\f[R]
like \-\-serve, but serve only the JSON web API, not the web UI
.TP
\f[CR]\-\-allow=view|add|edit\f[R]
set the user\[aq]s access level for changing data (default:
\f[CR]add\f[R]).
It also accepts \f[CR]sandstorm\f[R] for use on that platform (reads
permissions from the \f[CR]X\-Sandstorm\-Permissions\f[R] request
header).
.TP
\f[CR]\-\-cors=ORIGIN\f[R]
allow cross\-origin requests from the specified origin; setting ORIGIN
to \[dq]*\[dq] allows requests from any origin
.TP
\f[CR]\-\-host=IPADDR\f[R]
listen on this IP address (default: 127.0.0.1)
.IP
.EX
Flags:
\-\-serve \-\-server serve and log requests, don\[aq]t browse or auto\-exit
\-\-serve\-api like \-\-serve, but serve only the JSON web API,
not the web UI
\-\-allow=view|add|edit set the user\[aq]s access level for changing data
(default: \[ga]add\[ga]). It also accepts \[ga]sandstorm\[ga] for
use on that platform (reads permissions from the
\[ga]X\-Sandstorm\-Permissions\[ga] request header).
\-\-cors=ORIGIN allow cross\-origin requests from the specified
origin; setting ORIGIN to \[dq]*\[dq] allows requests from
any origin
\-\-host=IPADDR listen on this IP address (default: 127.0.0.1)
\-\-port=PORT listen on this TCP port (default: 5000)
\-\-socket=SOCKET listen on the given unix socket instead of an IP
address and port (unix only; implies \-\-serve)
\-\-base\-url=BASEURL set the base url (default: http://IPADDR:PORT)
\-\-test run hledger\-web\[aq]s tests and exit. hspec test
runner args may follow a \-\-, eg: hledger\-web \-\-test
\-\- \-\-help
.EE
.PP
By default the server listens on IP address \f[CR]127.0.0.1\f[R], which
is accessible only to requests from the local machine..
You can use \f[CR]\-\-host\f[R] to listen on a different address
configured on the machine, eg to allow access from other machines.
The special address \f[CR]0.0.0.0\f[R] causes it to listen on all
addresses configured on the machine.
.TP
\f[CR]\-\-port=PORT\f[R]
listen on this TCP port (default: 5000)
By default hledger\-web listens only on IP address \f[CR]127.0.0.1\f[R],
which be accessed only from the local machine.
.PP
To allow access from elsewhere, use \f[CR]\-\-host\f[R] to specify an
externally accessible address configured on this machine, The special
address \f[CR]0.0.0.0\f[R] causes it to listen on all of this
machine\[aq]s addresses.
.PP
Similarly, you can use \f[CR]\-\-port\f[R] to listen on a TCP port other
than 5000.
This is useful if you want to run multiple hledger\-web instances on a
machine.
.TP
\f[CR]\-\-socket=SOCKETFILE\f[R]
listen on the given unix socket instead of an IP address and port (unix
only; implies \-\-serve)
.PP
When \f[CR]\-\-socket\f[R] is used, hledger\-web creates and
communicates via a socket file instead of a TCP port.
@ -108,9 +108,6 @@ certain use cases easier, such as running per\-user instances behind an
nginx reverse proxy.
(Eg:
\f[CR]proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;\f[R].)
.TP
\f[CR]\-\-base\-url=URL\f[R]
set the base url (default: http://IPADDR:PORT).
.PP
You can use \f[CR]\-\-base\-url\f[R] to change the protocol, hostname,
port and path that appear in hledger\-web\[aq]s hyperlinks.
@ -119,26 +116,8 @@ The default is \f[CR]http://HOST:PORT/\f[R] using the server\[aq]s
configured host address and TCP port (or \f[CR]http://HOST\f[R] if PORT
is 80).
Note this affects url generation but not route parsing.
.TP
\f[CR]\-\-test\f[R]
run hledger\-web\[aq]s tests and exit.
hspec test runner args may follow a \-\-, eg: hledger\-web \-\-test \-\-
\-\-help
.PP
hledger\-web also supports many of hledger\[aq]s general options.
Query options and arguments may be used to set an initial filter, which
although not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
.PP
Note that hledger\-web shows accounts with zero balances by default,
like \f[CR]hledger\-ui\f[R] (and unlike \f[CR]hledger\f[R]).
Using the \f[CR]\-E/\-\-empty\f[R] flag at startup will hide them.
.PP
If you see accounts which appear to have a zero balance, but cannot be
hidden with \f[CR]\-E\f[R]: these have a mixed\-cost balance which looks
like zero when costs are hidden.
Currently hledger\-web does not show costs at all.
.SS General options
hledger\-web also supports many of hledger\[aq]s general options:
.IP
.EX
General input/data transformation flags:
@ -207,7 +186,6 @@ General output/reporting flags (supported by some commands):
Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
\-\-color=YN \-\-colour Use ANSI color codes in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].
(A NO_COLOR environment variable overrides this.)
\-\-pretty[=YN] Use box\-drawing characters in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
If YN is specified, the equals is required.
@ -216,10 +194,22 @@ General output/reporting flags (supported by some commands):
General help flags:
\-h \-\-help show command line help
\-\-tldr show command examples with tldr
\-\-info show the hledger manual with info
\-\-man show the hledger manual with man
\-\-info show the manual with info
\-\-man show the manual with man
\-\-version show version information
.EE
.PP
hledger\-web shows accounts with zero balances by default (like
\f[CR]hledger\-ui\f[R], and unlike \f[CR]hledger\f[R]).
Using the \f[CR]\-E/\-\-empty\f[R] flag will reverse this behaviour.
If you see accounts which appear to have a zero balance, but cannot be
hidden with \f[CR]\-E\f[R], it\[aq]s because they have a mixed\-cost
balance, which looks like zero when costs are hidden.
(hledger\-web does not show costs.)
.PP
Reporting options and/or query arguments can be used to set an initial
query, which although not shown in the UI, will restrict the data shown
(in addition to any search query entered in the UI).
.SH PERMISSIONS
By default, hledger\-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data.
@ -360,6 +350,7 @@ Most of the JSON corresponds to hledger\[aq]s data types; for details of
what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction.
And for a higher level understanding, see the journal docs.
There is also a basic OpenAPI specification.
.PP
In some cases there is outer JSON corresponding to a \[dq]Report\[dq]
type.

152
hledger-web/hledger-web.info
View File

@ -14,10 +14,11 @@ hledger-web(1)
hledger-web - web interface and API for 'hledger', a robust, friendly
plain text accounting app.
'hledger-web [--serve|--serve-api] [OPTS] [ARGS]'
'hledger web -- [--serve|--serve-api] [OPTS] [ARGS]'
'hledger-web [OPTS] [QUERY]'
or
'hledger web -- [OPTS] [QUERY]'
This manual is for hledger's web interface, version 1.33.99. See
This manual is for hledger's web interface, version 1.34.99. See
also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs
@ -78,54 +79,43 @@ File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top
hledger-web provides the following options:
'--serve'
Flags:
--serve --server serve and log requests, don't browse or auto-exit
--serve-api like --serve, but serve only the JSON web API,
not the web UI
--allow=view|add|edit set the user's access level for changing data
(default: `add`). It also accepts `sandstorm` for
use on that platform (reads permissions from the
`X-Sandstorm-Permissions` request header).
--cors=ORIGIN allow cross-origin requests from the specified
origin; setting ORIGIN to "*" allows requests from
any origin
--host=IPADDR listen on this IP address (default: 127.0.0.1)
--port=PORT listen on this TCP port (default: 5000)
--socket=SOCKET listen on the given unix socket instead of an IP
address and port (unix only; implies --serve)
--base-url=BASEURL set the base url (default: http://IPADDR:PORT)
--test run hledger-web's tests and exit. hspec test
runner args may follow a --, eg: hledger-web --test
-- --help
serve and log requests, don't browse or auto-exit after timeout
'--serve-api'
By default hledger-web listens only on IP address '127.0.0.1', which
be accessed only from the local machine.
like -serve, but serve only the JSON web API, not the web UI
'--allow=view|add|edit'
set the user's access level for changing data (default: 'add'). It
also accepts 'sandstorm' for use on that platform (reads
permissions from the 'X-Sandstorm-Permissions' request header).
'--cors=ORIGIN'
allow cross-origin requests from the specified origin; setting
ORIGIN to "*" allows requests from any origin
'--host=IPADDR'
listen on this IP address (default: 127.0.0.1)
By default the server listens on IP address '127.0.0.1', which is
accessible only to requests from the local machine.. You can use
'--host' to listen on a different address configured on the machine, eg
to allow access from other machines. The special address '0.0.0.0'
causes it to listen on all addresses configured on the machine.
'--port=PORT'
listen on this TCP port (default: 5000)
To allow access from elsewhere, use '--host' to specify an externally
accessible address configured on this machine, The special address
'0.0.0.0' causes it to listen on all of this machine's addresses.
Similarly, you can use '--port' to listen on a TCP port other than
5000. This is useful if you want to run multiple hledger-web instances
on a machine.
'--socket=SOCKETFILE'
listen on the given unix socket instead of an IP address and port
(unix only; implies -serve)
When '--socket' is used, hledger-web creates and communicates via a
socket file instead of a TCP port. This can be more secure, respects
unix file permissions, and makes certain use cases easier, such as
running per-user instances behind an nginx reverse proxy. (Eg:
'proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;'.)
'--base-url=URL'
set the base url (default: http://IPADDR:PORT).
You can use '--base-url' to change the protocol, hostname, port and
path that appear in hledger-web's hyperlinks. This is useful eg when
integrating hledger-web within a larger website. The default is
@ -133,34 +123,7 @@ integrating hledger-web within a larger website. The default is
port (or 'http://HOST' if PORT is 80). Note this affects url generation
but not route parsing.
'--test'
run hledger-web's tests and exit. hspec test runner args may
follow a -, eg: hledger-web -test - -help
hledger-web also supports many of hledger's general options. Query
options and arguments may be used to set an initial filter, which
although not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
Note that hledger-web shows accounts with zero balances by default,
like 'hledger-ui' (and unlike 'hledger'). Using the '-E/--empty' flag
at startup will hide them.
If you see accounts which appear to have a zero balance, but cannot
be hidden with '-E': these have a mixed-cost balance which looks like
zero when costs are hidden. Currently hledger-web does not show costs
at all.
* Menu:
* General options::

File: hledger-web.info, Node: General options, Up: OPTIONS
1.1 General options
===================
hledger-web also supports many of hledger's general options:
General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be
@ -228,7 +191,6 @@ General output/reporting flags (supported by some commands):
Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
(A NO_COLOR environment variable overrides this.)
--pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required.
@ -237,10 +199,21 @@ General output/reporting flags (supported by some commands):
General help flags:
-h --help show command line help
--tldr show command examples with tldr
--info show the hledger manual with info
--man show the hledger manual with man
--info show the manual with info
--man show the manual with man
--version show version information
hledger-web shows accounts with zero balances by default (like
'hledger-ui', and unlike 'hledger'). Using the '-E/--empty' flag will
reverse this behaviour. If you see accounts which appear to have a zero
balance, but cannot be hidden with '-E', it's because they have a
mixed-cost balance, which looks like zero when costs are hidden.
(hledger-web does not show costs.)
Reporting options and/or query arguments can be used to set an
initial query, which although not shown in the UI, will restrict the
data shown (in addition to any search query entered in the UI).

File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING, Prev: OPTIONS, Up: Top
@ -382,7 +355,8 @@ $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
Most of the JSON corresponds to hledger's data types; for details of
what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction. And for a higher level
understanding, see the journal docs.
understanding, see the journal docs. There is also a basic OpenAPI
specification.
In some cases there is outer JSON corresponding to a "Report" type.
To understand that, go to the Hledger.Web.Handler.MiscR haddock and look
@ -548,26 +522,24 @@ http://bugs.hledger.org), or on the #hledger chat or hledger mail list

Tag Table:
Node: Top223
Node: OPTIONS2608
Ref: #options2713
Node: General options5617
Ref: #general-options5722
Node: PERMISSIONS10872
Ref: #permissions11011
Node: EDITING UPLOADING DOWNLOADING12223
Ref: #editing-uploading-downloading12404
Node: RELOADING13238
Ref: #reloading13372
Node: JSON API13805
Ref: #json-api13920
Node: DEBUG OUTPUT19408
Ref: #debug-output19533
Node: Debug output19560
Ref: #debug-output-119661
Node: ENVIRONMENT20078
Ref: #environment20197
Node: BUGS20314
Ref: #bugs20398
Node: OPTIONS2569
Ref: #options2674
Node: PERMISSIONS10862
Ref: #permissions11001
Node: EDITING UPLOADING DOWNLOADING12213
Ref: #editing-uploading-downloading12394
Node: RELOADING13228
Ref: #reloading13362
Node: JSON API13795
Ref: #json-api13910
Node: DEBUG OUTPUT19444
Ref: #debug-output19569
Node: Debug output19596
Ref: #debug-output-119697
Node: ENVIRONMENT20114
Ref: #environment20233
Node: BUGS20350
Ref: #bugs20434

End Tag Table

101
hledger-web/hledger-web.txt
View File

@ -6,11 +6,12 @@ NAME
plain text accounting app.
SYNOPSIS
hledger-web [--serve|--serve-api] [OPTS] [ARGS]
hledger web -- [--serve|--serve-api] [OPTS] [ARGS]
hledger-web [OPTS] [QUERY]
or
hledger web -- [OPTS] [QUERY]
DESCRIPTION
This manual is for hledger's web interface, version 1.33.99. See also
This manual is for hledger's web interface, version 1.34.99. See also
the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs for
@ -55,50 +56,43 @@ DESCRIPTION
OPTIONS
hledger-web provides the following options:
--serve
serve and log requests, don't browse or auto-exit after timeout
Flags:
--serve --server serve and log requests, don't browse or auto-exit
--serve-api like --serve, but serve only the JSON web API,
not the web UI
--allow=view|add|edit set the user's access level for changing data
(default: `add`). It also accepts `sandstorm` for
use on that platform (reads permissions from the
`X-Sandstorm-Permissions` request header).
--cors=ORIGIN allow cross-origin requests from the specified
origin; setting ORIGIN to "*" allows requests from
any origin
--host=IPADDR listen on this IP address (default: 127.0.0.1)
--port=PORT listen on this TCP port (default: 5000)
--socket=SOCKET listen on the given unix socket instead of an IP
address and port (unix only; implies --serve)
--base-url=BASEURL set the base url (default: http://IPADDR:PORT)
--test run hledger-web's tests and exit. hspec test
runner args may follow a --, eg: hledger-web --test
-- --help
--serve-api
like --serve, but serve only the JSON web API, not the web UI
By default hledger-web listens only on IP address 127.0.0.1, which be
accessed only from the local machine.
--allow=view|add|edit
set the user's access level for changing data (default: add).
It also accepts sandstorm for use on that platform (reads per-
missions from the X-Sandstorm-Permissions request header).
--cors=ORIGIN
allow cross-origin requests from the specified origin; setting
ORIGIN to "*" allows requests from any origin
--host=IPADDR
listen on this IP address (default: 127.0.0.1)
By default the server listens on IP address 127.0.0.1, which is acces-
sible only to requests from the local machine.. You can use --host to
listen on a different address configured on the machine, eg to allow
access from other machines. The special address 0.0.0.0 causes it to
listen on all addresses configured on the machine.
--port=PORT
listen on this TCP port (default: 5000)
To allow access from elsewhere, use --host to specify an externally ac-
cessible address configured on this machine, The special address
0.0.0.0 causes it to listen on all of this machine's addresses.
Similarly, you can use --port to listen on a TCP port other than 5000.
This is useful if you want to run multiple hledger-web instances on a
machine.
--socket=SOCKETFILE
listen on the given unix socket instead of an IP address and
port (unix only; implies --serve)
When --socket is used, hledger-web creates and communicates via a
socket file instead of a TCP port. This can be more secure, respects
unix file permissions, and makes certain use cases easier, such as run-
ning per-user instances behind an nginx reverse proxy. (Eg: proxy_pass
http://unix:/tmp/hledger/${remote_user}.socket;.)
--base-url=URL
set the base url (default: http://IPADDR:PORT).
You can use --base-url to change the protocol, hostname, port and path
that appear in hledger-web's hyperlinks. This is useful eg when inte-
grating hledger-web within a larger website. The default is
@ -106,24 +100,8 @@ OPTIONS
port (or http://HOST if PORT is 80). Note this affects url generation
but not route parsing.
--test run hledger-web's tests and exit. hspec test runner args may
follow a --, eg: hledger-web --test -- --help
hledger-web also supports many of hledger's general options:
hledger-web also supports many of hledger's general options. Query op-
tions and arguments may be used to set an initial filter, which al-
though not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
Note that hledger-web shows accounts with zero balances by default,
like hledger-ui (and unlike hledger). Using the -E/--empty flag at
startup will hide them.
If you see accounts which appear to have a zero balance, but cannot be
hidden with -E: these have a mixed-cost balance which looks like zero
when costs are hidden. Currently hledger-web does not show costs at
all.
General options
General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be
specified more than once. If not specified, reads
@ -190,7 +168,6 @@ OPTIONS
Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
(A NO_COLOR environment variable overrides this.)
--pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required.
@ -199,10 +176,21 @@ OPTIONS
General help flags:
-h --help show command line help
--tldr show command examples with tldr
--info show the hledger manual with info
--man show the hledger manual with man
--info show the manual with info
--man show the manual with man
--version show version information
hledger-web shows accounts with zero balances by default (like
hledger-ui, and unlike hledger). Using the -E/--empty flag will re-
verse this behaviour. If you see accounts which appear to have a zero
balance, but cannot be hidden with -E, it's because they have a
mixed-cost balance, which looks like zero when costs are hidden.
(hledger-web does not show costs.)
Reporting options and/or query arguments can be used to set an initial
query, which although not shown in the UI, will restrict the data shown
(in addition to any search query entered in the UI).
PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data.
@ -327,7 +315,8 @@ JSON API
Most of the JSON corresponds to hledger's data types; for details of
what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction. And for a higher level un-
derstanding, see the journal docs.
derstanding, see the journal docs. There is also a basic OpenAPI spec-
ification.
In some cases there is outer JSON corresponding to a "Report" type. To
understand that, go to the Hledger.Web.Handler.MiscR haddock and look
@ -484,4 +473,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-web-1.33.99 May 2024 HLEDGER-WEB(1)
hledger-web-1.34.99 June 2024 HLEDGER-WEB(1)

2
hledger/.date.m4
View File

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

173
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t
.TH "HLEDGER" "1" "May 2024" "hledger-1.33.99 " "hledger User Manuals"
.TH "HLEDGER" "1" "June 2024" "hledger-1.34.99 " "hledger User Manuals"
@ -12,11 +12,19 @@ version).
.PD 0
.P
.PD
or
.PD 0
.P
.PD
\f[CR]hledger COMMAND [OPTS] [ARGS]\f[R]
.PD 0
.P
.PD
\f[CR]hledger ADDONCMD \-\- [OPTS] [ARGS]\f[R]
or
.PD 0
.P
.PD
\f[CR]hledger ADDONCMD [OPTS] \-\- [ADDONOPTS] [ADDONARGS]\f[R]
.SH DESCRIPTION
hledger is a robust, user\-friendly, cross\-platform set of programs for
tracking money, time, or any other commodity, using double\-entry
@ -25,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.33.99.
1.34.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!
@ -227,8 +235,8 @@ The file name \f[CR]\-\f[R] means standard input:
$ cat FILE | hledger \-f\- print
.EE
.PP
If reading non\-journal data in this way, you\[aq]ll need to add a file
format prefix, like:
If reading non\-journal data in this way, you\[aq]ll need to write the
format as a prefix, like \f[CR]timeclock:\f[R] here:
.IP
.EX
$ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print \-f timeclock:\-
@ -329,9 +337,9 @@ If this causes difficulty, you can always run the add\-on directly,
without using \f[CR]hledger\f[R]: \f[CR]hledger\-ui \-\-watch\f[R] or
\f[CR]hledger\-web \-\-serve\f[R].
.SH Options
Run \f[CR]hledger \-h\f[R] to see general command line help, and general
options which are common to most hledger commands.
These options can be written anywhere on the command line:
Run \f[CR]hledger \-h\f[R] to see general command line help.
The following general options are common to most hledger commands.
General options can be written either before or after the command name.
.IP
.EX
General input/data transformation flags:
@ -400,7 +408,6 @@ General output/reporting flags (supported by some commands):
Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
\-\-color=YN \-\-colour Use ANSI color codes in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].
(A NO_COLOR environment variable overrides this.)
\-\-pretty[=YN] Use box\-drawing characters in text output? Can be
\[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
If YN is specified, the equals is required.
@ -409,19 +416,24 @@ General output/reporting flags (supported by some commands):
General help flags:
\-h \-\-help show command line help
\-\-tldr show command examples with tldr
\-\-info show the hledger manual with info
\-\-man show the hledger manual with man
\-\-info show the manual with info
\-\-man show the manual with man
\-\-version show version information
.EE
.PP
Some reporting options can also be written as query arguments.
.SH Command line tips
Here are some details useful to know about for hledger command lines
(and elsewhere).
Feel free to skip this section until you need it.
.SS Option repetition
If options are repeated in a command line, hledger will generally use
the last (right\-most) occurence.
Usually hledger accepts any unambiguous flag prefix, eg you can write
\f[CR]\-\-tl\f[R] instead of \f[CR]\-\-tldr\f[R] or \f[CR]\-\-dry\f[R]
instead of \f[CR]\-\-dry\-run\f[R].
.PP
If the same option appears more than once in a command, usually the last
(right\-most) wins.
.PP
With most commands, arguments are interpreted as a hledger query which
filter the data.
Some queries can be expressed either with options or with arguments.
.PP
Below are more tips for using the command line interface \- feel free to
skip these until you need them.
.SS Special characters
.SS Single escaping (shell metacharacters)
In shell command lines, characters significant to your shell \- such as
@ -886,6 +898,7 @@ 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.
@ -1018,9 +1031,10 @@ If not set, they will try to use the available terminal width.
with \f[CR]\-f/\-\-file\f[R].
Default: \f[CR]$HOME/.hledger.journal\f[R].
.PP
\f[B]NO_COLOR\f[R] If this environment variable is set (with any value),
hledger will not use ANSI color codes in terminal output, unless
overridden by an explicit \f[CR]\-\-color/\-\-colour\f[R] option.
\f[B]NO_COLOR\f[R] If this environment variable exists (with any value,
including empty), hledger will not use ANSI color codes in terminal
output, unless overridden by an explicit
\f[CR]\-\-color=y\f[R]/\f[CR]\-\-colour=y\f[R] option.
.SH PART 2: DATA FORMATS
.SH Journal
hledger\[aq]s usual data source is a plain text file containing journal
@ -3411,24 +3425,39 @@ when evaluating a region of the journal in your editor.
A missing Y directive makes reports dependent on today\[aq]s date.
.SS Secondary dates
A secondary date is written after the primary date, following an equals
sign.
sign: \f[CR]DATE1=DATE2\f[R].
If the year is omitted, the primary date\[aq]s year is assumed.
When running reports, the primary (left) date is used by default, but
with the \f[CR]\-\-date2\f[R] flag (or \f[CR]\-\-aux\-date\f[R] or
\f[CR]\-\-effective\f[R]), the secondary (right) date will be used
instead.
When running reports, the primary (left side) date is used by default,
but with the \f[CR]\-\-date2\f[R] flag (\f[CR]\-\-aux\-date\f[R]
or\f[CR]\-\-effective\f[R] also work, for Ledger users), the secondary
(right side) date will be used instead.
.PP
The meaning of secondary dates is up to you, but it\[aq]s best to follow
a consistent rule.
Eg \[dq]primary = the bank\[aq]s clearing date, secondary = date the
transaction was initiated, if different\[dq].
The meaning of secondary dates is up to you.
Eg it could be \[dq]primary is the bank\[aq]s clearing date, secondary
is the date the transaction was initiated, if different\[dq].
.PP
Downsides: makes your financial data more complicated, less portable,
and less trustworthy in an audit.
Keeping the meaning of the two dates consistent requires discipline, and
you have to remember which reporting mode is appropriate for a given
report.
Posting dates are simpler and better.
In practice, this feature usually adds confusion:
.IP \[bu] 2
You have to remember the primary and secondary dates\[aq] meaning, and
follow that consistently.
.IP \[bu] 2
It splits your bookkeeping into two modes, and you have to remember
which mode is appropriate for a given report.
.IP \[bu] 2
Usually your balance assertions will work with only one of these modes.
.IP \[bu] 2
It makes your financial data more complicated, less portable, and less
clear in an audit.
.IP \[bu] 2
It interacts with every feature, creating an ongoing cost for
implementors.
.IP \[bu] 2
It distracts new users and supporters.
.IP \[bu] 2
Posting dates are simpler and work better.
.PP
So secondary dates are officially deprecated in hledger, remaining only
as a Ledger compatibility aid; we recommend using posting dates instead.
.SS Star comments
Lines beginning with \f[CR]*\f[R] (star/asterisk) are also comment
lines.
@ -6335,42 +6364,52 @@ $ hledger balance Income:Dues \-\-pivot kind:member
\-2 EUR
.EE
.SH Generating data
hledger has several features for generating data, such as:
hledger can enrich the data provided to it, or generate new data, in a
number of ways.
Mostly, this is done only if you request it:
.IP \[bu] 2
Periodic transaction rules can generate single or repeating transactions
following a template.
These are usually dated in the future, eg to help with forecasting.
They are activated by the \f[CR]\-\-forecast\f[R] option.
.IP \[bu] 2
The balance command\[aq]s \f[CR]\-\-budget\f[R] option uses these same
periodic rules to generate goals for the budget report.
.IP \[bu] 2
Auto posting rules can generate extra postings on certain matched
transactions.
They are always applied to forecast transactions; with the
\f[CR]\-\-auto\f[R] flag they are applied to transactions recorded in
the journal as well.
Missing amounts or missing costs in transactions are inferred
automatically when possible.
.IP \[bu] 2
The \f[CR]\-\-infer\-equity\f[R] flag infers missing conversion equity
postings from \[at]/\[at]\[at] costs.
And the inverse \f[CR]\-\-infer\-costs\f[R] flag infers missing
\[at]/\[at]\[at] costs from conversion equity postings.
.IP \[bu] 2
The \f[CR]\-\-infer\-costs\f[R] flag infers missing costs from
conversion equity postings.
.IP \[bu] 2
The \f[CR]\-\-infer\-market\-prices\f[R] flag infers \f[CR]P\f[R] price
directives from costs.
.IP \[bu] 2
The \f[CR]\-\-auto\f[R] flag adds extra postings to transactions matched
by auto posting rules.
.IP \[bu] 2
The \f[CR]\-\-forecast\f[R] option generates transactions from periodic
transaction rules.
.IP \[bu] 2
The \f[CR]balance \-\-budget\f[R] report infers budget goals from
periodic transaction rules.
.IP \[bu] 2
Commands like \f[CR]close\f[R], \f[CR]rewrite\f[R], and
\f[CR]hledger\-interest\f[R] generate transactions or postings.
.IP \[bu] 2
CSV data is converted to transactions by applying CSV conversion rules..
etc.
.PP
Generated data of this kind is temporary, existing only at report time.
But you can see it in the output of \f[CR]hledger print\f[R], and you
can save that to your journal, in effect converting it from temporary
generated data to permanent recorded data.
This could be useful as a data entry aid.
Such generated data is temporary, existing only at report time.
You can convert it to permanent recorded data by, eg, capturing the
output of \f[CR]hledger print\f[R] and saving it in your journal file.
This can sometimes be useful as a data entry aid.
.PP
If you are wondering what data is being generated and why, add the
\f[CR]\-\-verbose\-tags\f[R] flag.
In \f[CR]hledger print\f[R] output you will see extra tags like
\f[CR]generated\-transaction\f[R], \f[CR]generated\-posting\f[R], and
\f[CR]modified\f[R] on generated/modified data.
Also, even without \f[CR]\-\-verbose\-tags\f[R], generated data always
has equivalen hidden tags (with an underscore prefix), so eg you could
match generated transactions with
\f[CR]tag:_generated\-transaction\f[R].
If you are curious what data is being generated and why, run
\f[CR]hledger print \-x \-\-verbose\-tags\f[R].
\f[CR]\-x/\-\-explicit\f[R] shows inferred amounts and
\f[CR]\-\-verbose\-tags\f[R] adds tags like
\f[CR]generated\-transaction\f[R] (from periodic rules) and
\f[CR]generated\-posting\f[R], \f[CR]modified\f[R] (from auto posting
rules).
Similar hidden tags (with an underscore prefix) are always present,
also, so you can always match such data with queries like
\f[CR]tag:generated\f[R] or \f[CR]tag:modified\f[R].
.SH Forecasting
Forecasting, or speculative future reporting, can be useful for
estimating future balances, or for exploring different future scenarios.

2280
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

155
hledger/hledger.txt
View File

@ -7,8 +7,10 @@ NAME
SYNOPSIS
hledger
or
hledger COMMAND [OPTS] [ARGS]
hledger ADDONCMD -- [OPTS] [ARGS]
or
hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]
DESCRIPTION
hledger is a robust, user-friendly, cross-platform set of programs for
@ -17,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.33.99.
This manual is for hledger's command line interface, version 1.34.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
@ -149,8 +151,8 @@ Input
$ cat FILE | hledger -f- print
If reading non-journal data in this way, you'll need to add a file for-
mat prefix, like:
If reading non-journal data in this way, you'll need to write the for-
mat as a prefix, like timeclock: here:
$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
@ -239,9 +241,9 @@ Commands
hledger-ui --watch or hledger-web --serve.
Options
Run hledger -h to see general command line help, and general options
which are common to most hledger commands. These options can be writ-
ten anywhere on the command line:
Run hledger -h to see general command line help. The following general
options are common to most hledger commands. General options can be
written either before or after the command name.
General input/data transformation flags:
-f --file=FILE Read data from FILE, or from stdin if -. Can be
@ -309,7 +311,6 @@ Options
Eg: -c '.' or -c '1.000,00 EUR'
--color=YN --colour Use ANSI color codes in text output? Can be
'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
(A NO_COLOR environment variable overrides this.)
--pretty[=YN] Use box-drawing characters in text output? Can be
'y'/'yes' or 'n'/'no'.
If YN is specified, the equals is required.
@ -318,19 +319,22 @@ Options
General help flags:
-h --help show command line help
--tldr show command examples with tldr
--info show the hledger manual with info
--man show the hledger manual with man
--info show the manual with info
--man show the manual with man
--version show version information
Some reporting options can also be written as query arguments.
Usually hledger accepts any unambiguous flag prefix, eg you can write
--tl instead of --tldr or --dry instead of --dry-run.
Command line tips
Here are some details useful to know about for hledger command lines
(and elsewhere). Feel free to skip this section until you need it.
If the same option appears more than once in a command, usually the
last (right-most) wins.
Option repetition
If options are repeated in a command line, hledger will generally use
the last (right-most) occurence.
With most commands, arguments are interpreted as a hledger query which
filter the data. Some queries can be expressed either with options or
with arguments.
Below are more tips for using the command line interface - feel free to
skip these until you need them.
Special characters
Single escaping (shell metacharacters)
@ -616,7 +620,8 @@ Output
sentation of hledger's internal data types. To understand the JSON,
read the Haskell type definitions, which are mostly in
https://github.com/simonmichael/hledger/blob/mas-
ter/hledger-lib/Hledger/Data/Types.hs.
ter/hledger-lib/Hledger/Data/Types.hs. hledger-web's OpenAPI speci-
fication may also be relevant.
o hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals. Such numbers can
@ -728,9 +733,9 @@ Environment
LEDGER_FILE The main journal file to use when not specified with
-f/--file. Default: $HOME/.hledger.journal.
NO_COLOR If this environment variable is set (with any value), hledger
will not use ANSI color codes in terminal output, unless overridden by
an explicit --color/--colour option.
NO_COLOR If this environment variable exists (with any value, including
empty), hledger will not use ANSI color codes in terminal output, un-
less overridden by an explicit --color=y/--colour=y option.
PART 2: DATA FORMATS
Journal
@ -2670,20 +2675,40 @@ Journal
Secondary dates
A secondary date is written after the primary date, following an equals
sign. If the year is omitted, the primary date's year is assumed.
When running reports, the primary (left) date is used by default, but
with the --date2 flag (or --aux-date or --effective), the secondary
(right) date will be used instead.
sign: DATE1=DATE2. If the year is omitted, the primary date's year is
assumed. When running reports, the primary (left side) date is used by
default, but with the --date2 flag (--aux-date or--effective also work,
for Ledger users), the secondary (right side) date will be used in-
stead.
The meaning of secondary dates is up to you, but it's best to follow a
consistent rule. Eg "primary = the bank's clearing date, secondary =
date the transaction was initiated, if different".
The meaning of secondary dates is up to you. Eg it could be "primary
is the bank's clearing date, secondary is the date the transaction was
initiated, if different".
Downsides: makes your financial data more complicated, less portable,
and less trustworthy in an audit. Keeping the meaning of the two dates
consistent requires discipline, and you have to remember which report-
ing mode is appropriate for a given report. Posting dates are simpler
and better.
In practice, this feature usually adds confusion:
o You have to remember the primary and secondary dates' meaning, and
follow that consistently.
o It splits your bookkeeping into two modes, and you have to remember
which mode is appropriate for a given report.
o Usually your balance assertions will work with only one of these
modes.
o It makes your financial data more complicated, less portable, and
less clear in an audit.
o It interacts with every feature, creating an ongoing cost for imple-
mentors.
o It distracts new users and supporters.
o Posting dates are simpler and work better.
So secondary dates are officially deprecated in hledger, remaining only
as a Ledger compatibility aid; we recommend using posting dates in-
stead.
Star comments
Lines beginning with * (star/asterisk) are also comment lines. This
@ -4899,37 +4924,47 @@ Pivoting
-2 EUR
Generating data
hledger has several features for generating data, such as:
hledger can enrich the data provided to it, or generate new data, in a
number of ways. Mostly, this is done only if you request it:
o Periodic transaction rules can generate single or repeating transac-
tions following a template. These are usually dated in the future,
eg to help with forecasting. They are activated by the --forecast
option.
o The balance command's --budget option uses these same periodic rules
to generate goals for the budget report.
o Auto posting rules can generate extra postings on certain matched
transactions. They are always applied to forecast transactions; with
the --auto flag they are applied to transactions recorded in the
journal as well.
o Missing amounts or missing costs in transactions are inferred auto-
matically when possible.
o The --infer-equity flag infers missing conversion equity postings
from @/@@ costs. And the inverse --infer-costs flag infers missing
@/@@ costs from conversion equity postings.
from @/@@ costs.
Generated data of this kind is temporary, existing only at report time.
But you can see it in the output of hledger print, and you can save
that to your journal, in effect converting it from temporary generated
data to permanent recorded data. This could be useful as a data entry
aid.
o The --infer-costs flag infers missing costs from conversion equity
postings.
If you are wondering what data is being generated and why, add the
--verbose-tags flag. In hledger print output you will see extra tags
like generated-transaction, generated-posting, and modified on gener-
ated/modified data. Also, even without --verbose-tags, generated data
always has equivalen hidden tags (with an underscore prefix), so eg you
could match generated transactions with tag:_generated-transaction.
o The --infer-market-prices flag infers P price directives from costs.
o The --auto flag adds extra postings to transactions matched by auto
posting rules.
o The --forecast option generates transactions from periodic transac-
tion rules.
o The balance --budget report infers budget goals from periodic trans-
action rules.
o Commands like close, rewrite, and hledger-interest generate transac-
tions or postings.
o CSV data is converted to transactions by applying CSV conversion
rules.. etc.
Such generated data is temporary, existing only at report time. You
can convert it to permanent recorded data by, eg, capturing the output
of hledger print and saving it in your journal file. This can some-
times be useful as a data entry aid.
If you are curious what data is being generated and why, run hledger
print -x --verbose-tags. -x/--explicit shows inferred amounts and
--verbose-tags adds tags like generated-transaction (from periodic
rules) and generated-posting, modified (from auto posting rules). Sim-
ilar hidden tags (with an underscore prefix) are always present, also,
so you can always match such data with queries like tag:generated or
tag:modified.
Forecasting
Forecasting, or speculative future reporting, can be useful for esti-
@ -9112,4 +9147,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-1.33.99 May 2024 HLEDGER(1)
hledger-1.34.99 June 2024 HLEDGER(1)