imp: bal: doc: --commodity-column tweaks (#1626)

- promote the heading one level
- periodic CSV reports are supported too
- slight edits to manual and flag description

hledger/Hledger/Cli/Commands/Balance.hs

@@ -311,7 +311,7 @@ balancemode = hledgerCommandMode
     ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign"
     ,flagNone ["transpose"] (setboolopt "transpose") "transpose rows and columns"
     ,flagNone ["commodity-column"] (setboolopt "commodity-column")
-      "shows one row per commodity and puts the commodity symbol in its own column, leaving amounts as bare numbers"
+      "show commodity symbols in a separate column, amounts as bare numbers, one row per commodity"
     ,outputFormatFlag ["txt","html","csv","json"]
     ,outputFileFlag
     ]

hledger/Hledger/Cli/Commands/Balance.md

@@ -256,12 +256,11 @@ Here are some ways to handle that:
 [csv-mode]: https://elpa.gnu.org/packages/csv-mode.html
 [visidata]: https://www.visidata.org
 
-#### commodity column
+### Commodity column
 
-With `--commodity-column`, each commodity of an account is displayed as a
+With `--commodity-column`, commodity symbols are displayed in a separate column, and amounts are displayed as bare numbers. 
-separate row item row will only include the quantity. The commodity itself is
+In this mode, each report row will show amounts for a single commodity, using extra rows when necessary.
-shown as a separate column, one per row. This can be useful for a cleaner
+It can be useful for a cleaner display of reports with many commodities:
-display of multi-period reports with many commodities
 
 ```shell
 $ hledger bal -T -Y
@@ -291,7 +290,8 @@ Balance changes in 2012-01-01..2014-12-31:
                   || VHT        106.00   18.00   170.00   294.00
 ```
 
-Single-period CSV balance reports also follow this new convention.
+This flag also affects [CSV output](#output-formats),
+which is useful for producing data that is easier to consume, eg when making charts:
 
 ```shell
 $ hledger bal -T -O csv