simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-11-07 21:15:19 +03:00
Code Issues Projects Releases Wiki Activity

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2024-03-24 14:22:54 -10:00
parent 70b75e4921
commit 76f98f28fd
12 changed files with 4049 additions and 3594 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_}}, {{February 2024}})m4_dnl
m4_define({{_monthyear_}}, {{March 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_}}, {{February 2024}})m4_dnl
m4_define({{_monthyear_}}, {{March 2024}})m4_dnl

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

@ -1,5 +1,5 @@
.TH "HLEDGER\-UI" "1" "February 2024" "hledger-ui-1.32.99 " "hledger User Manuals"
.TH "HLEDGER\-UI" "1" "March 2024" "hledger-ui-1.32.99 " "hledger User Manuals"

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

@ -535,4 +535,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-ui-1.32.99 February 2024 HLEDGER-UI(1)
hledger-ui-1.32.99 March 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_}}, {{February 2024}})m4_dnl
m4_define({{_monthyear_}}, {{March 2024}})m4_dnl

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

@ -1,5 +1,5 @@
.TH "HLEDGER\-WEB" "1" "February 2024" "hledger-web-1.32.99 " "hledger User Manuals"
.TH "HLEDGER\-WEB" "1" "March 2024" "hledger-web-1.32.99 " "hledger User Manuals"
@ -128,6 +128,15 @@ 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 help options
.TP
\f[CR]\-h \-\-help\f[R]

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

@ -142,6 +142,15 @@ 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 help options::
@ -631,28 +640,28 @@ Tag Table:
Node: Top223
Node: OPTIONS2578
Ref: #options2683
Node: General help options5257
Ref: #general-help-options5407
Node: General input options5689
Ref: #general-input-options5875
Node: General reporting options6532
Ref: #general-reporting-options6697
Node: PERMISSIONS10087
Ref: #permissions10226
Node: EDITING UPLOADING DOWNLOADING11438
Ref: #editing-uploading-downloading11619
Node: RELOADING12453
Ref: #reloading12587
Node: JSON API13020
Ref: #json-api13135
Node: DEBUG OUTPUT18623
Ref: #debug-output18748
Node: Debug output18775
Ref: #debug-output-118876
Node: ENVIRONMENT19293
Ref: #environment19412
Node: BUGS19529
Ref: #bugs19613
Node: General help options5648
Ref: #general-help-options5798
Node: General input options6080
Ref: #general-input-options6266
Node: General reporting options6923
Ref: #general-reporting-options7088
Node: PERMISSIONS10478
Ref: #permissions10617
Node: EDITING UPLOADING DOWNLOADING11829
Ref: #editing-uploading-downloading12010
Node: RELOADING12844
Ref: #reloading12978
Node: JSON API13411
Ref: #json-api13526
Node: DEBUG OUTPUT19014
Ref: #debug-output19139
Node: Debug output19166
Ref: #debug-output-119267
Node: ENVIRONMENT19684
Ref: #environment19803
Node: BUGS19920
Ref: #bugs20004

End Tag Table

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

