From a3fa09b60403f50835b0f59fc118e601d70375a7 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Tue, 31 Oct 2017 12:37:01 -0700
Subject: [PATCH] doc: rename/flesh out "argument files" doc, add to cookbook

---
 Shake.hs                  |  1 +
 hledger/doc/options.m4.md |  7 ++--
 site/argfiles.md          | 78 +++++++++++++++++++++++++++++++++++++++
 site/docs.md              |  4 +-
 4 files changed, 86 insertions(+), 4 deletions(-)
 create mode 100644 site/argfiles.md

diff --git a/Shake.hs b/Shake.hs
index 1422cb30c..026b8fb42 100755
--- a/Shake.hs
+++ b/Shake.hs
@@ -146,6 +146,7 @@ main = do
         ,"site/account-aliases.md"
         ,"site/account-separator.md"
         ,"site/investments.md"
+        ,"site/argfiles.md"
         ]
 
       -- cookbook pages combined, ready for web output by hakyll
diff --git a/hledger/doc/options.m4.md b/hledger/doc/options.m4.md
index 49f19e0b9..6231b7c93 100644
--- a/hledger/doc/options.m4.md
+++ b/hledger/doc/options.m4.md
@@ -32,11 +32,12 @@ Or, you can run the addon executable directly: `hledger-ui --watch`.
 Most hledger commands accept arguments after the command name, 
 which are often a [query](#queries), filtering the data in some way. 
 
-## Argument expansion
+## Argument files
 
 You can save a set of command line options/arguments in a file, one per line,
-and then reuse them by writing `@FILE` in a command line.
-(To prevent this expansion of `@`-arguments, precede them with a `--` argument.)
+and then reuse them by writing `@FILENAME` in a command line.
+To prevent this expansion of `@`-arguments, precede them with a `--` argument.
+For more, see [Save frequently used options](argsfiles.html).
 
 ## Special characters
 
diff --git a/site/argfiles.md b/site/argfiles.md
new file mode 100644
index 000000000..b62024a35
--- /dev/null
+++ b/site/argfiles.md
@@ -0,0 +1,78 @@
+# Save frequently used options
+
+You can save frequently used options and arguments in an 
+[argument file](manual#argument-files), one per
+line, then reuse them via a @FILE argument on the command line.
+(hledger 1.4+)
+
+Here's an example.
+I keep frequently-used options for quick daily reports in a file
+called `simple.args`. The name can be anything; I use a `.args` suffix
+so I can find these easily. Here's the content of `simple.args`:
+```
+--alias=/:(business|personal):/=:
+--alias=/:(bank|cash|online):/=:
+--alias=/:bofi:/=:b
+--alias=/:unify:/=:u
+--alias=/:wf:/=:w
+-2
+cur:.
+```
+
+The format is one command-line flag or command-line argument per line.
+Now if I write `@simple.args` in a hledger command line, it will be replaced
+by all of the above options/flags:
+
+These options are just an example, but in case you're wondering:
+they remove some detail, giving simplified reports which are easier for me to read at a glance.
+
+- the aliases simplify the chart of accounts, hiding some distinctions (eg business vs. personal) and flattening some bank account names
+- the `-2` depth flag limits account depth to 2, hiding deeper subaccounts
+- the `cur:.` argument shows only single-character currencies, hiding a bunch of cluttersome commodities I don't want to see
+
+## Usage
+
+Generate a balance report showing the simplified accounts:
+```shell
+$ hledger bal @simple.args
+```
+Start a live-updating hledger-ui showing the simplified asset accounts only:
+```shell
+$ hledger-ui --watch @simple.args assets
+```
+
+Options in the arguments file can be overridden by similar options later on
+the command line, in the usual way. Eg, to show just a little more account detail:
+```shell
+$ hledger bal @simple.args -3
+```
+
+## Quoting
+
+Special characters in the arguments file may need quoted,
+following the usual rules of your shell (bash, fish etc.), 
+but they'll need one less level of quoting than on the
+command line. I think:
+```shell
+$ hledger bal @simple.args
+```
+is equivalent to writing:
+```shell
+$ hledger bal "--alias=/:(business|personal):/=:" "--alias=/:(bank|cash|online):/=:" "--alias=/:bofi:/=:b" "--alias=/:unify:/=:u" "--alias=/:wf:/=:w" "-2" "cur:."
+```
+So in this example, using the bash shell, the `|` pipe character does 
+not need to be quoted in the arguments file (and should not be). 
+
+## Suppressing this feature
+
+If you actually need to write an argument beginning with @, 
+eg let's say you have an account pattern beginning with that character, 
+you'll want a way to disable this feature.  On unix systems at least, 
+you can do that by inserting a `--` argument first. Eg:
+```
+$ hledger bal @somewhere.com       # looks for additional arguments in the ./somewhere.com file
+$ hledger bal -- @somewhere.com    # matches account names containing "@somewhere.com"
+```
+
+On windows, this might or might not require a hledger built with GHC 8.2+. 
+(Let us know.)
diff --git a/site/docs.md b/site/docs.md
index 7deecdc54..d5a818bbb 100644
--- a/site/docs.md
+++ b/site/docs.md
@@ -90,7 +90,9 @@ For more docs relevant to all ledger-likes, see [plaintextaccounting.org](http:/
 
 
 ### More..
-[PTA: Common tasks](http://plaintextaccounting.org/#common-tasks)
+
+[Save frequently used options](argfiles.html)\
+[PTA: Common tasks](http://plaintextaccounting.org/#common-tasks)\
 
 </div>