From 1d944ac1a92355be9986fe9d7ec9a6f6aa2b487f Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Sat, 10 Oct 2015 15:07:49 -0700
Subject: [PATCH] doc: balance --format does not support - any more

---
 doc/manual.md                            | 49 ++++++++++++------------
 hledger-lib/Hledger/Data/StringFormat.hs |  3 +-
 2 files changed, 26 insertions(+), 26 deletions(-)

diff --git a/doc/manual.md b/doc/manual.md
index 04c90993a..0c2048f4b 100644
--- a/doc/manual.md
+++ b/doc/manual.md
@@ -1581,19 +1581,19 @@ $ hledger balance -V ...
 ##### Custom balance output
 
 ``` {.shell .right}
-$ hledger balance --format "%20(account) %-(total)"
-              assets $-1
-         bank:saving $1
-                cash $-2
-            expenses $2
-                food $1
-            supplies $1
-              income $-2
-               gifts $-1
-              salary $-1
-   liabilities:debts $1
---------------------
-                   0
+$ hledger balance --format "%20(account) %12(total)"
+              assets          $-1
+         bank:saving           $1
+                cash          $-2
+            expenses           $2
+                food           $1
+            supplies           $1
+              income          $-2
+               gifts          $-1
+              salary          $-1
+   liabilities:debts           $1
+---------------------------------
+                                0
 ```
 
 In simple (non-multi-column) balance reports, you can customise the
@@ -1601,15 +1601,15 @@ output with `--format FMT`. FMT (plus a newline) will be displayed for
 each account/balance pair. It is a format string with data fields
 interpolated by
 
-`%[-][MIN][.MAX](FIELDNAME)`
+`%[MIN][.MAX](FIELDNAME)`
 
-where a minus sign means left-justify, MIN means pad with spaces to at
-least this width, and MAX means truncate at this width. The field name
-must be enclosed in parentheses. Three are available:
+where MIN means pad with spaces to at least this width, and MAX means
+truncate at this width. The field name must be enclosed in
+parentheses. Three fields are available:
 
 - `depth_spacer` - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces.
 - `account`      - the account's name
-- `total`        - the account's balance/sum of postings
+- `total`        - the account's balance/posted total, right justified
 
 When the total has multiple commodities, by default each commodity is
 displayed on a separate line, and the report item will be bottom
@@ -1620,13 +1620,12 @@ beginning the format with a special prefix:
 - `%^` - render on multiple lines, top-aligned
 - `%,` - render on one line, with multi-line values comma-separated
 
-There are some quirks:
-
-- In one-line mode, `%(depth_spacer)` has no effect, instead `%(account)` has indentation built in.
-- Consistent column widths are not well enforced, causing ragged edges unless you set suitable widths.
-- Beware of specifying a maximum width; it will clip account names and amounts that are too wide, with no visible indication.
-
-Some experimentation may be needed to get pleasing output.
+There are some quirks, and experimentation may be needed to get pleasing output.
+In one-line mode, `%(depth_spacer)` has no effect, instead `%(account)` has indentation built in.
+<!-- XXX retest:
+Consistent column widths are not well enforced, causing ragged edges unless you set suitable widths.
+Beware of specifying a maximum width; it will clip account names and amounts that are too wide, with no visible indication.
+-->
 
 Examples:
 
diff --git a/hledger-lib/Hledger/Data/StringFormat.hs b/hledger-lib/Hledger/Data/StringFormat.hs
index 20c253513..3dbd30960 100644
--- a/hledger-lib/Hledger/Data/StringFormat.hs
+++ b/hledger-lib/Hledger/Data/StringFormat.hs
@@ -63,7 +63,8 @@ data ReportItemField =
     AccountField      -- ^ A posting or balance report item's account name
   | DefaultDateField  -- ^ A posting or register or entry report item's date
   | DescriptionField  -- ^ A posting or register or entry report item's description
-  | TotalField        -- ^ A balance or posting report item's balance or running total
+  | TotalField        -- ^ A balance or posting report item's balance or running total.
+                      --   Always rendered right-justified.
   | DepthSpacerField  -- ^ A balance report item's indent level (which may be different from the account name depth).
                       --   Rendered as this number of spaces, multiplied by the minimum width spec if any.
   | FieldNo Int       -- ^ A report item's nth field. May be unimplemented.