Docs: Added API specification, eliminated reports.txt

doc/api.txt

@@ -0,0 +1,103 @@
+Extension API
+=============
+Timewarrior reports are written as extensions, which uses an API to provide
+filtered data and configuration to the external command. This is a one-way
+process, and the extension has no way to communicate back to Timewarrior.
+However, future rules features will allow this.
+
+
+Integration
+-----------
+Simply placing an executable script/program in the ~/.timewarrior/ext directory
+is sufficient to configure nad enable the extension. The name of the program is
+leftmost matched, so that this extension:
+
+  ~/.timewarrior/ext/my_report.py
+
+Can be run using all of the following commands, depending on the uniqueness of
+the name:
+
+  $ timew report my_report.py
+  $ timew report my_report
+  $ timew report my_r
+  $ timew my_report.py
+  $ timew my_report
+  $ timew my_r
+
+
+APІ Mechanism
+-------------
+Timewarrior will provide all configuration and filtered data in JSON format to
+the standard input of the extension program. There are no command line arguments
+used, and no environment changes. The extension must be a standalone executable
+entiry, as Timewarrior will fork/exec and not invoke a shell.
+
+All standard output generated by the extension is captured and presented
+verbatim by Timewarrior. There may be additional text prepended or appended to
+this.
+
+
+Input Format
+------------
+The input format looks like this:
+
+  name1: value1
+  name2: value2
+  version: 0.1.0
+  ...
+
+  [
+  { ... },
+  { ... },
+  ...
+  ]
+
+Specifically, there is an initial block of name/value pairs, which is a copy of
+the complete current configuration data.  It has the form:
+
+  <name>: <value>
+
+This configuration block includes the Timewarrior version, so that multiple
+releases maybe supported by the extension. Additionally, other data is included
+with the 'temp.' prefix, indicating that it is not part of the configuration
+data, but may be of use to the extension.  For example:
+
+  temp.db: /home/user/.timewarrior
+  temp.report.end: 20160401T000000Z
+  temp.report.start: 20160430T235959Z
+  temp.report.tags: "This is a multi-word tag",ProjectA,tag123
+
+After the configuration block, there is a single blank line to separate it from
+the JSON data.
+
+The JSON data is a single JSON array, containing zero or more Interval objects
+that look like this (line breaks for clarity):
+
+  {"start":"20160405T162205Z",\
+   "end":"20160405T162211Z",\
+   "tags":["This is a multi-word tag","ProjectA","tag123"]},
+
+Here the presence of the "end" data means this interval is closed, i.e. not
+actively being tracked. There is one JSON object per line. The timestamps are
+ISO format UTC.
+
+
+Guidelines
+----------
+A well-behaved extension is one that follows these guidelines, and conforms to
+the general pattern of behavior exhibited by Timewarrior. The guidelines are:
+
+- Obey the 'verbose' setting, and if the value is neither on/1/yes/y/true, then
+  consider it 'off', and generate minimal output, which may be no output at all.
+
+- Obey the 'debug' setting, and if the value is either one/1/yes/y/true, then
+  emit helpful feedback, but only that which can be useful for debugging a
+  problem, which may be no output at all.
+
+- Obey the 'confirmation' setting, and if the value is either one/1/yes/y/true,
+  then obtain user permission interactively before proceeding with any data
+  modification. Do not rely on, or implement a 'force'-like feature.
+
+
+--- Raw Notes ---
+

doc/project.txt

@@ -40,6 +40,24 @@ Non-Goals
 - No features without a compelling use case.
 
 
+Reports
+-------
+Anticipating all reporting needs is impossible, therefore custom reports are
+required. Rather than copy the Taskwarrior design where flexibility is provided
+via configurable options for fixed-format reports, Timewarrior will use a more
+flexible approach of providing configuration and data via an extension API.
+This will not limit the kind of reports or supported formats that can be added.
+
+Timewarrior will ship with several reports, which serve as example extensions
+for users to modify and improve, perhaps contribute back to the project.
+
+Purely as an example of what might be implemented, here are some report mockups:
+
+  ./report.week.txt
+  ./report.day.1.txt
+  ./report.exc.week.txt
+
+
 Tags
 ----
 Tags represent tracking categories. Tags are arbitrary UTF8 strings. A tag may
@@ -130,3 +148,14 @@ data.
   command, instead of "stop" use "forgot" or directly "edit".  Then I would
   like to express either "stopped 30min ago" or "it lasted only 1hour”.
 
+- Need a JSON --> CSV converter, for spreadsheet folks. Therefore csv.py could
+  be an extension that converts the format.
+
+- Use display granularity/resolution to see more or less details.  This would
+  combine nicely with a tag hierarchy. (Tomas Babej)
+
+- Need reports to help users doing fixed-rate work - finding the longest task
+  for example.
+
+- If an interval has more than one tag with a defined color, and is being
+  rendered, then use the first tag color. It doesn't really matter which.

doc/reports.txt

@@ -1,96 +0,0 @@
-Reporting
-=========
-Anticipating all reporting needs is impossible, therefore custom reports are
-required. Rather than copy the Taskwarrior design where flexibility is provided
-via configurable options for fixed-format reports, Timewarrior will use a more
-flexible approach of providing configuration and data via an API. This will not
-limit the kind of reports or supported formats that can be added.
-
-
-Requirements
-------------
-Timewarrior will ship with several reports, which serve as example extensions
-for users to modify and improve.
-
-Timewarrior will handle the command line options for reports, then pass off a
-standardized set of parameters to the report extension. These parameters will
-include:
-
-- Date range. Although Timewarrior might support "last month" as a reporting
-  range, the extensions themselves would be passed precise values, therefore
-  reducing the complexity of the extensions.
-
-- Data will be filtered by Timewarrior, so that extensions will not need to
-  reimplement this.
-
-- Reports will be sized according to need, not according to available terminal
-  width. If a report does not fit in a window, it is not an error.
-
-There will be a default report, which is configurable so that one of the reports
-or commands can be the default.
-
-
-Report Mockups
---------------
-Purely as an example of what might be implemented, here are some report mockups:
-
-  ./report.week.txt
-  ./report.day.1.txt
-  ./report.exc.week.txt
-
-  TBD (calendar like "task calendar" with table below)
-  TBD (timeline, l-r)
-  TBD (table with subtotals)
-
-
-Example Commands
-----------------
-Here are some provisional examples of report commands:
-
-  $ timew report day [monday] [±<tag> ...]
-  $ timew report week [±<tag> ...]
-  $ timew report month|quarter|year
-
-
-Report API
-----------
-The report API is simple - it invokes a program and feeds it input. All output
-is generated by the program. When running this command:
-
-  $ timew report x ...
-
-Timewarrior then runs this:
-
-  $ ~/.timewarrior/extensions/x.*
-
-With standard input consisting of:
-
-  filter: ...
-  name1: value1
-
-  [
-  { ... },
-  { ... },
-  ...
-  ]
-
-That is, the input is line-oriented, with first a header block of name/value
-pairs, then a blank line, then the JSON filtered data. The header block has all
-configuration names flattened, i.e. no hierarchy.
-
-
---- Raw Notes ---
-
-- Need a JSON --> CSV converter, for spreadsheet folks.
-
-- Use display granularity/resolution to see more or less details.  This would
-  combine nicely with a tag hierarchy. (Tomas Babej)
-
-- Need reports to help users doing fixed-rate work - finding the longest task
-  for example.
-
-- If an interval has more than one tag with a defined color, and is being
-  rendered, then use the first tag color. It doesn't really matter which.
-
-- Need a formal API description, for extension authors.
-