From cd5ff00a267b0c04831fa0e4bbfe3368da3dcd0b Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 26 Oct 2015 06:46:29 -0700 Subject: [PATCH] ui, web: man page updates --- hledger-ui/hledger-ui.1.md | 45 ++++++++++++++++++++++++++++++++++++ hledger-web/hledger-web.1.md | 35 +++++++++++++++++++++++----- 2 files changed, 74 insertions(+), 6 deletions(-) diff --git a/hledger-ui/hledger-ui.1.md b/hledger-ui/hledger-ui.1.md index a87445950..b8ec90e37 100644 --- a/hledger-ui/hledger-ui.1.md +++ b/hledger-ui/hledger-ui.1.md @@ -107,6 +107,51 @@ The following common hledger options should also work: `-B --cost` : show amounts in their cost price's commodity +# SCREENS + +Currently there are two: + +## Accounts screen + +This is the screen shown at startup by default. +It shows a scrollable list of accounts and their balances - all accounts, or just the matched accounts if you specified a query on the command line. +`f` toggles flat mode on and off. +You can limit the depth of accounts displayed, to reduce detail, by pressing `-` to reduce it. +`+` (or `=`) increases the depth limit again. +Or, press a number key to set a specific depth limit, eg `1` to see just top level accounts. +Use the cursor keys to move up or down, and cursor right (or enter) to view an account's transaction register. + +## Register screen + +This screen shows a register of transactions affecting a particular account - +all transactions, or just the matched ones if there was a query on the command line. + +You can reach the register screen by pressing cursor right or enter on +the accounts screen, or jump directly to it at startup by specifying +an account with `--register ACCTREGEX` on the command line. +The cursor left key returns to the accounts screen. + +The register screen shows transactions (like the register in +hledger-web, and other accounting systems), rather than postings +(like hledger's register command). This means: + +- It shows transactions affecting a selected current account, rather + than postings matching a pattern. Each line represents a whole transaction. + +- It lists the other account(s) involved in the transaction, in + abbreviated form. (As an exception, if both real and virtual + postings are involved, only the accounts affected by real postings + are listed.) + +- The amount field shows the overall effect of the transaction on the + current account; positive for an inflow to this account, negative + for an outflow. + +- (Not implemented yet: the balance field should usually show the + current account's historic balance as of the transaction date, even + if you have adjusted the report start date. Currently it always + shows the running total). + # ENVIRONMENT **LEDGER_FILE** diff --git a/hledger-web/hledger-web.1.md b/hledger-web/hledger-web.1.md index 1e0755548..1105a2ae4 100644 --- a/hledger-web/hledger-web.1.md +++ b/hledger-web/hledger-web.1.md @@ -18,12 +18,9 @@ using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1). hledger-web is hledger's web interface. It starts a simple web -application for browsing and adding transactions in a hledger journal -file, and also (unless started with --server) opens the app in a new -web browser window if possible, and exits after two minutes of -inactivity. - -hledger-web provides a more user-friendly UI than the hledger CLI or +application for browsing and adding transactions, and optionally +opens it in a web browser window if possible. +It provides a more user-friendly UI than the hledger CLI or hledger-ui interface, showing more at once (accounts, the current account register, balance charts) and allowing history-aware data entry, interactive searching, and bookmarking. @@ -37,6 +34,32 @@ the main journal file (only ?) on every edit. The journal file is `~/.hledger.journal`, `$LEDGER_FILE`, or another file specified with -f. For more about the format, see hledger(1) or hledger_journal(5). +By default, hledger-web starts the web app in "transient mode" and +also opens it in your default web browser if possible. In this mode +the web app will keep running for as long as you have it open in a +browser window, and will exit after two minutes of inactivity (no +requests and no browser windows viewing it). + +With `--server`, it starts the web app in non-transient mode and logs +requests to the console. Typically when running hledger web as part +of a website you'll want to use `--base-url` to set the +protocol/hostname/port/path to be used in hyperlinks. The +`--file-url` option allows static files to be served from a different +url, eg for better caching or cookie-less serving. + +You can use `--port` to listen on a different TCP port, eg if you are +running multiple hledger-web instances. This need not be the same as +the PORT in the base url. + +Note there is no built-in access control, so you will need to hide +hledger-web behind an authenticating proxy (such as apache or nginx) +if you want to restrict who can see and add entries to your journal. + +With journal and timelog files (but not CSV files, currently) +the web app detects changes and will show the new data on the next request. +If a change makes the file unparseable, hledger-web will show an error +until the file has been fixed. + # OPTIONS Note: if invoking hledger-web as a hledger subcommand, write `--` before options as shown above.