Consolidate in-repo documentation (#3143)

* move doc/misc to top level, add READMEs

* Move docs -> doc/devel

This also consolidates the _three_ documents describing (differently)
how to build Taskwarrior into a signle document.

doc/devel/rfcs/dom.md

@@ -0,0 +1,249 @@
+---
+title: "Taskwarrior - Full DOM Support"
+---
+
+## Work in Progress
+
+This design document is a work in progress, and subject to change.
+Once finalized, the feature will be scheduled for an upcoming release.
+
+
+# Full DOM Support
+
+Taskwarrior currently supports DOM references that can access any stored data item.
+The general forms supported are:
+
+    [ <id> | <uuid> ] <attribute> [ <part> ]
+
+Examples include:
+
+    due
+    123.uuid
+    entry.month
+    123.annotations.0.entry.year
+    a87bc10f-931b-4558-a44a-e901a77db011.description
+
+Additionally there are references for accessing configuration and system/program level items.
+
+    rc.<name>
+    context.program
+    context.args
+    context.width
+    context.height
+    system.version
+    system.os
+
+While this is adequate for data retrieval, we have the possibility of extending it further to include data formats, higher-level constructs, and then to make use of DOM references in more locations.
+This contributes to our goal of simplifying Taskwarrior.
+
+
+## Proposed Format Support
+
+When defining a custom report, the columns shown are defined like this:
+
+    report.x.columns=uuid.short,description.oneline ...
+
+This syntax is:
+
+    <attribute> [ . <format> ]
+
+If no `format` is specified, then `default` is assumed.
+The `src/columns/ColΧ\*` objects are responsible for supporting and rendering these formats.
+There is currently no consistency among these formats based on data type.
+
+By incorporating formats into DOM references, we eliminate the need for a separate syntax for custom reports, and provide this:
+
+    123.due.iso
+    123.due.month.short
+    123.uuid.short
+
+A standard set of formats per data type would be:
+
+Type
+
+Formats
+
+Example
+
+Numeric
+
+default
+
+`123                              `
+
+indicator
+
+Based on `rc.<attribute>.indicator` which overrides `rc.numeric.indicator`.
+
+json
+
+`"<attribute>":"<value>"`
+
+String
+
+default
+
+Buy milk
+
+short
+
+Feb
+
+indicator
+
+Based on `rc.<attribute>.indicator` which overrides `rc.string.indicator`.
+
+json
+
+`"<attribute>":"<value>"`
+
+Date
+
+default
+
+Based on `rc.dateformat`
+
+iso
+
+2017-02-20T09:02:12
+
+julian
+
+2457805.12858
+
+epoch
+
+1234567890
+
+age
+
+2min
+
+relative
+
+-2min
+
+remaining
+
+0:02:04
+
+countdown
+
+0:02:04
+
+indicator
+
+Based on `rc.<attribute>.indicator` which overrides `rc.date.indicator`.
+
+json
+
+`"<attribute>":"<value>"`
+
+Duration
+
+default
+
+1wk
+
+iso
+
+P1W
+
+indicator
+
+Based on `rc.<attribute>.indicator` which overrides `rc.duration.indicator`.
+
+json
+
+`"<attribute>":"<value>"`
+
+There will also be a set of attribute-specific formats, similar to the currently supported set:
+
+    depends.list
+    depends.count
+    description.combined
+    description.desc
+    description.oneline
+    description.truncated
+    description.count
+    description.truncated_count
+    parent.default|long
+    parent.short
+    project.full
+    project.parent
+    project.indented
+    status.default|long
+    status.short
+    tags.default|list
+    tags.count
+    urgency.default|real
+    urgency.integer
+    uuid.default|long
+    uuid.short
+
+Custom report sort criteria will also use DOM references.
+This will be augmented by the `+`/`-` sort direction and `/` break indicator, which are not part of the DOM.
+
+
+## High Level Construct Support
+
+There need to be read-only DOM references that do not correspond directly to stored attributes.
+Tasks have emergent properties represented by virtual tags, which will be accessible, in this case returning a `0` or `1`:
+
+    123.tags.OVERDUE
+
+Using `rc.due` and the `due` attribute, the `OVERDUE` virtual tag is a combination of the two.
+Other examples may include:
+
+    task.syncneeded
+    task.pending.count
+    task.hooks.installed
+
+
+## Writable References
+
+When a DOM reference refers to an attribute or RC setting, and does not extend further and reference a component or format, it may be writable.
+For example:
+
+    rc.hooks           # writable
+    123.description    # writable
+    123.entry.month    # not writable, not an attribute
+
+
+## Data Interchange
+
+The export command can be used to show a filtered set of tasks in JSON format, and this will also be available as a DOM format:
+
+    123.json
+    a87bc10f-931b-4558-a44a-e901a77db011.json
+
+
+## RC File Support
+
+The RC file (`~/.taskrc`) will support DOM references in values.
+This will form a late-bound reference, which is evaluated at runtime, every time.
+
+An example is to make two reports share the same description:
+
+    $ task config -- report.ls.description rc.report.list.description
+
+This sets the description for the `ls` report to be a reference to the description of the `list` report. 
+This reference is not evaluated when the entry is written, but is evaluated every time the value is read, thus providing late-bound behavior.
+Then if the description of the `list` report changes, so does that of the `ls` report automatically.
+
+
+## Implementation Details
+
+These notes list a series of anticipated changes to the codebase.  
+
+-   The `src/columns/Col*` objects will implement type-specific and attribute-specific DOM support.
+    DOM reference lookup will defer to the column objects first.
+
+-   Some DOM references will be writable, permitting a `_set` command to complement the `_get` command.
+
+-   The `Config` object will recognize DOM references in values and perform lookup at read time.
+    This will require circularity detection.
+
+-   `src/DOM.cpp` will provide a memoized function to determine whether a DOM reference is valid.
+
+-   `src/DOM.cpp` will provide a function to obtain a DOM reference value, with supporting metadata (type, writable).