doc: update command docs readme

hledger/Hledger/Cli/Commands/README

@@ -1,37 +1,73 @@
 hledger's built-in commands.
 
-Each command has a similarly-named module, Somecommand.hs.
+Each command has a similarly-named code module, Somecommand.hs, and
+documentation file, Somecommand.md.
 
-Each command's help is kept in Somecommand.md. 
+The command doc is converted to plain text in Somecommand.txt, and
-This file is included by Somecommand.hs to help build the command's --help output,
+which is included by Somecommand.hs to form command line help (the
-and by hledger/hledger_commands.m4.md to help build the hledger manual.
+output of `hledger COMMAND --help`).
-It has some special features:
 
-- The first line should specify the command name and any aliases,
+After changing md files, regenerating and committing the txt files is
-  as space or comma-separated words, and be terminated by a backslash
+optional. If you don't do it, it will get done later (before release).
-  (forcing a line break in the output). The help content should begin on line 2.
+It can be done by:
-  Eg:
 
-      close, equity\
+    ./Shake commandhelp
-      Prints a "closing balances" transaction...
 
-- A line containing just _FLAGS_ will be replaced in --help output by
+Or, by you can regenerate them while also building packages:
-  the command's flags list. Lines above _FLAGS_ are known as the short help.
-  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,
+    ./Shake hledger   # or, all packages: ./Shake build
-  especially the html version. But the markup will also appear
-  uninterpreted in the --help output, so use sparingly.
-  m4 macros can not be used.
 
-- Use only one newline on the first line (or cmdargs will display the
+Builds made with stack, cabal, etc. won't notice changes in these md
-  short help with two newlines after each line). This also means
+files, so use the above method if you need that.
-  cmdargs will strip out any blank lines, which prevents use of some
-  markdown features.
 
-- Keep the width of short help lines to 76 characters or less, or
+The md files are also included by hledger/hledger_commands.m4.md to
-  cmdargs will insert newlines. (In Emacs: C-u 77 C-x f).
+form the hledger manual, which can be regenerated with:
+
+    ./Shake manuals [website]
+
+Here are more special features/conventions of command doc files (see
+*.md for examples):
+
+- 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.
+
+- 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).
+
+- 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.
+
+- 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
 
-- GHC, stack, cabal, ghcid etc. won't notice changes in this file;
-  you have to also touch the .hs file.