From 1969a42a72efe4ab8e496d338ab975e3ddc36cf8 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 24 Jan 2019 15:42:23 -0800 Subject: [PATCH] doc: ui: fix bullet list [ci skip] --- hledger-ui/hledger-ui.1 | 13 ++- hledger-ui/hledger-ui.info | 38 ++++--- hledger-ui/hledger-ui.m4.md | 4 +- hledger-ui/hledger-ui.txt | 217 ++++++++++++++++++------------------ 4 files changed, 139 insertions(+), 133 deletions(-) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 0991dd001..838bdb48f 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -26,12 +26,13 @@ and some limited data entry capability. It is easier than hledger\[aq]s command\-line interface, and sometimes quicker and more convenient than the web interface. .PP -Note hledger\-ui has some different defaults: \- it generates -rule\-based transactions and postings by default (\-\-forecast and -\-\-auto are always on). -\- it hides transactions dated in the future by default (change this -with \-\-future or the F key). -Experimental. +Note hledger\-ui has some different defaults (experimental): +.IP \[bu] 2 +it generates rule\-based transactions and postings by default +(\-\-forecast and \-\-auto are always on). +.IP \[bu] 2 +it hides transactions dated in the future by default (change this with +\-\-future or the F key). .PP Like hledger, it reads data from one or more files in hledger journal, timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index b5ddfa286..e1edd0d4a 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -12,10 +12,12 @@ limited data entry capability. It is easier than hledger's command-line interface, and sometimes quicker and more convenient than the web interface. - Note hledger-ui has some different defaults: - it generates -rule-based transactions and postings by default (-forecast and -auto are -always on). - it hides transactions dated in the future by default -(change this with -future or the F key). Experimental. + Note hledger-ui has some different defaults (experimental): + + * it generates rule-based transactions and postings by default + (-forecast and -auto are always on). + * it hides transactions dated in the future by default (change this + with -future or the F key). Like hledger, it reads data from one or more files in hledger journal, timeclock, timedot, or CSV format specified with '-f', or @@ -396,19 +398,19 @@ to cancel the reload attempt.)  Tag Table: Node: Top71 -Node: OPTIONS1090 -Ref: #options1187 -Node: KEYS4606 -Ref: #keys4701 -Node: SCREENS7957 -Ref: #screens8042 -Node: Accounts screen8132 -Ref: #accounts-screen8260 -Node: Register screen10476 -Ref: #register-screen10631 -Node: Transaction screen12628 -Ref: #transaction-screen12786 -Node: Error screen13656 -Ref: #error-screen13778 +Node: OPTIONS1106 +Ref: #options1203 +Node: KEYS4622 +Ref: #keys4717 +Node: SCREENS7973 +Ref: #screens8058 +Node: Accounts screen8148 +Ref: #accounts-screen8276 +Node: Register screen10492 +Ref: #register-screen10647 +Node: Transaction screen12644 +Ref: #transaction-screen12802 +Node: Error screen13672 +Ref: #error-screen13794  End Tag Table diff --git a/hledger-ui/hledger-ui.m4.md b/hledger-ui/hledger-ui.m4.md index 7c17a1d71..3f637475d 100644 --- a/hledger-ui/hledger-ui.m4.md +++ b/hledger-ui/hledger-ui.m4.md @@ -45,10 +45,10 @@ for viewing accounts and transactions, and some limited data entry capability. It is easier than hledger's command-line interface, and sometimes quicker and more convenient than the web interface. -Note hledger-ui has some different defaults: +Note hledger-ui has some different defaults (experimental): + - it generates rule-based transactions and postings by default (--forecast and --auto are always on). - it hides transactions dated in the future by default (change this with --future or the F key). -Experimental. Like hledger, it reads _files_ For more about this see hledger(1), hledger_journal(5) etc. diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index cd92cb90d..2853ccaf1 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -22,22 +22,25 @@ DESCRIPTION mand-line interface, and sometimes quicker and more convenient than the web interface. - Note hledger-ui has some different defaults: - it generates rule-based - transactions and postings by default (--forecast and --auto are always - on). - it hides transactions dated in the future by default (change - this with --future or the F key). Experimental. + Note hledger-ui has some different defaults (experimental): - Like hledger, it reads data from one or more files in hledger journal, - timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, - or $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). For more about this see hledger(1), + o it generates rule-based transactions and postings by default (--fore- + cast and --auto are always on). + + o it hides transactions dated in the future by default (change this + with --future or the F key). + + Like hledger, it reads data from one or more files in hledger journal, + timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, + or $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). For more about this see hledger(1), hledger_journal(5) etc. OPTIONS - Note: if invoking hledger-ui as a hledger subcommand, write -- before + Note: if invoking hledger-ui as a hledger subcommand, write -- before options as shown above. - Any QUERYARGS are interpreted as a hledger search query which filters + Any QUERYARGS are interpreted as a hledger search query which filters the data. --watch @@ -50,7 +53,7 @@ OPTIONS start in the (first) matched account's register screen --change - show period balances (changes) at startup instead of historical + show period balances (changes) at startup instead of historical balances -F --flat @@ -69,7 +72,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 @@ -110,11 +113,11 @@ 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 (overrides the flags above) --date2 - match the secondary date instead (see command help for other + match the secondary date instead (see command help for other effects) -U --unmarked @@ -133,21 +136,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 at transaction time (using the + convert amounts to their cost at transaction time (using the transaction price, if any) -V --value - convert amounts to their market value on the report end date + convert amounts to their market value on the report end date (using the most recent applicable market price, if any) --auto apply automated posting rules to modify transactions. --forecast - apply periodic transaction rules to generate future transac- + apply periodic transaction rules to generate future transac- tions, to 6 months from now or report end date. When a reporting option appears more than once in the command line, the @@ -167,70 +170,70 @@ OPTIONS show debug output (levels 1-9, default: 1) A @FILE argument will be expanded to the contents of FILE, which should - contain one command line option/argument per line. (To prevent this, + contain one command line option/argument per line. (To prevent this, insert a -- argument before.) KEYS - ? shows a help dialog listing all keys. (Some of these also appear in + ? shows a help dialog listing all keys. (Some of these also appear in the quick help at the bottom of each screen.) Press ? again (or ESCAPE, or LEFT) to close it. The following keys work on most screens: The cursor keys navigate: right (or enter) goes deeper, left returns to - the previous screen, up/down/page up/page down/home/end move up and - down through lists. Vi-style (h/j/k/l) and Emacs-style + the previous screen, up/down/page up/page down/home/end move up and + down through lists. Vi-style (h/j/k/l) and Emacs-style (CTRL-p/CTRL-n/CTRL-f/CTRL-b) movement keys are also supported. A tip: - movement speed is limited by your keyboard repeat rate, to move faster - you may want to adjust it. (If you're on a mac, the Karabiner app is + movement speed is limited by your keyboard repeat rate, to move faster + you may want to adjust it. (If you're on a mac, the Karabiner app is one way to do that.) - With shift pressed, the cursor keys adjust the report period, limiting - the transactions to be shown (by default, all are shown). - shift-down/up steps downward and upward through these standard report + With shift pressed, the cursor keys adjust the report period, limiting + the transactions to be shown (by default, all are shown). + shift-down/up steps downward and upward through these standard report period durations: year, quarter, month, week, day. Then, - shift-left/right moves to the previous/next period. t sets the report - period to today. With the --watch option, when viewing a "current" - period (the current day, week, month, quarter, or year), the period - will move automatically to track the current date. To set a non-stan- + shift-left/right moves to the previous/next period. t sets the report + period to today. With the --watch option, when viewing a "current" + period (the current day, week, month, quarter, or year), the period + will move automatically to track the current date. To set a non-stan- dard period, you can use / and a date: query. - / lets you set a general filter query limiting the data shown, using - the same query terms as in hledger and hledger-web. While editing the - query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set + / lets you set a general filter query limiting the data shown, using + the same query terms as in hledger and hledger-web. While editing the + query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set it, or ESCAPEto cancel. There are also keys for quickly adjusting some - common filters like account depth and transaction status (see below). + common filters like account depth and transaction status (see below). BACKSPACE or DELETE removes all filters, showing all transactions. - As mentioned above, hledger-ui shows auto-generated periodic transac- + As mentioned above, hledger-ui shows auto-generated periodic transac- tions, and hides future transactions (auto-generated or not) by default. F toggles showing and hiding these future transactions. This - is similar to using a query like date:-tomorrow, but more convenient. + is similar to using a query like date:-tomorrow, but more convenient. (experimental) - ESCAPE removes all filters and jumps back to the top screen. Or, it + ESCAPE removes all filters and jumps back to the top screen. Or, it cancels a minibuffer edit or help dialog in progress. CTRL-l redraws the screen and centers the selection if possible (selec- - tions near the top won't be centered, since we don't scroll above the + tions near the top won't be centered, since we don't scroll above the top). - g reloads from the data file(s) and updates the current screen and any - previous screens. (With large files, this could cause a noticeable + g reloads from the data file(s) and updates the current screen and any + previous screens. (With large files, this could cause a noticeable pause.) - I toggles balance assertion checking. Disabling balance assertions + I toggles balance assertion checking. Disabling balance assertions temporarily can be useful for troubleshooting. - a runs command-line hledger's add command, and reloads the updated + a runs command-line hledger's add command, and reloads the updated file. This allows some basic data entry. - A is like a, but runs the hledger-iadd tool, which provides a - curses-style interface. This key will be available if hledger-iadd is + A is like a, but runs the hledger-iadd tool, which provides a + curses-style interface. This key will be available if hledger-iadd is installed in $PATH. - E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac- + E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac- sclient -a "" -nw) on the journal file. With some editors (emacs, vi), - the cursor will be positioned at the current transaction when invoked - from the register and transaction screens, and at the error location + the cursor will be positioned at the current transaction when invoked + from the register and transaction screens, and at the error location (if possible) when invoked from the error screen. q quits the application. @@ -239,44 +242,44 @@ KEYS SCREENS Accounts screen - This is normally the first screen displayed. It lists accounts and - their balances, like hledger's balance command. By default, it shows - all accounts and their latest ending balances (including the balances - of subaccounts). if you specify a query on the command line, it shows + This is normally the first screen displayed. It lists accounts and + their balances, like hledger's balance command. By default, it shows + all accounts and their latest ending balances (including the balances + of subaccounts). if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. - Account names are shown as a flat list by default. Press T to toggle - tree mode. In flat mode, account balances are exclusive of subac- - counts, except where subaccounts are hidden by a depth limit (see - below). In tree mode, all account balances are inclusive of subac- + Account names are shown as a flat list by default. Press T to toggle + tree mode. In flat mode, account balances are exclusive of subac- + counts, except where subaccounts are hidden by a depth limit (see + below). In tree mode, all account balances are inclusive of subac- counts. - To see less detail, press a number key, 1 to 9, to set a depth limit. + To see less detail, press a number key, 1 to 9, to set a depth limit. Or use - to decrease and +/= to increase the depth limit. 0 shows even - less detail, collapsing all accounts to a single total. To remove the - depth limit, set it higher than the maximum account depth, or press + less detail, collapsing all accounts to a single total. To remove the + depth limit, set it higher than the maximum account depth, or press ESCAPE. H toggles between showing historical balances or period balances. His- - torical balances (the default) are ending balances at the end of the - report period, taking into account all transactions before that date - (filtered by the filter query if any), including transactions before - the start of the report period. In other words, historical balances - are what you would see on a bank statement for that account (unless - disturbed by a filter query). Period balances ignore transactions + torical balances (the default) are ending balances at the end of the + report period, taking into account all transactions before that date + (filtered by the filter query if any), including transactions before + the start of the report period. In other words, historical balances + are what you would see on a bank statement for that account (unless + disturbed by a filter query). Period balances ignore transactions before the report start date, so they show the change in balance during the report period. They are more useful eg when viewing a time log. U toggles filtering by unmarked status, including or excluding unmarked postings in the balances. Similarly, P toggles pending postings, and C - toggles cleared postings. (By default, balances include all postings; - if you activate one or two status filters, only those postings are + toggles cleared postings. (By default, balances include all postings; + if you activate one or two status filters, only those postings are included; and if you activate all three, the filter is removed.) R toggles real mode, in which virtual postings are ignored. - Z toggles nonzero mode, in which only accounts with nonzero balances - are shown (hledger-ui shows zero items by default, unlike command-line + Z toggles nonzero mode, in which only accounts with nonzero balances + are shown (hledger-ui shows zero items by default, unlike command-line hledger). Press right or enter to view an account's transactions register. @@ -285,64 +288,64 @@ SCREENS This screen shows the transactions affecting a particular account, like a check register. Each line represents one transaction and shows: - o the other account(s) involved, in abbreviated form. (If there are - both real and virtual postings, it shows only the accounts affected + o the other account(s) involved, in abbreviated form. (If there are + both real and virtual postings, it shows only the accounts affected by real postings.) - o the overall change to the current account's balance; positive for an + o the overall change to the current account's balance; positive for an inflow to this account, negative for an outflow. o the running historical total or period total for the current account, - after the transaction. This can be toggled with H. Similar to the - accounts screen, the historical total is affected by transactions - (filtered by the filter query) before the report start date, while + after the transaction. This can be toggled with H. Similar to the + accounts screen, the historical total is affected by transactions + (filtered by the filter query) before the report start date, while the period total is not. If the historical total is not disturbed by - a filter query, it will be the running historical balance you would + a filter query, it will be the running historical balance you would see on a bank register for the current account. - Transactions affecting this account's subaccounts will be included in + Transactions affecting this account's subaccounts will be included in the register if the accounts screen is in tree mode, or if it's in flat - mode but this account has subaccounts which are not shown due to a - depth limit. In other words, the register always shows the transac- + mode but this account has subaccounts which are not shown due to a + depth limit. In other words, the register always shows the transac- tions contributing to the balance shown on the accounts screen. Tree mode/flat mode can be toggled with T here also. - U toggles filtering by unmarked status, showing or hiding unmarked + U toggles filtering by unmarked status, showing or hiding unmarked transactions. Similarly, P toggles pending transactions, and C toggles - cleared transactions. (By default, transactions with all statuses are - shown; if you activate one or two status filters, only those transac- - tions are shown; and if you activate all three, the filter is + cleared transactions. (By default, transactions with all statuses are + shown; if you activate one or two status filters, only those transac- + tions are shown; and if you activate all three, the filter is removed.)q R toggles real mode, in which virtual postings are ignored. - Z toggles nonzero mode, in which only transactions posting a nonzero - change are shown (hledger-ui shows zero items by default, unlike com- + Z toggles nonzero mode, in which only transactions posting a nonzero + change are shown (hledger-ui shows zero items by default, unlike com- mand-line hledger). Press right (or enter) to view the selected transaction in detail. Transaction screen - This screen shows a single transaction, as a general journal entry, - similar to hledger's print command and journal format (hledger_jour- + This screen shows a single transaction, as a general journal entry, + similar to hledger's print command and journal format (hledger_jour- nal(5)). - The transaction's date(s) and any cleared flag, transaction code, - description, comments, along with all of its account postings are - shown. Simple transactions have two postings, but there can be more + The transaction's date(s) and any cleared flag, transaction code, + description, comments, along with all of its account postings are + shown. Simple transactions have two postings, but there can be more (or in certain cases, fewer). - up and down will step through all transactions listed in the previous - account register screen. In the title bar, the numbers in parentheses - show your position within that account register. They will vary + up and down will step through all transactions listed in the previous + account register screen. In the title bar, the numbers in parentheses + show your position within that account register. They will vary depending on which account register you came from (remember most trans- actions appear in multiple account registers). The #N number preceding them is the transaction's position within the complete unfiltered jour- nal, which is a more stable id (at least until the next reload). Error screen - This screen will appear if there is a problem, such as a parse error, - when you press g to reload. Once you have fixed the problem, press g + This screen will appear if there is a problem, such as a parse error, + 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.) @@ -350,17 +353,17 @@ ENVIRONMENT COLUMNS The screen width to use. Default: the full terminal width. LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). BUGS - The need to precede options with -- when invoked from hledger is awk- + The need to precede options with -- when invoked from hledger is awk- ward. -f- doesn't work (hledger-ui can't read from stdin). @@ -368,13 +371,13 @@ BUGS -V affects only the accounts screen. When you press g, the current and all previous screens are regenerated, - which may cause a noticeable pause with large files. Also there is no + which may cause a noticeable pause with large files. Also there is no visual indication that this is in progress. - --watch is not yet fully robust. It works well for normal usage, but - many file changes in a short time (eg saving the file thousands of - times with an editor macro) can cause problems at least on OSX. Symp- - toms include: unresponsive UI, periodic resetting of the cursor posi- + --watch is not yet fully robust. It works well for normal usage, but + many file changes in a short time (eg saving the file thousands of + times with an editor macro) can cause problems at least on OSX. Symp- + toms include: unresponsive UI, periodic resetting of the cursor posi- tion, momentary display of parse errors, high CPU usage eventually sub- siding, and possibly a small but persistent build-up of CPU usage until the program is restarted. @@ -382,7 +385,7 @@ BUGS REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -396,7 +399,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1)