add: integrate CLI help & manual

2019-01-26 17:13:44 -08:00 · 2019-01-26 17:13:44 -08:00 · 64d78f1644
commit 64d78f1644
parent 53620d0df2
6 changed files with 179 additions and 187 deletions
--- a/hledger/Hledger/Cli/Commands/Add.hs
+++ b/hledger/Hledger/Cli/Commands/Add.hs
@ -4,6 +4,7 @@ A history-aware add command to help with data entry.

 {-# OPTIONS_GHC -fno-warn-missing-signatures -fno-warn-unused-do-bind #-}
 {-# LANGUAGE ScopedTypeVariables, DeriveDataTypeable, RecordWildCards, TypeOperators, FlexibleContexts, OverloadedStrings, PackageImports #-}
+{-# LANGUAGE TemplateHaskell #-}

 module Hledger.Cli.Commands.Add (
   addmode
@ -46,17 +47,12 @@ import Hledger.Cli.CliOptions
 import Hledger.Cli.Commands.Register (postingsReportAsText)


-addmode = (defCommandMode ["add"]) {
-  modeHelp = "prompt for transactions and add them to the journal"
- ,modeHelpSuffix = ["Defaults come from previous similar transactions; use query patterns to restrict these."]
- ,modeGroupFlags = Group {
-     groupUnnamed = [
-      flagNone ["no-new-accounts"]  (\opts -> setboolopt "no-new-accounts" opts) "don't allow creating new accounts"
-     ]
-    ,groupHidden = []
-    ,groupNamed = [generalflagsgroup2]
-    }
- }
+addmode = hledgerCommandMode
+  $(hereFileRelative "Hledger/Cli/Commands/Add.md")
+  [flagNone ["no-new-accounts"]  (\opts -> setboolopt "no-new-accounts" opts) "don't allow creating new accounts"]
+  [generalflagsgroup2]
+  []
+  ([], Just $ argsFlag "[QUERY]")

 -- | State used while entering transactions.
 data EntryState = EntryState {
--- a/hledger/Hledger/Cli/Commands/Add.md
+++ b/hledger/Hledger/Cli/Commands/Add.md
@ -0,0 +1,61 @@
+add\
+Prompt for transactions and add them to the journal.
+
+_FLAGS_
+
+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, 
+which prompts interactively on the console for new transactions, and appends
+them to the journal file (if there are multiple `-f FILE` options, the first file is used.)
+Existing transactions are not changed.
+This is the only hledger command that writes to the journal file.
+
+To use it, just run `hledger add` and follow the prompts.
+You can add as many transactions as you like; when you are finished,
+enter `.` or press control-d or control-c to exit.
+
+Features:
+
+- add tries to provide useful defaults, using the most similar (by description)
+  recent transaction (filtered by the query, if any) as a template.
+- You can also set the initial defaults with command line arguments.
+- [Readline-style edit keys](http://tiswww.case.edu/php/chet/readline/rluserman.html#SEC3)
+  can be used during data entry.
+- The tab key will auto-complete whenever possible - accounts,
+  descriptions, dates (`yesterday`, `today`, `tomorrow`). If the input
+  area is empty, it will insert the default value.
+- If the journal defines a [default commodity](#default-commodity),
+  it will be added to any bare numbers entered.
+- A parenthesised transaction [code](#entries) may be entered following a date.
+- [Comments](#comments) and tags may be entered following a description or amount.
+- If you make a mistake, enter `<` at any prompt to restart the transaction.
+- Input prompts are displayed in a different colour when the terminal supports it.
+
+Example (see the [tutorial](step-by-step.html#record-a-transaction-with-hledger-add) for a detailed explanation):
+
+``` shell
+$ hledger add
+Adding transactions to journal file /src/hledger/examples/sample.journal
+Any command line arguments will be used as defaults.
+Use tab key to complete, readline keys to edit, enter to accept defaults.
+An optional (CODE) may follow transaction dates.
+An optional ; COMMENT may follow descriptions or amounts.
+If you make a mistake, enter < at any prompt to restart the transaction.
+To end a transaction, enter . when prompted.
+To quit, enter . at a date prompt or press control-d or control-c.
+Date [2015/05/22]: 
+Description: supermarket
+Account 1: expenses:food
+Amount  1: $10
+Account 2: assets:checking
+Amount  2 [$-10.0]: 
+Account 3 (or . or enter to finish this transaction): .
+2015/05/22 supermarket
+    expenses:food             $10
+    assets:checking        $-10.0
+
+Save this transaction to the journal ? [y]: 
+Saved.
+Starting the next transaction (. or ctrl-D/ctrl-C to quit)
+Date [2015/05/22]: <CTRL-D> $
+```
--- a/hledger/hledger.1
+++ b/hledger/hledger.1
@ -1409,13 +1409,11 @@ $\ hledger\ activity\ \-\-quarterly
 .fi
 .SS add
 .PP
+add
+.PD 0
+.P
+.PD
 Prompt for transactions and add them to the journal.
-.TP
-.B \f[C]\-\-no\-new\-accounts\f[]
-don\[aq]t allow creating new accounts; helps prevent typos when entering
-account names
-.RS
-.RE
 .PP
 Many hledger users edit their journals directly with a text editor, or
 generate them from CSV.
@ -1432,8 +1430,9 @@ enter \f[C]\&.\f[] or press control\-d or control\-c to exit.
 .PP
 Features:
 .IP \[bu] 2
-add tries to provide useful defaults, using the most similar recent
-transaction (by description) as a template.
+add tries to provide useful defaults, using the most similar (by
+description) recent transaction (filtered by the query, if any) as a
+template.
 .IP \[bu] 2
 You can also set the initial defaults with command line arguments.
 .IP \[bu] 2
--- a/hledger/hledger.info
+++ b/hledger/hledger.info
@ -1071,13 +1071,9 @@ File: hledger.info,  Node: add,  Next: balance,  Prev: activity,  Up: COMMANDS
 4.3 add
 =======

+add
 Prompt for transactions and add them to the journal.

-'--no-new-accounts'
-
-     don't allow creating new accounts; helps prevent typos when
-     entering account names
-
   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, which prompts interactively on the console for new
@ -1092,8 +1088,9 @@ or press control-d or control-c to exit.

   Features:

-   * add tries to provide useful defaults, using the most similar recent
-     transaction (by description) as a template.
+   * add tries to provide useful defaults, using the most similar (by
+     description) recent transaction (filtered by the query, if any) as
+     a template.
   * You can also set the initial defaults with command line arguments.
   * Readline-style edit keys can be used during data entry.
   * The tab key will auto-complete whenever possible - accounts,
@ -2768,94 +2765,94 @@ Node: activity34448
 Ref: #activity34558
 Node: add34941
 Ref: #add35040
-Node: balance37701
-Ref: #balance37812
-Node: Classic balance report40932
-Ref: #classic-balance-report41105
-Node: Customising the classic balance report42474
-Ref: #customising-the-classic-balance-report42702
-Node: Colour support44776
-Ref: #colour-support44943
-Node: Flat mode45116
-Ref: #flat-mode45264
-Node: Depth limited balance reports45677
-Ref: #depth-limited-balance-reports45877
-Node: Multicolumn balance report46333
-Ref: #multicolumn-balance-report46531
-Node: Budget report51771
-Ref: #budget-report51914
-Node: Nested budgets56598
-Ref: #nested-budgets56710
-Ref: #output-format-160190
-Node: balancesheet60268
-Ref: #balancesheet60404
-Node: balancesheetequity62715
-Ref: #balancesheetequity62864
-Node: cashflow63401
-Ref: #cashflow63529
-Node: check-dates65652
-Ref: #check-dates65779
-Node: check-dupes65896
-Ref: #check-dupes66020
-Node: close66157
-Ref: #close66265
-Node: files69678
-Ref: #files69779
-Node: help69920
-Ref: #help70020
-Node: import71094
-Ref: #import71208
-Node: incomestatement71938
-Ref: #incomestatement72072
-Node: prices74476
-Ref: #prices74591
-Node: print74863
-Ref: #print74973
-Node: print-unique79867
-Ref: #print-unique79993
-Node: register80061
-Ref: #register80188
-Node: Custom register output84689
-Ref: #custom-register-output84818
-Node: register-match86048
-Ref: #register-match86182
-Node: rewrite86365
-Ref: #rewrite86480
-Node: roi86549
-Ref: #roi86647
-Node: stats86763
-Ref: #stats86862
-Node: tags87732
-Ref: #tags87830
-Node: test88066
-Ref: #test88150
-Node: ADD-ON COMMANDS88858
-Ref: #add-on-commands88968
-Node: Official add-ons90255
-Ref: #official-add-ons90395
-Node: api90482
-Ref: #api90571
-Node: ui90623
-Ref: #ui90722
-Node: web90780
-Ref: #web90869
-Node: Third party add-ons90915
-Ref: #third-party-add-ons91090
-Node: diff91225
-Ref: #diff91322
-Node: iadd91421
-Ref: #iadd91535
-Node: interest91618
-Ref: #interest91739
-Node: irr91834
-Ref: #irr91932
-Node: Experimental add-ons92063
-Ref: #experimental-add-ons92215
-Node: autosync92495
-Ref: #autosync92606
-Node: chart92845
-Ref: #chart92964
-Node: check93035
-Ref: #check93137
+Node: balance37627
+Ref: #balance37738
+Node: Classic balance report40858
+Ref: #classic-balance-report41031
+Node: Customising the classic balance report42400
+Ref: #customising-the-classic-balance-report42628
+Node: Colour support44702
+Ref: #colour-support44869
+Node: Flat mode45042
+Ref: #flat-mode45190
+Node: Depth limited balance reports45603
+Ref: #depth-limited-balance-reports45803
+Node: Multicolumn balance report46259
+Ref: #multicolumn-balance-report46457
+Node: Budget report51697
+Ref: #budget-report51840
+Node: Nested budgets56524
+Ref: #nested-budgets56636
+Ref: #output-format-160116
+Node: balancesheet60194
+Ref: #balancesheet60330
+Node: balancesheetequity62641
+Ref: #balancesheetequity62790
+Node: cashflow63327
+Ref: #cashflow63455
+Node: check-dates65578
+Ref: #check-dates65705
+Node: check-dupes65822
+Ref: #check-dupes65946
+Node: close66083
+Ref: #close66191
+Node: files69604
+Ref: #files69705
+Node: help69846
+Ref: #help69946
+Node: import71020
+Ref: #import71134
+Node: incomestatement71864
+Ref: #incomestatement71998
+Node: prices74402
+Ref: #prices74517
+Node: print74789
+Ref: #print74899
+Node: print-unique79793
+Ref: #print-unique79919
+Node: register79987
+Ref: #register80114
+Node: Custom register output84615
+Ref: #custom-register-output84744
+Node: register-match85974
+Ref: #register-match86108
+Node: rewrite86291
+Ref: #rewrite86406
+Node: roi86475
+Ref: #roi86573
+Node: stats86689
+Ref: #stats86788
+Node: tags87658
+Ref: #tags87756
+Node: test87992
+Ref: #test88076
+Node: ADD-ON COMMANDS88784
+Ref: #add-on-commands88894
+Node: Official add-ons90181
+Ref: #official-add-ons90321
+Node: api90408
+Ref: #api90497
+Node: ui90549
+Ref: #ui90648
+Node: web90706
+Ref: #web90795
+Node: Third party add-ons90841
+Ref: #third-party-add-ons91016
+Node: diff91151
+Ref: #diff91248
+Node: iadd91347
+Ref: #iadd91461
+Node: interest91544
+Ref: #interest91665
+Node: irr91760
+Ref: #irr91858
+Node: Experimental add-ons91989
+Ref: #experimental-add-ons92141
+Node: autosync92421
+Ref: #autosync92532
+Node: chart92771
+Ref: #chart92890
+Node: check92961
+Ref: #check93063

 End Tag Table
--- a/hledger/hledger.txt
+++ b/hledger/hledger.txt
@ -943,13 +943,10 @@ COMMANDS
              2008-07-01
              2008-10-01 **

+   add
       add
       Prompt for transactions and add them to the journal.

-       --no-new-accounts
-              don't allow creating new  accounts;  helps  prevent  typos  when
-              entering account names
-
       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, which prompts interactively on the console for new  trans-
@ -964,8 +961,9 @@ COMMANDS

       Features:

-       o add  tries  to provide useful defaults, using the most similar recent
-         transaction (by description) as a template.
+       o add tries to provide useful defaults,  using  the  most  similar  (by
+         description)  recent transaction (filtered by the query, if any) as a
+         template.

       o You can also set the initial defaults with command line arguments.

--- a/hledger/hledger_commands.m4.md
+++ b/hledger/hledger_commands.m4.md
@ -32,67 +32,8 @@ _include_(Hledger/Cli/Commands/Accounts.md)
 _include_(Hledger/Cli/Commands/Activity.md)

 ## add
-Prompt for transactions and add them to the journal.

-`--no-new-accounts`
-: don't allow creating new accounts; helps prevent typos when entering account names
-
-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, 
-which prompts interactively on the console for new transactions, and appends
-them to the journal file (if there are multiple `-f FILE` options, the first file is used.)
-Existing transactions are not changed.
-This is the only hledger command that writes to the journal file.
-
-To use it, just run `hledger add` and follow the prompts.
-You can add as many transactions as you like; when you are finished,
-enter `.` or press control-d or control-c to exit.
-
-Features:
-
- add tries to provide useful defaults, using the most similar recent
-  transaction (by description) as a template.
- You can also set the initial defaults with command line arguments.
- [Readline-style edit keys](http://tiswww.case.edu/php/chet/readline/rluserman.html#SEC3)
-  can be used during data entry.
- The tab key will auto-complete whenever possible - accounts,
-  descriptions, dates (`yesterday`, `today`, `tomorrow`). If the input
-  area is empty, it will insert the default value.
- If the journal defines a [default commodity](#default-commodity),
-  it will be added to any bare numbers entered.
- A parenthesised transaction [code](#entries) may be entered following a date.
- [Comments](#comments) and tags may be entered following a description or amount.
- If you make a mistake, enter `<` at any prompt to restart the transaction.
- Input prompts are displayed in a different colour when the terminal supports it.
-
-Example (see the [tutorial](step-by-step.html#record-a-transaction-with-hledger-add) for a detailed explanation):
-
-_shell_({{
-$ hledger add
-Adding transactions to journal file /src/hledger/examples/sample.journal
-Any command line arguments will be used as defaults.
-Use tab key to complete, readline keys to edit, enter to accept defaults.
-An optional (CODE) may follow transaction dates.
-An optional ; COMMENT may follow descriptions or amounts.
-If you make a mistake, enter < at any prompt to restart the transaction.
-To end a transaction, enter . when prompted.
-To quit, enter . at a date prompt or press control-d or control-c.
-Date [2015/05/22]: 
-Description: supermarket
-Account 1: expenses:food
-Amount  1: $10
-Account 2: assets:checking
-Amount  2 [$-10.0]: 
-Account 3 (or . or enter to finish this transaction): .
-2015/05/22 supermarket
-    expenses:food             $10
-    assets:checking        $-10.0
-
-Save this transaction to the journal ? [y]: 
-Saved.
-Starting the next transaction (. or ctrl-D/ctrl-C to quit)
-Date [2015/05/22]: <CTRL-D> $
-}})
+_include_(Hledger/Cli/Commands/Add.md)

 _include_({{hledger_balance.m4.md}})