diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 39f3c2ed2..50c20515a 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -258,6 +258,34 @@ error screen. .PP \f[C]q\f[R] quits the application. .PP +Experimental: +.PP +\f[C]B\f[R] toggles cost mode, showing amounts in their transaction +price\[aq]s commodity (like toggling the \f[C]-B/--cost\f[R] flag). +.PP +\f[C]V\f[R] toggles value mode, showing amounts\[aq] current market +value in their default valuation commodity (like toggling the +\f[C]-V/--market\f[R] flag). +Note, \[dq]current market value\[dq] means the value on the report end +date if specified, otherwise today. +To see the value on another date, such as the transaction\[aq]s date, +you can temporarily set a date filter ending on the following day. +Eg to see the contemporaneous value of a transaction on july 30, go to +the accounts or register screen, press \f[C]/\f[R], add +\f[C]date:-7/30\f[R]. +.PP +At most one of cost or value mode can be active at once (in hledger-ui). +.PP +There\[aq]s not yet any visual reminder when cost or value mode is +active; for now pressing \f[C]B\f[R] \f[C]B\f[R] \f[C]V\f[R] should +reliably reset to normal mode. +.PP +With --watch active, if you save an edit to the journal file while +viewing the transaction screen in cost or value mode, the +\f[C]B\f[R]/\f[C]V\f[R] keys will stop working. +To work around, press g to force a manual reload, or exit the +transaction screen. +.PP Additional screen-specific keys are described below. .SH SCREENS .SS Accounts screen diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index b2595d215..20edc66ea 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -250,6 +250,32 @@ possible) when invoked from the error screen. 'q' quits the application. + Experimental: + + 'B' toggles cost mode, showing amounts in their transaction price's +commodity (like toggling the '-B/--cost' flag). + + 'V' toggles value mode, showing amounts' current market value in +their default valuation commodity (like toggling the '-V/--market' +flag). Note, "current market value" means the value on the report end +date if specified, otherwise today. To see the value on another date, +such as the transaction's date, you can temporarily set a date filter +ending on the following day. Eg to see the contemporaneous value of a +transaction on july 30, go to the accounts or register screen, press +'/', add 'date:-7/30'. + + At most one of cost or value mode can be active at once (in +hledger-ui). + + There's not yet any visual reminder when cost or value mode is +active; for now pressing 'B' 'B' 'V' should reliably reset to normal +mode. + + With -watch active, if you save an edit to the journal file while +viewing the transaction screen in cost or value mode, the 'B'/'V' keys +will stop working. To work around, press g to force a manual reload, or +exit the transaction screen. + Additional screen-specific keys are described below.  @@ -403,15 +429,15 @@ Node: OPTIONS1103 Ref: #options1200 Node: KEYS4591 Ref: #keys4686 -Node: SCREENS7938 -Ref: #screens8023 -Node: Accounts screen8113 -Ref: #accounts-screen8241 -Node: Register screen10457 -Ref: #register-screen10612 -Node: Transaction screen12608 -Ref: #transaction-screen12766 -Node: Error screen13636 -Ref: #error-screen13758 +Node: SCREENS9049 +Ref: #screens9134 +Node: Accounts screen9224 +Ref: #accounts-screen9352 +Node: Register screen11568 +Ref: #register-screen11723 +Node: Transaction screen13719 +Ref: #transaction-screen13877 +Node: Error screen14747 +Ref: #error-screen14869  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 141dbae41..f6662d2d2 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -238,47 +238,72 @@ KEYS q quits the application. + Experimental: + + B toggles cost mode, showing amounts in their transaction price's com- + modity (like toggling the -B/--cost flag). + + V toggles value mode, showing amounts' current market value in their + default valuation commodity (like toggling the -V/--market flag). + Note, "current market value" means the value on the report end date if + specified, otherwise today. To see the value on another date, such as + the transaction's date, you can temporarily set a date filter ending on + the following day. Eg to see the contemporaneous value of a transac- + tion on july 30, go to the accounts or register screen, press /, add + date:-7/30. + + At most one of cost or value mode can be active at once (in hledger- + ui). + + There's not yet any visual reminder when cost or value mode is active; + for now pressing B B V should reliably reset to normal mode. + + With --watch active, if you save an edit to the journal file while + viewing the transaction screen in cost or value mode, the B/V keys will + stop working. To work around, press g to force a manual reload, or + exit the transaction screen. + Additional screen-specific keys are described below. 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 be- + 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 be- low). In tree mode, all account balances are inclusive of subaccounts. - 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 + less detail, collapsing all accounts to a single total. To remove the depth limit, set it higher than the maximum account depth, or press ES- CAPE. 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 be- - fore the report start date, so they show the change in balance during + 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 be- + fore 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 in- + toggles cleared postings. (By default, balances include all postings; + if you activate one or two status filters, only those postings are in- cluded; 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. @@ -287,63 +312,63 @@ 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- + 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 (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, de- - scription, comments, along with all of its account postings are shown. - Simple transactions have two postings, but there can be more (or in + The transaction's date(s) and any cleared flag, transaction code, de- + scription, 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 de- + 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 de- pending on which account register you came from (remember most transac- - tions appear in multiple account registers). The #N number preceding + tions 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.) @@ -351,17 +376,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). @@ -369,24 +394,24 @@ 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. - Also, if you are viewing files mounted from another machine, --watch + Also, if you are viewing files mounted from another machine, --watch requires that both machine clocks are roughly in step. 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) @@ -400,7 +425,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)