;doc: update command docs

hledger/Hledger/Cli/Commands/Accounts.txt

@@ -9,43 +9,40 @@ Flags:
      --unused               list accounts declared but not used
      --find                 list the first account matched by the first
                             argument (a case-insensitive infix regexp)
-     --types                also show account types when known
-     --positions            also show where accounts were declared
      --directives           show as account directives, for use in journals
+     --locations            also show where accounts were declared
+     --types                also show account types when known
   -l --flat                 list/tree mode: show accounts as a flat list
                             (default)
   -t --tree                 list/tree mode: show accounts as a tree
      --drop=N               flat mode: omit N leading account name parts
 
-This command lists account names - all of them by default. or just the
+This command lists account names - all of them by default, or just the
-ones which have been used in transactions, or declared with account
+ones which have been used in transactions (-u/--used), or declared with
-directives, or used but not declared, or declared but not used, or just
+account directives (-d/--declared), or used but not declared
-the first account name matched by a pattern.
+(--undeclared), or declared but not used (--unused), or just the first
+one matched by a pattern (--find, returning a non-zero exit code if it
+fails).
 
 You can add query arguments to select a subset of transactions or
 accounts.
 
-It shows a flat list by default. With --tree, it uses indentation to
-show the account hierarchy. In flat mode you can add --drop N to omit
-the first few account name components. Account names can be
-depth-clipped with depth:N or --depth N or -N.
-
-With --types, it also shows each account's type, if it's known. (See
-Declaring accounts > Account types.)
-
-With --positions, it also shows the file and line number of each
-account's declaration, if any, and the account's overall declaration
-order; these may be useful when troubleshooting account display order.
-
 With --directives, it shows valid account directives which could be
 pasted into a journal file. This is useful together with --undeclared
 when updating your account declarations to satisfy
 hledger check accounts.
 
-The --find flag can be used to look up a single account name, in the
+With --locations, it also shows the file and line number of each
-same way that the aregister command does. It returns the
+account's declaration, if any, and the account's overall declaration
-alphanumerically-first matched account name, or if none can be found, it
+order; these may be useful when troubleshooting account display order.
-fails with a non-zero exit code.
+
+With --types, it also shows each account's type, if it's known. (See
+Declaring accounts > Account types.)
+
+It shows a flat list by default. With --tree, it uses indentation to
+show the account hierarchy. In flat mode you can add --drop N to omit
+the first few account name components. Account names can be
+depth-clipped with depth:N or --depth N or -N.
 
 Examples:
 

hledger/Hledger/Cli/Commands/Aregister.txt

@@ -37,24 +37,22 @@ necessarily in historical mode). As a quick rule of thumb: - use
 aregister for reviewing and reconciling real-world asset/liability
 accounts - use register for reviewing detailed revenues/expenses.
 
-aregister requires one argument: the account to report on. You can write
+Note this command's non-standard, and required, first argument; it
-either the full account name, or a case-insensitive regular expression
+specifies the account whose register will be shown. You can write the
-which will select the alphabetically first matched account.
+account's name, or (to save typing) a case-insensitive infix regular
-
+expression matching the name, which selects the alphabetically first
-When there are multiple matches, the alphabetically-first choice can be
+matched account. (For example, if you have assets:personal checking and
-surprising; eg if you have assets:per:checking 1 and
+assets:business checking, hledger areg checking would select
-assets:biz:checking 2 accounts, hledger areg checking would select
+assets:business checking.)
-assets:biz:checking 2. It's just a convenience to save typing, so if in
-doubt, write the full account name, or a distinctive substring that
-matches uniquely.
 
 Transactions involving subaccounts of this account will also be shown.
 aregister ignores depth limits, so its final total will always match a
 historical balance report with similar arguments.
 
-Any additional arguments form a query which will filter the transactions
+Any additional arguments are standard query arguments, which will limit
-shown. Note some queries will disturb the running balance, causing it to
+the transactions shown. Note some queries will disturb the running
-be different from the account's real-world running balance.
+balance, causing it to be different from the account's real-world
+running balance.
 
 An example: this shows the transactions and historical running balance
 during july, in the first account whose name contains "checking":

hledger/Hledger/Cli/Commands/Commodities.txt

@@ -7,10 +7,13 @@ Flags:
      --declared             list commodities declared
      --undeclared           list commodities used but not declared
      --unused               list commodities declared but not used