@ -113,6 +113,15 @@ OPTIONS
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 help options
-h --help
show general or COMMAND help
@ -133,7 +142,7 @@ OPTIONS
$LEDGER_FILE or $HOME/.hledger.journal)
--rules-file=RULESFILE
Conversion rules file to use when reading CSV (default:
Conversion rules file to use when reading CSV (default:
FILE.rules)
--separator=CHAR
@ -150,7 +159,7 @@ OPTIONS
assignments)
-s --strict
do extra error checking (check that all posted accounts are de-
do extra error checking (check that all posted accounts are de-
clared)
General reporting options
@ -178,7 +187,7 @@ OPTIONS
multiperiod/multicolumn report by year
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
set start date, end date, and/or reporting interval all at once
using period expressions syntax
--date2
@ -186,7 +195,7 @@ OPTIONS
fects)
--today=DATE
override today's date (affects relative smart dates, for
override today's date (affects relative smart dates, for
tests/examples)
-U --unmarked
@ -205,21 +214,21 @@ OPTIONS
hide/aggregate accounts or postings more than NUM levels deep
-E --empty
show items with zero amount, normally hidden (and vice-versa in
show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web)
-B --cost
convert amounts to their cost/selling amount at transaction time
-V --market
convert amounts to their market value in default valuation com-
convert amounts to their market value in default valuation com-
modities
-X --exchange=COMM
convert amounts to their market value in commodity COMM
--value
convert amounts to cost or market value, more flexibly than
convert amounts to cost or market value, more flexibly than
-B/-V/-X
--infer-equity
@ -229,38 +238,38 @@ OPTIONS
infer costs from conversion equity postings
--infer-market-prices
use costs as additional market prices, as if they were P direc-
use costs as additional market prices, as if they were P direc-
tives
--forecast
generate transactions from periodic rules, between the latest
recorded txn and 6 months from today, or during the specified
PERIOD (= is required). Auto posting rules will be applied to
these transactions as well. Also, in hledger-ui make fu-
generate transactions from periodic rules, between the latest
recorded txn and 6 months from today, or during the specified
PERIOD (= is required). Auto posting rules will be applied to
these transactions as well. Also, in hledger-ui make fu-
ture-dated transactions visible.
--auto generate extra postings by applying auto posting rules to all
--auto generate extra postings by applying auto posting rules to all
txns (not just forecast txns)
--verbose-tags
add visible tags indicating transactions or postings which have
add visible tags indicating transactions or postings which have
been generated/modified
--commodity-style
Override the commodity style in the output for the specified
Override the commodity style in the output for the specified
commodity. For example 'EUR1.000,00'.
--color=WHEN (or --colour=WHEN)
Should color-supporting commands use ANSI color codes in text
Should color-supporting commands use ANSI color codes in text
output. 'auto' (default): whenever stdout seems to be a
color-supporting terminal. 'always' or 'yes': always, useful eg
when piping output into 'less -R'. 'never' or 'no': never. A
when piping output into 'less -R'. 'never' or 'no': never. A
NO_COLOR environment variable overrides this.
--pretty[=WHEN]
Show prettier output, e.g. using unicode box-drawing charac-
ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
'never' also work). If you provide an argument you must use
Show prettier output, e.g. using unicode box-drawing charac-
ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
'never' also work). If you provide an argument you must use
'=', e.g. '--pretty=yes'.
When a reporting option appears more than once in the command line, the
@ -269,13 +278,13 @@ OPTIONS
Some reporting options can also be written as query arguments.
PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the
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.
You can restrict who can reach it by
o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local ma-
o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local ma-
chine.
o putting it behind an authenticating proxy, using eg apache or nginx
@ -285,44 +294,44 @@ PERMISSIONS
You can restrict what the users who reach it can do, by
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
one or more of the following capabilities. The default value is
one or more of the following capabilities. The default value is
view,add:
o view - allows viewing the journal file and all included files
o add - allows adding new transactions to the main journal file
o manage - allows editing, uploading or downloading the main or in-
o manage - allows editing, uploading or downloading the main or in-
cluded files
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING
If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it in-
If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it in-
cludes.
Note, unlike any other hledger command, in this mode you (or any visi-
Note, unlike any other hledger command, in this mode you (or any visi-
tor) can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.)
RELOADING
hledger-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change
edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message un-
til the file has been fixed.
@ -330,8 +339,8 @@ RELOADING
that both machine clocks are roughly in step.)
JSON API
In addition to the web UI, hledger-web also serves a JSON API that can
be used to get data or add new transactions. If you want the JSON API
In addition to the web UI, hledger-web also serves a JSON API that can
be used to get data or add new transactions. If you want the JSON API
only, you can use the --serve-api flag. Eg:
$ hledger-web -f examples/sample.journal --serve-api
@ -348,7 +357,7 @@ JSON API
/accounttransactions/ACCOUNTNAME
Eg, all account names in the journal (similar to the accounts command).
(hledger-web's JSON does not include newlines, here we use python to
(hledger-web's JSON does not include newlines, here we use python to
prettify it):
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
@ -389,25 +398,25 @@ JSON API
"aprice": null,
...
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-
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.
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
at the source for the appropriate handler to see what it returns. Eg
understand that, go to the Hledger.Web.Handler.MiscR haddock and look
at the source for the appropriate handler to see what it returns. Eg
for /accounttransactions it's getAccounttransactionsR, returning a "ac-
countTransactionsReport ...". Looking up the haddock for that we can
see that /accounttransactions returns an AccountTransactionsReport,
which consists of a report title and a list of AccountTransactionsRe-
countTransactionsReport ...". Looking up the haddock for that we can
see that /accounttransactions returns an AccountTransactionsReport,
which consists of a report title and a list of AccountTransactionsRe-
portItem (etc).
You can add a new transaction to the journal with a PUT request to
/add, if hledger-web was started with the add capability (enabled by
You can add a new transaction to the journal with a PUT request to
/add, if hledger-web was started with the add capability (enabled by
default). The payload must be the full, exact JSON representation of a
hledger transaction (partial data won't do). You can get sample JSON
from hledger-web's /transactions or /accounttransactions, or you can
hledger transaction (partial data won't do). You can get sample JSON
from hledger-web's /transactions or /accounttransactions, or you can
export it with hledger-lib, eg like so:
.../hledger$ stack ghci hledger-lib
@ -503,28 +512,28 @@ JSON API
"tstatus": "Unmarked"
}
And here's how to test adding it with curl. This should add a new en-
And here's how to test adding it with curl. This should add a new en-
try to your journal:
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
DEBUG OUTPUT
Debug output
You can add --debug[=N] to the command line to log debug output. N
You can add --debug[=N] to the command line to log debug output. N
ranges from 1 (least output, the default) to 9 (maximum output). Typi-
cally you would start with 1 and increase until you are seeing enough.
Debug output goes to stderr, interleaved with the requests logged on
cally you would start with 1 and increase until you are seeing enough.
Debug output goes to stderr, interleaved with the requests logged on
stdout. To capture debug output in a log file instead, you can usually
redirect stderr, eg:
hledger-web --debug=3 2>hledger-web.log.
ENVIRONMENT
LEDGER_FILE The main journal file to use when not specified with
LEDGER_FILE The main journal file to use when not specified with
-f/--file. Default: $HOME/.hledger.journal.
BUGS
We welcome bug reports in the hledger issue tracker (shortcut:
http://bugs.hledger.org), or on the #hledger chat or hledger mail list
http://bugs.hledger.org), or on the #hledger chat or hledger mail list
(https://hledger.org/support).
Some known issues:
@ -549,4 +558,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-web-1.32.99 February 2024 HLEDGER-WEB(1)
hledger-web-1.32.99 March 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_}}, {{February 2024}})m4_dnl
m4_define({{_monthyear_}}, {{March 2024}})m4_dnl

1368
hledger/hledger.1
View File

File diff suppressed because it is too large Load Diff

3192
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

2874
hledger/hledger.txt
View File

File diff suppressed because it is too large Load Diff