From f388d9311a21c52bacd6a0c9a3c696c1ffdbfb7b Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 6 Sep 2018 12:03:50 -0700 Subject: [PATCH] update embedded manuals --- hledger-lib/hledger_journal.5 | 2 +- hledger-lib/hledger_journal.info | 177 ++++++++++++++++--------------- hledger-lib/hledger_journal.txt | 2 +- hledger/hledger.1 | 28 ++--- hledger/hledger.info | 76 +++++++------ hledger/hledger.txt | 90 +++++++++------- 6 files changed, 200 insertions(+), 175 deletions(-) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 89db873a7..aef8bad95 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1457,7 +1457,7 @@ Goals and actual performance can then be compared in budget reports. For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. .PP - ## Transaction Modifiers +.SS Transaction Modifiers .PP Transaction modifier rules describe changes that should be applied automatically to certain transactions. diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 89cb42788..904659bc8 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -82,6 +82,7 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: To * Tags:: * Directives:: * Periodic transactions:: +* Transaction Modifiers::  File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT @@ -1196,7 +1197,7 @@ If account aliases are present, they are applied after the default parent account.  -File: hledger_journal.info, Node: Periodic transactions, Prev: Directives, Up: FILE FORMAT +File: hledger_journal.info, Node: Periodic transactions, Next: Transaction Modifiers, Prev: Directives, Up: FILE FORMAT 1.15 Periodic transactions ========================== @@ -1292,9 +1293,13 @@ compared in budget reports. For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. - ## Transaction Modifiers + +File: hledger_journal.info, Node: Transaction Modifiers, Prev: Periodic transactions, Up: FILE FORMAT - Transaction modifier rules describe changes that should be applied +1.16 Transaction Modifiers +========================== + +Transaction modifier rules describe changes that should be applied automatically to certain transactions. Currently, this means adding extra postings (also known as "automated postings"). Transaction modifiers are enabled by the '--auto' flag. @@ -1364,87 +1369,89 @@ Tag Table: Node: Top76 Node: FILE FORMAT2378 Ref: #file-format2502 -Node: Transactions2763 -Ref: #transactions2884 -Node: Postings3568 -Ref: #postings3695 -Node: Dates4690 -Ref: #dates4805 -Node: Simple dates4870 -Ref: #simple-dates4996 -Node: Secondary dates5362 -Ref: #secondary-dates5516 -Node: Posting dates7079 -Ref: #posting-dates7208 -Node: Status8582 -Ref: #status8702 -Node: Description10410 -Ref: #description10548 -Node: Payee and note10867 -Ref: #payee-and-note10981 -Node: Account names11223 -Ref: #account-names11366 -Node: Amounts11853 -Ref: #amounts11989 -Node: Virtual Postings15006 -Ref: #virtual-postings15165 -Node: Balance Assertions16385 -Ref: #balance-assertions16560 -Node: Assertions and ordering17456 -Ref: #assertions-and-ordering17642 -Node: Assertions and included files18342 -Ref: #assertions-and-included-files18583 -Node: Assertions and multiple -f options18916 -Ref: #assertions-and-multiple--f-options19170 -Node: Assertions and commodities19302 -Ref: #assertions-and-commodities19537 -Node: Assertions and subaccounts20233 -Ref: #assertions-and-subaccounts20465 -Node: Assertions and virtual postings20986 -Ref: #assertions-and-virtual-postings21193 -Node: Balance Assignments21335 -Ref: #balance-assignments21516 -Node: Transaction prices22636 -Ref: #transaction-prices22805 -Node: Comments25073 -Ref: #comments25207 -Node: Tags26377 -Ref: #tags26495 -Node: Directives27897 -Ref: #directives28040 -Node: Comment blocks33896 -Ref: #comment-blocks34041 -Node: Including other files34217 -Ref: #including-other-files34397 -Node: Default year34805 -Ref: #default-year34974 -Node: Declaring commodities35397 -Ref: #declaring-commodities35580 -Node: Default commodity36807 -Ref: #default-commodity36983 -Node: Market prices37619 -Ref: #market-prices37784 -Node: Declaring accounts38625 -Ref: #declaring-accounts38801 -Node: Rewriting accounts40472 -Ref: #rewriting-accounts40657 -Node: Basic aliases41391 -Ref: #basic-aliases41537 -Node: Regex aliases42241 -Ref: #regex-aliases42412 -Node: Multiple aliases43130 -Ref: #multiple-aliases43305 -Node: end aliases43803 -Ref: #end-aliases43950 -Node: Default parent account44051 -Ref: #default-parent-account44217 -Node: Periodic transactions45101 -Ref: #periodic-transactions45253 -Node: Forecasting with periodic transactions46464 -Ref: #forecasting-with-periodic-transactions46707 -Node: Budgeting with periodic transactions48394 -Ref: #budgeting-with-periodic-transactions48633 -Node: EDITOR SUPPORT50380 -Ref: #editor-support50498 +Node: Transactions2789 +Ref: #transactions2910 +Node: Postings3594 +Ref: #postings3721 +Node: Dates4716 +Ref: #dates4831 +Node: Simple dates4896 +Ref: #simple-dates5022 +Node: Secondary dates5388 +Ref: #secondary-dates5542 +Node: Posting dates7105 +Ref: #posting-dates7234 +Node: Status8608 +Ref: #status8728 +Node: Description10436 +Ref: #description10574 +Node: Payee and note10893 +Ref: #payee-and-note11007 +Node: Account names11249 +Ref: #account-names11392 +Node: Amounts11879 +Ref: #amounts12015 +Node: Virtual Postings15032 +Ref: #virtual-postings15191 +Node: Balance Assertions16411 +Ref: #balance-assertions16586 +Node: Assertions and ordering17482 +Ref: #assertions-and-ordering17668 +Node: Assertions and included files18368 +Ref: #assertions-and-included-files18609 +Node: Assertions and multiple -f options18942 +Ref: #assertions-and-multiple--f-options19196 +Node: Assertions and commodities19328 +Ref: #assertions-and-commodities19563 +Node: Assertions and subaccounts20259 +Ref: #assertions-and-subaccounts20491 +Node: Assertions and virtual postings21012 +Ref: #assertions-and-virtual-postings21219 +Node: Balance Assignments21361 +Ref: #balance-assignments21542 +Node: Transaction prices22662 +Ref: #transaction-prices22831 +Node: Comments25099 +Ref: #comments25233 +Node: Tags26403 +Ref: #tags26521 +Node: Directives27923 +Ref: #directives28066 +Node: Comment blocks33922 +Ref: #comment-blocks34067 +Node: Including other files34243 +Ref: #including-other-files34423 +Node: Default year34831 +Ref: #default-year35000 +Node: Declaring commodities35423 +Ref: #declaring-commodities35606 +Node: Default commodity36833 +Ref: #default-commodity37009 +Node: Market prices37645 +Ref: #market-prices37810 +Node: Declaring accounts38651 +Ref: #declaring-accounts38827 +Node: Rewriting accounts40498 +Ref: #rewriting-accounts40683 +Node: Basic aliases41417 +Ref: #basic-aliases41563 +Node: Regex aliases42267 +Ref: #regex-aliases42438 +Node: Multiple aliases43156 +Ref: #multiple-aliases43331 +Node: end aliases43829 +Ref: #end-aliases43976 +Node: Default parent account44077 +Ref: #default-parent-account44243 +Node: Periodic transactions45127 +Ref: #periodic-transactions45309 +Node: Forecasting with periodic transactions46520 +Ref: #forecasting-with-periodic-transactions46763 +Node: Budgeting with periodic transactions48450 +Ref: #budgeting-with-periodic-transactions48689 +Node: Transaction Modifiers49148 +Ref: #transaction-modifiers49311 +Node: EDITOR SUPPORT50567 +Ref: #editor-support50685  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 52446824e..5dc616798 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -1047,8 +1047,8 @@ FILE FORMAT For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. - ## Transaction Modifiers + Transaction Modifiers Transaction modifier rules describe changes that should be applied automatically to certain transactions. Currently, this means adding extra postings (also known as "automated postings"). Transaction modi- diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 272e346e0..f13b30b7f 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -2806,20 +2806,22 @@ are considered. .SS test .PP Run built\-in unit tests. -.IP -.nf -\f[C] -$\ hledger\ test -Cases:\ 74\ \ Tried:\ 74\ \ Errors:\ 0\ \ Failures:\ 0 -\f[] -.fi .PP -This command runs hledger's built\-in unit tests and displays a quick -report. -With a regular expression argument, it selects only tests with matching -names. -It's mainly used in development, but it's also nice to be able to check -your hledger executable for smoke at any time. +Prints test names and their results on stdout. +If any test fails or gives an error, the exit code will be non\-zero. +.PP +Test names include a group prefix. +If a (exact, case sensitive) group prefix, or a full test name is +provided as the first argument, only that group or test is run. +.PP +If a numeric second argument is provided, it will set the randomness +seed, for repeatable results from tests using randomness (currently none +of them). +.PP +This is mainly used by developers, but it's nice to be able to +sanity\-check your installed hledger executable at any time. +All tests are expected to pass \- if you ever see otherwise, something +has gone wrong, please report a bug! .SH ADD\-ON COMMANDS .PP hledger also searches for external add\-on commands, and will include diff --git a/hledger/hledger.info b/hledger/hledger.info index 7c658c438..9dcb5ca73 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -2256,13 +2256,21 @@ File: hledger.info, Node: test, Prev: tags, Up: COMMANDS Run built-in unit tests. -$ hledger test -Cases: 74 Tried: 74 Errors: 0 Failures: 0 + Prints test names and their results on stdout. If any test fails or +gives an error, the exit code will be non-zero. - This command runs hledger's built-in unit tests and displays a quick -report. With a regular expression argument, it selects only tests with -matching names. It's mainly used in development, but it's also nice to -be able to check your hledger executable for smoke at any time. + Test names include a group prefix. If a (exact, case sensitive) +group prefix, or a full test name is provided as the first argument, +only that group or test is run. + + If a numeric second argument is provided, it will set the randomness +seed, for repeatable results from tests using randomness (currently none +of them). + + This is mainly used by developers, but it's nice to be able to +sanity-check your installed hledger executable at any time. All tests +are expected to pass - if you ever see otherwise, something has gone +wrong, please report a bug!  File: hledger.info, Node: ADD-ON COMMANDS, Prev: COMMANDS, Up: Top @@ -2541,33 +2549,33 @@ Node: tags76896 Ref: #tags76994 Node: test77230 Ref: #test77314 -Node: ADD-ON COMMANDS77682 -Ref: #add-on-commands77792 -Node: Official add-ons79079 -Ref: #official-add-ons79219 -Node: api79306 -Ref: #api79395 -Node: ui79447 -Ref: #ui79546 -Node: web79604 -Ref: #web79693 -Node: Third party add-ons79739 -Ref: #third-party-add-ons79914 -Node: diff80049 -Ref: #diff80146 -Node: iadd80245 -Ref: #iadd80359 -Node: interest80442 -Ref: #interest80563 -Node: irr80658 -Ref: #irr80756 -Node: Experimental add-ons80834 -Ref: #experimental-add-ons80986 -Node: autosync81266 -Ref: #autosync81377 -Node: chart81616 -Ref: #chart81735 -Node: check81806 -Ref: #check81908 +Node: ADD-ON COMMANDS78022 +Ref: #add-on-commands78132 +Node: Official add-ons79419 +Ref: #official-add-ons79559 +Node: api79646 +Ref: #api79735 +Node: ui79787 +Ref: #ui79886 +Node: web79944 +Ref: #web80033 +Node: Third party add-ons80079 +Ref: #third-party-add-ons80254 +Node: diff80389 +Ref: #diff80486 +Node: iadd80585 +Ref: #iadd80699 +Node: interest80782 +Ref: #interest80903 +Node: irr80998 +Ref: #irr81096 +Node: Experimental add-ons81174 +Ref: #experimental-add-ons81326 +Node: autosync81606 +Ref: #autosync81717 +Node: chart81956 +Ref: #chart82075 +Node: check82146 +Ref: #check82248  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index beaff5c50..158cc1850 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -2012,37 +2012,45 @@ COMMANDS test Run built-in unit tests. - $ hledger test - Cases: 74 Tried: 74 Errors: 0 Failures: 0 + Prints test names and their results on stdout. If any test fails or + gives an error, the exit code will be non-zero. - This command runs hledger's built-in unit tests and displays a quick - report. With a regular expression argument, it selects only tests with - matching names. It's mainly used in development, but it's also nice to - be able to check your hledger executable for smoke at any time. + Test names include a group prefix. If a (exact, case sensitive) group + prefix, or a full test name is provided as the first argument, only + that group or test is run. + + If a numeric second argument is provided, it will set the randomness + seed, for repeatable results from tests using randomness (currently + none of them). + + This is mainly used by developers, but it's nice to be able to san- + ity-check your installed hledger executable at any time. All tests are + expected to pass - if you ever see otherwise, something has gone wrong, + please report a bug! ADD-ON COMMANDS - hledger also searches for external add-on commands, and will include + hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- + whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few + Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them - from hledger. So hledger web --serve --port 9000 will be rejected; + o Flags specific to the add-on must have a preceding -- to hide them + from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. - o You can always run add-ons directly if preferred: + o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger (and - haskell) library functions that built-in commands do, for command-line + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. Here are some hledger add-ons available: @@ -2060,7 +2068,7 @@ ADD-ON COMMANDS hledger-web provides a simple web interface. Third party add-ons - These are maintained separately, and usually updated shortly after a + These are maintained separately, and usually updated shortly after a hledger release. diff @@ -2068,7 +2076,7 @@ ADD-ON COMMANDS journal file and another. iadd - hledger-iadd is a curses-style, more interactive replacement for the + hledger-iadd is a curses-style, more interactive replacement for the add command. interest @@ -2076,19 +2084,19 @@ ADD-ON COMMANDS ing to various schemes. irr - hledger-irr calculates the internal rate of return of an investment + hledger-irr calculates the internal rate of return of an investment account. Experimental add-ons - These are available in source form in the hledger repo's bin/ direc- + These are available in source form in the hledger repo's bin/ direc- tory; installing them is pretty easy. They may be less mature and doc- - umented than built-in commands. Reading and tweaking these is a good + umented than built-in commands. Reading and tweaking these is a good way to start making your own! autosync hledger-autosync is a symbolic link for easily running ledger-autosync, - if installed. ledger-autosync does deduplicating conversion of OFX - data and some CSV formats, and can also download the data if your bank + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank offers OFX Direct Connect. chart @@ -2098,21 +2106,21 @@ ADD-ON COMMANDS hledger-check.hs checks more powerful account balance assertions. ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. 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 addon command options with -- when invoked from + The need to precede addon command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -2125,33 +2133,33 @@ BUGS In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command `hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu @@ -2170,7 +2178,7 @@ TROUBLESHOOTING $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ bash --login - If we preferred to use eg fr_FR.utf8, we might have to install that + If we preferred to use eg fr_FR.utf8, we might have to install that first: $ apt-get install language-pack-fr @@ -2191,7 +2199,7 @@ TROUBLESHOOTING 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) @@ -2205,7 +2213,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)