doc: begin integrating commands' CLI help and manual section

Just the close command to start with.

doc/lib.m4

@@ -197,3 +197,6 @@ m4_define({{_LEDGER_FILE_}}, {{
 The journal file path when not specified with `-f`.
 Default: `~/.hledger.journal` (on windows, perhaps `C:/Users/USER/.hledger.journal`).
 }} )m4_dnl
+m4_dnl
+m4_define({{_FLAGS_}}, {{}})m4_dnl
+m4_dnl

hledger/Hledger/Cli/CliOptions.hs

@@ -226,27 +226,33 @@ quickAddonCommandMode name = (defCommandMode [name]) {
      }
   }
 
--- | A template for a command's CLI help, influencing the content and layout
+-- | A command's documentation. Used both as part of CLI help, and as
--- of the usage text generated by a cmdargs mode. 
+-- part of the hledger manual. See parseHelpTemplate.
--- It is a multiline string structured like so:
--- The first line defines the command name (first word) and aliases (any other words). 
--- From the second line up to a line containing just "FLAGS", or the end, is the preamble,
--- displayed above the flags list generated by cmdargs. Short help goes here.
--- Any lines after the FLAGS line are the postamble, displayed below the flags list.
--- Long help/full manual goes here.
 type HelpTemplate = String
 
--- | Parse a help template into command names, help preamble, and help postamble lines.
+-- | Parse a command's documentation, as follows:
+--
+-- - First line: the command name then any aliases, as one or more space or comma-separated words
+--
+-- - Second line to a line containing just _FLAGS_, or the end: the short help
+--
+-- - Any lines after _FLAGS_: the long help (split into lines for cmdargs)
+--
+-- The CLI help displays the short help, then the cmdargs-generated
+-- flags list, then the long help (which some day we might make
+-- optional again).  The manual displays the short help followed by
+-- the long help, with no flags list.
+--
 parseHelpTemplate :: HelpTemplate -> Maybe ([Name], String, [String])
 parseHelpTemplate t =
   case lines t of
     [] -> Nothing
-    (l:ls) -> Just (names, preamble, postamblelines)
+    (l:ls) -> Just (names, shorthelp, longhelplines)
       where
-        names = words l
+        names = words $ map (\c -> if c==',' then ' ' else c) l
-        (preamblels, postamblels) = break (== "FLAGS") ls
+        (shorthelpls, longhelpls) = break (== "_FLAGS_") ls
-        preamble = unlines $ reverse $ dropWhile null $ reverse preamblels
+        shorthelp = unlines $ reverse $ dropWhile null $ reverse shorthelpls
-        postamblelines = dropWhile null $ drop 1 postamblels
+        longhelplines = dropWhile null $ drop 1 longhelpls
 
 -- | Build a cmdarg mode for a hledger command,
 -- from a help template and flag/argument specifications.
@@ -257,11 +263,11 @@ hledgerCommandMode :: HelpTemplate -> [Flag RawOpts] -> [(Help, [Flag RawOpts])]
 hledgerCommandMode tmpl ungroupedflags groupedflags hiddenflags args =
   case parseHelpTemplate tmpl of
     Nothing -> error' $ "Could not parse help template:\n"++tmpl++"\n"
