;doc: update command help

hledger/Hledger/Cli/Commands/Aregister.txt

@@ -61,16 +61,20 @@ ensure perfect alignment, at the cost of more time and memory, use the
 --align-all flag.
 
 This command also supports the output destination and output format
-options. The output formats supported are txt, csv, and json.
+options. The output formats supported are txt, csv, tsv, and json.
 
-aregister and custom posting dates
+aregister and posting dates
 
-Transactions whose date is outside the report period can still be shown,
+aregister always shows one line (and date and amount) per transaction.
-if they have a posting to this account dated inside the report period.
+But sometimes transactions have postings with different dates. Also, not
-(And in this case it's the posting date that is shown.) This ensures
+all of a transaction's postings may be within the report period. To
-that aregister can show an accurate historical running balance, matching
+resolve this, aregister shows the earliest of the transaction's date and
-the one shown by register -H with the same arguments.
+posting dates that is in-period, and the sum of the in-period postings.
+In other words it will show a combined line item with just the earliest
+date, and the running balance will (temporarily, until the transaction's
+last posting) be inaccurate. Use register -H if you need to see the
+individual postings.
 
-To filter strictly by transaction date instead, add the --txn-dates
+There is also a --txn-dates flag, which filters strictly by transaction
-flag. If you use this flag and some of your postings have custom dates,
+date, ignoring posting dates. This too can cause an inaccurate running
-it's probably best to assume the running balance is wrong.
+balance.

hledger/Hledger/Cli/Commands/Balance.txt

@@ -66,9 +66,9 @@ balance can show..
 -   commodities displayed on the same line or multiple lines (--layout)
 
 This command supports the output destination and output format options,
-with output formats txt, csv, json, and (multi-period reports only:)
+with output formats txt, csv, tsv, json, and (multi-period reports
-html. In txt output in a colour-supporting terminal, negative amounts
+only:) html. In txt output in a colour-supporting terminal, negative
-are shown in red.
+amounts are shown in red.
 
 The --related/-r flag shows the balance of the other postings in the
 transactions of the postings which would normally be shown.

hledger/Hledger/Cli/Commands/Balancesheet.txt

@@ -41,5 +41,5 @@ It is similar to hledger balance -H assets liabilities, but with smarter
 account detection, and liabilities displayed with their sign flipped.
 
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, html, and
+options The output formats supported are txt, csv, tsv, html, and
 (experimental) json.

hledger/Hledger/Cli/Commands/Balancesheetequity.txt

@@ -46,5 +46,5 @@ smarter account detection, and liabilities/equity displayed with their
 sign flipped.
 
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, html, and
+options The output formats supported are txt, csv, tsv, html, and
 (experimental) json.

hledger/Hledger/Cli/Commands/Cashflow.txt

@@ -47,5 +47,5 @@ hledger balance assets not:fixed not:investment not:receivable, but with
 smarter account detection.
 
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, html, and
+options The output formats supported are txt, csv, tsv, html, and
 (experimental) json.

hledger/Hledger/Cli/Commands/Import.txt

@@ -1,9 +1,9 @@
 import
 
-Read new transactions added to each FILE since last run, and add them to
+Read new transactions added to each FILE provided as arguments since
-the journal. Or with --dry-run, just print the transactions that would
+last run, and add them to the journal. Or with --dry-run, just print the
-be added. Or with --catchup, just mark all of the FILEs' transactions as
+transactions that would be added. Or with --catchup, just mark all of
-imported, without actually importing any.
+the FILEs' current transactions as imported, without importing them.
 
 _FLAGS
 
@@ -23,14 +23,15 @@ common import source, and these docs focus on that case.
 
 Deduplication
 
-As a convenience import does deduplication while reading transactions.
+import does time-based deduplication, to detect only the new
-This does not mean "ignore transactions that look the same", but rather
+transactions since the last successful import. (This does not mean
-"ignore transactions that have been seen before". This is intended for
+"ignore transactions that look the same", but rather "ignore
-when you are periodically importing foreign data which may contain
+transactions that have been seen before".) This is intended for when you
-already-imported transactions. So eg, if every day you download bank CSV
+are periodically importing downloaded data, which may overlap with
-files containing redundant data, you can safely run
+previous downloads. Eg if every week (or every day) you download a
-hledger import bank.csv and only new transactions will be imported.
+bank's last three months of CSV data, you can safely run
-(import is idempotent.)
+hledger import thebank.csv each time and only new transactions will be
+imported.
 
 Since the items being read (CSV records, eg) often do not come with
 unique identifiers, hledger detects new transactions by date, assuming
@@ -48,8 +49,10 @@ you import often, the new transactions will be few, so less likely to be
 the ones affected).
 
 hledger remembers the latest date processed in each input file by saving
-a hidden ".latest" state file in the same directory. Eg when reading
+a hidden ".latest.FILE" file in FILE's directory (after a succesful
-finance/bank.csv, it will look for and update the
+import).
+
+Eg when reading finance/bank.csv, it will look for and update the
 finance/.latest.bank.csv state file. The format is simple: one or more
 lines containing the same ISO-format date (YYYY-MM-DD), meaning "I have
 processed transactions up to this date, and this many of them on that

