[tasks] Add examples to the date parser strings

[Ross Burton <rburton src gnome org>]

commit ea05c4231bc68b16e3ab07f29e3d946cf3053951
Author: Ross Burton <ross linux intel com>
Date:   Thu Jul 23 11:54:04 2009 +0100

    Add examples to the date parser strings

 libkoto/koto-date-parser.c |   57 ++++++++++++++++++++-----------------------
 1 files changed, 27 insertions(+), 30 deletions(-)
---
diff --git a/libkoto/koto-date-parser.c b/libkoto/koto-date-parser.c
index 8894881..02b2ed9 100644
--- a/libkoto/koto-date-parser.c
+++ b/libkoto/koto-date-parser.c
@@ -452,7 +452,6 @@ init_matchers (void)
 {
   GList *matchers = NULL;
   Matcher *m;
-  char *s;
 
   init_days ();
   init_months ();
@@ -462,73 +461,71 @@ init_matchers (void)
     expressions then skip these, otherwise
     http://www.burtonini.com/blog/computers/tasks-2008-10-01-21-17 has some
     details about how this works.
+
+    These strings are used to parse the user's input in the "New Task" entry to
+    extract the meaning of what they entered, such as the due date.
+
+    The important thing to preserve in the translation are the (?<name>expr)
+    blocks, which identify a regular expression "expr" with the identifier
+    "name".  These mark sections which will be used in the new task.  All of the
+    strings have a block called "task", which is the actual task summary.  Other
+    examples are "day" (day of the month), "month" (month name) and so on.
   */
 
-  /* Translators: just translate "today" */
+  /* Translators: "Pay bills today".  Just translate "today" */
   m = matcher_new (_("^(?<task>.+) today$"), match_today);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate "tomorrow" */
+  /* Translators: "Pay bills tomorrow". Just translate "tomorrow" */
   m = matcher_new (_("^(?<task>.+) tomorrow$"), match_tomorrow);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate "yesterday" */
+  /* Translators: "Pay bills yesterday".  Just translate "yesterday" */
   m = matcher_new (_("^(?<task>.+) yesterday$"), match_yesterday);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate "next" */
-  s = g_strdup_printf (_("^(?<task>.+) next (?<day>%s)$"),
-		       _("monday|tuesday|wednesday|thursday|friday|saturday|sunday|"
-			 "mon|tue|wed|thr|fri|sat|sun"));
-  m = matcher_new (s, match_next);
-  g_free (s);
+  /* Translators: "Pay bills next Monday". */
+  m = matcher_new (_("^(?<task>.+) next (?<day>\\w+)$"), match_next);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate this|on|by|due to contain relevant words in
+  /* Translators: "Pay bills this tuesday".  just translate this|on|by|due to contain relevant words in
      your language, moving the day block is required. */
   m = matcher_new (_("^(?<task>.+) (this|on|by|due) (?<day>\\w+)$"),  match_this);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: replace by|due|on with suitable words, and re-order the day
-     and month expressions as suitable */
+  /* Translators: "Pay bills by 4/12" (day/month).  Re-arrange as required. */
   m = matcher_new (_("^(?<task>.+) (?:by|due|on) (?<day>\\d{1,2})/(?<month>\\d{1,2})$"),  match_date);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate on|by|due and st|nd|rd|th to contain relevant
-     words in your language. */
+  /* Translators: "Pay bills on 3rd" or "Pay bills on 12".  Not all languages
+     have numeric suffixes so feel free to remove them. */
   m = matcher_new (_("^(?<task>.+) (?:by|due|on)? (?<day>\\d{1,2})(?:st|nd|rd|th)?$"),  match_day);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate on|by|due and st|nd|rd|th to contain relevant
-     words in your language, and move the month block if required. */
+  /* Translators: "Pay bills on 12th January" or "Pay bills on 23 June". */
   m = matcher_new (_("^(?<task>.+) (?:by|due|on)? (?<day>\\d{1,2})(?:st|nd|rd|th)? (?<month>\\w+)$"),  match_day_month);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate on|by|due and st|nd|rd|th to contain relevant
-     words in your language, and move the month block if required. */
+  /* Translators: "Pay bills on January 12th" or "Pay bills on 23 June".  This
+     is for languages where there is two way of writing a day, if there is only
+     one correct way then translate this identically to the previous one. */
   m = matcher_new (_("^(?<task>.+) (?:by|due|on)? (?<month>\\w+) (?<day>\\d{1,2})(?:st|nd|rd|th)?$"),  match_day_month);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate this|on|by|due to contain relevant words in
-     your language */
+  /* Translators: "Pay bills on 15/4". */
   m = matcher_new (_("^(?<task>.+) (?:by|due|on)? (?<digits>[\\d/-]+)$"), match_digits);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate this|on|by|due to contain relevant words in
-     your language and replace the w with whatever shortcut indicated "week". In
-     English, w34 means "week 34". */
+  /* Translators: "Pay bills by w43".  In English, w34 means "week 34", not all
+     languages have this concept. */
   m = matcher_new (_("^(?<task>.+) (?:by|due|on)? w(?<week>\\d{1,2})$"), match_week);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate in ... days to contain relevant words in your
-     language. Remember the trailing ? is part of the regular expression to be
-     translated.*/
+  /* Translators: "Pay bills in 4 days". */
   m = matcher_new (_("^(?<task>.+) in (?<days>\\d+) days?$"), match_days);
   if (m) matchers = g_list_prepend (matchers, m);
 
-  /* Translators: just translate in ... weeksto contain relevant words in your
-     language. Remember the trailing ? is part of the regular expression to be
-     translated.*/
+  /* Translators: "Pay bills in 2 weeks". */
   m = matcher_new (_("^(?<task>.+) in (?<weeks>\\d+) weeks?$"), match_weeks);
   if (m) matchers = g_list_prepend (matchers, m);