From 0567935e4b07c09b1f63c6c4301f9dcf70d1c89e Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 5 Jan 2023 09:04:19 -1000 Subject: [PATCH] cli: simplify command doc inclusion, give them normal heading structure --- hledger/Hledger/Cli/CliOptions.hs | 31 +++++---- hledger/Hledger/Cli/Commands/Accounts.md | 3 +- hledger/Hledger/Cli/Commands/Activity.md | 3 +- hledger/Hledger/Cli/Commands/Add.md | 3 +- hledger/Hledger/Cli/Commands/Aregister.md | 4 +- hledger/Hledger/Cli/Commands/Balance.md | 5 +- hledger/Hledger/Cli/Commands/Balancesheet.md | 5 +- .../Cli/Commands/Balancesheetequity.md | 5 +- hledger/Hledger/Cli/Commands/Cashflow.md | 5 +- hledger/Hledger/Cli/Commands/Check.md | 3 +- hledger/Hledger/Cli/Commands/Close.md | 5 +- hledger/Hledger/Cli/Commands/Codes.md | 3 +- hledger/Hledger/Cli/Commands/Commodities.md | 3 +- hledger/Hledger/Cli/Commands/Descriptions.md | 3 +- hledger/Hledger/Cli/Commands/Diff.md | 3 +- hledger/Hledger/Cli/Commands/Files.md | 3 +- hledger/Hledger/Cli/Commands/Help.md | 3 +- hledger/Hledger/Cli/Commands/Import.md | 3 +- .../Hledger/Cli/Commands/Incomestatement.md | 5 +- hledger/Hledger/Cli/Commands/Notes.md | 3 +- hledger/Hledger/Cli/Commands/Payees.md | 3 +- hledger/Hledger/Cli/Commands/Prices.md | 3 +- hledger/Hledger/Cli/Commands/Print.md | 3 +- hledger/Hledger/Cli/Commands/Register.md | 5 +- hledger/Hledger/Cli/Commands/Rewrite.md | 3 +- hledger/Hledger/Cli/Commands/Roi.md | 3 +- hledger/Hledger/Cli/Commands/Stats.md | 3 +- hledger/Hledger/Cli/Commands/Tags.md | 5 +- hledger/Hledger/Cli/Commands/Test.md | 3 +- hledger/Hledger/Cli/Commands/commands.m4 | 66 +++++++++---------- hledger/hledger.m4.md | 5 +- 31 files changed, 128 insertions(+), 75 deletions(-) diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs index 1378e0653..7a0a368a3 100644 --- a/hledger/Hledger/Cli/CliOptions.hs +++ b/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 diff --git a/hledger/Hledger/Cli/Commands/Accounts.md b/hledger/Hledger/Cli/Commands/Accounts.md index e5995ba7c..ce21d94fb 100644 --- a/hledger/Hledger/Cli/Commands/Accounts.md +++ b/hledger/Hledger/Cli/Commands/Accounts.md @@ -1,4 +1,5 @@ -accounts\ +## accounts + Show account names. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Activity.md b/hledger/Hledger/Cli/Commands/Activity.md index b8289a914..fd6d03188 100644 --- a/hledger/Hledger/Cli/Commands/Activity.md +++ b/hledger/Hledger/Cli/Commands/Activity.md @@ -1,4 +1,5 @@ -activity\ +## activity + Show an ascii barchart of posting counts per interval. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Add.md b/hledger/Hledger/Cli/Commands/Add.md index 8d4d85531..b49bbcc27 100644 --- a/hledger/Hledger/Cli/Commands/Add.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Aregister.md b/hledger/Hledger/Cli/Commands/Aregister.md index c9470c586..b14883bb1 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Balance.md b/hledger/Hledger/Cli/Commands/Balance.md index 3be902d25..bdf360468 100644 --- a/hledger/Hledger/Cli/Commands/Balance.md +++ b/hledger/Hledger/Cli/Commands/Balance.md @@ -1,4 +1,7 @@ -balance, bal\ +## balance + +(bal) + Show accounts and their balances. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Balancesheet.md b/hledger/Hledger/Cli/Commands/Balancesheet.md index db0a8204e..ba95bc170 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheet.md +++ b/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.) diff --git a/hledger/Hledger/Cli/Commands/Balancesheetequity.md b/hledger/Hledger/Cli/Commands/Balancesheetequity.md index ec5ad1191..f1287bb65 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheetequity.md +++ b/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 diff --git a/hledger/Hledger/Cli/Commands/Cashflow.md b/hledger/Hledger/Cli/Commands/Cashflow.md index 91f5980eb..0f60131e0 100644 --- a/hledger/Hledger/Cli/Commands/Cashflow.md +++ b/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 diff --git a/hledger/Hledger/Cli/Commands/Check.md b/hledger/Hledger/Cli/Commands/Check.md index 47cfce4d5..bb89757fb 100644 --- a/hledger/Hledger/Cli/Commands/Check.md +++ b/hledger/Hledger/Cli/Commands/Check.md @@ -1,4 +1,5 @@ -check\ +## check + Check for various kinds of errors in your data. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md index 62472b9d7..46e05fe1d 100644 --- a/hledger/Hledger/Cli/Commands/Close.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Codes.md b/hledger/Hledger/Cli/Commands/Codes.md index 3e599e0db..183e3ba5c 100644 --- a/hledger/Hledger/Cli/Commands/Codes.md +++ b/hledger/Hledger/Cli/Commands/Codes.md @@ -1,4 +1,5 @@ -codes\ +## codes + List the codes seen in transactions, in the order parsed. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Commodities.md b/hledger/Hledger/Cli/Commands/Commodities.md index c09581712..b5d4dc589 100644 --- a/hledger/Hledger/Cli/Commands/Commodities.md +++ b/hledger/Hledger/Cli/Commands/Commodities.md @@ -1,4 +1,5 @@ -commodities\ +## commodities + List all commodity/currency symbols used or declared in the journal. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Descriptions.md b/hledger/Hledger/Cli/Commands/Descriptions.md index 885b1b11c..686cbb794 100644 --- a/hledger/Hledger/Cli/Commands/Descriptions.md +++ b/hledger/Hledger/Cli/Commands/Descriptions.md @@ -1,4 +1,5 @@ -descriptions\ +## descriptions + List the unique descriptions that appear in transactions. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Diff.md b/hledger/Hledger/Cli/Commands/Diff.md index 1d38def8a..926ce799d 100644 --- a/hledger/Hledger/Cli/Commands/Diff.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Files.md b/hledger/Hledger/Cli/Commands/Files.md index 57508bcb0..a88c56e33 100644 --- a/hledger/Hledger/Cli/Commands/Files.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Help.md b/hledger/Hledger/Cli/Commands/Help.md index 0c6321da4..d44fdc8b6 100644 --- a/hledger/Hledger/Cli/Commands/Help.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Import.md b/hledger/Hledger/Cli/Commands/Import.md index aa8eaa1b4..c10ad1405 100644 --- a/hledger/Hledger/Cli/Commands/Import.md +++ b/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' diff --git a/hledger/Hledger/Cli/Commands/Incomestatement.md b/hledger/Hledger/Cli/Commands/Incomestatement.md index 751638f83..4e751fba7 100644 --- a/hledger/Hledger/Cli/Commands/Incomestatement.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Notes.md b/hledger/Hledger/Cli/Commands/Notes.md index c79c3273b..1a4d73477 100644 --- a/hledger/Hledger/Cli/Commands/Notes.md +++ b/hledger/Hledger/Cli/Commands/Notes.md @@ -1,4 +1,5 @@ -notes\ +## notes + List the unique notes that appear in transactions. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Payees.md b/hledger/Hledger/Cli/Commands/Payees.md index 20d35de94..1063babea 100644 --- a/hledger/Hledger/Cli/Commands/Payees.md +++ b/hledger/Hledger/Cli/Commands/Payees.md @@ -1,4 +1,5 @@ -payees\ +## payees + List the unique payee/payer names that appear in transactions. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Prices.md b/hledger/Hledger/Cli/Commands/Prices.md index d4a0204bd..ca09306fc 100644 --- a/hledger/Hledger/Cli/Commands/Prices.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Print.md b/hledger/Hledger/Cli/Commands/Print.md index ceef1056a..f60049dae 100644 --- a/hledger/Hledger/Cli/Commands/Print.md +++ b/hledger/Hledger/Cli/Commands/Print.md @@ -1,4 +1,5 @@ -print\ +## print + Show transaction journal entries, sorted by date. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Register.md b/hledger/Hledger/Cli/Commands/Register.md index 6a7482a7f..6e96fb066 100644 --- a/hledger/Hledger/Cli/Commands/Register.md +++ b/hledger/Hledger/Cli/Commands/Register.md @@ -1,4 +1,7 @@ -register, reg\ +## register + +(reg) + Show postings and their running total. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Rewrite.md b/hledger/Hledger/Cli/Commands/Rewrite.md index a36e0457c..5501093dd 100644 --- a/hledger/Hledger/Cli/Commands/Rewrite.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Roi.md b/hledger/Hledger/Cli/Commands/Roi.md index b7900b86f..6350b0d5a 100644 --- a/hledger/Hledger/Cli/Commands/Roi.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Stats.md b/hledger/Hledger/Cli/Commands/Stats.md index 047eedac6..bbafcaa14 100644 --- a/hledger/Hledger/Cli/Commands/Stats.md +++ b/hledger/Hledger/Cli/Commands/Stats.md @@ -1,4 +1,5 @@ -stats\ +## stats + Show journal and performance statistics. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Tags.md b/hledger/Hledger/Cli/Commands/Tags.md index 18cd07f40..a0bddc1a1 100644 --- a/hledger/Hledger/Cli/Commands/Tags.md +++ b/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. diff --git a/hledger/Hledger/Cli/Commands/Test.md b/hledger/Hledger/Cli/Commands/Test.md index 2709fccd6..358c83125 100644 --- a/hledger/Hledger/Cli/Commands/Test.md +++ b/hledger/Hledger/Cli/Commands/Test.md @@ -1,4 +1,5 @@ -test\ +## test + Run built-in unit tests. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/commands.m4 b/hledger/Hledger/Cli/Commands/commands.m4 index 73e6d2775..70f5be546 100644 --- a/hledger/Hledger/Cli/Commands/commands.m4 +++ b/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 diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 2da71e53a..6376747e3 100644 --- a/hledger/hledger.m4.md +++ b/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_