From 6e5c30ea1a919ada651f5a27a43838abe9a7513f Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 7 Nov 2022 16:18:28 -1000 Subject: [PATCH] ;doc: update manuals --- hledger-ui/hledger-ui.1 | 30 +++++- hledger-ui/hledger-ui.info | 97 +++++++++++------- hledger-ui/hledger-ui.txt | 205 ++++++++++++++++++++----------------- 3 files changed, 198 insertions(+), 134 deletions(-) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 1de69e425..91d2acede 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -53,6 +53,18 @@ watch for data and date changes and reload automatically \f[B]\f[CB]--theme=default|terminal|greenterm\f[B]\f[R] use this custom display theme .TP +\f[B]\f[CB]--menu\f[B]\f[R] +start in the menu screen +.TP +\f[B]\f[CB]--all\f[B]\f[R] +start in the all accounts screen +.TP +\f[B]\f[CB]--bs\f[B]\f[R] +start in the balance sheet accounts screen +.TP +\f[B]\f[CB]--is\f[B]\f[R] +start in the income statement accounts screen +.TP \f[B]\f[CB]--register=ACCTREGEX\f[B]\f[R] start in the (first) matched account\[aq]s register screen .TP @@ -335,6 +347,17 @@ reliably reset to normal mode. .PP Additional screen-specific keys are described below. .SH SCREENS +.PP +hledger-ui can show a number of different screens, described below. +It shows the Balance sheet accounts screen to start with, except in the +following situations: +.IP \[bu] 2 +If no asset/liability/equity accounts can be detected, or if an account +query has been given on the command line, it starts in the All accounts +screen. +.IP \[bu] 2 +If a starting screen is specified with --menu/--all/--bs/--is/--register +on the command line, it starts there. .SS Menu screen .PP The top-most screen. @@ -343,14 +366,13 @@ to navigate to it. From here you can navigate to three accounts screens: .SS All accounts screen .PP -This screen shows all accounts (unless filtered by a query), and their +This screen shows all accounts (possibly filtered by a query), and their current balances. It is like the \f[C]hledger balance\f[R] command. .SS Balance sheet accounts screen .PP -This is the screen normally shown at startup. -It shows asset, liability and equity accounts, if these can be detected -(see account types). +This screen shows asset, liability and equity accounts, if these can be +detected (see account types). It always shows historical end balances on some date (not balance changes). It is like the \f[C]hledger balancesheetequity\f[R] command. diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index 058710185..43650aa2c 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -68,6 +68,18 @@ the data. '--theme=default|terminal|greenterm' use this custom display theme +'--menu' + + start in the menu screen +'--all' + + start in the all accounts screen +'--bs' + + start in the balance sheet accounts screen +'--is' + + start in the income statement accounts screen '--register=ACCTREGEX' start in the (first) matched account's register screen @@ -352,6 +364,17 @@ File: hledger-ui.info, Node: SCREENS, Next: TIPS, Prev: KEYS, Up: Top 4 SCREENS ********* +hledger-ui can show a number of different screens, described below. It +shows the Balance sheet accounts screen to start with, except in the +following situations: + + * If no asset/liability/equity accounts can be detected, or if an + account query has been given on the command line, it starts in the + All accounts screen. + + * If a starting screen is specified with -menu/-all/-bs/-is/-register + on the command line, it starts there. + * Menu: * Menu screen:: @@ -378,7 +401,7 @@ File: hledger-ui.info, Node: All accounts screen, Next: Balance sheet accounts 4.2 All accounts screen ======================= -This screen shows all accounts (unless filtered by a query), and their +This screen shows all accounts (possibly filtered by a query), and their current balances. It is like the 'hledger balance' command.  @@ -387,10 +410,10 @@ File: hledger-ui.info, Node: Balance sheet accounts screen, Next: Income state 4.3 Balance sheet accounts screen ================================= -This is the screen normally shown at startup. It shows asset, liability -and equity accounts, if these can be detected (see account types). It -always shows historical end balances on some date (not balance changes). -It is like the 'hledger balancesheetequity' command. +This screen shows asset, liability and equity accounts, if these can be +detected (see account types). It always shows historical end balances +on some date (not balance changes). It is like the 'hledger +balancesheetequity' command.  File: hledger-ui.info, Node: Income statement accounts screen, Next: Register screen, Prev: Balance sheet accounts screen, Up: SCREENS @@ -676,38 +699,38 @@ Tag Table: Node: Top221 Node: OPTIONS1657 Ref: #options1755 -Node: MOUSE6637 -Ref: #mouse6732 -Node: KEYS7014 -Ref: #keys7107 -Node: SCREENS11193 -Ref: #screens11291 -Node: Menu screen11472 -Ref: #menu-screen11592 -Node: All accounts screen11761 -Ref: #all-accounts-screen11935 -Node: Balance sheet accounts screen12068 -Ref: #balance-sheet-accounts-screen12283 -Node: Income statement accounts screen12554 -Ref: #income-statement-accounts-screen12771 -Node: Register screen15216 -Ref: #register-screen15388 -Node: Transaction screen17372 -Ref: #transaction-screen17530 -Node: Error screen18400 -Ref: #error-screen18522 -Node: TIPS18766 -Ref: #tips18865 -Node: Watch mode18907 -Ref: #watch-mode19014 -Node: Debug output20470 -Ref: #debug-output20581 -Node: ENVIRONMENT20793 -Ref: #environment20904 -Node: FILES22289 -Ref: #files22388 -Node: BUGS22601 -Ref: #bugs22678 +Node: MOUSE6839 +Ref: #mouse6934 +Node: KEYS7216 +Ref: #keys7309 +Node: SCREENS11395 +Ref: #screens11493 +Node: Menu screen12123 +Ref: #menu-screen12243 +Node: All accounts screen12412 +Ref: #all-accounts-screen12586 +Node: Balance sheet accounts screen12721 +Ref: #balance-sheet-accounts-screen12936 +Node: Income statement accounts screen13170 +Ref: #income-statement-accounts-screen13387 +Node: Register screen15832 +Ref: #register-screen16004 +Node: Transaction screen17988 +Ref: #transaction-screen18146 +Node: Error screen19016 +Ref: #error-screen19138 +Node: TIPS19382 +Ref: #tips19481 +Node: Watch mode19523 +Ref: #watch-mode19630 +Node: Debug output21086 +Ref: #debug-output21197 +Node: ENVIRONMENT21409 +Ref: #environment21520 +Node: FILES22905 +Ref: #files23004 +Node: BUGS23217 +Ref: #bugs23294  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index fbac4bfcf..9b5f5237b 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -47,6 +47,14 @@ OPTIONS --theme=default|terminal|greenterm use this custom display theme + --menu start in the menu screen + + --all start in the all accounts screen + + --bs start in the balance sheet accounts screen + + --is start in the income statement accounts screen + --register=ACCTREGEX start in the (first) matched account's register screen @@ -308,173 +316,184 @@ KEYS Additional screen-specific keys are described below. SCREENS + hledger-ui can show a number of different screens, described below. It + shows the Balance sheet accounts screen to start with, except in the + following situations: + + o If no asset/liability/equity accounts can be detected, or if an + account query has been given on the command line, it starts in the + All accounts screen. + + o If a starting screen is specified with --menu/--all/--bs/--is/--reg- + ister on the command line, it starts there. + Menu screen - The top-most screen. hledger-ui does not show this screen at startup, - but you can press LEFT to navigate to it. From here you can navigate + The top-most screen. hledger-ui does not show this screen at startup, + but you can press LEFT to navigate to it. From here you can navigate to three accounts screens: All accounts screen - This screen shows all accounts (unless filtered by a query), and their - current balances. It is like the hledger balance command. + This screen shows all accounts (possibly filtered by a query), and + their current balances. It is like the hledger balance command. Balance sheet accounts screen - This is the screen normally shown at startup. It shows asset, liabil- - ity and equity accounts, if these can be detected (see account types). - It always shows historical end balances on some date (not balance - changes). It is like the hledger balancesheetequity command. + This screen shows asset, liability and equity accounts, if these can be + detected (see account types). It always shows historical end balances + on some date (not balance changes). It is like the hledger bal- + ancesheetequity command. Income statement accounts screen - This screen shows revenue and expense accounts. It always shows bal- + This screen shows revenue and expense accounts. It always shows bal- ance changes in some period (not end balances). It is like the hledger incomestatement command. All of these accounts screens work in much the same way: - They show accounts which have been posted to by transactions, as well - as accounts which have been declared with an account directive (except + They show accounts which have been posted to by transactions, as well + as accounts which have been declared with an account directive (except for empty parent accounts). - If you specify a query on the command line, it shows just the matched + 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 list 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 list 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 (on + H toggles between showing historical balances or period balances (on the "All accounts" screen). Historical balances (the default) are end- - ing balances at the end of the report period, taking into account all - transactions before that date (filtered by the filter query if any), + ing 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 + 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 + 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 to view an account's register screen, Or, LEFT to see the + Press RIGHT to view an account's register screen, Or, LEFT to see the menu screen. Register screen 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 list - 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 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/list 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- + 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.) 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 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.) TIPS 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- + 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. - This is very useful when reconciling. A good workflow is to have your - bank's online register open in a browser window, for reference; the - journal file open in an editor window; and hledger-ui in watch mode in + This is very useful when reconciling. A good workflow is to have your + bank's online register open in a browser window, for reference; the + journal file open in an editor window; and hledger-ui in watch mode in a terminal window, eg: $ hledger-ui --watch --register checking -C - As you mark things cleared in the editor, you can see the effect imme- - diately 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 + As you mark things cleared in the editor, you can see the effect imme- + diately 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. Here are some current limitations to be aware of: - Changes might not be detected with certain editors, possibly including - Jetbrains IDEs, gedit, other Gnome applications; or on certain unusual + Changes might not be detected with certain editors, possibly including + Jetbrains IDEs, gedit, other Gnome applications; or on certain unusual filesystems. (#1617, #911). To work around, reload manually by press- - ing g in the hledger-ui window. (Or see #1617 for another workaround, + ing g in the hledger-ui window. (Or see #1617 for another workaround, and let us know if it works for you.) - CPU and memory usage can sometimes gradually increase, if hledger-ui - --watch is left running for days. (Possibly correlated with certain - platforms, many transactions, and/or large numbers of other files - present). To work around, quit and restart it, or (where supported) + CPU and memory usage can sometimes gradually increase, if hledger-ui + --watch is left running for days. (Possibly correlated with certain + platforms, many transactions, and/or large numbers of other files + present). To work around, quit and restart it, or (where supported) suspend (CTRL-z) and restart it (fg). 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 + 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 @@ -484,17 +503,17 @@ ENVIRONMENT On unix computers, the default value is: ~/.hledger.journal. - A more typical value is something like ~/finance/YYYY.journal, where - ~/finance is a version-controlled finance directory and YYYY is the - current year. Or, ~/finance/current.journal, where current.journal is + A more typical value is something like ~/finance/YYYY.journal, where + ~/finance is a version-controlled finance directory and YYYY is the + current year. Or, ~/finance/current.journal, where current.journal is a symbolic link to YYYY.journal. - The usual way to set this permanently is to add a command to one of + The usual way to set this permanently is to add a command to one of your shell's startup files (eg ~/.profile): export LEDGER_FILE=~/finance/current.journal` - On some Mac computers, there is a more thorough way to set environment + On some Mac computers, there is a more thorough way to set environment variables, that will also affect applications started from the GUI (eg, Emacs started from a dock icon): In ~/.MacOSX/environment.plist, add an entry like: @@ -505,24 +524,24 @@ ENVIRONMENT For this to take effect you might need to killall Dock, or reboot. - On Windows computers, the default value is probably C:\Users\YOUR- - NAME\.hledger.journal. You can change this by running a command like - this in a powershell window (let us know if you need to be an Adminis- + On Windows computers, the default value is probably C:\Users\YOUR- + NAME\.hledger.journal. You can change this by running a command like + this in a powershell window (let us know if you need to be an Adminis- trator, and if this persists across a reboot): > setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal" - Or, change it in settings: see https://www.java.com/en/down- + Or, change it in settings: see https://www.java.com/en/down- load/help/path.html. 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). @@ -530,13 +549,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. @@ -547,7 +566,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)