[notmuch] [PATCH 4/4] add documentation for the new daterange parser and remove TODO list item

[Sebastian Spaeth]

Signed-off-by: Sebastian Spaeth <Sebastian at SSpaeth.de>
---
 TODO      |    9 ---------
 notmuch.1 |   29 ++++++++++++++++++++---------
 notmuch.c |   24 +++++++++++++-----------
 3 files changed, 33 insertions(+), 29 deletions(-)

diff --git a/TODO b/TODO
index bdfe64c..86cbf74 100644
--- a/TODO
+++ b/TODO
@@ -114,15 +114,6 @@ notmuch library
 ---------------
 Index content from citations, please.
 
-Provide a sane syntax for date ranges. First, we don't want to require
-both endpoints to be specified. For example it would be nice to be
-able to say things like "since:2009-01-1" or "until:2009-01-1" and
-have the other endpoint be implicit. Second we'd like to support
-relative specifications of time such as "since:'2 months ago'". To do
-any of this we're probably going to need to break down an write our
-own parser for the query string rather than using Xapian's QueryParser
-class.
-
 Make failure to read a file (such as a permissions problem) a warning
 rather than an error (should be similar to the existing warning for a
 non-mail file).
diff --git a/notmuch.1 b/notmuch.1
index 282ad98..19628f0 100644
--- a/notmuch.1
+++ b/notmuch.1
@@ -413,17 +413,28 @@ expression).
 Finally, results can be restricted to only messages within a
 particular time range, (based on the Date: header) with a syntax of:
 
-	<intial-timestamp>..<final-timestamp>
+	date:<startdate>..<enddate>
 
-Each timestamp is a number representing the number of seconds since
-1970-01-01 00:00:00 UTC. This is not the most convenient means of
-expressing date ranges, but until notmuch is fixed to accept a more
-convenient form, one can use the date program to construct
-timestamps. For example, with the bash shell the folowing syntax would
-specify a date range to return messages from 2009-10-01 until the
-current time:
+A
+.B date
+can be specified in various formats. It parses the formats in this order and stops if one pattern matches:
+
+	Keywords:
+.B today,
+.B yesterday,
+.B thisweek,
+.B lastweek,
+.B thismonth,
+.B lastmonth.
+
+	Month-day: month[-day]] (month: "January", "Jan", 1)
+
+	ISO format: year[-month[-day]]
+
+	US format : month[/day[/year]]
+
+The date parser will try to fill in bits in the enddate from context if left out, e.g. a 'date:2004..01' will find from 2004-01-01 through 2004-01-31.
 
-	$(date +%s -d 2009-10-01)..$(date +%s)
 .SH SEE ALSO
 The emacs-based interface to notmuch (available as
 .B notmuch.el
diff --git a/notmuch.c b/notmuch.c
index 87479f8..b8fe01a 100644
--- a/notmuch.c
+++ b/notmuch.c
@@ -92,19 +92,21 @@ static const char search_terms_help[] =
     "\t\tmarks around any parenthesized expression).\n"
     "\n"
     "\t\tFinally, results can be restricted to only messages within a\n"
-    "\t\tparticular time range, (based on the Date: header) with:\n"
+    "\t\tparticular time range, (based on the Date: header) with a\n"
+    "\t\tsyntax of: date:<startdate>..<enddate>\n"
     "\n"
-    "\t\t\t<intial-timestamp>..<final-timestamp>\n"
+    "\t\tIt can be specified in the following formats, parsing will \n"
+    "\t\tstop if the first pattern matches:\n"
+    "\t\tKeywords: 'today','yesterday','thisweek','lastweek',\n"
+    "\t\t'thismonth', 'lastmonth'. \n"
+    "\t\tmonth-day : month[-day]] (month: January, Jan, or 1)\n"
+    "\t\tISO format: year[-month[-day]] (month: January, Jan, or 1)\n"
+    "\t\tUS format : month[/day[/year]]\n"
     "\n"
-    "\t\tEach timestamp is a number representing the number of seconds\n"
-    "\t\tsince 1970-01-01 00:00:00 UTC. This is not the most convenient\n"
-    "\t\tmeans of expressing date ranges, but until notmuch is fixed to\n"
-    "\t\taccept a more convenient form, one can use the date program to\n"
-    "\t\tconstruct timestamps. For example, with the bash shell the\n"
-    "\t\tfollowing syntax would specify a date range to return messages\n"
-    "\t\tfrom 2009-10-01 until the current time:\n"
-    "\n"
-    "\t\t\t$(date +%%s -d 2009-10-01)..$(date +%%s)\n\n";
+    "\t\tThe parser will fill in bits in the enddate from context if\n"
+    "\t\tleft out, e.g. a 'date:2004..01' will find from 2004-01-01\n"
+    "\t\tthrough 2004-01-31\n"
+    "\n\n";
 
 command_t commands[] = {
     { "setup", notmuch_setup_command,
-- 
1.6.3.3