From 6b4be651afef57e0117f64cfd809f4df6d1c78b1 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 17 Dec 2020 17:14:32 -0800 Subject: [PATCH 01/17] doc: rewrite commands intro; drop command docs from man page --- doc/common.m4 | 18 ++-- hledger/hledger.m4.md | 198 +++++++++++++++++++++++++++--------------- 2 files changed, 134 insertions(+), 82 deletions(-) diff --git a/doc/common.m4 b/doc/common.m4 index 6672bb620..6973a9d00 100644 --- a/doc/common.m4 +++ b/doc/common.m4 @@ -13,16 +13,14 @@ m4_dnl m4_dnl Author to show in man pages. m4_define({{_author_}}, {{}})m4_dnl m4_dnl -m4_dnl Macros for conditionally including format-specific content -m4_dnl $1 is the manual's web slug: hledger, hledger-ui, journal, csv etc. -m4_dnl include in man pages only -m4_define({{_man_}}, m4_ifdef({{MAN}},{{$1}}) )m4_dnl -m4_dnl include in web manuals only -m4_define({{_web_}}, m4_ifdef({{WEB}},{{$1}}) )m4_dnl -m4_dnl include in info manuals only -m4_define({{_info_}}, m4_ifdef({{INFO}},{{$1}}) )m4_dnl -m4_dnl include in text manuals only - not implemented -m4_dnl m4_define({{_txt_}}, m4_ifdef({{TXT}},{{$1}}) )m4_dnl +m4_dnl Macros for conditionally including or excluding content based on the format +m4_dnl (man, web or info). +m4_define({{_man_}}, m4_ifdef({{MAN}},{{$1}}) )m4_dnl +m4_define({{_notman_}}, m4_ifdef({{MAN}},,{{$1}}) )m4_dnl +m4_define({{_web_}}, m4_ifdef({{WEB}},{{$1}}) )m4_dnl +m4_define({{_notweb_}}, m4_ifdef({{WEB}},,{{$1}}) )m4_dnl +m4_define({{_info_}}, m4_ifdef({{INFO}},{{$1}}) )m4_dnl +m4_define({{_notinfo_}}, m4_ifdef({{INFO}},,{{$1}}) )m4_dnl m4_dnl m4_dnl Two side-by-side columns. m4_define({{_col2_}}, diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index e6f9821f3..1ea309a4d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1571,21 +1571,134 @@ Related: # COMMANDS -hledger provides a number of subcommands; `hledger` with no arguments -shows a list. +hledger provides a number of commands for producing reports and managing your data. +Run `hledger` with no arguments to list the commands available. -If you install additional `hledger-*` packages, or if you put programs -or scripts named `hledger-NAME` in your PATH, these will also be -listed as subcommands. +To run a command, write its name as hledger's first argument (eg: `hledger balance`). +Or, you can write one of the standard short aliases which are +shown in parentheses in the command list (eg: `hledger bal`); +or, any unambiguous prefix of a command name. -Run a subcommand by writing its name as first argument (eg `hledger -incomestatement`). You can also write one of the standard short aliases -displayed in parentheses in the command list (`hledger b`), or any -any unambiguous prefix of a command name (`hledger inc`). +Each command's detailed help is available as one or more of: -Here are all the builtin commands in alphabetical order. -See also `hledger` for a more organised command list, -and `hledger CMD -h` for detailed command help. +- command line help, eg: `hledger balance --help` + +- info manuals, eg: `hledger help --info hledger` -> Commands -> balance +- web manuals, eg: + +## Built-in commands + +**Data entry (these modify the journal file):** + +- [add](#add) add transactions using guided prompts +- [import](#import) add any new transactions from other files (eg csv) + +**Data management**: + +- [check](#check) check for various kinds of issue in the data +- [close](#close) (equity) generate balance-resetting transactions +- [diff](#diff) compare account transactions in two journal files +- [rewrite](#rewrite) generate extra postings, similar to print --auto + +**Financial statements:** + +- [aregister](#aregister) (areg) show transactions in a particular account +- [balancesheet](#balancesheet) (bs) show assets, liabilities and net worth +- [balancesheetequity](#balancesheetequity) (bse) show assets, liabilities and equity +- [cashflow](#cashflow) (cf) show changes in liquid assets +- [incomestatement](#incomestatement) (is) show revenues and expenses +- [roi](#roi) show return on investments + +**Miscellaneous reports:** + +- [accounts](#accounts) (a) show account names +- [activity](#activity) show postings-per-interval bar charts +- [balance](#balance) (b, bal) show balance changes/end balances/budgets in accounts +- [codes](#codes) show transaction codes +- [commodities](#commodities) show commodity/currency symbols +- [descriptions](#descriptions) show unique transaction descriptions +- [files](#files) show input file paths +- [notes](#notes) show unique note segments of transaction descriptions +- [payees](#payees) show unique payee segments of transaction descriptions +- [prices](#prices) show market price records +- [print](#print) (p, txns) show transactions (journal entries) +- [print-unique](#print-unique) show only transactions with unique descriptions +- [register](#register) (r, reg) show postings in one or more accounts & running total +- [register-match](#register-match) show a recent posting that best matches a description +- [stats](#stats) show journal statistics +- [tags](#tags) show tag names +- [test](#test) run self tests + +## Add-on commands + +Any programs or scripts in your PATH named named `hledger-SOMETHING` +will also appear in the commands list (with a `+` mark). +These are called add-on commands. + +These offical add-ons are maintained and released along with hledger: + +- [ui](hledger-ui.html) an efficient terminal interface for hledger (TUI) +- [web](hledger-web.html) a simple web interface for hledger (WUI) + +These add-ons are maintained separately: + +- [iadd](http://hackage.haskell.org/package/hledger-iadd) + a more interactive alternative for the [add](hledger.html#add) command +- [interest](http://hackage.haskell.org/package/hledger-interest) + generates interest transactions according to various schemes +- [stockquotes](http://hackage.haskell.org/package/hledger-stockquotes) + downloads market prices for your commodities from AlphaVantage *(experimental)* + + + + + + + + + + +Additional experimental add-ons, which may not be in a working state, +can be found in the bin/ directory in the hledger repo. + +## Add-on command flags + +In a hledger command line, add-on command flags must have a double dash (`--`) preceding them. +Eg you must write: +```shell +$ hledger web -- --serve +``` +and not: +```shell +$ hledger web --serve +``` +(because the `--serve` flag belongs to `hledger-web`, not `hledger`). + +The `-h/--help` and `--version` flags work without `--`, with their position deciding which program they refer to. +Eg `hledger -h web` shows hledger's help, `hledger web -h` shows hledger-web's help. + +If you have any trouble with this, remember you can always run the add-on program directly, eg: +```shell +$ hledger-web --serve +``` + +## Making add-on commands + +Add-on commands are programs or scripts in your PATH + +- whose name starts with `hledger-` +- whose name ends with a recognised file extension: + `.bat`,`.com`,`.exe`, `.hs`,`.lhs`,`.pl`,`.py`,`.rb`,`.rkt`,`.sh` or none +- and (on unix, mac) which are executable by the current user. + +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 library functions that built-in commands use for command-line options, parsing and reporting. + +_notman_({{ +## Detailed command help + +Here are the detailed command docs, in alphabetical order. ## accounts @@ -1707,67 +1820,8 @@ _include_({{Hledger/Cli/Commands/Tags.md}}) _include_({{Hledger/Cli/Commands/Test.md}}) +}}) -## Add-on commands - -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 extension -(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 things to be aware of. -Eg if the `hledger-web` add-on is installed, - -- `hledger -h web` shows hledger's help, while `hledger web -h` shows hledger-web's help. - -- 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`. - -- 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 options, journal parsing, reporting, etc. - -Two important add-ons are the hledger-ui and hledger-web user interfaces. -These are maintained and released along with hledger: - -### ui -[hledger-ui](hledger-ui.html) provides an efficient terminal interface. - -### web -[hledger-web](hledger-web.html) provides a simple web interface. - -Third party add-ons, maintained separately from hledger, include: - -### iadd - -[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) -is a more interactive, terminal UI replacement for the [add command](hledger.html#add). - -### interest - -[hledger-interest](http://hackage.haskell.org/package/hledger-interest) -generates interest transactions for an account according to various schemes. - - - - - - - - - - -### stockquotes - -[hledger-stockquotes](http://hackage.haskell.org/package/hledger-stockquotes) -downloads market prices for the commodities in your journal from AlphaVantage. - - -A few more experimental or old add-ons can be found in hledger's bin/ -directory. These are typically prototypes and not guaranteed to work. # ENVIRONMENT From ad3b5ef2fbfb26706addf24b7203e7f0d9eb6cb4 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 18 Dec 2020 17:30:23 -0800 Subject: [PATCH 02/17] ;doc: cli: reorder command docs; clean up includes --- doc/common.m4 | 7 + hledger/Hledger/Cli/Commands.hs | 1 + hledger/hledger.m4.md | 261 +++++++++++--------------------- 3 files changed, 96 insertions(+), 173 deletions(-) diff --git a/doc/common.m4 b/doc/common.m4 index 6973a9d00..4e6cfe237 100644 --- a/doc/common.m4 +++ b/doc/common.m4 @@ -22,6 +22,13 @@ m4_define({{_notweb_}}, m4_ifdef({{WEB}},,{{$1}}) )m4_dnl m4_define({{_info_}}, m4_ifdef({{INFO}},{{$1}}) )m4_dnl m4_define({{_notinfo_}}, m4_ifdef({{INFO}},,{{$1}}) )m4_dnl m4_dnl +m4_dnl A command's heading and included doc source. +m4_dnl Usage: _command_(## commandname, Markdownfilebasename) +m4_define({{_command_}}, +{{$1 +_include_(Hledger/Cli/Commands/$2.md) +}})m4_dnl +m4_dnl m4_dnl Two side-by-side columns. m4_define({{_col2_}}, {{
diff --git a/hledger/Hledger/Cli/Commands.hs b/hledger/Hledger/Cli/Commands.hs index 4f7b0b832..f1812cc0d 100644 --- a/hledger/Hledger/Cli/Commands.hs +++ b/hledger/Hledger/Cli/Commands.hs @@ -156,6 +156,7 @@ builtinCommands = [ -- commandsList :: String -> [String] -> [String] commandsList progversion othercmds = [ + -- keep synced with hledger.m4.md -> Commands --> "-------------------------------------------------------------------------------" ,progversion ,"Usage: hledger COMMAND [OPTIONS] [-- ADDONCMDOPTIONS]" diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 1ea309a4d..06cfbdf35 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1574,60 +1574,102 @@ Related: hledger provides a number of commands for producing reports and managing your data. Run `hledger` with no arguments to list the commands available. -To run a command, write its name as hledger's first argument (eg: `hledger balance`). -Or, you can write one of the standard short aliases which are -shown in parentheses in the command list (eg: `hledger bal`); -or, any unambiguous prefix of a command name. +To run a command, write its name (or its abbreviation shown in the commands list, +or any unambiguous prefix of the name) as hledger's first argument. +Eg: `hledger balance` or `hledger bal`. -Each command's detailed help is available as one or more of: +## Built-in commands + + +**Data entry (these modify the journal file):** + +- [add](#add) - add transactions using guided prompts +- [import](#import) - add any new transactions from other files (eg csv) + +**Data management**: + +- [check](#check) - check for various kinds of issue in the data +- [close](#close) (equity) - generate balance-resetting transactions +- [diff](#diff) - compare account transactions in two journal files +- [rewrite](#rewrite) - generate extra postings, similar to print --auto + +**Financial statements:** + +- [aregister](#aregister) (areg) - show transactions in a particular account +- [balancesheet](#balancesheet) (bs) - show assets, liabilities and net worth +- [balancesheetequity](#balancesheetequity) (bse) - show assets, liabilities and equity +- [cashflow](#cashflow) (cf) - show changes in liquid assets +- [incomestatement](#incomestatement) (is) - show revenues and expenses +- [roi](#roi) - show return on investments + +**Miscellaneous reports:** + +- [accounts](#accounts) (a) - show account names +- [activity](#activity) - show postings-per-interval bar charts +- [balance](#balance) (b, bal) - show balance changes/end balances/budgets in accounts +- [codes](#codes) - show transaction codes +- [commodities](#commodities) - show commodity/currency symbols +- [descriptions](#descriptions) - show unique transaction descriptions +- [files](#files) - show input file paths +- [notes](#notes) - show unique note segments of transaction descriptions +- [payees](#payees) - show unique payee segments of transaction descriptions +- [prices](#prices) - show market price records +- [print](#print) (p, txns) - show transactions (journal entries) +- [print-unique](#print-unique) - show only transactions with unique descriptions +- [register](#register) (r, reg) - show postings in one or more accounts & running total +- [register-match](#register-match) - show a recent posting that best matches a description +- [stats](#stats) - show journal statistics +- [tags](#tags) - show tag names +- [test](#test) - run self tests + +## Command documentation + +Each command's detailed docs are available as one or more of: - command line help, eg: `hledger balance --help` - info manuals, eg: `hledger help --info hledger` -> Commands -> balance - web manuals, eg: -## Built-in commands +_man_({{ +(Detailed command docs are omitted here for brevity; +if you need them please use one of the above.) +}}) +_notman_({{ +Here are the detailed command docs, in alphabetical order: -**Data entry (these modify the journal file):** - -- [add](#add) add transactions using guided prompts -- [import](#import) add any new transactions from other files (eg csv) - -**Data management**: - -- [check](#check) check for various kinds of issue in the data -- [close](#close) (equity) generate balance-resetting transactions -- [diff](#diff) compare account transactions in two journal files -- [rewrite](#rewrite) generate extra postings, similar to print --auto - -**Financial statements:** - -- [aregister](#aregister) (areg) show transactions in a particular account -- [balancesheet](#balancesheet) (bs) show assets, liabilities and net worth -- [balancesheetequity](#balancesheetequity) (bse) show assets, liabilities and equity -- [cashflow](#cashflow) (cf) show changes in liquid assets -- [incomestatement](#incomestatement) (is) show revenues and expenses -- [roi](#roi) show return on investments - -**Miscellaneous reports:** - -- [accounts](#accounts) (a) show account names -- [activity](#activity) show postings-per-interval bar charts -- [balance](#balance) (b, bal) show balance changes/end balances/budgets in accounts -- [codes](#codes) show transaction codes -- [commodities](#commodities) show commodity/currency symbols -- [descriptions](#descriptions) show unique transaction descriptions -- [files](#files) show input file paths -- [notes](#notes) show unique note segments of transaction descriptions -- [payees](#payees) show unique payee segments of transaction descriptions -- [prices](#prices) show market price records -- [print](#print) (p, txns) show transactions (journal entries) -- [print-unique](#print-unique) show only transactions with unique descriptions -- [register](#register) (r, reg) show postings in one or more accounts & running total -- [register-match](#register-match) show a recent posting that best matches a description -- [stats](#stats) show journal statistics -- [tags](#tags) show tag names -- [test](#test) run self tests +m4_dnl commandnameheading: Commandmdfile: +_command_({{### accounts}} ,{{Accounts}}) +_command_({{### activity}} ,{{Activity}}) +_command_({{### add}} ,{{Add}}) +_command_({{### aregister}} ,{{Aregister}}) +_command_({{### balance}} ,{{Balance}}) +_command_({{### balancesheet}} ,{{Balancesheet}}) +_command_({{### balancesheetequity}} ,{{Balancesheetequity}}) +_command_({{### cashflow}} ,{{Cashflow}}) +_command_({{### check}} ,{{Check}}) +_command_({{### close}} ,{{Close}}) +_command_({{### codes}} ,{{Codes}}) +_command_({{### commodities}} ,{{Commodities}}) +_command_({{### descriptions}} ,{{Descriptions}}) +_command_({{### diff}} ,{{Diff}}) +_command_({{### files}} ,{{Files}}) +_command_({{### help}} ,{{Help}}) +_command_({{### import}} ,{{Import}}) +_command_({{### incomestatement}} ,{{Incomestatement}}) +_command_({{### notes}} ,{{Notes}}) +_command_({{### payees}} ,{{Payees}}) +_command_({{### prices}} ,{{Prices}}) +_command_({{### print}} ,{{Print}}) +_command_({{### print-unique}} ,{{Printunique}}) +_command_({{### register}} ,{{Register}}) +_command_({{### register-match}} ,{{Registermatch}}) +_command_({{### rewrite}} ,{{Rewrite}}) +_command_({{### roi}} ,{{Roi}}) +_command_({{### stats}} ,{{Stats}}) +_command_({{### tags}} ,{{Tags}}) +_command_({{### test}} ,{{Test}}) +}}) ## Add-on commands @@ -1695,133 +1737,6 @@ Add-ons are a relatively easy way to add local features or experiment with new i They can be written in any language, but haskell scripts have a big advantage: they can use the same hledger library functions that built-in commands use for command-line options, parsing and reporting. -_notman_({{ -## Detailed command help - -Here are the detailed command docs, in alphabetical order. - -## accounts - -_include_(Hledger/Cli/Commands/Accounts.md) - -## activity - -_include_(Hledger/Cli/Commands/Activity.md) - -## add - -_include_(Hledger/Cli/Commands/Add.md) - -## aregister - -_include_(Hledger/Cli/Commands/Aregister.md) - -## balance - -_include_({{Hledger/Cli/Commands/Balance.md}}) - -## balancesheet - -_include_({{Hledger/Cli/Commands/Balancesheet.md}}) - -## balancesheetequity - -_include_({{Hledger/Cli/Commands/Balancesheetequity.md}}) - -## cashflow - -_include_({{Hledger/Cli/Commands/Cashflow.md}}) - -## check - -_include_({{Hledger/Cli/Commands/Check.md}}) - -## close - -_include_({{Hledger/Cli/Commands/Close.md}}) - -## codes - -_include_({{Hledger/Cli/Commands/Codes.md}}) - -## commodities - -_include_({{Hledger/Cli/Commands/Commodities.md}}) - -## descriptions - -_include_({{Hledger/Cli/Commands/Descriptions.md}}) - -## diff - -_include_({{Hledger/Cli/Commands/Diff.md}}) - -## files - -_include_({{Hledger/Cli/Commands/Files.md}}) - -## help - -_include_({{Hledger/Cli/Commands/Help.md}}) - -## import - -_include_({{Hledger/Cli/Commands/Import.md}}) - -## incomestatement - -_include_({{Hledger/Cli/Commands/Incomestatement.md}}) - -## notes - -_include_({{Hledger/Cli/Commands/Notes.md}}) - -## payees - -_include_({{Hledger/Cli/Commands/Payees.md}}) - -## prices - -_include_({{Hledger/Cli/Commands/Prices.md}}) - -## print - -_include_({{Hledger/Cli/Commands/Print.md}}) - -## print-unique - -_include_({{Hledger/Cli/Commands/Printunique.md}}) - -## register - -_include_({{Hledger/Cli/Commands/Register.md}}) - -## register-match - -_include_({{Hledger/Cli/Commands/Registermatch.md}}) - -## rewrite - -_include_({{Hledger/Cli/Commands/Rewrite.md}}) - -## roi - -_include_({{Hledger/Cli/Commands/Roi.md}}) - -## stats - -_include_({{Hledger/Cli/Commands/Stats.md}}) - -## tags - -_include_({{Hledger/Cli/Commands/Tags.md}}) - -## test - -_include_({{Hledger/Cli/Commands/Test.md}}) - -}}) - # ENVIRONMENT From 6e1a9f83e17805d9e19e893124441db2eab5a66b Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 18 Dec 2020 20:58:17 -0800 Subject: [PATCH 03/17] ;doc: info: add standalone headers, incl. text encoding --- Shake.hs | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Shake.hs b/Shake.hs index 982eb424e..8a2667fb9 100755 --- a/Shake.hs +++ b/Shake.hs @@ -97,7 +97,7 @@ usage = -- ,"./Shake relnotes create draft release notes" -- groff = "groff -c" ++ " -Wall" -- see "groff" below -makeinfo = "makeinfo" ++ " --no-warn" -- silence makeinfo warnings - comment out to see them +makeinfo = "makeinfo --no-split --force --no-warn --no-validate" -- silence makeinfo warnings, comment these to see them pandoc = "pandoc --strip-comments" gitcommit = "git commit --allow-empty" @@ -408,7 +408,6 @@ main = do deps <- liftIO $ filter (/= src) . filter (".m4.md" `isSuffixOf`) . map (dir ) <$> S.getDirectoryContents dir need $ [src, commonm4, packagemanversionm4, packagemandatem4, tmpl] ++ deps when (dir=="hledger") $ need commandmds - -- cmd_ Shell sed "-i -e" ("'s/(_monthyear_}}, *)\\{\\{[^}]+/\\1{{"++mandate++"/;'") packagem4 -- forces a rebuild, only when month has changed ? cmd Shell "m4 -P -DMAN -I" dir commonm4 packagemanversionm4 packagemandatem4 src "|" pandoc fromsrcmd "-s" "--template" tmpl @@ -444,13 +443,13 @@ main = do when (dir=="hledger") $ need commandmds cmd Shell "m4 -P -DINFO -I" dir commonm4 packagemanversionm4 src "|" - sed "-e 's/^#(#+)/\\1/'" "|" + -- sed "-e 's/^#(#+)/\\1/'" "|" pandoc fromsrcmd "--lua-filter tools/pandoc-drop-html-blocks.lua" "--lua-filter tools/pandoc-drop-html-inlines.lua" "--lua-filter tools/pandoc-drop-links.lua" - "-t texinfo |" - makeinfo "--force --no-split -o" out + "-t texinfo -s |" + makeinfo "-o" out -- WEBSITE MARKDOWN SOURCE From c92c27d5652b3369c1e4a39dca4f3d4c87dd8ad3 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 18 Dec 2020 21:16:16 -0800 Subject: [PATCH 04/17] doc: tweak manuals' top heading to improve info structure --- hledger-lib/hledger_csv.m4.md | 6 +++++- hledger-lib/hledger_journal.m4.md | 6 +++++- hledger-lib/hledger_timeclock.m4.md | 6 +++++- hledger-lib/hledger_timedot.m4.md | 6 +++++- hledger-ui/hledger-ui.m4.md | 6 +++++- hledger-web/hledger-web.m4.md | 6 +++++- hledger/hledger.m4.md | 6 +++++- 7 files changed, 35 insertions(+), 7 deletions(-) diff --git a/hledger-lib/hledger_csv.m4.md b/hledger-lib/hledger_csv.m4.md index c36680f1c..fc0c2c1ca 100644 --- a/hledger-lib/hledger_csv.m4.md +++ b/hledger-lib/hledger_csv.m4.md @@ -6,7 +6,11 @@ _man_({{ # NAME }}) -CSV - how hledger reads CSV data, and the CSV rules file format +_info_({{ +# hledger csv format +}}) + +How hledger reads CSV data, and the CSV rules file format. _man_({{ # DESCRIPTION diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index 65511a61e..471f07cd3 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -6,7 +6,11 @@ _man_({{ # NAME }}) -Journal - hledger's default file format, representing a General Journal +_info_({{ +# hledger journal format +}}) + +hledger's default file format, representing a General Journal. _man_({{ # DESCRIPTION diff --git a/hledger-lib/hledger_timeclock.m4.md b/hledger-lib/hledger_timeclock.m4.md index 7ef27cc4c..0e16b677e 100644 --- a/hledger-lib/hledger_timeclock.m4.md +++ b/hledger-lib/hledger_timeclock.m4.md @@ -6,7 +6,11 @@ _man_({{ # NAME }}) -Timeclock - the time logging format of timeclock.el, as read by hledger +_info_({{ +# hledger timeclock format +}}) + +The time logging format of timeclock.el, as read by hledger. _man_({{ # DESCRIPTION diff --git a/hledger-lib/hledger_timedot.m4.md b/hledger-lib/hledger_timedot.m4.md index 09c300592..b0b0f3f60 100644 --- a/hledger-lib/hledger_timedot.m4.md +++ b/hledger-lib/hledger_timedot.m4.md @@ -6,7 +6,11 @@ _man_({{ # NAME }}) -Timedot - hledger's human-friendly time logging format +_info_({{ +# hledger timedot format +}}) + +hledger's human-friendly time logging format. _man_({{ # DESCRIPTION diff --git a/hledger-ui/hledger-ui.m4.md b/hledger-ui/hledger-ui.m4.md index b1ad65db6..9ade76de9 100644 --- a/hledger-ui/hledger-ui.m4.md +++ b/hledger-ui/hledger-ui.m4.md @@ -6,7 +6,11 @@ _man_({{ # NAME }}) -hledger-ui - terminal interface for the hledger accounting tool +_info_({{ +# hledger-ui +}}) + +A terminal interface (TUI) for the hledger accounting tool. _man_({{ # SYNOPSIS diff --git a/hledger-web/hledger-web.m4.md b/hledger-web/hledger-web.m4.md index 8ef6ce739..c9c62a8e7 100644 --- a/hledger-web/hledger-web.m4.md +++ b/hledger-web/hledger-web.m4.md @@ -6,7 +6,11 @@ _man_({{ # NAME }}) -hledger-web - web interface for the hledger accounting tool +_info_({{ +# hledger-web +}}) + +A web interface (WUI) for the hledger accounting tool. _man_({{ # SYNOPSIS diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 06cfbdf35..d2e23a8bb 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -17,7 +17,11 @@ _man_({{ # NAME }}) -hledger - a command-line accounting tool +_info_({{ +# hledger +}}) + +A command-line accounting tool for both power users and folks new to accounting. _man_({{ # SYNOPSIS From 11b787e8ec37743164a33be5c711863f7cf50e22 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 07:57:01 -0800 Subject: [PATCH 05/17] ;doc: info: drop areg/bal's "Output format" heading to fix node loops These were making it impossible to page through the entier manual with the space key. --- hledger/Hledger/Cli/Commands/Aregister.md | 12 +++++------- hledger/Hledger/Cli/Commands/Balance.md | 13 ++++++------- 2 files changed, 11 insertions(+), 14 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Aregister.md b/hledger/Hledger/Cli/Commands/Aregister.md index 35466bc66..b9b317180 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.md +++ b/hledger/Hledger/Cli/Commands/Aregister.md @@ -32,6 +32,11 @@ transactions shown. Transactions making a net change of zero are not shown by default; add the `-E/--empty` flag to show them. +This command also supports the +[output destination](hledger.html#output-destination) and +[output format](hledger.html#output-format) options +The output formats supported are `txt`, `csv`, and `json`. + ### aregister and custom posting dates Transactions whose date is outside the report period can still be @@ -45,13 +50,6 @@ To filter strictly by transaction date instead, add the `--txn-dates` flag. If you use this flag and some of your postings have custom dates, it's probably best to assume the running balance is wrong. -### Output format - -This command also supports the -[output destination](hledger.html#output-destination) and -[output format](hledger.html#output-format) options -The output formats supported are `txt`, `csv`, and `json`. - Examples: Show all transactions and historical running balance in the first diff --git a/hledger/Hledger/Cli/Commands/Balance.md b/hledger/Hledger/Cli/Commands/Balance.md index 934d17839..af4ab291d 100644 --- a/hledger/Hledger/Cli/Commands/Balance.md +++ b/hledger/Hledger/Cli/Commands/Balance.md @@ -21,6 +21,12 @@ transaction setting the correct starting balance on that date. Then the balance command will show real-world account balances. In some cases the -H/--historical flag is used to ensure this (more below). +This command also supports the +[output destination](hledger.html#output-destination) and +[output format](hledger.html#output-format) options +The output formats supported are (in most modes): +`txt`, `csv`, `html`, and `json`. + The balance command can produce several styles of report: ### Classic balance report @@ -570,10 +576,3 @@ Budget performance in 2019/01: || 0 [ 0] ``` -### Output format - -This command also supports the -[output destination](hledger.html#output-destination) and -[output format](hledger.html#output-format) options -The output formats supported are (in most modes): -`txt`, `csv`, `html`, and `json`. From 18303bd3d20bbdcd3dc7055f9c895146e3b729dc Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 09:04:40 -0800 Subject: [PATCH 06/17] ;doc: tweak man pages' See also --- doc/manpage.nroff | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/manpage.nroff b/doc/manpage.nroff index 25baa9cac..5c8c7b8e8 100644 --- a/doc/manpage.nroff +++ b/doc/manpage.nroff @@ -36,6 +36,6 @@ Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) + +hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5) From f42d2e2b61811e9f38a46828ed454445ac3c216d Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 11:03:21 -0800 Subject: [PATCH 07/17] ;doc: info: drop standalone headers again, they break things --- Shake.hs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Shake.hs b/Shake.hs index 8a2667fb9..6122758f4 100755 --- a/Shake.hs +++ b/Shake.hs @@ -448,7 +448,10 @@ main = do "--lua-filter tools/pandoc-drop-html-blocks.lua" "--lua-filter tools/pandoc-drop-html-inlines.lua" "--lua-filter tools/pandoc-drop-links.lua" - "-t texinfo -s |" + -- add "standalone" headers ? sounds good for setting text encoding, + -- but messes up quotes ('a' becomes ^Xa^Y) + -- "-s" + "-t texinfo |" makeinfo "-o" out From 57a176193d8f7d1e9dc47144c5422f7dec6b4c4b Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 11:04:45 -0800 Subject: [PATCH 08/17] ;doc: commands: include in man pages again; simplify headings Simplify things for now. --- hledger/Hledger/Cli/Commands/Rewrite.md | 6 +- hledger/hledger.m4.md | 90 ++++++++++++------------- 2 files changed, 46 insertions(+), 50 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Rewrite.md b/hledger/Hledger/Cli/Commands/Rewrite.md index 3a1fb24a5..a36e0457c 100644 --- a/hledger/Hledger/Cli/Commands/Rewrite.md +++ b/hledger/Hledger/Cli/Commands/Rewrite.md @@ -41,7 +41,7 @@ amount of original matched posting. If the amount includes a commodity name, the new posting amount will be in the new commodity; otherwise, it will be in the matched posting amount's commodity. -#### Re-write rules in a file +### Re-write rules in a file During the run this tool will execute so called ["Automated Transactions"](http://ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions) @@ -83,7 +83,7 @@ $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) It is important to understand that relative order of such entries in journal is important. You can re-use result of previously added postings. -#### Diff output format +### Diff output format To use this tool for batch modification of your journal files you may find useful output in form of unified diff. @@ -123,7 +123,7 @@ See also: https://github.com/simonmichael/hledger/issues/99 -#### rewrite vs. print --auto +### rewrite vs. print --auto This command predates print --auto, and currently does much the same thing, but with these differences: diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index d2e23a8bb..fb4186296 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1582,7 +1582,16 @@ To run a command, write its name (or its abbreviation shown in the commands list or any unambiguous prefix of the name) as hledger's first argument. Eg: `hledger balance` or `hledger bal`. -## Built-in commands +m4_dnl XXX maybe later +m4_dnl Each command's detailed docs are available : +m4_dnl +m4_dnl - command line help, eg: `hledger balance --help` +m4_dnl - +m4_dnl - info manuals, eg: `hledger help --info hledger` (or possibly `info hledger`) +m4_dnl - web manuals, eg: +m4_dnl + +Here are the built-in commands: **Data entry (these modify the journal file):** @@ -1626,54 +1635,41 @@ Eg: `hledger balance` or `hledger bal`. - [tags](#tags) - show tag names - [test](#test) - run self tests -## Command documentation - -Each command's detailed docs are available as one or more of: - -- command line help, eg: `hledger balance --help` - -- info manuals, eg: `hledger help --info hledger` -> Commands -> balance -- web manuals, eg: - -_man_({{ -(Detailed command docs are omitted here for brevity; -if you need them please use one of the above.) -}}) -_notman_({{ -Here are the detailed command docs, in alphabetical order: +m4_dnl XXX maybe later +m4_dnl _man_({{ +m4_dnl (Detailed command docs are omitted here for brevity, +m4_dnl if you need them please use one of the other doc formats mentioned above.) +m4_dnl }}) +m4_dnl _notman_({{ +m4_dnl Here are the detailed command docs, in alphabetical order: m4_dnl commandnameheading: Commandmdfile: -_command_({{### accounts}} ,{{Accounts}}) -_command_({{### activity}} ,{{Activity}}) -_command_({{### add}} ,{{Add}}) -_command_({{### aregister}} ,{{Aregister}}) -_command_({{### balance}} ,{{Balance}}) -_command_({{### balancesheet}} ,{{Balancesheet}}) -_command_({{### balancesheetequity}} ,{{Balancesheetequity}}) -_command_({{### cashflow}} ,{{Cashflow}}) -_command_({{### check}} ,{{Check}}) -_command_({{### close}} ,{{Close}}) -_command_({{### codes}} ,{{Codes}}) -_command_({{### commodities}} ,{{Commodities}}) -_command_({{### descriptions}} ,{{Descriptions}}) -_command_({{### diff}} ,{{Diff}}) -_command_({{### files}} ,{{Files}}) -_command_({{### help}} ,{{Help}}) -_command_({{### import}} ,{{Import}}) -_command_({{### incomestatement}} ,{{Incomestatement}}) -_command_({{### notes}} ,{{Notes}}) -_command_({{### payees}} ,{{Payees}}) -_command_({{### prices}} ,{{Prices}}) -_command_({{### print}} ,{{Print}}) -_command_({{### print-unique}} ,{{Printunique}}) -_command_({{### register}} ,{{Register}}) -_command_({{### register-match}} ,{{Registermatch}}) -_command_({{### rewrite}} ,{{Rewrite}}) -_command_({{### roi}} ,{{Roi}}) -_command_({{### stats}} ,{{Stats}}) -_command_({{### tags}} ,{{Tags}}) -_command_({{### test}} ,{{Test}}) -}}) +_command_({{## accounts}} ,{{Accounts}}) +_command_({{## activity}} ,{{Activity}}) +_command_({{## add}} ,{{Add}}) +_command_({{## aregister}} ,{{Aregister}}) +_command_({{## balance}} ,{{Balance}}) +_command_({{## balancesheet}} ,{{Balancesheet}}) +_command_({{## balancesheetequity}} ,{{Balancesheetequity}}) +_command_({{## cashflow}} ,{{Cashflow}}) +_command_({{## check}} ,{{Check}}) +_command_({{## close}} ,{{Close}}) +_command_({{## codes}} ,{{Codes}}) +_command_({{## commodities}} ,{{Commodities}}) +_command_({{## descriptions}} ,{{Descriptions}}) +_command_({{## diff}} ,{{Diff}}) +_command_({{## files}} ,{{Files}}) +_command_({{## help}} ,{{Help}}) +_command_({{## import}} ,{{Import}}) +_command_({{## incomestatement}} ,{{Incomestatement}}) +_command_({{## notes}} ,{{Notes}}) +_command_({{## rewrite}} ,{{Rewrite}}) +_command_({{## roi}} ,{{Roi}}) +_command_({{## stats}} ,{{Stats}}) +_command_({{## tags}} ,{{Tags}}) +_command_({{## test}} ,{{Test}}) + +m4_dnl }}) ## Add-on commands From 006db6136c2a482862988a5c76b9484d6524424f Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 11:34:07 -0800 Subject: [PATCH 09/17] ;doc: info: consistent indenting of synopsis command lines --- hledger/hledger.m4.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index fb4186296..e4221c473 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -27,10 +27,12 @@ _man_({{ # SYNOPSIS }}) -`hledger [-f FILE] COMMAND [OPTIONS] [ARGS]`\ -`hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]`\ `hledger` +`hledger [-f FILE] COMMAND [OPTIONS] [ARGS]` + +`hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]` + _man_({{ # DESCRIPTION }}) From 24fad7ce3562c41f77b6e338ed64f3b9d5c75aa2 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 17:10:51 -0800 Subject: [PATCH 10/17] ;doc: man: show program name & version in footer --- Shake.hs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Shake.hs b/Shake.hs index 6122758f4..34286b4ce 100755 --- a/Shake.hs +++ b/Shake.hs @@ -400,10 +400,12 @@ main = do let src = manpageNameToManualName out <.> "m4.md" commonm4 = "doc/common.m4" dir = takeDirectory out + pkg = dir packagemanversionm4 = dir ".version.m4" packagemandatem4 = dir ".date.m4" tmpl = "doc/manpage.nroff" - mandate <- formatTime defaultTimeLocale "%B %Y" <$> liftIO getCurrentDay + pkgversion <- liftIO $ readFile $ dir ".version" + -- mandate <- formatTime defaultTimeLocale "%B %Y" <$> liftIO getCurrentDay -- XXX not using this.. compare with .date.m4 -- assume all other m4 files in dir are included by this one XXX not true in hledger-lib deps <- liftIO $ filter (/= src) . filter (".m4.md" `isSuffixOf`) . map (dir ) <$> S.getDirectoryContents dir need $ [src, commonm4, packagemanversionm4, packagemandatem4, tmpl] ++ deps @@ -411,6 +413,7 @@ main = do cmd Shell "m4 -P -DMAN -I" dir commonm4 packagemanversionm4 packagemandatem4 src "|" pandoc fromsrcmd "-s" "--template" tmpl + ("-V footer='"++pkg++"-"++pkgversion++"'") "--lua-filter tools/pandoc-drop-html-blocks.lua" "--lua-filter tools/pandoc-drop-html-inlines.lua" "--lua-filter tools/pandoc-drop-links.lua" From a424541e38f470ca0188e24578508a6a9f44bbab Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 17:17:44 -0800 Subject: [PATCH 11/17] ;doc: man: show program name in upper case, per man-page(7) --- doc/manpage.nroff | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manpage.nroff b/doc/manpage.nroff index 5c8c7b8e8..fcc230a07 100644 --- a/doc/manpage.nroff +++ b/doc/manpage.nroff @@ -2,7 +2,7 @@ $if(has-tables)$ .\"t $endif$ -.TH "$title/nowrap$" "$section/nowrap$" "$date/nowrap$" "$footer/nowrap$" "hledger User Manuals" +.TH "$title/nowrap/uppercase$" "$section/nowrap$" "$date/nowrap$" "$footer/nowrap$" "hledger User Manuals" $for(header-includes)$ $header-includes$ From 9daaabeda23a0357a7dda8db8ce6df681f1c807f Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 17:19:02 -0800 Subject: [PATCH 12/17] ;doc: simplify manuals' title metadata to fit man/info better --- hledger-lib/hledger_csv.m4.md | 2 +- hledger-lib/hledger_journal.m4.md | 2 +- hledger-lib/hledger_timeclock.m4.md | 2 +- hledger-lib/hledger_timedot.m4.md | 2 +- hledger-ui/hledger-ui.m4.md | 2 +- hledger-web/hledger-web.m4.md | 2 +- hledger/hledger.m4.md | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/hledger-lib/hledger_csv.m4.md b/hledger-lib/hledger_csv.m4.md index fc0c2c1ca..670e275c1 100644 --- a/hledger-lib/hledger_csv.m4.md +++ b/hledger-lib/hledger_csv.m4.md @@ -1,4 +1,4 @@ -% hledger_csv(5) hledger _version_ +% hledger_csv(5) % _author_ % _monthyear_ diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index 471f07cd3..688de6608 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -1,4 +1,4 @@ -% hledger_journal(5) hledger _version_ +% hledger_journal(5) % _author_ % _monthyear_ diff --git a/hledger-lib/hledger_timeclock.m4.md b/hledger-lib/hledger_timeclock.m4.md index 0e16b677e..66b1a63d4 100644 --- a/hledger-lib/hledger_timeclock.m4.md +++ b/hledger-lib/hledger_timeclock.m4.md @@ -1,4 +1,4 @@ -% hledger_timeclock(5) hledger _version_ +% hledger_timeclock(5) % _author_ % _monthyear_ diff --git a/hledger-lib/hledger_timedot.m4.md b/hledger-lib/hledger_timedot.m4.md index b0b0f3f60..4abf5ffec 100644 --- a/hledger-lib/hledger_timedot.m4.md +++ b/hledger-lib/hledger_timedot.m4.md @@ -1,4 +1,4 @@ -% hledger_timedot(5) hledger _version_ +% hledger_timedot(5) % _author_ % _monthyear_ diff --git a/hledger-ui/hledger-ui.m4.md b/hledger-ui/hledger-ui.m4.md index 9ade76de9..bfeee56e9 100644 --- a/hledger-ui/hledger-ui.m4.md +++ b/hledger-ui/hledger-ui.m4.md @@ -1,4 +1,4 @@ -% hledger-ui(1) hledger-ui _version_ +% hledger-ui(1) % _author_ % _monthyear_ diff --git a/hledger-web/hledger-web.m4.md b/hledger-web/hledger-web.m4.md index c9c62a8e7..512da27fe 100644 --- a/hledger-web/hledger-web.m4.md +++ b/hledger-web/hledger-web.m4.md @@ -1,4 +1,4 @@ -% hledger-web(1) hledger-web _version_ +% hledger-web(1) % _author_ % _monthyear_ diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index e4221c473..df9b0ddb0 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1,4 +1,4 @@ -% hledger(1) hledger _version_ +% hledger(1) % _author_ % _monthyear_ From 0ff65456fabaf2748c1d6a1299c44e7c4b8a8cc3 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 17:32:43 -0800 Subject: [PATCH 13/17] ;doc: info: tweak first/top heading again to improve structure --- hledger-lib/hledger_csv.m4.md | 6 +++--- hledger-lib/hledger_journal.m4.md | 6 +++--- hledger-lib/hledger_timeclock.m4.md | 6 +++--- hledger-lib/hledger_timedot.m4.md | 6 +++--- hledger-ui/hledger-ui.m4.md | 4 ---- hledger-web/hledger-web.m4.md | 4 ---- hledger/hledger.m4.md | 4 ---- 7 files changed, 12 insertions(+), 24 deletions(-) diff --git a/hledger-lib/hledger_csv.m4.md b/hledger-lib/hledger_csv.m4.md index 670e275c1..650c518b3 100644 --- a/hledger-lib/hledger_csv.m4.md +++ b/hledger-lib/hledger_csv.m4.md @@ -6,9 +6,9 @@ _man_({{ # NAME }}) -_info_({{ -# hledger csv format -}}) +m4_dnl _info_({{ +m4_dnl # hledger csv format +m4_dnl }}) How hledger reads CSV data, and the CSV rules file format. diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index 688de6608..95c011891 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -6,9 +6,9 @@ _man_({{ # NAME }}) -_info_({{ -# hledger journal format -}}) +m4_dnl _info_({{ +m4_dnl # hledger journal format +m4_dnl }}) hledger's default file format, representing a General Journal. diff --git a/hledger-lib/hledger_timeclock.m4.md b/hledger-lib/hledger_timeclock.m4.md index 66b1a63d4..524ac78f1 100644 --- a/hledger-lib/hledger_timeclock.m4.md +++ b/hledger-lib/hledger_timeclock.m4.md @@ -6,9 +6,9 @@ _man_({{ # NAME }}) -_info_({{ -# hledger timeclock format -}}) +m4_dnl _info_({{ +m4_dnl # hledger timeclock format +m4_dnl }}) The time logging format of timeclock.el, as read by hledger. diff --git a/hledger-lib/hledger_timedot.m4.md b/hledger-lib/hledger_timedot.m4.md index 4abf5ffec..2e9e16497 100644 --- a/hledger-lib/hledger_timedot.m4.md +++ b/hledger-lib/hledger_timedot.m4.md @@ -6,9 +6,9 @@ _man_({{ # NAME }}) -_info_({{ -# hledger timedot format -}}) +m4_dnl _info_({{ +m4_dnl # hledger timedot format +m4_dnl }}) hledger's human-friendly time logging format. diff --git a/hledger-ui/hledger-ui.m4.md b/hledger-ui/hledger-ui.m4.md index bfeee56e9..b1f6c06cc 100644 --- a/hledger-ui/hledger-ui.m4.md +++ b/hledger-ui/hledger-ui.m4.md @@ -6,10 +6,6 @@ _man_({{ # NAME }}) -_info_({{ -# hledger-ui -}}) - A terminal interface (TUI) for the hledger accounting tool. _man_({{ diff --git a/hledger-web/hledger-web.m4.md b/hledger-web/hledger-web.m4.md index 512da27fe..4a91d7757 100644 --- a/hledger-web/hledger-web.m4.md +++ b/hledger-web/hledger-web.m4.md @@ -6,10 +6,6 @@ _man_({{ # NAME }}) -_info_({{ -# hledger-web -}}) - A web interface (WUI) for the hledger accounting tool. _man_({{ diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index df9b0ddb0..4ec9fdbd6 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -17,10 +17,6 @@ _man_({{ # NAME }}) -_info_({{ -# hledger -}}) - A command-line accounting tool for both power users and folks new to accounting. _man_({{ From 63876a41862fd9dbbae6992562091f1661480bc1 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 17:40:42 -0800 Subject: [PATCH 14/17] ;cli: doc: commands glue text --- hledger/hledger.m4.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 4ec9fdbd6..6dfd6fb98 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1639,7 +1639,8 @@ m4_dnl (Detailed command docs are omitted here for brevity, m4_dnl if you need them please use one of the other doc formats mentioned above.) m4_dnl }}) m4_dnl _notman_({{ -m4_dnl Here are the detailed command docs, in alphabetical order: + +Next, the detailed command docs, in alphabetical order. m4_dnl commandnameheading: Commandmdfile: _command_({{## accounts}} ,{{Accounts}}) From 4639522d9c7d889fa979d561154b7183fae6cf66 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 17:56:54 -0800 Subject: [PATCH 15/17] ui: doc: fix decapitalisation in manual, present since 1.19 Added accidentally by 847fc23 on 2020-07-17. --- hledger-ui/hledger-ui.m4.md | 94 ++++++++++++++++++------------------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/hledger-ui/hledger-ui.m4.md b/hledger-ui/hledger-ui.m4.md index b1f6c06cc..ea34a83ff 100644 --- a/hledger-ui/hledger-ui.m4.md +++ b/hledger-ui/hledger-ui.m4.md @@ -87,18 +87,18 @@ hledger help options: _helpoptions_ -a @file argument will be expanded to the contents of file, +A @FILE argument will be expanded to the contents of FILE, which should contain one command line option/argument per line. -(to prevent this, insert a `--` argument before.) +(To prevent this, insert a `--` argument before.) -# keys +# KEYS `?` 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`, or `q`) to close it. -the following keys work on most screens: +(Some of these also appear in the quick help at the bottom of each screen.) +Press `?` again (or `ESCAPE`, or `LEFT`, or `q`) to close it. +The following keys work on most screens: -the cursor keys navigate: +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. @@ -108,90 +108,90 @@ 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 one way to do that.) -with shift pressed, the cursor keys adjust the report period, +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. +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 +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-standard period, you can use `/` and a `date:` query. +To set a non-standard period, you can use `/` and a `date:` query. `/` lets you set a general filter query limiting the data shown, using the same [query terms](hledger.html#queries) as in hledger and hledger-web. -while editing the query, you can use [ctrl-a/e/d/k, bs, cursor keys](http://hackage.haskell.org/package/brick-0.7/docs/brick-widgets-edit.html#t:editor); -press `enter` to set it, or `escape`to cancel. -there are also keys for quickly adjusting some common filters like account depth and transaction status (see below). -`backspace` or `delete` removes all filters, showing all transactions. +While editing the query, you can use [CTRL-a/e/d/k, BS, cursor keys](http://hackage.haskell.org/package/brick-0.7/docs/brick-widgets-edit.html#t:editor); +press `ENTER` to set it, or `ESCAPE`to cancel. +There are also keys for quickly adjusting some common filters like account depth and transaction status (see below). +`BACKSPACE` or `DELETE` removes all filters, showing all transactions. -as mentioned above, by default hledger-ui hides future transactions - +As mentioned above, by default hledger-ui hides future transactions - both ordinary transactions recorded in the journal, and periodic -transactions generated by rule. `f` toggles forecast mode, in which -future/forecasted transactions are shown. *(experimental)* +transactions generated by rule. `F` toggles forecast mode, in which +future/forecasted transactions are shown. -`escape` resets the UI state and jumps back to the top screen, +`ESCAPE` resets the UI state and jumps back to the top screen, restoring the app's initial state at startup. Or, it cancels minibuffer data entry or the help dialog. -`ctrl-l` redraws the screen and centers the selection if possible +`CTRL-l` redraws the screen and centers the selection if possible (selections 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 pause.) +previous screens. (With large files, this could cause a noticeable pause.) -`i` toggles balance assertion checking. -disabling balance assertions temporarily can be useful for troubleshooting. +`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 file. -this allows some basic data entry. +This allows some basic data entry. -`a` is like `a`, but runs the [hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) tool, +`A` is like `a`, but runs the [hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) tool, which provides a terminal interface. -this key will be available if `hledger-iadd` is installed in $path. +This key will be available if `hledger-iadd` is installed in $path. -`e` runs $hledger_ui_editor, or $editor, or a default (`emacsclient -a "" -nw`) on the journal file. -with some editors (emacs, vi), the cursor will be positioned at the current transaction +`E` runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (`emacsclient -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 (if possible) when invoked from the error screen. -`b` toggles cost mode, showing amounts in their transaction price's +`B` toggles cost mode, showing amounts in their transaction price's commodity (like toggling the -[`-b/--cost`](https://hledger.org/hledger.html#b-cost) flag). +[`-B/--cost`](https://hledger.org/hledger.html#b-cost) flag). -`v` toggles value mode, showing amounts' current market value in their +`V` toggles value mode, showing amounts' current market value in their default valuation commodity (like toggling the -[`-v/--market`](https://hledger.org/hledger.html#v-market-value) flag). -note, "current market value" means the value on the report end date if specified, otherwise today. -to see the value on another date, you can temporarily set that as the report end date. -eg: to see a transaction as it was valued on july 30, +[`-V/--market`](https://hledger.org/hledger.html#v-market-value) flag). +Note, "current market value" means the value on the report end date if specified, otherwise today. +To see the value on another date, you can temporarily set that as the report end date. +Eg: to see a transaction as it was valued on july 30, go to the accounts or register screen, press `/`, and add ` date:-7/30` to the query. -at most one of cost or value mode can be active at once. +At most one of cost or value mode can be active at once. -there's not yet any visual reminder when cost or value mode is active; +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 +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. +the `B`/`V` keys will stop working. +To work around, press `g` to force a manual reload, or exit the transaction screen. `q` quits the application. -additional screen-specific keys are described below. +Additional screen-specific keys are described below. -# screens +# SCREENS -## accounts screen +## 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 just the matched accounts and the balances from matched transactions. +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 list mode, account balances are exclusive of subaccounts, except where subaccounts are hidden by a depth limit (see below). From 753ee5f50f42f282ab46eb9ddd408088a7a9ed41 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 17:58:23 -0800 Subject: [PATCH 16/17] ;doc: note dependency between shake targets --- Shake.hs | 1 + 1 file changed, 1 insertion(+) diff --git a/Shake.hs b/Shake.hs index 34286b4ce..a549b321a 100755 --- a/Shake.hs +++ b/Shake.hs @@ -421,6 +421,7 @@ main = do -- Generate plain text manuals suitable for embedding in -- executables and viewing with a pager, from the man pages. + -- (Depends on the nroffmanuals.) phony "txtmanuals" $ need txtmanuals txtmanuals |%> \out -> do -- hledger/hledger.txt let src = manualNameToManpageName $ dropExtension out From 3d6dab7683b2f53d4ee586109da141f43dbf6299 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 18:04:13 -0800 Subject: [PATCH 17/17] journal: doc: raise all headings, improving info structure --- hledger-lib/hledger_journal.m4.md | 136 +++++++++++++++--------------- 1 file changed, 66 insertions(+), 70 deletions(-) diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index 95c011891..7455e0a70 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -76,10 +76,6 @@ Here's an example: ``` --> -_man_({{ -# FILE FORMAT -}}) - Here's a description of each part of the file format (and hledger's data model). These are mostly in the order you'll use them, but in some cases @@ -87,7 +83,7 @@ related concepts have been grouped together for easy reference, or linked before they are introduced, so feel free to skip over anything that looks unnecessary right now. -## Transactions +# TRANSACTIONS Transactions are the main unit of information in a journal file. They represent events, typically a movement of some quantity of @@ -113,9 +109,9 @@ Here's a simple journal file containing one transaction: ``` -## Dates +# DATES -### Simple dates +## Simple dates Dates in the journal file use *simple dates* format: `YYYY-MM-DD` or `YYYY/MM/DD` or `YYYY.MM.DD`, with leading zeros optional. @@ -127,7 +123,7 @@ Some examples: `2010-01-31`, `2010/01/31`, `2010.1.31`, `1/31`. (The UI also accepts simple dates, as well as the more flexible [smart dates](hledger.html#smart-dates) documented in the hledger manual.) -### Secondary dates +## Secondary dates Real-life transactions sometimes involve more than one date - eg the date you write a cheque, and the date it clears in your bank. When you want to @@ -165,7 +161,7 @@ $ hledger register checking --date2 2010-02-19 movie ticket assets:checking $-10 $-10 ``` -### Posting dates +## Posting dates You can give individual postings a different date from their parent transaction, by adding a [posting comment](#comments) containing a @@ -202,7 +198,7 @@ attempt to parse any square-bracketed sequence of the `0123456789/-.=` characters in this way. With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE. -## Status +# STATUS Transactions, or individual postings within a transaction, can have a status mark, which is a single character before @@ -243,20 +239,20 @@ With this scheme, you would use `-U` to see things which will probably hit your bank soon (like uncashed checks), and no flags to see the most up-to-date state of your finances. -## Description +# DESCRIPTION A transaction's description is the rest of the line following the date and status mark (or until a comment begins). Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you wish, or left blank. Transaction descriptions can be queried, unlike [comments](#comments). -### Payee and note +## Payee and note You can optionally include a `|` (pipe) character in descriptions to subdivide the description into separate fields for payee/payer name on the left (up to the first `|`) and an additional note field on the right (after the first `|`). This may be worthwhile if you need to do more precise [querying](hledger.html#queries) and [pivoting](hledger.html#pivoting) by payee or by note. -## Comments +# COMMENTS Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or star (`*`) are comments, and will be ignored. (Star comments cause @@ -295,7 +291,7 @@ end comment You can also comment larger regions of a file using [`comment` and `end comment` directives](#comment-blocks). -## Tags +# TAGS Tags are a way to add extra labels or labelled data to postings and transactions, which you can then [search](hledger.html#queries) or [pivot](hledger.html#pivoting) on. @@ -337,7 +333,7 @@ Tags are like Ledger's [metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata) feature, except hledger's tag values are simple strings. -## Postings +# POSTINGS A posting is an addition of some amount to, or removal of some amount from, an account. Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by: @@ -355,7 +351,7 @@ Be sure to note the unusual two-space delimiter between account name and amount. This makes it easy to write account names containing spaces. But if you accidentally leave only one space (or tab) before the amount, the amount will be considered part of the account name. -### Virtual postings +## Virtual postings A posting with a parenthesised account name is called a *virtual posting* or *unbalanced posting*, which means it is exempt from the usual rule @@ -390,7 +386,7 @@ Ordinary non-parenthesised, non-bracketed postings are called *real postings*. You can exclude virtual postings from reports with the `-R/--real` flag or `real:1` query. -## Account names +# ACCOUNT NAMES Account names typically have several parts separated by a full colon, from which hledger derives a hierarchical chart of accounts. They can be @@ -402,7 +398,7 @@ Because of this, they must always be followed by **two or more spaces** (or newl Account names can be [aliased](#rewriting-accounts). -## Amounts +# AMOUNTS After the account name, there is usually an amount. (Important: between account name and amount, there must be **two or more spaces**.) @@ -447,7 +443,7 @@ A decimal mark can be written as a period or a comma: 1.23 1,23456780000009 -### Digit group marks +## Digit group marks In the integer part of the quantity (left of the decimal mark), groups of digits can optionally be separated by a "digit group mark" - a @@ -483,7 +479,7 @@ commodity 1 000 000.9455 -### Commodity display style +## Commodity display style For each commodity, hledger chooses a consistent style to use when displaying amounts. (Except [price amounts](#prices), which are always @@ -519,7 +515,7 @@ In summary, each commodity's amounts will be normalised to If reports are showing amounts in a way you don't like (eg, with too many decimal places), use a [commodity directive](#declaring-commodities) to set your preferred style. -### Rounding +## Rounding Amounts are stored internally as decimal numbers with up to 255 decimal places, and displayed with the number of decimal places specified by the commodity display style. @@ -528,7 +524,7 @@ it rounds to the nearest even number, eg 0.5 displayed with zero decimal places (Guaranteed since hledger 1.17.1; in older versions this could vary if hledger was built with Decimal < 0.5.1.) -## Transaction prices +# TRANSACTION PRICES Within a transaction, you can note an amount's price in another commodity. This can be used to document the cost (in a purchase) or selling price (in a sale). @@ -601,7 +597,7 @@ $ hledger bal -N --flat -B €100 assets:euros ``` -## Lot prices and lot dates +# LOT PRICES, LOT DATES Ledger allows another kind of price, [lot price](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices) @@ -612,7 +608,7 @@ hledger will parse these, for compatibility with Ledger journals, but currently A [transaction price](#transaction-prices), lot price and/or lot date may appear in any order, after the posting amount and before the balance assertion if any. -## Balance assertions +# BALANCE ASSERTIONS hledger supports [Ledger-style balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions) @@ -639,7 +635,7 @@ the `-I/--ignore-assertions` flag, which can be useful for troubleshooting or for reading Ledger files. (Note: this flag currently does not disable balance assignments, below). -### Assertions and ordering +## Assertions and ordering hledger sorts an account's postings and assertions first by date and then (for postings on the same day) by parse order. Note this is @@ -654,7 +650,7 @@ updating. This order dependence does bring an advantage: precise control over the order of postings and assertions within a day, so you can assert intra-day balances. -### Assertions and included files +## Assertions and included files With [included files](#including-other-files), things are a little more complicated. Including preserves the ordering of postings and @@ -663,13 +659,13 @@ day, split across different files, and you also want to assert the account's balance on the same day, you'll have to put the assertion in the right file. -### Assertions and multiple -f options +## Assertions and multiple -f options Balance assertions don't work well across files specified with multiple -f options. Use include or [concatenate the files](hledger.html#input-files) instead. -### Assertions and commodities +## Assertions and commodities The asserted balance must be a simple single-commodity amount, and in fact the assertion checks only this commodity's balance within the @@ -717,7 +713,7 @@ One workaround is to isolate each commodity into its own subaccount: a:euro 0 == 1€ ``` -### Assertions and prices +## Assertions and prices Balance assertions ignore [transaction prices](#transaction-prices), and should normally be written without one: @@ -732,7 +728,7 @@ even though they don't affect whether the assertion passes or fails. This is for backward compatibility (hledger's [close](hledger.html#close) command used to generate balance assertions with prices), and because [balance *assignments*](#balance-assignments) do use them (see below). -### Assertions and subaccounts +## Assertions and subaccounts The balance assertions above (`=` and `==`) do not count the balance from subaccounts; they check the account's exclusive balance only. @@ -746,13 +742,13 @@ You can assert the balance including subaccounts by writing `=*` or `==*`, eg: checking 1 ==* 11 ``` -### Assertions and virtual postings +## Assertions and virtual postings Balance assertions are checked against all postings, both real and [virtual](#virtual-postings). They are not affected by the `--real/-R` flag or `real:` query. -### Assertions and precision +## Assertions and precision Balance assertions compare the exactly calculated amounts, which are not always what is shown by reports. @@ -760,7 +756,7 @@ Eg a [commodity directive](http://hledger.org/journal.html#declaring-commodities may limit the display precision, but this will not affect balance assertions. Balance assertion failure messages show exact amounts. -## Balance assignments +# BALANCE ASSIGNMENTS [Ledger-style balance assignments](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assignments) are also supported. These are like [balance assertions](#balance-assertions), but with no posting amount on the left side of the equals sign; @@ -789,7 +785,7 @@ Note that using balance assignments makes your journal a little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. -### Balance assignments and prices +## Balance assignments and prices A [transaction price](#transaction-prices) in a balance assignment will cause the calculated amount to have that price attached: @@ -804,7 +800,7 @@ $ hledger print --explicit (a) $1 @ €2 = $1 @ €2 ``` -## Directives +# DIRECTIVES A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. @@ -867,7 +863,7 @@ As you can see, directives vary in which journal entries and files they affect, and whether they are focussed on input (parsing) or output (reports). Some directives have multiple effects. -### Directives and multiple files +## Directives and multiple files If you use multiple `-f`/`--file` options, or the `include` directive, hledger will process multiple input files. But note that directives @@ -884,13 +880,13 @@ It can be surprising though; for example, it means that [`alias` directives do not affect parent or sibling files](#aliases-and-multiple-files) (see below). -### Comment blocks +## Comment blocks A line containing just `comment` starts a commented region of the file, and a line containing just `end comment` (or the end of the current file) ends it. See also [comments](#comments). -### Including other files +## Including other files You can pull in the content of additional files by writing an include directive, like this: @@ -918,7 +914,7 @@ overriding the file extension (as described in [glob patterns]: https://hackage.haskell.org/package/Glob-0.9.2/docs/System-FilePath-Glob.html#v:compile -### Default year +## Default year You can set a default year to be used for subsequent dates which don't specify a year. This is a line beginning with `Y` followed by the year. Eg: @@ -941,7 +937,7 @@ Y2010 ; change default year to 2010 assets ``` -### Declaring commodities +## Declaring commodities The `commodity` directive has several functions: @@ -996,12 +992,12 @@ Note hledger normally uses so 0.5 displayed with zero decimal digits is "0". (More at [Commodity display style](#commodity-display-style).) -#### Commodity error checking +### Commodity error checking In [strict mode], enabled with the `-s`/`--strict` flag, hledger will report an error if a commodity symbol is used that has not been declared by a [`commodity` directive](#declaring-commodities). This works similarly to [account error checking](#account-error-checking), see the notes there for more details. -### Default commodity +## Default commodity The `D` directive sets a default commodity, to be used for amounts without a commodity symbol (ie, plain numbers). This commodity will be applied to all subsequent commodity-less amounts, or until the next `D` directive. @@ -1023,7 +1019,7 @@ D $1,000.00 b ``` -### Declaring market prices +## Declaring market prices The `P` directive declares a market price, which is an exchange rate between two commodities on a certain date. @@ -1053,7 +1049,7 @@ P 2010/1/1 € $1.40 The `-V`, `-X` and `--value` flags use these market prices to show amount values in another commodity. See [Valuation](hledger.html#valuation). -### Declaring accounts +## Declaring accounts `account` directives can be used to declare accounts (ie, the places that amounts are transferred from and to). @@ -1079,7 +1075,7 @@ The simplest form is just the word `account` followed by a hledger-style account assets:bank:checking ``` -#### Account error checking +### Account error checking By default, accounts come into existence when a transaction references them by name. This is convenient, but it means hledger can't warn you when you mis-spell an account name in the journal. @@ -1093,7 +1089,7 @@ In [strict mode], enabled with the `-s`/`--strict` flag, hledger will report an - Accounts can only be declared in `journal` files (but will affect included files in other formats). - It's currently not possible to declare "all possible subaccounts" with a wildcard; every account posted to must be declared. -#### Account comments +### Account comments [Comments](#comments), beginning with a semicolon, can be added: @@ -1112,7 +1108,7 @@ Same-line comments are not supported by Ledger, or hledger <1.13. -#### Account subdirectives +### Account subdirectives We also allow (and ignore) Ledger-style indented subdirectives, just for compatibility.: ```journal @@ -1127,7 +1123,7 @@ account ACCTNAME [ACCTTYPE] [;COMMENT] [LEDGER-STYLE SUBDIRECTIVES, IGNORED] ``` -#### Account types +### Account types hledger recognises five main types of account, corresponding to the account classes in the [accounting equation][]: @@ -1143,7 +1139,7 @@ and which causes accounts to appear in the [cashflow][] report. ("Cash" here means [liquid assets][CCE], eg bank balances but typically not investments or receivables.) -##### Declaring account types +#### Declaring account types Generally, to make these reports work you should declare your top-level accounts and their types, @@ -1166,7 +1162,7 @@ account revenues ; type: Revenue account expenses ; type: Expense ``` -##### Auto-detected account types +#### Auto-detected account types If you happen to use common english top-level account names, you may not need to declare account types, as they will be detected @@ -1187,7 +1183,7 @@ automatically using the following rules: Even so, explicit declarations may be a good idea, for clarity and predictability. -##### Interference from auto-detected account types +#### Interference from auto-detected account types If you assign any account type, it's a good idea to assign all of them, to prevent any confusion from mixing declared and auto-detected @@ -1205,7 +1201,7 @@ account liabilities ; type:Equity equity -2 ``` -##### Old account type syntax +#### Old account type syntax In some hledger journals you might instead see this old syntax (the letters ALERX, separated from the account name by two or more spaces); @@ -1229,7 +1225,7 @@ account expenses X [accounting equation]: https://en.wikipedia.org/wiki/Accounting_equation -#### Account display order +### Account display order Account directives also set the order in which accounts are displayed, eg in reports, the hledger-ui accounts screen, and the hledger-web sidebar. @@ -1266,7 +1262,7 @@ This means: - you will sometimes declare parent accounts (eg `account other` above) that you don't intend to post to, just to customize their display order - sibling accounts stay together (you couldn't display `x:y` in between `a:b` and `a:c`). -### Rewriting accounts +## Rewriting accounts You can define account alias rules which rewrite your account names, or parts of them, before generating reports. @@ -1282,7 +1278,7 @@ They do not affect account names being entered via hledger add or hledger-web. See also [Rewrite account names](rewrite-account-names.html). -#### Basic aliases +### Basic aliases To set an account alias, use the `alias` directive in your journal file. This affects all subsequent journal entries in the current file or its @@ -1305,7 +1301,7 @@ alias checking = assets:bank:wells fargo:checking ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" ``` -#### Regex aliases +### Regex aliases There is also a more powerful variant that uses a regular expression, indicated by the forward slashes: @@ -1332,7 +1328,7 @@ alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 Also note that REPLACEMENT continues to the end of line (or on command line, to end of option argument), so it can contain trailing whitespace. -#### Combining aliases +### Combining aliases You can define as many aliases as you like, using journal directives and/or command line options. @@ -1357,7 +1353,7 @@ independent of which files are being read and in which order. In case of trouble, adding `--debug=6` to the command line will show which aliases are being applied when. -#### Aliases and multiple files +### Aliases and multiple files As explained at [Directives and multiple files](#directives-and-multiple-files), `alias` directives do not affect parent or sibling files. Eg in this command, @@ -1386,7 +1382,7 @@ alias bar=Bar include c.journal ; also affected ``` -#### `end aliases` +### `end aliases` You can clear (forget) all currently defined aliases with the `end aliases` directive: @@ -1395,7 +1391,7 @@ aliases` directive: end aliases ``` -### Default parent account +## Default parent account You can specify a parent account which will be prepended to all accounts within a section of the journal. Use the `apply account` and `end apply account` @@ -1434,7 +1430,7 @@ A default parent account also affects [account directives](#declaring-accounts). It does not affect account names being entered via hledger add or hledger-web. If account aliases are present, they are applied after the default parent account. -## Periodic transactions +# PERIODIC TRANSACTIONS Periodic transaction rules describe transactions that recur. They allow hledger to generate temporary future transactions to help with forecasting, @@ -1461,7 +1457,7 @@ Periodic transaction rules also have a second meaning: they are used to define budget goals, shown in [budget reports](hledger.html#budget-report). -### Periodic rule syntax +## Periodic rule syntax A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde (`~`) followed by a @@ -1480,7 +1476,7 @@ Partial or relative dates (M/D, D, tomorrow, last week) in the period expression can work (useful or not). They will be relative to today's date, unless a Y default year directive is in effect, in which case they will be relative to Y/1/1. -### Two spaces between period expression and description! +## Two spaces between period expression and description! If the period expression is followed by a transaction description, these must be separated by **two or more spaces**. @@ -1501,7 +1497,7 @@ So, - Do write two spaces between your period expression and your transaction description, if any. - Don't accidentally write two spaces in the middle of your period expression. -### Forecasting with periodic transactions +## Forecasting with periodic transactions The `--forecast` flag activates any periodic transaction rules in the journal. They will generate temporary recurring transactions, @@ -1548,7 +1544,7 @@ like in a [`date:` query](hledger.html#queries). (See also hledger.1 -> [Report start & end date](hledger.html#report-start-end-date)). Some examples: `--forecast=202001-202004`, `--forecast=jan-`, `--forecast=2020`. -### Budgeting with periodic transactions +## Budgeting with periodic transactions With the `--budget` flag, currently supported by the balance command, each periodic transaction rule declares recurring budget goals for the specified accounts. @@ -1562,7 +1558,7 @@ See also: [Budgeting and Forecasting](budgeting-and-forecasting.html). -## Auto postings +# AUTO POSTINGS "Automated postings" or "auto postings" are extra postings which get added automatically to transactions which match certain queries, @@ -1630,20 +1626,20 @@ $ hledger print --auto assets:checking $20 ``` -### Auto postings and multiple files +## Auto postings and multiple files An auto posting rule can affect any transaction in the current file, or in any parent file or child file. Note, currently it will not affect sibling files (when multiple `-f`/`--file` are used - see [#1212](https://github.com/simonmichael/hledger/issues/1212)). -### Auto postings and dates +## Auto postings and dates A [posting date](#posting-dates) (or secondary date) in the matched posting, or (taking precedence) a posting date in the auto posting rule itself, will also be used in the generated posting. -### Auto postings and transaction balancing / inferred amounts / balance assertions +## Auto postings and transaction balancing / inferred amounts / balance assertions Currently, auto postings are added: @@ -1655,7 +1651,7 @@ after auto postings are added. This changed in hledger 1.12+; see [#893](https://github.com/simonmichael/hledger/issues/893) for background. -### Auto posting tags +## Auto posting tags Automated postings will have some extra [tags](#tags-1):