+     --find                 list the first commodity matched by the first
+                            argument (a case-insensitive infix regexp)
 
 This command lists commodity symbols/names - all of them by default, or
 just the ones which have been used in transactions or P directives, or
 declared with commodity directives, or used but not declared, or
-declared but not used.
+declared but not used, or just the first one matched by a pattern (with
+--find, returning a non-zero exit code if it fails).
 
 You can add cur: query arguments to further limit the commodities.

hledger/Hledger/Cli/Commands/Payees.txt

@@ -7,11 +7,14 @@ Flags:
      --declared             list payees declared
      --undeclared           list payees used but not declared
      --unused               list payees declared but not used
+     --find                 list the first payee matched by the first
+                            argument (a case-insensitive infix regexp)
 
 This command lists unique payee/payer names - all of them by default, or
 just the ones which have been used in transaction descriptions, or
 declared with payee directives, or used but not declared, or declared
-but not used.
+but not used, or just the first one matched by a pattern (with --find,
+returning a non-zero exit code if it fails).
 
 The payee/payer name is the part of the transaction description before a
 | character (or if there is no |, the whole description).

hledger/Hledger/Cli/Commands/Print.md

@@ -11,10 +11,6 @@ Flags:
                             description closest to DESC
      --new                  show only newer-dated transactions added in each
                             file since last run
-     --no-lots              remove lot subaccounts and their balance
-                            assertions
-     --no-lots2             remove lot subaccounts and their costs and
-                            balance assertions (can produce unbalanced entries)
      --round=TYPE           how much rounding or padding should be done when
                             displaying amounts ?
                             none - show original decimal digits,

hledger/Hledger/Cli/Commands/Print.txt

@@ -5,15 +5,11 @@ Show full journal entries, representing transactions.
 Flags:
   -x --explicit             show all amounts explicitly
      --invert               display all amounts with reversed sign
-     --location             add tags showing file paths and line numbers
+     --locations            add tags showing file paths and line numbers
   -m --match=DESC           fuzzy search for one recent transaction with
                             description closest to DESC
      --new                  show only newer-dated transactions added in each
                             file since last run
-     --no-lots              remove lot subaccounts and their balance
-                            assertions
-     --no-lots2             remove lot subaccounts and their costs and
-                            balance assertions (can produce unbalanced entries)
      --round=TYPE           how much rounding or padding should be done when
                             displaying amounts ?
                             none - show original decimal digits,
@@ -56,7 +52,7 @@ $ hledger print -f examples/sample.journal date:200806
     expenses:supplies            $1
     assets:cash                 $-2
 
-print explicitness
+print amount explicitness
 
 Normally, whether posting amounts are implicit or explicit is preserved.
 For example, when an amount is omitted in the journal, it will not
@@ -73,19 +69,22 @@ amount (which can arise when a multi-commodity transaction has an
 implicit amount) to be split into multiple single-commodity postings,
 keeping the output parseable.
 
-print amount style
+print alignment
 
 Amounts are shown right-aligned within each transaction (but not aligned
-across all transactions; you can do that with ledger-mode in Emacs).
+across all transactions; you can achieve that with ledger-mode in
+Emacs).
 
-Amounts will be (mostly) normalised to their commodity display style:
+print amount style
-their symbol placement, decimal mark, and digit group marks will be made
-consistent. By default, decimal digits are shown as they are written in
-the journal.
 
-With the --round (Added in 1.32) option, print will try increasingly
+Amounts will be displayed mostly in their commodity's display style,
-hard to display decimal digits according to the commodity display
+with standardised symbol placement, decimal mark, and digit group marks.
-styles:
+This does not apply to their decimal digits; print normally shows the
+same decimal digits that are recorded in each journal entry.
+
+You can override the decimal precisions with print's special --round
+option (since 1.32). --round tries to show amounts with their
+commodities' standard decimal precisions, increasingly strongly:
 
 - --round=none show amounts with original precisions (default)
 - --round=soft add/remove decimal zeros in amounts (except costs)
@@ -93,30 +92,35 @@ styles:
   digits
 - --round=all round all amounts and costs
 
-soft is good for non-lossy cleanup, formatting amounts more consistently
+soft is good for non-lossy cleanup, displaying more consistent decimals
-where it's safe to do so.
+where possible, without making entries unbalanced.
 
-hard and all can cause print to show invalid unbalanced journal entries;
+hard or all can be good for stronger cleanup, when decimal rounding is
-they may be useful eg for stronger cleanup, with manual fixups when
+wanted. Note rounding can produce unbalanced journal entries, perhaps
-needed.
+requiring manual fixup.
 
 print parseability
 
