From 845fdf83029e6f0a8d79a10c02e9a045aad9faf5 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 30 Jan 2019 17:58:23 -0800 Subject: [PATCH] doc: update command docs readme --- hledger/Hledger/Cli/Commands/README | 90 ++++++++++++++++++++--------- 1 file changed, 63 insertions(+), 27 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/README b/hledger/Hledger/Cli/Commands/README index 778884f25..34ffde947 100644 --- a/hledger/Hledger/Cli/Commands/README +++ b/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. -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 command doc is converted to plain text in Somecommand.txt, and +which is included by Somecommand.hs to form command line help (the +output of `hledger COMMAND --help`). -- The first line should specify the command name and any aliases, - as space or comma-separated words, and be terminated by a backslash - (forcing a line break in the output). The help content should begin on line 2. - Eg: +After changing md files, regenerating and committing the txt files is +optional. If you don't do it, it will get done later (before release). +It can be done by: - close, equity\ - Prints a "closing balances" transaction... + ./Shake commandhelp -- A line containing just _FLAGS_ will be replaced in --help output by - 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. +Or, by you can regenerate them while also building packages: -- 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. - m4 macros can not be used. + ./Shake hledger # or, all packages: ./Shake build -- Use only one newline on the first line (or cmdargs will display the - short help with two newlines after each line). This also means - cmdargs will strip out any blank lines, which prevents use of some - markdown features. +Builds made with stack, cabal, etc. won't notice changes in these md +files, so use the above method if you need that. -- Keep the width of short help lines to 76 characters or less, or - cmdargs will insert newlines. (In Emacs: C-u 77 C-x f). +The md files are also included by hledger/hledger_commands.m4.md to +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.