From 713f7eab65ef2be0ccc94fc6c050d114b2a8e0e3 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Wed, 22 Dec 2021 15:08:01 -1000
Subject: [PATCH] journal: doc updates for aliases corrupting account names
 (#1788)

---
 hledger/Hledger/Cli/Commands/Print.md |  2 +-
 hledger/hledger.m4.md                 | 19 ++++++++++---------
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/hledger/Hledger/Cli/Commands/Print.md b/hledger/Hledger/Cli/Commands/Print.md
index 2f1d5129f..d3bfd1887 100644
--- a/hledger/Hledger/Cli/Commands/Print.md
+++ b/hledger/Hledger/Cli/Commands/Print.md
@@ -58,7 +58,7 @@ There are some situations where print's output can become unparseable:
 
 - [Valuation](#valuation) affects posting amounts but not [balance assertion](#balance-assertions) or [balance assignment](#balance-assignments) amounts, potentially causing those to [fail](https://github.com/simonmichael/hledger/issues/1429).
 - [Auto postings](#auto-postings) can generate postings with [too many missing amounts](https://github.com/simonmichael/hledger/issues/1276).
-- [Account aliases can generate invalid account names](#account-aliases-can-generate-invalid-account-names).
+- [Account aliases can generate bad account names](#account-aliases-can-generate-bad-account-names).
 
 Normally, the journal entry's explicit or implicit amount style is preserved.
 For example, when an amount is omitted in the journal, it will not appear in the output.
diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md
index b245e2e3e..0525a97b1 100644
--- a/hledger/hledger.m4.md
+++ b/hledger/hledger.m4.md
@@ -3281,11 +3281,11 @@ with this directive:
 end aliases
 ```
 
-### Aliases can generate invalid account names
+### Aliases can generate bad account names
 
 Be aware that account aliases can produce malformed account names,
-which could cause confusing reports or and invalid [`print`](#print) output.
-Two examples: you can erase an account name:
+which could cause confusing reports or invalid [`print`](#print) output.
+For example, you could erase all account names:
 
 ```journal
 2021-01-01
@@ -3293,14 +3293,15 @@ Two examples: you can erase an account name:
   b
 ```
 ```shell
-$ hledger -f- print --alias '/a:.*/='
+$ hledger print --alias '/.*/='
 2021-01-01
-                    1
-    b
+                   1
+
 ```
 
-or insert an illegal double space, causing part of the account name
-to be treated as part of the amount if reparsed:
+The above `print` output is not a valid journal. 
+Or you could insert an illegal double space, causing `print` output
+that would give a different journal when reparsed:
 
 ```journal
 2021-01-01
@@ -3308,7 +3309,7 @@ to be treated as part of the amount if reparsed:
   other
 ```
 ```shell
-$ hledger -f- --alias old="new  USD" print | hledger -f- print
+$ hledger print --alias old="new  USD" | hledger -f- print
 2021-01-01
     new             USD 1
     other