hledger/Hledger/Cli/Commands/Incomestatement.txt

@@ -43,5 +43,5 @@ smarter account detection, and revenues/income displayed with their sign
 flipped.
 
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, html, and
+options The output formats supported are txt, csv, tsv, html, and
 (experimental) json.

hledger/Hledger/Cli/Commands/Prices.txt

@@ -1,9 +1,18 @@
 prices
 
-Print market price directives from the journal. With
+Print the market prices declared with P directives. With
---infer-market-prices, generate additional market prices from costs.
+--infer-market-prices, also show any additional prices inferred from
-With --infer-reverse-prices, also generate market prices by inverting
+costs. With --show-reverse, also show additional prices inferred by
-known prices. Prices can be filtered by a query. Price amounts are
+reversing known prices.
-displayed with their full precision.
+
+Price amounts are always displayed with their full precision, except for
+reverse prices which are limited to 8 decimal digits.
+
+Prices can be filtered by a date:, cur: or amt: query.
+
+Generally if you run this command with --infer-market-prices
+--show-reverse, it will show the same prices used internally to
+calculate value reports. But if in doubt, you can inspect those directly
+by running the value report with --debug=2.
 
 _FLAGS

hledger/Hledger/Cli/Commands/Print.txt

@@ -7,26 +7,14 @@ _FLAGS
 The print command displays full journal entries (transactions) from the
 journal file, sorted by date (or with --date2, by secondary date).
 
-Amounts are shown mostly normalised to commodity display style, eg the
-placement of commodity symbols will be consistent. All of their decimal
-places are shown, as in the original journal entry (with one alteration:
-in some cases trailing zeroes are added.)
-
-Amounts are shown right-aligned within each transaction (but not across
-all transactions).
-
 Directives and inter-transaction comments are not shown, currently. This
 means the print command is somewhat lossy, and if you are using it to
-reformat your journal you should take care to also copy over the
+reformat/regenerate your journal you should take care to also copy over
-directives and file-level comments.
+the directives and inter-transaction comments.
 
 Eg:
 
-$ hledger print
+$ hledger print -f examples/sample.journal date:200806
-2008/01/01 income
-    assets:bank:checking            $1
-    income:salary                  $-1
-
 2008/06/01 gift
     assets:bank:checking            $1
     income:gifts                   $-1
@@ -40,13 +28,55 @@ $ hledger print
     expenses:supplies            $1
     assets:cash                 $-2
 
