;doc: update embedded manuals
This commit is contained in:
Simon Michael
parent
af9822a60a
commit
2899b46c59
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{March 2025}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{June 2025}})m4_dnl
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{March 2025}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{June 2025}})m4_dnl
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER\-UI" "1" "March 2025" "hledger-ui-1.42.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER\-UI" "1" "June 2025" "hledger-ui-1.43.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.42.99.
|
||||
This manual is for hledger\[aq]s terminal interface, version 1.43.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
|
||||
@ -437,33 +437,51 @@ immediately without having to context switch.
|
||||
This leaves more mental bandwidth for your accounting.
|
||||
Of course you can still interact with hledger\-ui when needed, eg to
|
||||
toggle cleared mode, or to explore the history.
|
||||
.PP
|
||||
There are currently some limitations with \f[CR]\-\-watch\f[R]:
|
||||
.PP
|
||||
It may not work correctly for you, depending on platform or system
|
||||
.SS \-\-watch problems
|
||||
\f[I]However.\f[R] There are limitations/unresolved bugs with
|
||||
\f[CR]\-\-watch\f[R]:
|
||||
.IP \[bu] 2
|
||||
It may not work at all for you, depending on platform or system
|
||||
configuration.
|
||||
(Eg #836.)
|
||||
On some unix systems, increasing fs.inotify.max_user_watches or
|
||||
fs.file\-max parameters in /etc/sysctl.conf might help.
|
||||
(#836)
|
||||
.IP \[bu] 2
|
||||
It may not detect file changes made by certain tools, such as Jetbrains
|
||||
IDEs or gedit.
|
||||
(#1617)
|
||||
.IP \[bu] 2
|
||||
It may not detect changes made from outside a virtual machine, ie by an
|
||||
editor running on the host system.
|
||||
.IP \[bu] 2
|
||||
It may not detect file changes on certain less common filesystems.
|
||||
.IP \[bu] 2
|
||||
It may use increasing CPU and RAM over time, especially with large
|
||||
files.
|
||||
(This is probably not \-\-watch specific, you may be able to reproduce
|
||||
it by pressing \f[CR]g\f[R] repeatedly.)
|
||||
(#1825)
|
||||
.PP
|
||||
At least on mac, there can be a slow build\-up of CPU usage over time,
|
||||
until the program is restarted (or, suspending and restarting with
|
||||
\f[CR]CTRL\-z\f[R] \f[CR]fg\f[R] may be enough).
|
||||
.PP
|
||||
It will not detect file changes made by certain editors, such as
|
||||
Jetbrains IDEs or \f[CR]gedit\f[R], or on certain less common
|
||||
filesystems.
|
||||
(To work around, press \f[CR]g\f[R] to reload manually, or try
|
||||
#1617\[aq]s \f[CR]fs.inotify.max_user_watches\f[R] workaround and let us
|
||||
know.)
|
||||
.PP
|
||||
If you are viewing files mounted from another machine, the system clocks
|
||||
on both machines should be roughly in agreement.
|
||||
Tips/workarounds:
|
||||
.IP \[bu] 2
|
||||
If \-\-watch won\[aq]t work for you, press \f[CR]g\f[R] to reload data
|
||||
manually instead.
|
||||
.IP \[bu] 2
|
||||
If \-\-watch is leaking resources over time, quit and restart (or
|
||||
suspend and resume) hledger\-ui when you\[aq]re not using it.
|
||||
.IP \[bu] 2
|
||||
When running hledger\-ui inside a VM, also make file changes inside the
|
||||
VM.
|
||||
.IP \[bu] 2
|
||||
When working with files mounted from another machine, make sure the
|
||||
system clocks on both machines are roughly in agreement.
|
||||
.SH ENVIRONMENT
|
||||
\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified
|
||||
with \f[CR]\-f/\-\-file\f[R].
|
||||
Default: \f[CR]$HOME/.hledger.journal\f[R].
|
||||
.SH BUGS
|
||||
We welcome bug reports in the hledger issue tracker (shortcut:
|
||||
https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
We welcome bug reports in the hledger issue tracker
|
||||
(https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
(https://hledger.org/support).
|
||||
.PP
|
||||
Some known issues:
|
||||
@ -471,14 +489,15 @@ Some known issues:
|
||||
\f[CR]\-f\-\f[R] doesn\[aq]t work (hledger\-ui can\[aq]t read from
|
||||
stdin).
|
||||
.PP
|
||||
\f[CR]\-\-watch\f[R] is not robust, especially with large files (see
|
||||
WATCH MODE above).
|
||||
.PP
|
||||
The Transaction screen does not update after file changes, even if you
|
||||
press \f[CR]g\f[R], until you exit and re\-enter it.
|
||||
(#2288)
|
||||
.PP
|
||||
If you press \f[CR]g\f[R] with large files, there could be a noticeable
|
||||
pause.
|
||||
.PP
|
||||
The Transaction screen does not update from file changes until you exit
|
||||
and re\-endter it (see SCREENS > Transaction above).
|
||||
.PP
|
||||
\f[CR]\-\-watch\f[R] is not yet fully robust on all platforms (see Watch
|
||||
mode above).
|
||||
pause with the UI unresponsive.
|
||||
|
||||
|
||||
.SH AUTHORS
|
||||
|
||||
@ -18,7 +18,7 @@ plain text accounting app.
|
||||
or
|
||||
'hledger ui -- [OPTS] [QUERYARGS]'
|
||||
|
||||
This manual is for hledger's terminal interface, version 1.42.99.
|
||||
This manual is for hledger's terminal interface, version 1.43.99.
|
||||
See also the hledger manual for common concepts and file formats.
|
||||
|
||||
hledger is a robust, user-friendly, cross-platform set of programs
|
||||
@ -491,22 +491,41 @@ bandwidth for your accounting. Of course you can still interact with
|
||||
hledger-ui when needed, eg to toggle cleared mode, or to explore the
|
||||
history.
|
||||
|
||||
There are currently some limitations with '--watch':
|
||||
* Menu:
|
||||
|
||||
It may not work correctly for you, depending on platform or system
|
||||
configuration. (Eg #836.)
|
||||
* --watch problems::
|
||||
|
||||
At least on mac, there can be a slow build-up of CPU usage over time,
|
||||
until the program is restarted (or, suspending and restarting with
|
||||
'CTRL-z' 'fg' may be enough).
|
||||
|
||||
File: hledger-ui.info, Node: --watch problems, Up: WATCH MODE
|
||||
|
||||
It will not detect file changes made by certain editors, such as
|
||||
Jetbrains IDEs or 'gedit', or on certain less common filesystems. (To
|
||||
work around, press 'g' to reload manually, or try #1617's
|
||||
'fs.inotify.max_user_watches' workaround and let us know.)
|
||||
5.1 -watch problems
|
||||
===================
|
||||
|
||||
If you are viewing files mounted from another machine, the system
|
||||
clocks on both machines should be roughly in agreement.
|
||||
_However._ There are limitations/unresolved bugs with '--watch':
|
||||
|
||||
* It may not work at all for you, depending on platform or system
|
||||
configuration. On some unix systems, increasing
|
||||
fs.inotify.max_user_watches or fs.file-max parameters in
|
||||
/etc/sysctl.conf might help. (#836)
|
||||
* It may not detect file changes made by certain tools, such as
|
||||
Jetbrains IDEs or gedit. (#1617)
|
||||
* It may not detect changes made from outside a virtual machine, ie
|
||||
by an editor running on the host system.
|
||||
* It may not detect file changes on certain less common filesystems.
|
||||
* It may use increasing CPU and RAM over time, especially with large
|
||||
files. (This is probably not -watch specific, you may be able to
|
||||
reproduce it by pressing 'g' repeatedly.) (#1825)
|
||||
|
||||
Tips/workarounds:
|
||||
|
||||
* If -watch won't work for you, press 'g' to reload data manually
|
||||
instead.
|
||||
* If -watch is leaking resources over time, quit and restart (or
|
||||
suspend and resume) hledger-ui when you're not using it.
|
||||
* When running hledger-ui inside a VM, also make file changes inside
|
||||
the VM.
|
||||
* When working with files mounted from another machine, make sure the
|
||||
system clocks on both machines are roughly in agreement.
|
||||
|
||||
|
||||
File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: WATCH MODE, Up: Top
|
||||
@ -523,22 +542,23 @@ File: hledger-ui.info, Node: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
7 BUGS
|
||||
******
|
||||
|
||||
We welcome bug reports in the hledger issue tracker (shortcut:
|
||||
https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
We welcome bug reports in the hledger issue tracker
|
||||
(https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
(https://hledger.org/support).
|
||||
|
||||
Some known issues:
|
||||
|
||||
'-f-' doesn't work (hledger-ui can't read from stdin).
|
||||
|
||||
If you press 'g' with large files, there could be a noticeable pause.
|
||||
|
||||
The Transaction screen does not update from file changes until you
|
||||
exit and re-endter it (see SCREENS > Transaction above).
|
||||
|
||||
'--watch' is not yet fully robust on all platforms (see Watch mode
|
||||
'--watch' is not robust, especially with large files (see WATCH MODE
|
||||
above).
|
||||
|
||||
The Transaction screen does not update after file changes, even if
|
||||
you press 'g', until you exit and re-enter it. (#2288)
|
||||
|
||||
If you press 'g' with large files, there could be a noticeable pause
|
||||
with the UI unresponsive.
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top221
|
||||
@ -555,8 +575,9 @@ Node: Register screen16383
|
||||
Node: Transaction screen18826
|
||||
Node: Error screen20401
|
||||
Node: WATCH MODE20767
|
||||
Node: ENVIRONMENT22343
|
||||
Node: BUGS22576
|
||||
Node: --watch problems21665
|
||||
Node: ENVIRONMENT23018
|
||||
Node: BUGS23251
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@ SYNOPSIS
|
||||
hledger ui -- [OPTS] [QUERYARGS]
|
||||
|
||||
DESCRIPTION
|
||||
This manual is for hledger's terminal interface, version 1.42.99. See
|
||||
This manual is for hledger's terminal interface, version 1.43.99. See
|
||||
also the hledger manual for common concepts and file formats.
|
||||
|
||||
hledger is a robust, user-friendly, cross-platform set of programs for
|
||||
@ -394,44 +394,62 @@ WATCH MODE
|
||||
hledger-ui when needed, eg to toggle cleared mode, or to explore the
|
||||
history.
|
||||
|
||||
There are currently some limitations with --watch:
|
||||
--watch problems
|
||||
However. There are limitations/unresolved bugs with --watch:
|
||||
|
||||
It may not work correctly for you, depending on platform or system con-
|
||||
figuration. (Eg #836.)
|
||||
o It may not work at all for you, depending on platform or system con-
|
||||
figuration. On some unix systems, increasing fs.ino-
|
||||
tify.max_user_watches or fs.file-max parameters in /etc/sysctl.conf
|
||||
might help. (#836)
|
||||
|
||||
At least on mac, there can be a slow build-up of CPU usage over time,
|
||||
until the program is restarted (or, suspending and restarting with
|
||||
CTRL-z fg may be enough).
|
||||
o It may not detect file changes made by certain tools, such as Jet-
|
||||
brains IDEs or gedit. (#1617)
|
||||
|
||||
It will not detect file changes made by certain editors, such as Jet-
|
||||
brains IDEs or gedit, or on certain less common filesystems. (To work
|
||||
around, press g to reload manually, or try #1617's fs.ino-
|
||||
tify.max_user_watches workaround and let us know.)
|
||||
o It may not detect changes made from outside a virtual machine, ie by
|
||||
an editor running on the host system.
|
||||
|
||||
If you are viewing files mounted from another machine, the system
|
||||
clocks on both machines should be roughly in agreement.
|
||||
o It may not detect file changes on certain less common filesystems.
|
||||
|
||||
o It may use increasing CPU and RAM over time, especially with large
|
||||
files. (This is probably not --watch specific, you may be able to
|
||||
reproduce it by pressing g repeatedly.) (#1825)
|
||||
|
||||
Tips/workarounds:
|
||||
|
||||
o If --watch won't work for you, press g to reload data manually in-
|
||||
stead.
|
||||
|
||||
o If --watch is leaking resources over time, quit and restart (or sus-
|
||||
pend and resume) hledger-ui when you're not using it.
|
||||
|
||||
o When running hledger-ui inside a VM, also make file changes inside
|
||||
the VM.
|
||||
|
||||
o When working with files mounted from another machine, make sure the
|
||||
system clocks on both machines are roughly in agreement.
|
||||
|
||||
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:
|
||||
https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
We welcome bug reports in the hledger issue tracker
|
||||
(https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
(https://hledger.org/support).
|
||||
|
||||
Some known issues:
|
||||
|
||||
-f- doesn't work (hledger-ui can't read from stdin).
|
||||
|
||||
If you press g with large files, there could be a noticeable pause.
|
||||
|
||||
The Transaction screen does not update from file changes until you exit
|
||||
and re-endter it (see SCREENS > Transaction above).
|
||||
|
||||
--watch is not yet fully robust on all platforms (see Watch mode
|
||||
--watch is not robust, especially with large files (see WATCH MODE
|
||||
above).
|
||||
|
||||
The Transaction screen does not update after file changes, even if you
|
||||
press g, until you exit and re-enter it. (#2288)
|
||||
|
||||
If you press g with large files, there could be a noticeable pause with
|
||||
the UI unresponsive.
|
||||
|
||||
|
||||
|
||||
AUTHORS
|
||||
@ -450,4 +468,4 @@ LICENSE
|
||||
SEE ALSO
|
||||
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
|
||||
|
||||
hledger-ui-1.42.99 March 2025 HLEDGER-UI(1)
|
||||
hledger-ui-1.43.99 June 2025 HLEDGER-UI(1)
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{March 2025}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{June 2025}})m4_dnl
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER\-WEB" "1" "March 2025" "hledger-web-1.42.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER\-WEB" "1" "June 2025" "hledger-web-1.43.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.42.99.
|
||||
This manual is for hledger\[aq]s web interface, version 1.43.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
|
||||
@ -220,38 +220,33 @@ If this is not working see Install > Shell completions.
|
||||
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.
|
||||
.PP
|
||||
You can restrict who can reach it by
|
||||
You can restrict who can reach it, by
|
||||
.IP \[bu] 2
|
||||
setting the IP address it listens on (see \f[CR]\-\-host\f[R] above).
|
||||
By default it listens on 127.0.0.1, accessible to all users on the local
|
||||
machine.
|
||||
By default it listens on 127.0.0.1, accessible to users on the local
|
||||
machine only.
|
||||
.IP \[bu] 2
|
||||
putting it behind an authenticating proxy, using eg apache or nginx
|
||||
putting it behind an authenticating proxy, such as caddy or apache
|
||||
.IP \[bu] 2
|
||||
custom firewall rules
|
||||
putting it behind a firewall
|
||||
.PP
|
||||
You can restrict what the users who reach it can do, by
|
||||
And you can restrict what the users reaching it can do, by specifying
|
||||
the \f[CR]\-\-allow=ACCESSLEVEL\f[R] option at startup.
|
||||
ACCESSLEVEL is one of:
|
||||
.IP \[bu] 2
|
||||
using the \f[CR]\-\-capabilities=CAP[,CAP..]\f[R] flag when you start
|
||||
it, enabling one or more of the following capabilities.
|
||||
The default value is \f[CR]view,add\f[R]:
|
||||
.RS 2
|
||||
\f[CR]view\f[R] \- allows viewing the journal file(s)
|
||||
.IP \[bu] 2
|
||||
\f[CR]view\f[R] \- allows viewing the journal file and all included
|
||||
files
|
||||
\f[CR]add\f[R] \- also allows adding new transactions to the main
|
||||
journal file
|
||||
.IP \[bu] 2
|
||||
\f[CR]add\f[R] \- allows adding new transactions to the main journal
|
||||
file
|
||||
\f[CR]edit\f[R] \- also allows editing, uploading or downloading the
|
||||
journal file(s)
|
||||
.IP \[bu] 2
|
||||
\f[CR]manage\f[R] \- allows editing, uploading or downloading the main
|
||||
or included files
|
||||
.RE
|
||||
.IP \[bu] 2
|
||||
using the \f[CR]\-\-capabilities\-header=HTTPHEADER\f[R] 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\[aq]s permissions.
|
||||
This is disabled by default.
|
||||
\f[CR]sandstorm\f[R] \- (for the hledger\-web Sandstorm app:) allows
|
||||
whichever of \f[CR]view\f[R], \f[CR]add\f[R], or \f[CR]edit\f[R] are
|
||||
specified in the \f[CR]X\-Sandstorm\-Permissions\f[R] HTTP header
|
||||
.PP
|
||||
The default access level is \f[CR]add\f[R].
|
||||
.SH EDITING, UPLOADING, DOWNLOADING
|
||||
If you enable the \f[CR]manage\f[R] capability mentioned above,
|
||||
you\[aq]ll see a new \[dq]spanner\[dq] button to the right of the search
|
||||
@ -500,8 +495,8 @@ stderr, eg:
|
||||
with \f[CR]\-f/\-\-file\f[R].
|
||||
Default: \f[CR]$HOME/.hledger.journal\f[R].
|
||||
.SH BUGS
|
||||
We welcome bug reports in the hledger issue tracker (shortcut:
|
||||
https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
We welcome bug reports in the hledger issue tracker
|
||||
(https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
(https://hledger.org/support).
|
||||
.PP
|
||||
Some known issues:
|
||||
|
||||
@ -18,7 +18,7 @@ plain text accounting app.
|
||||
or
|
||||
'hledger web -- [OPTS] [QUERY]'
|
||||
|
||||
This manual is for hledger's web interface, version 1.42.99. See
|
||||
This manual is for hledger's web interface, version 1.43.99. See
|
||||
also the hledger manual for common concepts and file formats.
|
||||
|
||||
hledger is a robust, user-friendly, cross-platform set of programs
|
||||
@ -229,30 +229,27 @@ File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING
|
||||
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
|
||||
You can restrict who can reach it, by
|
||||
|
||||
* 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 machine.
|
||||
* putting it behind an authenticating proxy, using eg apache or nginx
|
||||
* custom firewall rules
|
||||
default it listens on 127.0.0.1, accessible to users on the local
|
||||
machine only.
|
||||
* putting it behind an authenticating proxy, such as caddy or apache
|
||||
* putting it behind a firewall
|
||||
|
||||
You can restrict what the users who reach it can do, by
|
||||
And you can restrict what the users reaching it can do, by specifying
|
||||
the '--allow=ACCESSLEVEL' option at startup. ACCESSLEVEL is one of:
|
||||
|
||||
* using the '--capabilities=CAP[,CAP..]' flag when you start it,
|
||||
enabling one or more of the following capabilities. The default
|
||||
value is 'view,add':
|
||||
* 'view' - allows viewing the journal file and all included
|
||||
files
|
||||
* 'add' - allows adding new transactions to the main journal
|
||||
file
|
||||
* 'manage' - allows editing, uploading or downloading the main
|
||||
or included files
|
||||
* 'view' - allows viewing the journal file(s)
|
||||
* 'add' - also allows adding new transactions to the main journal
|
||||
file
|
||||
* 'edit' - also allows editing, uploading or downloading the journal
|
||||
file(s)
|
||||
* 'sandstorm' - (for the hledger-web Sandstorm app:) allows whichever
|
||||
of 'view', 'add', or 'edit' are specified in the
|
||||
'X-Sandstorm-Permissions' HTTP header
|
||||
|
||||
* 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.
|
||||
The default access level is 'add'.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top
|
||||
@ -517,8 +514,8 @@ File: hledger-web.info, Node: BUGS, Prev: ENVIRONMENT, Up: Top
|
||||
8 BUGS
|
||||
******
|
||||
|
||||
We welcome bug reports in the hledger issue tracker (shortcut:
|
||||
https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
We welcome bug reports in the hledger issue tracker
|
||||
(https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
(https://hledger.org/support).
|
||||
|
||||
Some known issues:
|
||||
@ -530,13 +527,13 @@ Tag Table:
|
||||
Node: Top223
|
||||
Node: OPTIONS2581
|
||||
Node: PERMISSIONS11270
|
||||
Node: EDITING UPLOADING DOWNLOADING12621
|
||||
Node: RELOADING13636
|
||||
Node: JSON API14203
|
||||
Node: DEBUG OUTPUT19852
|
||||
Node: Debug output20004
|
||||
Node: ENVIRONMENT20522
|
||||
Node: BUGS20758
|
||||
Node: EDITING UPLOADING DOWNLOADING12420
|
||||
Node: RELOADING13435
|
||||
Node: JSON API14002
|
||||
Node: DEBUG OUTPUT19651
|
||||
Node: Debug output19803
|
||||
Node: ENVIRONMENT20321
|
||||
Node: BUGS20557
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@ SYNOPSIS
|
||||
hledger web -- [OPTS] [QUERY]
|
||||
|
||||
DESCRIPTION
|
||||
This manual is for hledger's web interface, version 1.42.99. See also
|
||||
This manual is for hledger's web interface, version 1.43.99. See also
|
||||
the hledger manual for common concepts and file formats.
|
||||
|
||||
hledger is a robust, user-friendly, cross-platform set of programs for
|
||||
@ -201,57 +201,55 @@ 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.
|
||||
|
||||
You can restrict who can reach it by
|
||||
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-
|
||||
chine.
|
||||
it listens on 127.0.0.1, accessible to users on the local machine
|
||||
only.
|
||||
|
||||
o putting it behind an authenticating proxy, using eg apache or nginx
|
||||
o putting it behind an authenticating proxy, such as caddy or apache
|
||||
|
||||
o custom firewall rules
|
||||
o putting it behind a firewall
|
||||
|
||||
You can restrict what the users who reach it can do, by
|
||||
And you can restrict what the users reaching it can do, by specifying
|
||||
the --allow=ACCESSLEVEL option at startup. ACCESSLEVEL is one of:
|
||||
|
||||
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
|
||||
one or more of the following capabilities. The default value is
|
||||
view,add:
|
||||
o view - allows viewing the journal file(s)
|
||||
|
||||
o view - allows viewing the journal file and all included files
|
||||
o add - also allows adding new transactions to the main journal file
|
||||
|
||||
o add - allows adding new transactions to the main journal file
|
||||
o edit - also allows editing, uploading or downloading the journal
|
||||
file(s)
|
||||
|
||||
o manage - allows editing, uploading or downloading the main or in-
|
||||
cluded files
|
||||
o sandstorm - (for the hledger-web Sandstorm app:) allows whichever of
|
||||
view, add, or edit are specified in the X-Sandstorm-Permissions HTTP
|
||||
header
|
||||
|
||||
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.
|
||||
The default access level is add.
|
||||
|
||||
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.
|
||||
|
||||
@ -259,8 +257,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
|
||||
@ -277,7 +275,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
|
||||
@ -318,26 +316,26 @@ 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. 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
|
||||
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
|
||||
@ -433,28 +431,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:
|
||||
https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
We welcome bug reports in the hledger issue tracker
|
||||
(https://bugs.hledger.org), or on the hledger chat or mail list
|
||||
(https://hledger.org/support).
|
||||
|
||||
Some known issues:
|
||||
@ -479,4 +477,4 @@ LICENSE
|
||||
SEE ALSO
|
||||
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
|
||||
|
||||
hledger-web-1.42.99 March 2025 HLEDGER-WEB(1)
|
||||
hledger-web-1.43.99 June 2025 HLEDGER-WEB(1)
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{March 2025}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{June 2025}})m4_dnl
|
||||
|
||||
1027
hledger/hledger.1
1027
hledger/hledger.1
File diff suppressed because it is too large
Load Diff
1698
hledger/hledger.info
1698
hledger/hledger.info
File diff suppressed because it is too large
Load Diff
2885
hledger/hledger.txt
2885
hledger/hledger.txt
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user