doc: bring account alias docs up to date

doc/manual.md

@@ -447,25 +447,54 @@ In [tag queries](manual#queries), remember the tag name must match exactly, whil
 
 ##### Account aliases
 
-You can define account aliases to rewrite certain account names (and their subaccounts).
+You can define account aliases to rewrite account names. For a quick example,
-This tends to be a little more reliable than post-processing with sed or similar.
+see [How to use account aliases](how-to-use-account-aliases.html).
-The directive is `alias ORIG = ALIAS`, where ORIG and ALIAS are full account names.
+
+In hledger, this feature is quite powerful and requires a little care.
+It can be used for
+
+- expanding shorthand account names to their full form, so your entries require less typing
+- adjusting old data to match your current chart of accounts, which tends to change over time
+- experimenting with new account organisations
+- massaging reports, both cosmetic changes and deeper ones ("combine these separate accounts into one")
+
+An account alias can be defined on the command line:
+
+    $ hledger --alias 'REGEX=REPLACEMENT' balance
+
+or with a directive in the journal file:
+```
+alias REGEX = REPLACEMENT
+```
 Eg:
 
-    alias expenses = equity:draw:personal
+    alias ^expenses = equity:draw:personal
 
-To forget all aliases defined to this point, use:
+Spaces around the = are optional and ignored.
+You can define as many aliases as you like.
+
+Each alias is tested against each account name as those are read from the journal.
+When REGEX (a case-insensitive regular expression) matches
+anywhere within the account name, the matched part is replaced by
+REPLACEMENT.
+An alias can replace multiple matches in one account name.
+REGEX can contain parenthesised match groups, and REPLACEMENT can
+include these with a numeric backreference (like `\1`).
+
+An alias becomes active when it is read, and affects all entries
+read after it. It will also affect the entries of any files [included](#including-other-files)
+after it. It will not affect a parent file (aliases do not "leak"
+upward).  To forget all aliases defined to this point, use this
+directive:
 
     end aliases
 
-You can also specify aliases on the command line:
+Active aliases are applied in the order they were defined, and are
+cumulative (each alias sees the result of applying the previous ones).
 
-    $ hledger --alias 'my earning=income:business' ...
+Account aliases changed significantly in hledger 0.24 and are
-
+currently somewhat incompatible with Ledger's aliases, which do not
-Journal directive aliases are applied first, then command-line aliases,
+use regular expressions. They can also hurt performance.
-and at most one of each will be applied to each account name.
-
-See also [How to use account aliases](how-to-use-account-aliases.html).
 
 ##### Default commodity
 
@@ -1257,8 +1286,8 @@ and last intervals will be "full" and comparable to the others.
 console output, and they do it differently.)
 
 register uses the full terminal width by default, except on windows.
-You can set a different output width via the `COLUMNS` environment
+You can override this by setting the `COLUMNS` environment variable (not a bash shell variable)
-variable (not a bash shell variable) or by using the `--width`/`-w` option.
+or by using the `--width`/`-w` option.
 
 The description and account columns normally share the space equally
 (about half of (width - 40) each). You can adjust this by adding a

doc/site/how-to-use-account-aliases.md

@@ -19,8 +19,8 @@ However, at tax reporting time we need to view these as a single entity (at leas
 In `unified.journal`, we include both files, and rewrite the personal
 account names to fit into the business chart of accounts,
 
-    alias expenses    = equity:draw:personal
+    alias ^expenses    = equity:draw:personal
-    alias assets:cash = assets:personal cash
+    alias ^assets:cash = assets:personal cash
     include personal.journal
     end aliases
 
@@ -43,6 +43,3 @@ your accountant:
 
     $ hledger --alias 'my earning=income:business' ...
 
-Note that 
-journal directive aliases are applied first, then command-line aliases,
-and at most one of each will be applied to each account name.