cli: simplify command doc inclusion, give them normal heading structure

hledger/Hledger/Cli/CliOptions.hs

@@ -105,6 +105,7 @@ import Hledger
 import Hledger.Cli.DocFiles
 import Hledger.Cli.Version
 import Data.Time.Clock.POSIX (POSIXTime)
+import Data.List (isPrefixOf, isSuffixOf)
 
 
 -- common cmdargs flags
@@ -371,29 +372,37 @@ hledgerCommandMode doc unnamedflaggroup namedflaggroups hiddenflaggroup argsdesc
         ,modeArgs        = argsdescr
         }
 
--- | Parse a command's documentation, as follows:
+-- | Parse a command's help text file (Somecommand.txt).
+-- This is generated from the command's doc source file (Somecommand.md)
+-- by Shake cmdhelp, and it should be formatted as follows:
 --
--- - First line: the command name then any aliases, as one or more space or comma-separated words
+-- - First line: main command name
 --
--- - Second line to a line containing just _FLAGS, or the end: the short help
+-- - Third line: command aliases, comma-and-space separated, in parentheses (optional)
 --
--- - Any lines after _FLAGS: the long help (split into lines for cmdargs)
+-- - Fifth or third line to the line containing just _FLAGS (or end of file): short command help
 --
--- 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.
+-- - Any lines after _FLAGS: long command help
+--
+-- The CLI --help displays the short help, the flags help generated by cmdargs,
+-- then the long help (which some day we might make optional again).
+-- The manual displays the short help, then the long help (but not the flags list).
 --
 parseCommandDoc :: CommandDoc -> Maybe ([Name], String, [String])
 parseCommandDoc t =
   case lines t of
     [] -> Nothing
-    (l:ls) -> Just (names, shorthelp, longhelplines)
+    (l1:_:l3:ls) -> Just (cmdname:cmdaliases, shorthelp, longhelplines)
       where
-        names = words $ map (\c -> if c `elem` [',','\\'] then ' ' else c) l
-        (shorthelpls, longhelpls) = break (== "_FLAGS") ls
+        cmdname = strip l1
+        (cmdaliases, rest) =
+          if "(" `isPrefixOf` l3 && ")" `isSuffixOf` l3
+          then (words $ filter (/=',') $ drop 1 $ init l3, ls)
+          else ([], l3:ls)
+        (shorthelpls, longhelpls) = break (== "_FLAGS") $ dropWhile (=="") rest
         shorthelp = unlines $ reverse $ dropWhile null $ reverse shorthelpls
         longhelplines = dropWhile null $ drop 1 longhelpls
+    _ -> Nothing  -- error' "misformatted command help text file"
 
 -- | Get a mode's usage message as a nicely wrapped string.
 showModeUsage :: Mode a -> String

hledger/Hledger/Cli/Commands/Accounts.md

@@ -1,4 +1,5 @@
-accounts\
+## accounts
+
 Show account names.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Activity.md

@@ -1,4 +1,5 @@
-activity\
+## activity
+
 Show an ascii barchart of posting counts per interval.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Add.md

@@ -1,4 +1,5 @@
-add\
+## add
+
 Prompt for transactions and add them to the journal.
 Any arguments will be used as default inputs for the first N prompts.
 

hledger/Hledger/Cli/Commands/Aregister.md

@@ -1,4 +1,6 @@
-aregister, areg\
+## aregister
+
+(areg)
 
 Show the transactions and running historical balance of a single account,
 with each transaction displayed as one line.

hledger/Hledger/Cli/Commands/Balance.md

@@ -1,4 +1,7 @@
-balance, bal\
+## balance
+
+(bal)
+
 Show accounts and their balances.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Balancesheet.md