-2008/12/31 * pay off
+print explicitness
-    liabilities:debts               $1
+
-    assets:bank:checking           $-1
+Normally, whether posting amounts are implicit or explicit is preserved.
+For example, when an amount is omitted in the journal, it will not
+appear in the output. Similarly, if a conversion cost is implied but not
+written, it will not appear in the output.
+
+You can use the -x/--explicit flag to force explicit display of all
+amounts and costs. This can be useful for troubleshooting or for making
+your journal more readable and robust against data entry errors. -x is
+also implied by using any of -B,-V,-X,--value.
+
+The -x/--explicit flag will cause any postings with a multi-commodity
+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
+
+Amounts are shown right-aligned within each transaction (but not aligned
+across all transactions; you can do that with ledger-mode in Emacs).
+
+Amounts will be (mostly) normalised to their commodity display 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 option, print will try increasingly hard to display
+decimal digits according to the commodity display styles:
+
+-   --round=none show amounts with original precisions (default)
+-   --round=soft add/remove decimal zeros in amounts (except costs)
+-   --round=hard round amounts (except costs), possibly hiding
+    significant digits
+-   --round=all round all amounts and costs
+
+soft is good for non-lossy cleanup, formatting amounts more consistently
+where it's safe to do so.
+
+hard and all can cause print to show invalid unbalanced journal entries;
+they may be useful eg for stronger cleanup, with manual fixups when
+needed.
+
+print parseability
 
 print's output is usually a valid hledger journal, and you can process
 it again with a second hledger command. This can be useful for certain
-kinds of search, eg:
+kinds of search (though the same can be achieved with expr: queries
+now):
 
 # Show running total of food expenses paid from cash.
 # -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
@@ -59,35 +89,38 @@ There are some situations where print's output can become unparseable:
 -   Auto postings can generate postings with too many missing amounts.
 -   Account aliases can generate bad account names.
 
-Normally, the journal entry's explicit or implicit amount style is
+print, other features
-preserved. For example, when an amount is omitted in the journal, it
-will not appear in the output. Similarly, when a cost is implied but not
-written, it will not appear in the output. You can use the -x/--explicit
-flag to make all amounts and costs explicit, which can be useful for
-troubleshooting or for making your journal more readable and robust
-against data entry errors. -x is also implied by using any of
--B,-V,-X,--value.
 
-Note, -x/--explicit will cause postings with a multi-commodity amount
+With -B/--cost, amounts with costs are shown converted to cost.
-(these can arise when a multi-commodity transaction has an implicit
-amount) to be split into multiple single-commodity postings, keeping the
-output parseable.
 
-With -B/--cost, amounts with costs are converted to cost using that
+With --new, print shows only transactions it has not seen on a previous
-price. This can be used for troubleshooting.
+run. This uses the same deduplication system as the import command. (See
+import's docs for details.)
 
-With -m DESC/--match=DESC, print does a fuzzy search for one recent
+With -m DESC/--match=DESC, print shows one recent transaction whose
-transaction whose description is most similar to DESC. DESC should
+description is most similar to DESC. DESC should contain at least two
-contain at least two characters. If there is no similar-enough match, no
+characters. If there is no similar-enough match, no transaction will be
-transaction will be shown and the program exit code will be non-zero.
+shown and the program exit code will be non-zero.
 
-With --new, hledger prints only transactions it has not seen on a
+print output format
-previous run. This uses the same deduplication system as the import
-command. (See import's docs for details.)
 
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, and (experimental)
+options The output formats supported are txt, beancount, csv, tsv, json
-json and sql.
+and sql.
+
+Experimental: The beancount format tries to produce Beancount-compatible
+output. It is very basic and may require additional manual fixups:
+
+-   Transaction and postings with unmarked status are converted to
+    cleared (`*``) status.
+-   Transactions' payee and or note are wrapped in double quotes.
+-   Transaction tags are copied to Beancount #tag format.
+-   Account name parts are capitalised, and if the first account name
+    part is not one of Assets, Liabilities, Equity, Income, or Expenses,
+    "Equity:" is prepended.
+-   The $ commodity symbol is converted to USD.
+-   An open directive is generated for each account used, on the
+    earliest transaction date.
 
 Here's an example of print's CSV output:
 

hledger/Hledger/Cli/Commands/Register.txt

@@ -125,5 +125,5 @@ $ hledger reg -w 100,40           # set overall width 100, description width 40
 $ hledger reg -w $COLUMNS,40      # use terminal width, & description width 40
 
 This command also supports the output destination and output format
-options The output formats supported are txt, csv, and (experimental)
+options The output formats supported are txt, csv, tsv, and
-json.
+(experimental) json.