Documentation

- Started the new parser documentation.

doc/misc/parser/README

@@ -0,0 +1,77 @@
+The main focus of the 2.4.0 release is a new command line parser that has more
+capabilities, and fewer quirks and bugs.
+
+
+Improvements needed:
+
+- Assorted quoting issues.  If this command is issued, then the quoting should
+  be obeyed:
+
+    task add one project:'Bob\'s Project'
+    task add "one 'two' three"
+    task add 'one "two" three'
+    task add 'one \'two\' three'
+    task add "one \"two\" three"
+
+- The process of splitting and rejoining tokens causes this kind of problem:
+
+    "one (two) three" --> "one ( two) three"
+
+- Any formatting in the input that makes it past the shell should be preserved.
+
+- The '--' token should faithfully cause no further parsing - lexing only.
+
+- The ability to perform simple math:
+
+    task add one due:eoy wait:due-2wks scheduled:wait-1wk
+
+  When processed left to right, this command has referential integrity.
+
+- An attribute value must be a single argument, but can be presented in several
+  equivalent ways:
+
+    wait:due-2wks
+    wait:'due-2wks'
+    wait:"due-2wks'
+    wait:"due -2wks'
+    wait:"due - 2wks'
+    wait:due\ -\ 2wks
+
+
+Grammar:
+
+To achieve the above, a formal grammar will be developed, otherwise a hand-
+crafted parser is going to be unmaintainable.  See the grammar.txt file for the
+formal definition.
+
+This grammar.txt will be embedded into task as a single-string document, then
+itself parsed and used.  This has several advantages:
+
+- It allows the grammar to be discussed in its purest form, with an
+  authoritative document as a definition.
+- It allows the grammar to be tweaked at a high level without code changes.
+- It allows a developer to experiment with grammar.
+
+
+Expressions:
+
+The expression evaluator will be capable of applying any supported filter.
+
+The expression evaluator will also be capable of evaluating fragments of output
+from the parser, yielding a single value.  As an example, the command line:
+
+  task add one due:eoy wait:due-2wks
+
+Is parsed as:
+
+  raw     | add     one    due:eoy    wait:due-2wks
+  type    | command string attr       attr
+  subtype | read
+  attr    |         desc   due        wait
+  value   |                eval 'eoy' eval 'due-2wks'
+
+The eval needs of this command are:
+
+  'eoy'      == date literal
+  'due-2wks' == <dom> - <duration>
+