@@ -1,4 +1,7 @@
-balancesheet, bs\
+## balancesheet
+
+(bs)
+
 This command displays a [balance sheet](https://en.wikipedia.org/wiki/Balance_sheet), 
 showing historical ending balances of asset and liability accounts. 
 (To see equity as well, use the [balancesheetequity](#balancesheetequity) command.)

hledger/Hledger/Cli/Commands/Balancesheetequity.md

@@ -1,4 +1,7 @@
-balancesheetequity, bse\
+## balancesheetequity
+
+(bse)
+
 This command displays a [balance sheet](https://en.wikipedia.org/wiki/Balance_sheet), 
 showing historical ending balances of asset, liability and equity accounts.
 Amounts are shown with normal positive sign, as in conventional

hledger/Hledger/Cli/Commands/Cashflow.md

@@ -1,4 +1,7 @@
-cashflow, cf\
+## cashflow
+
+(cf)
+
 This command displays a [cashflow statement](https://en.wikipedia.org/wiki/Cash_flow_statement), 
 showing the inflows and outflows affecting "cash" (ie, liquid, easily convertible) assets.
 Amounts are shown with normal positive sign, as in conventional

hledger/Hledger/Cli/Commands/Check.md

@@ -1,4 +1,5 @@
-check\
+## check
+
 Check for various kinds of errors in your data. 
 
 _FLAGS

hledger/Hledger/Cli/Commands/Close.md

@@ -1,4 +1,7 @@
-close, equity\
+## close
+
+(equity)
+
 Prints a sample "closing" transaction bringing specified account balances to zero,
 and an inverse "opening" transaction restoring the same account balances.
 

hledger/Hledger/Cli/Commands/Codes.md

@@ -1,4 +1,5 @@
-codes\
+## codes
+
 List the codes seen in transactions, in the order parsed.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Commodities.md

@@ -1,4 +1,5 @@
-commodities\
+## commodities
+
 List all commodity/currency symbols used or declared in the journal.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Descriptions.md

@@ -1,4 +1,5 @@
-descriptions\
+## descriptions
+
 List the unique descriptions that appear in transactions.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Diff.md

@@ -1,4 +1,5 @@
-diff\
+## diff
+
 Compares a particular account's transactions in two input files.
 It shows any transactions to this account which are in one file but
 not in the other.

hledger/Hledger/Cli/Commands/Files.md

@@ -1,4 +1,5 @@
-files\
+## files
+
 List all files included in the journal. With a REGEX argument,
 only file names matching the regular expression (case sensitive) are shown.
 

hledger/Hledger/Cli/Commands/Help.md

@@ -1,4 +1,5 @@
-help\
+## help
+
 Show the hledger user manual in the terminal, with `info`, `man`, or a pager.
 With a TOPIC argument, open it at that topic if possible.
 TOPIC can be any heading in the manual, or a heading prefix, case insensitive.

hledger/Hledger/Cli/Commands/Import.md

@@ -1,4 +1,5 @@
-import\
+## import
+
 Read new transactions added to each FILE since last run, and add them to
 the journal. Or with --dry-run, just print the transactions 
 that would be added. Or with --catchup, just mark all of the FILEs'

hledger/Hledger/Cli/Commands/Incomestatement.md

@@ -1,4 +1,7 @@
-incomestatement, is\
+## incomestatement
+
+(is)
+
 This command displays an
 [income statement](http://en.wikipedia.org/wiki/Income_statement), 
 showing revenues and expenses during one or more periods. 

hledger/Hledger/Cli/Commands/Notes.md

@@ -1,4 +1,5 @@
-notes\
+## notes
+
 List the unique notes that appear in transactions.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Payees.md

@@ -1,4 +1,5 @@
-payees\
+## payees
+
 List the unique payee/payer names that appear in transactions.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Prices.md

@@ -1,4 +1,5 @@
-prices\
+## prices
+
 Print [market price directives](https://hledger.org/hledger.html#market-prices) from the journal.
 With --infer-market-prices, generate additional market prices from [costs](https://hledger.org/hledger.html#costs).
 With --infer-reverse-prices, also generate market prices by inverting known prices.

hledger/Hledger/Cli/Commands/Print.md

@@ -1,4 +1,5 @@
-print\
+## print
+
 Show transaction journal entries, sorted by date. 
 
 _FLAGS

hledger/Hledger/Cli/Commands/Register.md

@@ -1,4 +1,7 @@
-register, reg\
+## register
+
+(reg)
+
 Show postings and their running total.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Rewrite.md

@@ -1,4 +1,5 @@
-rewrite\
+## rewrite
+
 Print all transactions, rewriting the postings of matched transactions.
 For now the only rewrite available is adding new postings, like print --auto.
 

hledger/Hledger/Cli/Commands/Roi.md

@@ -1,4 +1,5 @@
-roi\
+## roi
+
 Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
 on your investments.
 

hledger/Hledger/Cli/Commands/Stats.md

@@ -1,4 +1,5 @@
-stats\
+## stats
+
 Show journal and performance statistics.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Tags.md

@@ -1,5 +1,6 @@
-tags\
-List the [tags](#tags) used in the journal, or their values.
+## tags
+
+List the tags used in the journal, or their values.
 
 <!-- same section name as Journal > Tags, if reordering these update all #tags[-1] links -->
 

hledger/Hledger/Cli/Commands/Test.md

@@ -1,4 +1,5 @@
-test\
+## test
+
 Run built-in unit tests.
 
 _FLAGS

hledger/Hledger/Cli/Commands/commands.m4

@@ -1,41 +1,41 @@
-m4_dnl _commands_(HEADINGHASHES)
+m4_dnl _commands_
 m4_dnl Used in the hledger manual to include all command docs.
 m4_dnl Keep synced with Hledger.Cli.Commands.commandsList, hledger.m4.md
 m4_define({{_commands_}}, 
 {{
-_command_({{$1 accounts}}           ,{{Accounts}})
-_command_({{$1 activity}}           ,{{Activity}})
-_command_({{$1 add}}                ,{{Add}})
-_command_({{$1 aregister}}          ,{{Aregister}})
-_command_({{$1 balance}}            ,{{Balance}})
-_command_({{$1 balancesheet}}       ,{{Balancesheet}})
-_command_({{$1 balancesheetequity}} ,{{Balancesheetequity}})
-_command_({{$1 cashflow}}           ,{{Cashflow}})
-_command_({{$1 check}}              ,{{Check}})
-_command_({{$1 close}}              ,{{Close}})
-_command_({{$1 codes}}              ,{{Codes}})
-_command_({{$1 commodities}}        ,{{Commodities}})
-_command_({{$1 descriptions}}       ,{{Descriptions}})
-_command_({{$1 diff}}               ,{{Diff}})
-_command_({{$1 files}}              ,{{Files}})
-_command_({{$1 help}}               ,{{Help}})
-_command_({{$1 import}}             ,{{Import}})
-_command_({{$1 incomestatement}}    ,{{Incomestatement}})
-_command_({{$1 notes}}              ,{{Notes}})
-_command_({{$1 payees}}             ,{{Payees}})
-_command_({{$1 prices}}             ,{{Prices}})
-_command_({{$1 print}}              ,{{Print}})
-_command_({{$1 register}}           ,{{Register}})
-_command_({{$1 rewrite}}            ,{{Rewrite}})
-_command_({{$1 roi}}                ,{{Roi}})
-_command_({{$1 stats}}              ,{{Stats}})
-_command_({{$1 tags}}               ,{{Tags}})
-_command_({{$1 test}}               ,{{Test}})
+_command_({{Accounts}})
+_command_({{Activity}})
+_command_({{Add}})
+_command_({{Aregister}})
+_command_({{Balance}})
+_command_({{Balancesheet}})
+_command_({{Balancesheetequity}})
+_command_({{Cashflow}})
+_command_({{Check}})
+_command_({{Close}})
+_command_({{Codes}})
+_command_({{Commodities}})
+_command_({{Descriptions}})
+_command_({{Diff}})
+_command_({{Files}})
+_command_({{Help}})
+_command_({{Import}})
+_command_({{Incomestatement}})
+_command_({{Notes}})
+_command_({{Payees}})
+_command_({{Prices}})
+_command_({{Print}})
+_command_({{Register}})
+_command_({{Rewrite}})
+_command_({{Roi}})
+_command_({{Stats}})
+_command_({{Tags}})
+_command_({{Test}})
 }})m4_dnl
 m4_dnl
-m4_dnl _command_(NAME, MDFILE)
-m4_dnl Create a command heading and include its doc.
+m4_dnl _command_(MDFILE)
+m4_dnl Include a command's doc. The doc should start with a level two heading.
 m4_define({{_command_}},
-{{$1
-_include_(hledger/Hledger/Cli/Commands/$2.md)
+{{
+_include_(hledger/Hledger/Cli/Commands/$1.md)
 }})m4_dnl

hledger/hledger.m4.md

@@ -5751,8 +5751,9 @@ m4_dnl _notman_({{
 
 Next, each command is described in detail, in alphabetical order.
 
-m4_dnl cf Hledger/Cli/Commands/commands.m4:
-_commands_({{##}})
+m4_dnl Include the command docs. Each starts with a level 2 heading.
+m4_dnl (To change that, see Hledger/Cli/Commands/{*.md,commands.m4})
+_commands_
 
 <a name="common-tasks"></a>