-    Just (names, preamble, postamblelines) ->
+    Just (names, shorthelp, longhelplines) ->
       (defCommandMode names) {
-         modeHelp = preamble
+         modeHelp        = shorthelp
-        ,modeHelpSuffix = postamblelines
+        ,modeHelpSuffix  = longhelplines
-        ,modeGroupFlags = Group {
+        ,modeGroupFlags  = Group {
             groupUnnamed = ungroupedflags
            ,groupNamed   = groupedflags
            ,groupHidden  = hiddenflags

hledger/Hledger/Cli/Commands/Close.hs

@@ -16,56 +16,7 @@ import Hledger.Cli.CliOptions
 import System.Console.CmdArgs.Explicit as C
 
 closemode = hledgerCommandMode
-  [here| close equity
+  [hereFile|hledger/Hledger/Cli/Commands/Close.md|]
-Print a "closing balances" transaction that brings all accounts (or with
-query arguments, just the matched accounts) to a zero (historical) balance, 
-followed by an opposite "opening balances" transaction that restores the 
-balances from zero.
-
-FLAGS
-
-The opening transaction is useful to carry over asset/liability balances 
-if you choose to start a new journal file, eg yearly. The closing transaction
-can be a useful complement, allowing you to optionally include old files 
-(for more history) without disturbing the asset/liability balances 
-(since the closing/opening pairs cancel out).
-
-This command may also be useful for closing out expense/income accounts 
-for a period (ie "closing the books" in accounting).
-
-Both transactions include balance assertions for the closed/reopened accounts.
-
-You probably shouldn't use status or realness queries (eg -C or -R) with this 
-command, or the balance assertions will require that query to pass.
-Likewise, if you generate them with --auto, the assertions will depend on
-any auto postings and --auto will be required to make them pass.
-
-By default, the closing transaction is dated yesterday, with balances 
-calculated as of end of yesterday, and the opening transaction is dated today.
-To close on some other date, use: `hledger close -e OPENINGDATE ...`.
-(-p or date: can also be used, the begin date is ignored.)
-
-You can chose to print just one of the transactions with `--opening` 
-or `--closing`.
-
-For example, carrying asset/liability balances into a new file for 2018:
-```
-$ hledger close -f 2017.journal -e 2018/1/1 ^assets ^liab >>2017.journal
-# cut & paste the opening transaction from 2017.journal to a new 2018.journal
-# now:
-$ hledger bs -f 2018.journal                   # correct balances
-$ hledger bs -f 2018.journal -f 2017.journal   # still correct
-$ hledger bs -f 2017.journal not:desc:closing  # must exclude closing txn 
-```
-
-Transactions spanning the closing date may complicate matters. Eg, if
-closing at end of 2017:
-```
-2017/12/31
-    expenses:food          1
-    assets:bank:checking  -1  ; date:2018/1/1
-```
-  |]
   [flagNone ["opening"] (\opts -> setboolopt "opening" opts) "show just opening transaction"
   ,flagNone ["closing"] (\opts -> setboolopt "closing" opts) "show just closing transaction"
   ]

hledger/Hledger/Cli/Commands/Close.md

@@ -0,0 +1,79 @@
+close, equity
+
+Prints a "closing balances" transaction and an "opening balances" transaction,
+that bring account balances to and from zero, respectively.
+Useful for, eg:
+
+- bringing asset/liability balances forward into a new journal file
+- closing out revenues/expenses to retained earnings at the end of a period
+
+_FLAGS_
+
+The closing transaction transfers balances to "equity:closing balances".
+The opening transaction transfers balances from "equity:opening balances".
+You can chose to print just one of the transactions by using the
+`--opening` or `--closing` flag.
+
+If you split your journal files by time (eg yearly), you will
+typically run this command at the end of the year, and save the
+closing transaction as last entry of the old file, and the opening
+transaction as the first entry of the new file.
+This makes the files self contained, so that correct balances are
+reported no matter which of them are loaded. Ie, if you load just one
+file, the balances are initialised correctly; or if you load several
+files, the redundant closing/opening transactions cancel each other
+out. (They will show up in print or register reports; you can exclude
+them with a query like `not:desc:'(opening|closing) balances'`.)
+
+If you're running a business, you might also use this command to
+"close the books" at the end of an accounting period, transferring
+income statement account balances to retained earnings. (You may want
+to change the equity account name to something like 
+"equity:retained earnings" for clarity.)
+
+By default, the closing transaction is dated yesterday, the balances 
+are calculated as of end of yesterday, and the opening transaction is dated today.
+To close on some other date, use: `hledger close -e OPENINGDATE`.
+Eg, to close/open on the 2018/2019 boundary, use `-e 2019`.
+You can also use -p or `date:PERIOD` (any starting date is ignored).
+
+Both transactions will include balance assertions for the
+closed/reopened accounts.  You probably shouldn't use status or
+realness filters (like -C or -R or `status:`) with this command, or
+the generated balance assertions will depend on these flags.
+Likewise, if you run this command with --auto, the balance assertions
+will probably always require --auto.
+
+Examples:
+
+Carrying asset/liability balances into a new file for 2019, all from command line.
+
+*Warning: we use `>>` here to append; be careful not to type a single `>` which would wipe your journal!*
+
+    $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal
+    $ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal
+
+Now:
+
+    $ hledger bs -f 2019.journal                   # one file - balances are correct
+    $ hledger bs -f 2018.journal -f 2019.journal   # two files - balances still correct
+    $ hledger bs -f 2018.journal not:desc:closing  # to see year-end balances, must exclude closing txn
+
+Transactions spanning the closing date can complicate matters, breaking balance assertions:
+
+    2018/12/30 a purchase made in 2018, clearing the following year
+        expenses:food          5
+        assets:bank:checking  -5  ; [2019/1/2]
+
+Here's one way to resolve that:
+
+    ; in 2018.journal:
+    2018/12/30 a purchase made in 2018, clearing the following year
+        expenses:food          5
+        liabilities:pending
+
+    ; in 2019.journal:
+    2019/1/2 clearance of last year's pending transactions
+        liabilities:pending    5 = 0
+        assets:checking
+

hledger/Hledger/Cli/Commands/README

@@ -0,0 +1,22 @@
+hledger's built-in commands.
+
+Each command has a similarly-named module, Somecommand.hs.
+
+Each command's help is kept in Somecommand.md. 
+This file is included by Somecommand.hs to help build the command's --help output,
+and by hledger/hledger_commands.m4.md to help build the hledger manual.
+It has some special features:
+
+- The first line should specify the command name and any aliases,
+  as space or comma-separated words.
+
+- A line containing just _FLAGS_ will be replaced in --help output by
+  the command's flags list. If there's no such line, the flags will be
+  displayed at the end. In the manual, no flags list is shown.
+
+- Markdown can be used to influence the appearance of the manuals,
+  especially the html version. But the markup will also appear
+  uninterpreted in the --help output, so use sparingly.
+
+- GHC (and ghcid etc.) won't notice changes in this file;
+  you have to also touch the .hs file.

hledger/hledger_commands.m4.md

@@ -362,11 +362,8 @@ Report account names having the same leaf but different prefixes.
 An example: http://stefanorodighiero.net/software/hledger-dupes.html
 
 ## close
-Print closing/opening transactions that bring some or all account balances to zero and back. 
+
-Can be useful for bringing asset/liability balances across file boundaries,
+_include_(Hledger/Cli/Commands/Close.md)
-or for closing out income/expenses for a period.
-This was formerly called "equity", as in Ledger, and that alias is also accepted.
-See close --help for more.   
 
 ## files
 List all files included in the journal. With a REGEX argument,