;doc: update CLI usage texts

hledger/Hledger/Cli/Commands/Aregister.txt

@@ -1,36 +1,39 @@
 aregister, areg
 
-Show the transactions and running historical balance in an account, with
+Show the transactions and running historical balance of a single
-each line item representing one transaction.
+account, with each transaction displayed as one line.
 
 _FLAGS
 
-aregister shows the transactions affecting a particular account and its
+aregister shows the overall transactions affecting a particular account
-subaccounts, with each line item representing a whole transaction - as
+(and any subaccounts). Each report line represents one transaction in
-in bank statements, hledger-ui, hledger-web and other accounting apps.
+this account. Transactions before the report start date are always
+included in the running balance (--historical mode is always on).
 
-Note this is unlike the register command, which shows individual
+This is a more "real world", bank-like view than the register command
-postings and does not always show a single account or a historical
+(which shows individual postings, possibly from multiple accounts, not
-balance.
+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.
 
-A reminder, "historical" balances include any balance from transactions
+aregister requires one argument: the account to report on. You can write
-before the report start date, so (if opening balances are recorded
-correctly) aregister will show the real-world balances of an account, as
-you would see in a bank statement.
-
-As a quick rule of thumb, use aregister for reconciling real-world
-asset/liability accounts and register for reviewing detailed
-revenues/expenses.
-
-aregister shows the register for just one account (and its subaccounts).
-This account must be specified as the first argument. You can write
 either the full account name, or a case-insensitive regular expression
 which will select the alphabetically first matched account. (Eg if you
 have assets:aaa:checking and assets:bbb:checking accounts,
 hledger areg checking would select assets:aaa:checking.)
 
+Transactions involving subaccounts of this account will also be shown.
+aregister ignores depth limits, so its final total will always match a
+balance report with similar arguments.
+
 Any additional arguments form a query which will filter the transactions
-shown.
+shown. Note some queries will disturb the running 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 areg checking date:jul
 
 Each aregister line item shows:
 
@@ -44,11 +47,8 @@ Each aregister line item shows:
 Transactions making a net change of zero are not shown by default; add
 the -E/--empty flag to show them.
 
-aregister ignores a depth limit, so its final total will always match a
-balance report with similar arguments.
-
 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, and json.
 
 aregister and custom posting dates
 
@@ -61,15 +61,3 @@ the one shown by register -H with the same arguments.
 To filter strictly by transaction date instead, add the --txn-dates
 flag. If you use this flag and some of your postings have custom dates,
 it's probably best to assume the running balance is wrong.
-
-Examples:
-
-Show all transactions and historical running balance in the first
-account whose name contains "checking":
-
-$ hledger areg checking
-
-Show transactions and historical running balance in all asset accounts
-during july:
-
-$ hledger areg assets date:jul

hledger/Hledger/Cli/Commands/Balance.txt

@@ -58,6 +58,8 @@ balance can show..
 -   rows and columns swapped (--transpose)
 -   another field used as account name (--pivot)
 -   custom-formatted line items (single-period reports only) (--format)
+-   commodities shown in a separate column, one per row
+    (--commodity-column)
 
 This command supports the output destination and output format options,
 with output formats txt, csv, json, and (multi-period reports only:)
@@ -230,6 +232,61 @@ in the terminal. Here are some ways to handle that:
 -   Output as HTML and view with a browser:
     hledger bal -D -o a.html && open a.html
 
+Commodity column
+
+With --commodity-column, commodity symbols are displayed in a separate
+column, and amounts are displayed as bare numbers. In this mode, each
+report row will show amounts for a single commodity, using extra rows
+when necessary. It can be useful for a cleaner display of reports with
+many commodities:
+
+$ hledger bal -T -Y
+Balance changes in 2012-01-01..2014-12-31:
+
+                  ||                               2012                             2013                   2014                            Total
+==================++=============================================================================================================================
+ Assets:US:ETrade ||   10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more..
+------------------++-----------------------------------------------------------------------------------------------------------------------------
+ total            ||   10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more..
+
+$ hledger bal -T -Y --commodity-column
+Balance changes in 2012-01-01..2014-12-31:
+
+                   || Commodity    2012    2013     2014    Total
+==================++=============================================
+ Assets:US:ETrade || GLD             0   70.00        0    70.00
+ Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00
+ Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50
+ Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00
+ Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00
+------------------++---------------------------------------------
+                  || GLD             0   70.00        0    70.00
+                  || ITOT        10.00   18.00   -11.00    17.00
+                  || USD        337.18  -98.12  4881.44  5120.50
+                  || VEA         12.00   10.00    14.00    36.00
+                  || VHT        106.00   18.00   170.00   294.00
+
+This flag also affects CSV output, which is useful for producing data
+that is easier to consume, eg when making charts:
+
+$ hledger bal -T -O csv
+"account","balance"
+"Assets:US:ETrade","70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT"
+"total","70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT"
+
+$ hledger bal -T -O csv --commodity-column
+"account","commodity","balance"
+"Assets:US:ETrade","GLD","70.00"
+"Assets:US:ETrade","ITOT","17.00"
+"Assets:US:ETrade","USD","5120.50"
+"Assets:US:ETrade","VEA","36.00"
+"Assets:US:ETrade","VHT","294.00"
+"total","GLD","70.00"
+"total","ITOT","17.00"
+"total","USD","5120.50"
+"total","VEA","36.00"
+"total","VHT","294.00"
+
 Sorting by amount
 
 With -S/--sort-amount, accounts with the largest (most positive)