From 2101939345a5372b49fa52ccc9e91627def0c825 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Sun, 5 Jan 2020 10:53:22 -0800
Subject: [PATCH] ;doc: update arg file doc, note syntax limitations

[ci skip]
---
 hledger/hledger_options.m4.md | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/hledger/hledger_options.m4.md b/hledger/hledger_options.m4.md
index 81c23aabf..6aabcbe63 100644
--- a/hledger/hledger_options.m4.md
+++ b/hledger/hledger_options.m4.md
@@ -34,10 +34,37 @@ which are often a [query](#queries), filtering the data in some way.
 
 ## Argument files
 
-You can save a set of command line options/arguments in a file, one per line,
-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](save-frequently-used-options.html).
+You can save a set of command line options/arguments in a file,
+and then reuse them by writing `@FILENAME` as a command line argument.
+Eg: `hledger bal @foo.args`.
+(To prevent this, eg if you have an argument that begins with a literal `@`,
+precede it with `--`, eg: `hledger bal -- @ARG`).
+
+Inside the argument file, each line should contain just one option or argument.
+Avoid the use of spaces, except inside quotes (or you'll see a confusing error).
+Between a flag and its argument, use = (or nothing).
+Bad:
+
+    assets depth:2
+    -X USD
+
+Good:
+
+    assets
+    depth:2
+    -X=USD
+
+For special characters (see below), use one less level of quoting than
+you would at the command prompt. 
+Bad:
+
+    -X"$"
+
+Good:
+
+    -X$
+
+See also: [Save frequently used options](save-frequently-used-options.html).
 
 ## Special characters in arguments and queries