From 8b2ddbc38beb113732ba540cc49e5ebe534f62c4 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Wed, 9 Mar 2016 07:16:04 -0800
Subject: [PATCH] docs: clarify dotted account name example (#331)

---
 data/sample.timedot                           | 30 ++++++------
 site/docs.md                                  |  4 ++
 ...use-another-account-separator-character.md | 48 +++++++++++++++++++
 site/manual.md                                | 19 +-------
 4 files changed, 70 insertions(+), 31 deletions(-)
 create mode 100644 site/how-to-use-another-account-separator-character.md

diff --git a/data/sample.timedot b/data/sample.timedot
index e4925de0f..ceb91da04 100644
--- a/data/sample.timedot
+++ b/data/sample.timedot
@@ -1,22 +1,24 @@
+# see also http://hledger.org/docs -> How To Use Another Account Separator Character
+
 2/1
-fos.haskell  ....
-biz.research  .
-inc.client1  .... .... .... .... .... ....
+fos:haskell   ....
+biz:research  .
+inc:client1   .... .... .... .... .... ....
 
 2/2
-biz.research  .
-inc.client1  .... .... ..
+biz:research  .
+inc:client1   .... .... ..
 
 2/3
-biz.research  .
-fos.hledger  .... .... ...
-biz.it  .... ..
-inc.client1  .... .... .... .... ....
+biz:research  .
+fos:hledger   .... .... ...
+biz:it        .... ..
+inc:client1   .... .... .... .... ....
 
 2/4
-biz.research  .... ..
-fos.hledger  .... .... ....
-fos.ledger  .
-fos.haskell  ..
-inc.client1  .... ....
+biz:research  .... ..
+fos:hledger   .... .... ....
+fos:ledger    0.25
+fos:haskell   .5
+inc:client1   2
 
diff --git a/site/docs.md b/site/docs.md
index 7f42a7787..18213f40e 100644
--- a/site/docs.md
+++ b/site/docs.md
@@ -32,6 +32,10 @@ An example of converting bank data.
 #### [How to use account aliases](how-to-use-account-aliases.html)
 Aliases for account name rewriting.
 
+#### [How to use another account separator character](how-to-use-another-account-separator-character.html)
+Writing `some.sub.account` instead of `some:sub:account`.
+
+
 ## General info
 
 #### [More docs](more-docs.html)
diff --git a/site/how-to-use-another-account-separator-character.md b/site/how-to-use-another-account-separator-character.md
new file mode 100644
index 000000000..3ce4436be
--- /dev/null
+++ b/site/how-to-use-another-account-separator-character.md
@@ -0,0 +1,48 @@
+# How to use another account separator character
+
+[Timedot format](manual.html#timedot) makes me want to use dots (`.`) for separating account components, instead of colon (`:`). 
+For example, instead of `fos:hledger:timedot` I'd like to write `fos.hledger.timedot`.
+We can use the powerful [account aliases](manual.html#account-aliases) feature 
+to rewrite account names before hledger's account name parser sees them.
+
+In journal files, we can use an alias directive.
+Note the backslash which tells the regular expression engine it's a literal `.` not a wildcard:
+
+```journal
+# alias /REGEX/=REPLACEMENT
+alias /\./=:
+
+2008/01/01 income
+    assets.bank.checking  $1
+    income.salary
+```
+Check that subaccounts are recognised:
+```shell
+$ hledger -f t.journal bal --no-elide
+                  $1  assets
+                  $1    bank
+                  $1      checking
+                 $-1  income
+                 $-1    salary
+--------------------
+                   0
+```
+
+Alias directives aren't supported in the timedot format,
+
+```timedot
+2016/2/4
+fos.hledger.timedot  2
+fos.ledger           1
+```
+so we would use the `--alias` command line option instead.
+The second backslash tells the shell that's a literal backslash, not a shell escape sequence:
+```shell
+$ hledger --alias /\\./=: -f t.timedot bal --no-elide
+                3.00  fos
+                2.00    hledger
+                2.00      timedot
+                1.00    ledger
+--------------------
+                3.00
+```
diff --git a/site/manual.md b/site/manual.md
index 1e514f95a..147bdfc76 100644
--- a/site/manual.md
+++ b/site/manual.md
@@ -927,28 +927,13 @@ Balance changes in 2016/02/01-2016/02/03:
             ||         7.75         2.25         8.00 
 ```
 
-I prefer to use period for separating account components.
-We can make this work with an [account alias](#account-aliases):
-
-```timedot
-2016/2/4
-fos.hledger.timedot  4
-fos.ledger           ..
-```
-```shell
-$ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4
-                4.50  fos
-                4.00    hledger:timedot
-                0.50    ledger
---------------------
-                4.50
-```
-
 [default year directives](#default-year) may be used.
 
 Here is a
 [sample.timedot](https://raw.github.com/simonmichael/hledger/master/data/sample.timedot).
 
+If you'd like to use dot in account names as well, see
+[how to use another account separator character](how-to-use-another-account-separator-character.html).
 
 
 ### CSV