-print's output is usually a valid hledger journal, and you can process
+Normally, print's output is a valid hledger journal, which you can
-it again with a second hledger command. This can be useful for certain
+"pipe" to a second hledger command for further processing. This is
-kinds of search (though the same can be achieved with expr: queries
+sometimes convenient for achieving certain kinds of query (though less
-now):
+needed now that queries have become more powerful):
 
 # Show running total of food expenses paid from cash.
 # -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
 $ hledger print assets:cash | hledger -f- -I reg expenses:food
 
-There are some situations where print's output can become unparseable:
+But here are some things which can cause print's output to become
+unparseable:
 
-- Value reporting affects posting amounts but not balance assertion or
+- --round (see above) can disrupt transaction balancing.
-  balance assignment amounts, potentially causing those to fail.
+- Account aliases or pivoting can disrupt account names, balance
-- Auto postings can generate postings with too many missing amounts.
+  assertions, or balance assignments.
-- Account aliases can generate bad account names.
+- Value reporting also can disrupt balance assertions or balance
+  assignments.
+- Auto postings can generate too many amountless postings.
+- --infer-costs or --infer-equity can generate too-complex redundant
+  costs.
 
 print, other features
 
@@ -126,28 +130,17 @@ With --invert, posting amounts are shown with their sign flipped. It
 could be useful if you have accidentally recorded some transactions with
 the wrong signs.
 
-With --location, print adds the source file and line number to every
+With --new, print shows only transactions it has not seen on a previous
-transaction, as a tag.
+run. This uses the same deduplication system as the import command. (See
+import's docs for details.)
 
 With -m DESC/--match=DESC, print shows one recent transaction whose
 description is most similar to DESC. DESC should contain at least two
 characters. If there is no similar-enough match, no transaction will be
 shown and the program exit code will be non-zero.
 
-With --new, print shows only transactions it has not seen on a previous
+With --locations, print adds the source file and line number to every
-run, using the same deduplication system as the import command (see
+transaction, as a tag.
-import's docs). (Unlike import, there is no dry run - you'll see the new
-transactions only once.)
-
-With --no-lots, print will hide lot subaccounts, and their balance
-assertions. (Or with --no-lots2, their costs will also be removed,
-possibly producing unbalanced entries.) Lot subaccounts are leaf
-accounts whose last part begins with a date (YYYY-MM-DD or YYYYMMDD).
-This can be useful for converting journal entries which use explicit lot
-subaccounts, if you want to discard lot information. Note the
-limitations: all postings in the same account with similar cost will be
-consolidated, and all posting comments will be removed (including from
-non-lot postings).
 
 print output format
 

hledger/Hledger/Cli/Commands/Register.txt

@@ -116,7 +116,7 @@ $ hledger register --monthly income -E
 Often, you'll want to see just one line per interval. The --depth option
 helps with this, causing subaccounts to be aggregated:
 
-$ hledger register --monthly assets --depth 1h
+$ hledger register --monthly assets --depth 1
 2008/01                 assets                                  $1           $1
 2008/06                 assets                                 $-1            0
 2008/12                 assets                                 $-1          $-1

hledger/Hledger/Cli/Commands/Tags.txt

@@ -7,19 +7,23 @@ Flags:
      --declared             list tags declared
      --undeclared           list tags used but not declared
      --unused               list tags declared but not used
+     --find                 list the first tag whose name is matched by the
+                            first argument (a case-insensitive infix regexp)
      --values               list tag values instead of tag names
      --parsed               show them in the order they were parsed (mostly),
                             including duplicates
 
 This command lists tag names - all of them by default, or just the ones
 which have been used on transactions/postings/accounts, or declared with
-tag directives, or used but not declared, or declared but not used.
+tag directives, or used but not declared, or declared but not used, or
+just the first one matched by a pattern (with --find, returning a
+non-zero exit code if it fails).
 
-You can add one TAGREGEX argument, to show only tags whose name is
+Note this command's non-standard first argument: it is a
-matched by this case-insensitive, infix-matching regular expression.
+case-insensitive infix regular expression for matching tag names, which
-
+limits the tags shown. Any additional arguments are standard query
-After that, you can add query arguments to filter the transactions,
+arguments, which limit the transactions, postings, or accounts providing
-postings, or accounts providing tags.
+tags.
 
 With --values, the tags' unique non-empty values are listed instead.