From 7f36d2330368862a82abccbdbc53529dfdb8e035 Mon Sep 17 00:00:00 2001
From: Felix Schlitter <felixschlitter@gmail.com>
Date: Wed, 5 Oct 2016 11:03:42 +1300
Subject: [PATCH] Update README in response to #76

---
 README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 64 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index e3c8052b..423c9bc5 100644
--- a/README.md
+++ b/README.md
@@ -520,8 +520,8 @@ Here, `--foo` won't be expanded again and hence remain required.
 > when it comes down to it. The universal docopt test suite has been adjusted
 > accordingly.
 
-* **Better Error reporting.** Let the user of your utility know why his input
-  was rejected.
+* **Better Error reporting.** Let the user of your utility know why input was
+  rejected and how to fix it
 * **Optional arguments.** Neodoc understands `--foo[=BAR]` (or `-f[=<bar>]`) as
   an option that can be provided either with or without an argument.
 * **Alias matches.** If `--verbose` yields a value, so will `-v` <sub>(given
@@ -548,8 +548,6 @@ Here, `--foo` won't be expanded again and hence remain required.
   ```sh
   Usage: prog [[<name>] [<type>]]
   ```
-  Also refer to issue #44 which will introduce a slight change in behaviour once
-  completed.
 * **No abbreviations:**
   `--ver` does not match `--verbose`.
   <sub>[(mis-feature in the original implementation)](https://github.com/docopt/docopt/issues/104)</sub>
@@ -562,7 +560,67 @@ Here, `--foo` won't be expanded again and hence remain required.
     1. User input (per `process.argv`)
     1. Environment variables (per `[env: ...]` tag)
     1. Option defaults (per `[default: ...]` tag)
-
+* **Stricter document layout**. Neodoc imposes more restrictions on the format
+  of the help text in order to achieve certain goals, such as:
+  * Neodoc allows associating option aliases over newlines:
+    ```
+    options:
+     -f,
+     --foo this is foo
+    ```
+  * Neodoc does **not** require 2 spaces between option and argument. Instead,
+    only those arguments that visually "look like" arguments are considered for
+    binding (i.e. all-caps: `ARG` and in-angles: `<arg>`):
+    ```
+    options:
+     -f,
+     --foo ARG
+    ```
+    Should there be any ambiguity, the option can also be explicitly bound:
+    ```
+    options:
+     -f,
+     --foo=ARG
+    ```
+    The same is true for optional arguments:
+    ```
+    options:
+     -f,
+     --foo [ARG]
+     -b,
+     --bar[=ARG]
+    ```
+  * Neodoc is more conservative on learning about options in order to prevent
+    subtly introducing options:
+    ```
+    usage: prog [options]
+
+    options:
+
+    --foo this is foo, and it is similar to some-command's
+            --bar in that it does qux.
+    ```
+    Here, the author is talking about `--bar` in another context, so it should
+    not be considered an option to the program. Neodoc figures this out based on
+    indentation of the previous description start.
+  * Neodoc allows interspersing spaces in between usage layouts:
+    ```
+    usage:
+      prog foo bar
+
+      prog qux woo
+    ```
+    it is important to not that in this format (above), identation of the layout
+    **is required**.
+    or:
+    ```
+    usage: prog foo bar
+
+       or: prog qux woo
+    ```
+   * Neodoc requires an `Options:` section title in order to parse any options
+     (see [#76][issue-76] for discussion). **note: I am interested in a proposal
+     on how to lift this requirement**.
 
 ## License ##
 
@@ -577,3 +635,4 @@ See file `LICENSE` for a more detailed description of its terms.
 [issue-55]: https://github.com/felixSchl/neodoc/issues/55
 [issue-24]: https://github.com/felixSchl/neodoc/issues/24
 [issue-57]: https://github.com/felixSchl/neodoc/issues/57
+[issue-76]: https://github.com/felixSchl/neodoc/issues/76