From f36937ddff07fde99cc5914e64f983b747e8e3b0 Mon Sep 17 00:00:00 2001
From: Paul Beckingham <paul@beckingham.net>
Date: Sun, 13 Mar 2016 10:53:12 -0400
Subject: [PATCH] Docs: Added report API

---
 doc/reports.txt | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/doc/reports.txt b/doc/reports.txt
index 0dcaa049..42237f9d 100644
--- a/doc/reports.txt
+++ b/doc/reports.txt
@@ -48,6 +48,33 @@ Here are some provisional examples of report commands:
   $ 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 it 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.
+
 ---
 
 - The Taskwarrior hook script should use a set of attributes for time tracking