diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs
index 3dc272032..c5988471f 100644
--- a/hledger/Hledger/Cli/CliOptions.hs
+++ b/hledger/Hledger/Cli/CliOptions.hs
@@ -13,6 +13,7 @@ related utilities used by hledger commands.
 {-# LANGUAGE TemplateHaskell     #-}
 {-# LANGUAGE TypeFamilies        #-}
 {-# LANGUAGE TypeOperators       #-}
+{-# LANGUAGE NamedFieldPuns #-}
 
 module Hledger.Cli.CliOptions (
   progname,
@@ -58,7 +59,8 @@ module Hledger.Cli.CliOptions (
   rawOptsToCliOpts,
   outputFormats,
   defaultOutputFormat,
-  CommandDoc,
+  CommandHelpStr,
+  parseCommandHelp,
 
   -- possibly these should move into argsToCliOpts
   -- * CLI option accessors
@@ -87,7 +89,7 @@ import qualified Control.Exception as C
 import Control.Monad (when)
 import Data.Char
 import Data.Default
-import Data.Either (fromRight, isRight)
+import Data.Either (isRight)
 import Data.List.Extra (groupSortOn, intercalate, isInfixOf, nubSort)
 import qualified Data.List.NonEmpty as NE (NonEmpty, fromList, head, nonEmpty)
 import Data.List.Split (splitOn)
@@ -396,23 +398,33 @@ addonCommandMode nam = (defCommandMode [nam]) {
      }
   }
 
+-- | A command's name, optional official abbreviation, and help preamble & postamble,
+-- as a specially formatted single string. Used to generate the CLI help, and also
+-- the command's doc in the hledger manual. See parseCommandHelp for the format.
+type CommandHelpStr = String
+
 -- | A command's documentation. Used both as part of CLI help, and as
--- part of the hledger manual. See parseCommandDoc.
-type CommandDoc = String
+-- part of the hledger manual. See parseCommandHelpStr.
+data CommandHelp = CommandHelp {
+   cmdName           :: Name        -- the official command name
+  ,mcmdShortName     :: Maybe Name  -- optional official name abbreviation
+  ,cmdHelpPreamble   :: String      -- help preamble, shown before flags help
+  ,cmdHelpPostamble ::  String      -- help postamble, shown after flags help
+} deriving (Show)
 
 -- | Build a cmdarg mode for a hledger command,
 -- from a help template and flag/argument specifications.
 -- Reduces boilerplate a little, though the complicated cmdargs
 -- flag and argument specs are still required.
-hledgerCommandMode :: CommandDoc -> [Flag RawOpts] -> [(String, [Flag RawOpts])]
+hledgerCommandMode :: CommandHelpStr -> [Flag RawOpts] -> [(String, [Flag RawOpts])]
   -> [Flag RawOpts] -> ([Arg RawOpts], Maybe (Arg RawOpts)) -> Mode RawOpts
-hledgerCommandMode doc unnamedflaggroup namedflaggroups hiddenflaggroup argsdescr =
-  case parseCommandDoc doc of
-    Nothing -> error' $ "Could not parse command doc:\n"++doc++"\n"  -- PARTIAL:
-    Just (names, shorthelp, longhelplines) ->
-      (defCommandMode names) {
-         modeHelp        = shorthelp
-        ,modeHelpSuffix  = longhelplines
+hledgerCommandMode helpstr unnamedflaggroup namedflaggroups hiddenflaggroup argsdescr =
+  case parseCommandHelp helpstr of
+    Nothing -> error' $ "Could not parse command doc:\n"++helpstr++"\n"  -- PARTIAL:
+    Just CommandHelp{cmdName, mcmdShortName, cmdHelpPreamble, cmdHelpPostamble} ->
+      (defCommandMode $ cmdName : maybeToList mcmdShortName) {
+         modeHelp        = cmdHelpPreamble
+        ,modeHelpSuffix  = lines cmdHelpPostamble
         ,modeGroupFlags  = Group {
             groupUnnamed = unnamedflaggroup
            ,groupNamed   = namedflaggroups
@@ -421,36 +433,45 @@ hledgerCommandMode doc unnamedflaggroup namedflaggroups hiddenflaggroup argsdesc
         ,modeArgs        = argsdescr
         }
 
--- | 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:
+-- | Parse a command's help text file (@Somecommand.txt@).
+-- This is generated by @Shake cmdhelp@ from the command's doc source (@Somecommand.md@).
+-- @Somecommand.md@ should be formatted as follows:
 --
--- - First line: main command name
+-- - First line: main command name, as a markdown heading.
 --
--- - Third line: command aliases, comma-and-space separated, in parentheses (optional)
+-- - Optional parenthesised third line: an official abbreviation of the command name.
 --
--- - Fifth or third line to the line containing just _FLAGS (or end of file): short command help
+-- - From third or fifth line to a @```flags@ line: the command help preamble.
+--   Usually one sentence or paragraph; any blank lines will not be rendered.
 --
--- - Any lines after _FLAGS: long command help
+-- - A fenced code block beginning with @```flags@, containing a @Flags:@ line,
+--   followed by a snapshot of the command-specific flags help as generated by cmdargs
+--   or "none" if there are no command-specific flags.
+--   This should contain no blank lines (no extra newlines in the cmdargs command mode help strings).
+--   This is shown as-is in manuals, and regenerated at runtime for --help output.
 --
--- 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).
+-- - Any remaining lines: the command help postamble.
 --
-parseCommandDoc :: CommandDoc -> Maybe ([Name], String, [String])
-parseCommandDoc t =
+-- (Note the difference between
+-- @Somecommand.md@, which is the markdown source file, and
+-- @Somecommand.txt@, which is the plain text file generated by @Shake cmdhelp@,
+-- which this function parses.)
+--
+parseCommandHelp :: CommandHelpStr -> Maybe CommandHelp
+parseCommandHelp t =
   case lines t of
     [] -> Nothing
-    (l1:_:l3:ls) -> Just (cmdname:cmdaliases, shorthelp, longhelplines)
+    (l1:_:l3:ls) -> Just $ CommandHelp cmdname (Just cmdalias) preamble postamble
       where
-        cmdname = strip l1
-        (cmdaliases, rest) =
+        cmdname = l1
+        (cmdalias, rest) =
           if "(" `isPrefixOf` l3 && ")" `isSuffixOf` l3
-          then (words $ filter (/=',') $ drop 1 $ init l3, ls)
+          then (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
+        (preamblels, rest2) = break (== "Flags:") $ dropWhile null rest
+        postamblels = dropWhile null $ dropWhile (not.null) rest2
+        preamble = unlines $ reverse $ dropWhile null $ reverse preamblels
+        postamble = unlines postamblels
     _ -> Nothing  -- error' "misformatted command help text file"
 
 -- | Get a mode's usage message as a nicely wrapped string.
@@ -497,15 +518,6 @@ s `withAliases` as = s ++ " (" ++ intercalate ", " as ++ ")"
 -- s `withAliases` as     = s ++ " (aliases: " ++ intercalate ", " as ++ ")"
 
 
--- help_postscript = [
---   -- "DATES can be Y/M/D or smart dates like \"last month\"."
---   -- ,"PATTERNS are regular"
---   -- ,"expressions which filter by account name.  Prefix a pattern with desc: to"
---   -- ,"filter by transaction description instead, prefix with not: to negate it."
---   -- ,"When using both, not: comes last."
---  ]
-
-
 -- CliOpts
 
 -- | Command line options, used in the @hledger@ package and above.
@@ -569,8 +581,8 @@ rawOptsToCliOpts rawopts = do
   currentDay <- getCurrentDay
   let day = case maybestringopt "today" rawopts of
               Nothing -> currentDay
-              Just d  -> fromRight (error' $ "Unable to parse date \"" ++ d ++ "\"") $ -- PARTIAL:
-                         fromEFDay <$> fixSmartDateStrEither' currentDay (T.pack d)
+              Just d  -> either (const err) fromEFDay $ fixSmartDateStrEither' currentDay (T.pack d)
+                where err = error' $ "Unable to parse date \"" ++ d ++ "\""
   let iopts = rawOptsToInputOpts day rawopts
   rspec <- either error' pure $ rawOptsToReportSpec day rawopts  -- PARTIAL:
   mcolumns <- readMay <$> getEnvSafe "COLUMNS"
diff --git a/hledger/Hledger/Cli/Commands/Accounts.md b/hledger/Hledger/Cli/Commands/Accounts.md
index 287ba4109..8f94dcfea 100644
--- a/hledger/Hledger/Cli/Commands/Accounts.md
+++ b/hledger/Hledger/Cli/Commands/Accounts.md
@@ -1,8 +1,23 @@
-## accounts
+## accounts 
 
 List account names.
 
-_FLAGS
+```flags
+Flags:
+  -u --used                 show only accounts used by transactions
+  -d --declared             show only accounts declared by account directive
+     --unused               show only accounts declared but not used
+     --undeclared           show only accounts used but not declared
+     --types                also show account types when known
+     --positions            also show where accounts were declared
+     --directives           show as account directives, for use in journals
+     --find                 find the first account matched by the first
+                            argument (a case-insensitive infix regexp or
+                            account name)
+  -l --flat                 show accounts as a flat list (default)
+  -t --tree                 show accounts as a tree
+     --drop=N               flat mode: omit N leading account name parts
+```
 
 This command lists account names.
 By default it shows all known accounts, either used in transactions or declared with account directives.
diff --git a/hledger/Hledger/Cli/Commands/Activity.md b/hledger/Hledger/Cli/Commands/Activity.md
index faac136af..440e01cae 100644
--- a/hledger/Hledger/Cli/Commands/Activity.md
+++ b/hledger/Hledger/Cli/Commands/Activity.md
@@ -2,7 +2,10 @@
 
 Show an ascii barchart of posting counts per interval.
 
-_FLAGS
+```flags
+Flags:
+no command-specific flags
+```
 
 The activity command displays an ascii histogram showing transaction
 counts by day, week, month or other reporting interval (by day is the
diff --git a/hledger/Hledger/Cli/Commands/Add.md b/hledger/Hledger/Cli/Commands/Add.md
index 8f81775c3..2c3e87f98 100644
--- a/hledger/Hledger/Cli/Commands/Add.md
+++ b/hledger/Hledger/Cli/Commands/Add.md
@@ -2,7 +2,10 @@
 
 Record new transactions with interactive prompting in the console.
 
-_FLAGS
+```flags
+Flags:
+     --no-new-accounts      don't allow creating new accounts
+```
 
 Many hledger users edit their journals directly with a text editor, or generate them from CSV.
 For more interactive data entry, there is the `add` command, 
diff --git a/hledger/Hledger/Cli/Commands/Aregister.md b/hledger/Hledger/Cli/Commands/Aregister.md
index 2cb9e54e1..3ad54a425 100644
--- a/hledger/Hledger/Cli/Commands/Aregister.md
+++ b/hledger/Hledger/Cli/Commands/Aregister.md
@@ -5,7 +5,20 @@
 Show the transactions and running balances in one account,
 with each transaction on one line.
 
-_FLAGS
+```flags
+Flags:
+     --txn-dates            filter strictly by transaction date, not posting
+                            date. Warning: this can show a wrong running
+                            balance.
+     --no-elide             don't show only 2 commodities per amount
+  -w --width=N              set output width (default: terminal width or
+                            $COLUMNS). -wN,M sets description width as well.
+     --align-all            guarantee alignment across all lines (slower)
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+```
 
 `aregister` shows the overall transactions affecting a particular account (and
 any subaccounts). Each report line represents one transaction in this account.
diff --git a/hledger/Hledger/Cli/Commands/Balance.md b/hledger/Hledger/Cli/Commands/Balance.md
index ef13e20e5..1a7b55e62 100644
--- a/hledger/Hledger/Cli/Commands/Balance.md
+++ b/hledger/Hledger/Cli/Commands/Balance.md
@@ -5,7 +5,64 @@
 A flexible, general purpose "summing" report that shows accounts with some kind of numeric data.
 This can be balance changes per period, end balances, budget performance, unrealised capital gains, etc.
 
-_FLAGS
+```flags
+Flags:
+     --sum                  show sum of posting amounts (default)
+     --budget[=DESCPAT]     show sum of posting amounts together with budget
+                            goals defined by periodic
+                            transactions. With a DESCPAT argument (must be
+                            separated by = not space),
+                            use only periodic transactions with matching
+                            description
+                            (case insensitive substring match).
+     --valuechange          show total change of value of period-end
+                            historical balances (caused by deposits,
+                            withdrawals, market price fluctuations)
+     --gain                 show unrealised capital gain/loss (historical
+                            balance value minus cost basis)
+     --count                show the count of postings
+     --change               accumulate amounts from column start to column
+                            end (in multicolumn reports, default)
+     --cumulative           accumulate amounts from report start (specified
+                            by e.g. -b/--begin) to column end
+  -H --historical           accumulate amounts from journal start to column
+                            end (includes postings before report start date)
+  -l --flat                 show accounts as a flat list (default). Amounts
+                            exclude subaccount amounts, except where the
+                            account is depth-clipped.
+  -t --tree                 show accounts as a tree. Amounts include
+                            subaccount amounts.
+     --drop=N               omit N leading account name parts (in flat mode)
+     --declared             include non-parent declared accounts (best used
+                            with -E)
+  -A --average              show a row average column (in multicolumn
+                            reports)
+  -r --related              show postings' siblings instead
+  -T --row-total            show a row total column (in multicolumn reports)
+     --summary-only         display only row summaries (e.g. row total,
+                            average) (in multicolumn reports)
+  -N --no-total             omit the final total row
+     --no-elide             don't squash boring parent accounts (in tree
+                            mode)
+     --format=FORMATSTR     use this custom line format (in simple reports)
+  -S --sort-amount          sort by amount instead of account code/name (in
+                            flat mode). With multiple columns, sorts by the row
+                            total, or by row average if that is displayed.
+  -% --percent              express values in percentage of each column's
+                            total
+     --invert               display all amounts with reversed sign
+     --transpose            transpose rows and columns
+     --layout=ARG           how to lay out multi-commodity amounts and the
+                            overall table:
+                            'wide[,WIDTH]': commodities on one line
+                            'tall'        : commodities on separate lines
+                            'bare'        : commodity symbols in one column
+                            'tidy'        : every attribute in its own column
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+```
 
 `balance` is one of hledger's oldest and most versatile commands,
 for listing account balances, balance changes, values, value changes and more,
diff --git a/hledger/Hledger/Cli/Commands/Balancesheet.md b/hledger/Hledger/Cli/Commands/Balancesheet.md
index 0227b13ad..01d417f96 100644
--- a/hledger/Hledger/Cli/Commands/Balancesheet.md
+++ b/hledger/Hledger/Cli/Commands/Balancesheet.md
@@ -5,7 +5,52 @@
 Show the end balances in asset and liability accounts.
 Amounts are shown with normal positive sign, as in conventional financial statements.
 
-_FLAGS
+```flags
+Flags:
+     --sum                  show sum of posting amounts (default)
+     --valuechange          show total change of period-end historical
+                            balance value (caused by deposits, withdrawals,
+                            market price fluctuations)
+     --gain                 show unrealised capital gain/loss (historical
+                            balance value minus cost basis)
+     --budget               show sum of posting amounts compared to budget
+                            goals defined by periodic transactions
+     --change               accumulate amounts from column start to column
+                            end (in multicolumn reports)
+     --cumulative           accumulate amounts from report start (specified
+                            by e.g. -b/--begin) to column end
+  -H --historical           accumulate amounts from journal start to column
+                            end (includes postings before report start date)
+                            (default)
+  -l --flat                 show accounts as a flat list (default). Amounts
+                            exclude subaccount amounts, except where the
+                            account is depth-clipped.
+  -t --tree                 show accounts as a tree. Amounts include
+                            subaccount amounts.
+     --drop=N               flat mode: omit N leading account name parts
+     --declared             include non-parent declared accounts (best used
+                            with -E)
+  -A --average              show a row average column (in multicolumn
+                            reports)
+  -T --row-total            show a row total column (in multicolumn reports)
+     --summary-only         display only row summaries (e.g. row total,
+                            average) (in multicolumn reports)
+  -N --no-total             omit the final total row
+     --no-elide             don't squash boring parent accounts (in tree
+                            mode)
+     --format=FORMATSTR     use this custom line format (in simple reports)
+  -S --sort-amount          sort by amount instead of account code/name
+  -% --percent              express values in percentage of each column's
+                            total
+     --layout=ARG           how to show multi-commodity amounts:
+                            'wide[,WIDTH]': all commodities on one line
+                            'tall'        : each commodity on a new line
+                            'bare'        : bare numbers, symbols in a column
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+```
 
 This command displays a [balance sheet](https://en.wikipedia.org/wiki/Balance_sheet), 
 showing historical ending balances of asset and liability accounts. 
diff --git a/hledger/Hledger/Cli/Commands/Balancesheetequity.md b/hledger/Hledger/Cli/Commands/Balancesheetequity.md
index b102ca573..4db12205e 100644
--- a/hledger/Hledger/Cli/Commands/Balancesheetequity.md
+++ b/hledger/Hledger/Cli/Commands/Balancesheetequity.md
@@ -7,7 +7,52 @@ showing historical ending balances of asset, liability and equity accounts.
 Amounts are shown with normal positive sign, as in conventional
 financial statements.
 
-_FLAGS
+```flags
+Flags:
+     --sum                  show sum of posting amounts (default)
+     --valuechange          show total change of period-end historical
+                            balance value (caused by deposits, withdrawals,
+                            market price fluctuations)
+     --gain                 show unrealised capital gain/loss (historical
+                            balance value minus cost basis)
+     --budget               show sum of posting amounts compared to budget
+                            goals defined by periodic transactions
+     --change               accumulate amounts from column start to column
+                            end (in multicolumn reports)
+     --cumulative           accumulate amounts from report start (specified
+                            by e.g. -b/--begin) to column end
+  -H --historical           accumulate amounts from journal start to column
+                            end (includes postings before report start date)
+                            (default)
+  -l --flat                 show accounts as a flat list (default). Amounts
+                            exclude subaccount amounts, except where the
+                            account is depth-clipped.
+  -t --tree                 show accounts as a tree. Amounts include
+                            subaccount amounts.
+     --drop=N               flat mode: omit N leading account name parts
+     --declared             include non-parent declared accounts (best used
+                            with -E)
+  -A --average              show a row average column (in multicolumn
+                            reports)
+  -T --row-total            show a row total column (in multicolumn reports)
+     --summary-only         display only row summaries (e.g. row total,
+                            average) (in multicolumn reports)
+  -N --no-total             omit the final total row
+     --no-elide             don't squash boring parent accounts (in tree
+                            mode)
+     --format=FORMATSTR     use this custom line format (in simple reports)
+  -S --sort-amount          sort by amount instead of account code/name
+  -% --percent              express values in percentage of each column's
+                            total
+     --layout=ARG           how to show multi-commodity amounts:
+                            'wide[,WIDTH]': all commodities on one line
+                            'tall'        : each commodity on a new line
+                            'bare'        : bare numbers, symbols in a column
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+```
 
 This report shows accounts declared with the `Asset`, `Cash`, `Liability` or `Equity` type
 (see [account types](https://hledger.org/hledger.html#account-types)).
@@ -58,4 +103,4 @@ This command also supports the
 The output formats supported are
 `txt`, `csv`, `tsv`, `html`, and `json`.
 
-[accounting equation]: https://plaintextaccounting.org/FAQ#what-is-the-accounting-equation
\ No newline at end of file
+[accounting equation]: https://plaintextaccounting.org/FAQ#what-is-the-accounting-equation
diff --git a/hledger/Hledger/Cli/Commands/Cashflow.md b/hledger/Hledger/Cli/Commands/Cashflow.md
index 3034f2ccb..1c2efbcb5 100644
--- a/hledger/Hledger/Cli/Commands/Cashflow.md
+++ b/hledger/Hledger/Cli/Commands/Cashflow.md
@@ -7,7 +7,51 @@ showing the inflows and outflows affecting "cash" (ie, liquid, easily convertibl
 Amounts are shown with normal positive sign, as in conventional
 financial statements.
 
-_FLAGS
+```flags
+Flags:
+     --sum                  show sum of posting amounts (default)
+     --valuechange          show total change of period-end historical
+                            balance value (caused by deposits, withdrawals,
+                            market price fluctuations)
+     --gain                 show unrealised capital gain/loss (historical
+                            balance value minus cost basis)
+     --budget               show sum of posting amounts compared to budget
+                            goals defined by periodic transactions
+     --change               accumulate amounts from column start to column
+                            end (in multicolumn reports) (default)
+     --cumulative           accumulate amounts from report start (specified
+                            by e.g. -b/--begin) to column end
+  -H --historical           accumulate amounts from journal start to column
+                            end (includes postings before report start date)
+  -l --flat                 show accounts as a flat list (default). Amounts
+                            exclude subaccount amounts, except where the
+                            account is depth-clipped.
+  -t --tree                 show accounts as a tree. Amounts include
+                            subaccount amounts.
+     --drop=N               flat mode: omit N leading account name parts
+     --declared             include non-parent declared accounts (best used
+                            with -E)
+  -A --average              show a row average column (in multicolumn
+                            reports)
+  -T --row-total            show a row total column (in multicolumn reports)
+     --summary-only         display only row summaries (e.g. row total,
+                            average) (in multicolumn reports)
+  -N --no-total             omit the final total row
+     --no-elide             don't squash boring parent accounts (in tree
+                            mode)
+     --format=FORMATSTR     use this custom line format (in simple reports)
+  -S --sort-amount          sort by amount instead of account code/name
+  -% --percent              express values in percentage of each column's
+                            total
+     --layout=ARG           how to show multi-commodity amounts:
+                            'wide[,WIDTH]': all commodities on one line
+                            'tall'        : each commodity on a new line
+                            'bare'        : bare numbers, symbols in a column
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+```
 
 This report shows accounts declared with the `Cash` type
 (see [account types](https://hledger.org/hledger.html#account-types)).
diff --git a/hledger/Hledger/Cli/Commands/Check.md b/hledger/Hledger/Cli/Commands/Check.md
index 6d4af57c2..e8a3d300f 100644
--- a/hledger/Hledger/Cli/Commands/Check.md
+++ b/hledger/Hledger/Cli/Commands/Check.md
@@ -2,7 +2,10 @@
 
 Check for various kinds of errors in your data. 
 
-_FLAGS
+```flags
+Flags:
+no command-specific flags
+```
 
 hledger provides a number of built-in correctness checks to help validate your data and prevent errors.
 Some are run automatically, some when you enable `--strict` mode;
diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md
index a8f2260cc..798b2fbed 100644
--- a/hledger/Hledger/Cli/Commands/Close.md
+++ b/hledger/Hledger/Cli/Commands/Close.md
@@ -7,7 +7,37 @@ migrating balances to a new journal file, retaining earnings into equity, consol
 Like `print`, it prints valid journal entries.
 You can append or copy these to your journal file(s) when you are happy with how they look.
 
-_FLAGS
+```flags
+Flags:
+     --migrate[=NEW]        show closing and opening transactions, for Asset
+                            and Liability accounts by default, tagged for easy
+                            matching. The tag's default value can be overridden
+                            by providing NEW.
+     --close[=NEW]          (default) show a closing transaction
+     --open[=NEW]           show an opening transaction
+     --assign[=NEW]         show opening balance assignments
+     --assert[=NEW]         show closing balance assertions
+     --retain[=NEW]         show a retain earnings transaction, for Revenue
+                            and Expense accounts by default
+  -x --explicit             show all amounts explicitly
+     --show-costs           show amounts with different costs separately
+     --interleaved          show source and destination postings together
+     --assertion-type=TYPE  =, ==, =* or ==*
+     --close-desc=DESC      set closing transaction's description
+     --close-acct=ACCT      set closing transaction's destination account
+     --open-desc=DESC       set opening transaction's description
+     --open-acct=ACCT       set opening transaction's source account
+     --round=TYPE           how much rounding or padding should be done when
+                            displaying amounts ?
+                            none - show original decimal digits,
+                                   as in journal
+                            soft - just add or remove decimal zeros
+                                   to match precision (default)
+                            hard - round posting amounts to precision
+                                   (can unbalance transactions)
+                            all  - also round cost amounts to precision
+                                   (can unbalance transactions)
+```
 
 `close` currently has six modes, selected by a single mode flag:
 
diff --git a/hledger/Hledger/Cli/Commands/Codes.md b/hledger/Hledger/Cli/Commands/Codes.md
index 58f207196..33f99984d 100644
--- a/hledger/Hledger/Cli/Commands/Codes.md
+++ b/hledger/Hledger/Cli/Commands/Codes.md
@@ -2,7 +2,10 @@
 
 List the codes seen in transactions, in the order parsed.
 
-_FLAGS
+```flags
+Flags:
+no command-specific flags
+```
 
 This command prints the value of each transaction's code field, in the
 order transactions were parsed. The transaction code is an optional
diff --git a/hledger/Hledger/Cli/Commands/Commodities.md b/hledger/Hledger/Cli/Commands/Commodities.md
index b5d4dc589..465ffe6ab 100644
--- a/hledger/Hledger/Cli/Commands/Commodities.md
+++ b/hledger/Hledger/Cli/Commands/Commodities.md
@@ -2,4 +2,8 @@
 
 List all commodity/currency symbols used or declared in the journal.
 
-_FLAGS
+```flags
+Flags:
+no command-specific flags
+```
+
diff --git a/hledger/Hledger/Cli/Commands/Demo.md b/hledger/Hledger/Cli/Commands/Demo.md
index f7e5f5702..3ca971d8f 100644
--- a/hledger/Hledger/Cli/Commands/Demo.md
+++ b/hledger/Hledger/Cli/Commands/Demo.md
@@ -2,7 +2,11 @@
 
 Play demos of hledger usage in the terminal, if asciinema is installed.
 
-_FLAGS
+```flags
+Flags:
+  -s --speed=SPEED  playback speed (1 is original speed, .5 is half, 2 is
+                    double, etc (default: 2))
+```
 
 Run this command with no argument to list the demos.
 To play a demo, write its number or a prefix or substring of its title.
diff --git a/hledger/Hledger/Cli/Commands/Descriptions.md b/hledger/Hledger/Cli/Commands/Descriptions.md
index 1db645707..5984df825 100644
--- a/hledger/Hledger/Cli/Commands/Descriptions.md
+++ b/hledger/Hledger/Cli/Commands/Descriptions.md
@@ -2,7 +2,10 @@
 
 List the unique descriptions that appear in transactions.
 
-_FLAGS
+```flags
+Flags:
+no command-specific flags
+```
 
 This command lists the unique descriptions that appear in transactions,
 in alphabetic order.
diff --git a/hledger/Hledger/Cli/Commands/Diff.md b/hledger/Hledger/Cli/Commands/Diff.md
index 5e15023a9..0f24e6c49 100644
--- a/hledger/Hledger/Cli/Commands/Diff.md
+++ b/hledger/Hledger/Cli/Commands/Diff.md
@@ -16,7 +16,10 @@ from your bank (eg as CSV data). When hledger and your bank disagree
 about the account balance, you can compare the bank data with your
 journal to find out the cause. 
 
-_FLAGS
+```flags
+Flags:
+no command-specific flags
+```
 
 Examples:
 
diff --git a/hledger/Hledger/Cli/Commands/Files.md b/hledger/Hledger/Cli/Commands/Files.md
index a88c56e33..3a54ceeab 100644
--- a/hledger/Hledger/Cli/Commands/Files.md
+++ b/hledger/Hledger/Cli/Commands/Files.md
@@ -3,4 +3,7 @@
 List all files included in the journal. With a REGEX argument,
 only file names matching the regular expression (case sensitive) are shown.
 
-_FLAGS
+```flags
+Flags:
+no command-specific flags
+```
diff --git a/hledger/Hledger/Cli/Commands/Help.md b/hledger/Hledger/Cli/Commands/Help.md
index 79924b8ff..0d4d6ed51 100644
--- a/hledger/Hledger/Cli/Commands/Help.md
+++ b/hledger/Hledger/Cli/Commands/Help.md
@@ -3,7 +3,13 @@
 Show the hledger user manual with `info`, `man`, or a pager.
 With a (case insensitive) TOPIC argument, try to open it at that section heading.
 
-_FLAGS
+```flags
+Flags:
+  -i            show the manual with info
+  -m            show the manual with man
+  -p            show the manual with $PAGER or less
+                (less is always used if TOPIC is specified)
+```
 
 This command shows the hledger manual built in to your hledger executable.
 It can be useful when offline, or when you prefer the terminal to a web browser,
diff --git a/hledger/Hledger/Cli/Commands/Import.md b/hledger/Hledger/Cli/Commands/Import.md
index d7893d1e1..7172fd4c8 100644
--- a/hledger/Hledger/Cli/Commands/Import.md
+++ b/hledger/Hledger/Cli/Commands/Import.md
@@ -2,7 +2,11 @@
 
 Import new transactions from one or more data files to the main journal.
 
-_FLAGS
+```flags
+Flags:
+     --catchup              just mark all transactions as already imported
+     --dry-run              just show the transactions to be imported
+```
 
 This command detects new transactions in each FILE argument since it was last run, 
 and appends them to the main journal.
diff --git a/hledger/Hledger/Cli/Commands/Incomestatement.md b/hledger/Hledger/Cli/Commands/Incomestatement.md
index 37ab30309..314c2b7e2 100644
--- a/hledger/Hledger/Cli/Commands/Incomestatement.md
+++ b/hledger/Hledger/Cli/Commands/Incomestatement.md
@@ -5,7 +5,51 @@
 Show revenue inflows and expense outflows during the report period.
 Amounts are shown with normal positive sign, as in conventional financial statements.
 
-_FLAGS
+```flags
+Flags:
+     --sum                  show sum of posting amounts (default)
+     --valuechange          show total change of period-end historical
+                            balance value (caused by deposits, withdrawals,
+                            market price fluctuations)
+     --gain                 show unrealised capital gain/loss (historical
+                            balance value minus cost basis)
+     --budget               show sum of posting amounts compared to budget
+                            goals defined by periodic transactions
+     --change               accumulate amounts from column start to column
+                            end (in multicolumn reports) (default)
+     --cumulative           accumulate amounts from report start (specified
+                            by e.g. -b/--begin) to column end
+  -H --historical           accumulate amounts from journal start to column
+                            end (includes postings before report start date)
+  -l --flat                 show accounts as a flat list (default). Amounts
+                            exclude subaccount amounts, except where the
+                            account is depth-clipped.
+  -t --tree                 show accounts as a tree. Amounts include
+                            subaccount amounts.
+     --drop=N               flat mode: omit N leading account name parts
+     --declared             include non-parent declared accounts (best used
+                            with -E)
+  -A --average              show a row average column (in multicolumn
+                            reports)
+  -T --row-total            show a row total column (in multicolumn reports)
+     --summary-only         display only row summaries (e.g. row total,
+                            average) (in multicolumn reports)
+  -N --no-total             omit the final total row
+     --no-elide             don't squash boring parent accounts (in tree
+                            mode)
+     --format=FORMATSTR     use this custom line format (in simple reports)
+  -S --sort-amount          sort by amount instead of account code/name
+  -% --percent              express values in percentage of each column's
+                            total
+     --layout=ARG           how to show multi-commodity amounts:
+                            'wide[,WIDTH]': all commodities on one line
+                            'tall'        : each commodity on a new line
+                            'bare'        : bare numbers, symbols in a column
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+```
 
 This command displays an [income statement](http://en.wikipedia.org/wiki/Income_statement), 
 showing revenues and expenses during one or more periods. 
diff --git a/hledger/Hledger/Cli/Commands/Notes.md b/hledger/Hledger/Cli/Commands/Notes.md
index b86264e0e..15eab6d21 100644
--- a/hledger/Hledger/Cli/Commands/Notes.md
+++ b/hledger/Hledger/Cli/Commands/Notes.md
@@ -2,7 +2,10 @@
 
 List the unique notes that appear in transactions.
 
-_FLAGS
+```flags
+Flags:
+no command-specific flags
+```
 
 This command lists the unique notes that appear in transactions,
 in alphabetic order.
diff --git a/hledger/Hledger/Cli/Commands/Payees.md b/hledger/Hledger/Cli/Commands/Payees.md
index 459bc8d61..1f160347a 100644
--- a/hledger/Hledger/Cli/Commands/Payees.md
+++ b/hledger/Hledger/Cli/Commands/Payees.md
@@ -2,7 +2,11 @@
 
 List the unique payee/payer names that appear in transactions.
 
-_FLAGS
+```flags
+Flags:
+     --declared             show payees declared with payee directives
+     --used                 show payees referenced by transactions
+```
 
 This command lists unique payee/payer names which have been 
 declared with payee directives (--declared), 
diff --git a/hledger/Hledger/Cli/Commands/Prices.md b/hledger/Hledger/Cli/Commands/Prices.md
index 666a95cd5..9cdb61cce 100644
--- a/hledger/Hledger/Cli/Commands/Prices.md
+++ b/hledger/Hledger/Cli/Commands/Prices.md
@@ -14,4 +14,8 @@ it will show the same prices used internally to calculate value reports.
 But if in doubt, you can inspect those directly by running the value report
 with --debug=2.
 
-_FLAGS
+```flags
+Flags:
+     --show-reverse         also show the prices inferred by reversing known
+                            prices
+```
diff --git a/hledger/Hledger/Cli/Commands/Print.md b/hledger/Hledger/Cli/Commands/Print.md
index 5f3dfd9c2..22ecd5c34 100644
--- a/hledger/Hledger/Cli/Commands/Print.md
+++ b/hledger/Hledger/Cli/Commands/Print.md
@@ -2,7 +2,30 @@
 
 Show full journal entries, representing transactions.
 
-_FLAGS
+```flags
+Flags:
+  -x --explicit             show all amounts explicitly
+     --show-costs           show transaction prices even with conversion
+                            postings
+     --round=TYPE           how much rounding or padding should be done when
+                            displaying amounts ?
+                            none - show original decimal digits,
+                                   as in journal
+                            soft - just add or remove decimal zeros
+                                   to match precision (default)
+                            hard - round posting amounts to precision
+                                   (can unbalance transactions)
+                            all  - also round cost amounts to precision
+                                   (can unbalance transactions)
+     --new                  show only newer-dated transactions added in each
+                            file since last run
+  -m --match=DESC           fuzzy search for one recent transaction with
+                            description closest to DESC
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, beancount, csv, tsv, json, sql.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+```
 
 The print command displays full journal entries (transactions) 
 from the journal file, sorted by date
diff --git a/hledger/Hledger/Cli/Commands/README.md b/hledger/Hledger/Cli/Commands/README.md
index 82d34e65a..8da520dd6 100644
--- a/hledger/Hledger/Cli/Commands/README.md
+++ b/hledger/Hledger/Cli/Commands/README.md
@@ -30,44 +30,29 @@ Here are more special features/conventions of command doc files (see
 
 - The content is pandoc markdown. m4 macros are not supported.
 
-- In manuals, they are rendered with formatting and hyperlinks when
-  supported by the various output formats.
+- The format is "hledger command help". Basically there should be
+  a command name and blank line,
+  an optional parenthesised command alias/abbreviation and blank line,
+  a short help preamble,
+  a code block with `flags` class containing a `Flags:` line
+  then the command-specific flags help output (or "none"),
+  and an optional longer help postamble.
+  See parseCommandHelp in ../CliOptions.hs for the exact format.
 
-- In command line help, they are rendered as plain text, with verbatim
-  blocks unindented, and with lines longer than 78 characters wrapped
-  (unless they contain no spaces).
+- In manuals, these are rendered with formatting and hyperlinks in
+  output formats which support those.
 
-- To avoid unsightly line wrapping in command line help, try to keep
-  verbatim examples to at most 78 characters wide. When necessary, we
-  may be forced to cheat and alter command output slightly, eg
-  reducing the width of register's typically 79-wide reports by one.
+- In --help output, they are rendered
 
-- The first line should specify the command name and any aliases, as
-  words separated by spaces and/or commas. It should end with a
-  backslash (to force a line break in the output).
-
-- Short help, about one paragraph in length, should begin on the
-  second line.
-
-- If the short help is more than one line, its first line should end
-  with a single newline, not two (otherwise it will be displayed with
-  two newlines after each line in command line help).
-
-- In command line help, the short help is displayed with blank lines
-  removed (paragraphs run together). Blank lines can still be used for
-  markdown formatting though, eg to define a list.
-
-- After the short help, there should be a paragraph containing just
-  _FLAGS. This marks the end of the short help, and it will be
-  replaced in command line help by the flags list. (Without it, the
-  flags list appears at the end of command line help.) The flags list
-  will not appear in the hledger manual.
-
-- Long help (as many paragraphs as needed) follows the _FLAGS marker.
-  This often ends with one or more examples.
-
-
-XXX Command docs with examples wider than 78:
-close
-rewrite
+  - as plain text
+  - with blank lines removed from the preamble
+  - with lines longer than 78 characters wrapped (unless they contain no spaces)
+  - with code blocks unindented
+  - with the `flags` code block replaced by dynamically generated flags help
+    (for both command-specific and general flags)
 
+The postamble often ends with one or more examples.
+To avoid unsightly line wrapping in command line help, try to keep
+code blocks to at most 78 characters wide. When necessary, we may be
+forced to cheat and alter command output slightly, eg reducing the
+width of register's typically 79-wide reports by one.
diff --git a/hledger/Hledger/Cli/Commands/Register.hs b/hledger/Hledger/Cli/Commands/Register.hs
index 6988d0a62..d03c277a0 100644
--- a/hledger/Hledger/Cli/Commands/Register.hs
+++ b/hledger/Hledger/Cli/Commands/Register.hs
@@ -41,7 +41,7 @@ registermode = hledgerCommandMode
   ([flagNone ["cumulative"] (setboolopt "cumulative")
      "show running total from report start date (default)"
   ,flagNone ["historical","H"] (setboolopt "historical")
-     "show historical running total/balance (includes postings before report start date)\n "
+     "show historical running total/balance (includes postings before report start date)"
   ,flagNone ["average","A"] (setboolopt "average")
      "show running average of posting amounts instead of total (implies --empty)"
   ,let arg = "DESC" in
diff --git a/hledger/Hledger/Cli/Commands/Register.md b/hledger/Hledger/Cli/Commands/Register.md
index 717c09179..a983d5f80 100644
--- a/hledger/Hledger/Cli/Commands/Register.md
+++ b/hledger/Hledger/Cli/Commands/Register.md
@@ -4,7 +4,26 @@
 
 Show postings and their running total.
 
-_FLAGS
+```flags
+Flags:
+     --cumulative           show running total from report start date
+                            (default)
+  -H --historical           show historical running total/balance (includes
+                            postings before report start date)
+  -A --average              show running average of posting amounts instead
+                            of total (implies --empty)
+  -m --match=DESC           fuzzy search for one recent posting with
+                            description closest to DESC
+  -r --related              show postings' siblings instead
+     --invert               display all amounts with reversed sign
+  -w --width=N              set output width (default: terminal width or
+                            $COLUMNS). -wN,M sets description width as well.
+     --align-all            guarantee alignment across all lines (slower)
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+```
 
 The register command displays matched postings, across all accounts,
 in date order, with their running total or running historical balance.
diff --git a/hledger/Hledger/Cli/Commands/Rewrite.md b/hledger/Hledger/Cli/Commands/Rewrite.md
index be1a9a4c3..54d2774bf 100644
--- a/hledger/Hledger/Cli/Commands/Rewrite.md
+++ b/hledger/Hledger/Cli/Commands/Rewrite.md
@@ -3,7 +3,17 @@
 Print all transactions, rewriting the postings of matched transactions.
 For now the only rewrite available is adding new postings, like print --auto.
 
-_FLAGS
+```flags
+Flags:
+     --add-posting='ACCT  AMTEXPR'  add a posting to ACCT, which may be
+                                    parenthesised. AMTEXPR is either a literal
+                                    amount, or *N which means the transaction's
+                                    first matched amount multiplied by N (a
+                                    decimal number). Two spaces separate ACCT
+                                    and AMTEXPR.
+     --diff                         generate diff suitable as an input for
+                                    patch tool
+```
 
 This is a start at a generic rewriter of transaction entries.
 It reads the default journal and prints the transactions, like print,
diff --git a/hledger/Hledger/Cli/Commands/Roi.md b/hledger/Hledger/Cli/Commands/Roi.md
index 73357991d..b656409bb 100644
--- a/hledger/Hledger/Cli/Commands/Roi.md
+++ b/hledger/Hledger/Cli/Commands/Roi.md
@@ -3,7 +3,14 @@
 Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
 on your investments.
 
-_FLAGS
+```flags
+Flags:
+     --cashflow                 show all amounts that were used to compute
+                                returns
+     --investment=QUERY         query to select your investment transactions
+     --profit-loss=QUERY --pnl  query to select profit-and-loss or
+                                appreciation/valuation transactions
+```
 
 At a minimum, you need to supply a query (which could be just an
 account name) to select your investment(s) with `--inv`, and another
diff --git a/hledger/Hledger/Cli/Commands/Stats.md b/hledger/Hledger/Cli/Commands/Stats.md
index 85a0227cc..2da7a3f36 100644
--- a/hledger/Hledger/Cli/Commands/Stats.md
+++ b/hledger/Hledger/Cli/Commands/Stats.md
@@ -2,7 +2,11 @@
 
 Show journal and performance statistics.
 
-_FLAGS
+```flags
+Flags:
+  -v --verbose              show more detailed output
+  -o --output-file=FILE     write output to FILE.
+```
 
 The stats command shows summary information for the whole journal, or
 a matched part of it. With a [reporting interval](#reporting-interval),
diff --git a/hledger/Hledger/Cli/Commands/Tags.md b/hledger/Hledger/Cli/Commands/Tags.md
index a0bddc1a1..659e17997 100644
--- a/hledger/Hledger/Cli/Commands/Tags.md
+++ b/hledger/Hledger/Cli/Commands/Tags.md
@@ -4,7 +4,12 @@ List the tags used in the journal, or their values.
 
 <!-- same section name as Journal > Tags, if reordering these update all #tags[-1] links -->
 
-_FLAGS
+```flags
+Flags:
+     --values               list tag values instead of tag names
+     --parsed               show tags/values in the order they were parsed,
+                            including duplicates
+```
 
 This command lists the tag names used in the journal,
 whether on transactions, postings, or account declarations.
diff --git a/hledger/Hledger/Cli/Commands/Test.md b/hledger/Hledger/Cli/Commands/Test.md
index 1300b506e..a04890551 100644
--- a/hledger/Hledger/Cli/Commands/Test.md
+++ b/hledger/Hledger/Cli/Commands/Test.md
@@ -2,7 +2,10 @@
 
 Run built-in unit tests.
 
-_FLAGS
+```flags
+Flags:
+no command-specific flags
+```
 
 This command runs the unit tests built in to hledger and hledger-lib,
 printing the results on stdout. If any test fails, the exit code will
diff --git a/hledger/Hledger/Cli/CompoundBalanceCommand.hs b/hledger/Hledger/Cli/CompoundBalanceCommand.hs
index fec0983d8..df07a6f1e 100644
--- a/hledger/Hledger/Cli/CompoundBalanceCommand.hs
+++ b/hledger/Hledger/Cli/CompoundBalanceCommand.hs
@@ -44,7 +44,7 @@ import Hledger.Cli.Utils (unsupportedOutputFormatError, writeOutputLazyText)
 -- it should be added to or subtracted from the grand total.
 --
 data CompoundBalanceCommandSpec = CompoundBalanceCommandSpec {
-  cbcdoc      :: CommandDoc,                      -- ^ the command's name(s) and documentation
+  cbcdoc      :: CommandHelpStr,                  -- ^ the command's name(s) and documentation
   cbctitle    :: String,                          -- ^ overall report title
   cbcqueries  :: [CBCSubreportSpec DisplayName],  -- ^ subreport details
   cbcaccum    :: BalanceAccumulation              -- ^ how to accumulate balances (per-period, cumulative, historical)
@@ -64,7 +64,7 @@ compoundBalanceCommandMode CompoundBalanceCommandSpec{..} =
     ,flagNone ["gain"] (setboolopt "gain")
       "show unrealised capital gain/loss (historical balance value minus cost basis)"
    ,flagNone ["budget"] (setboolopt "budget")
-      "show sum of posting amounts compared to budget goals defined by periodic transactions\n "
+      "show sum of posting amounts compared to budget goals defined by periodic transactions"
 
    ,flagNone ["change"] (setboolopt "change")
        ("accumulate amounts from column start to column end (in multicolumn reports)"
@@ -74,7 +74,7 @@ compoundBalanceCommandMode CompoundBalanceCommandSpec{..} =
            ++ defaultMarker Cumulative)
     ,flagNone ["historical","H"] (setboolopt "historical")
        ("accumulate amounts from journal start to column end (includes postings before report start date)"
-           ++ defaultMarker Historical ++ "\n ")
+           ++ defaultMarker Historical)
     ]
     ++ flattreeflags True ++
     [flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"