add docs

diff --git a/README.cond-date b/README.cond-date
new file mode 100644 (file)
index 0000000..d95027c
--- /dev/null
+++ b/README.cond-date
@@ -0,0 +1,163 @@
+Conditional Dates Patch
+=======================
+
+    Use rules to choose date format
+
+Patch
+-----
+
+    To check if Mutt supports "Conditional Dates", look for "patch-cond-date"
+    in the mutt version.
+
+    Dependencies
+    * mutt-1.5.24
+    * nested-if patch
+
+Introduction
+------------
+
+    The "cond-date" patch allows you to construct $index_format expressions
+    based on the age of the email.
+
+    Mutt's default '$index_format' displays email dates in the form:
+    abbreviated-month day-of-month — "Jan 14".
+
+    The format is configurable but only per-mailbox. This patch allows you to
+    configure the display depending on the age of the email.
+
+    Potential Formatting Scheme
+
+    | Email Sent        | Format  | Example |
+    |-------------------|---------|---------|
+    | Today             | '%H:%M' | 13:23   |
+    | This Month        | '%a %d' | Thu 17  |
+    | This Year         | '%b %d' | Dec 10  |
+    | Older than 1 Year | '%m/%y' | 06/14   |
+
+    For an explanation of the date formatting strings, see 'strftime(3).'
+
+    By carefully picking your formats, the dates can remain unambiguous and
+    compact.
+
+    Mutt's conditional format strings have the form: (whitespace introduced for
+    clarity)
+
+        %? TEST ? TRUE & FALSE ?
+
+    The examples below use the test "%[" — the date of the message in the local
+    timezone. They will also work with "%(" — the local time that the message
+    arrived.
+
+    The date tests are of the form:
+
+        %[nX? TRUE & FALSE ?
+
+    * "n" is an optional count (defaults to 1 if missing)
+    * "X" is the time period
+
+    Date Formatting Codes
+
+    | Letter | Time Period |
+    |--------|-------------|
+    | y      | Years       |
+    | m      | Months      |
+    | w      | Weeks       |
+    | d      | Days        |
+    | H      | Hours       |
+    | M      | Minutes     |
+
+    Date Tests
+
+    | Test   | Meaning              |
+    |--------|----------------------|
+    | '%[y'  | This year            |
+    | '%[1y' | This year            |
+    | '%[6m' | In the last 6 months |
+    | '%[w'  | This week            |
+    | '%[d'  | Today                |
+    | '%[4H' | In the last 4 hours  |
+
+### Example 1
+
+    We start with a one-condition test.
+
+    Example 1
+
+    | Test   | Date Range | Format String | Example    |
+    |--------|------------|---------------|------------|
+    | '%[1m' | This month | '%[%b %d]'    | Dec 10     |
+    |        | Older      | '%[%Y-%m-%d]' | 2015-04-23 |
+
+    The $index_format string would contain:
+
+        %?[1m?%[%b %d]&%[%Y-%m-%d]?
+
+    Reparsed a little, for clarity, you can see the test condition and the two
+    format strings.
+
+        %?[1m?        &           ?
+              %[%b %d] %[%Y-%m-%d]
+
+### Example 2
+
+    This example contains three test conditions and four date formats.
+
+    Example 2
+
+    | Test  | Date Range | Format String | Example |
+    |-------|------------|---------------|---------|
+    | '%[d' | Today      | '%[%H:%M ] '  | 12:34   |
+    | '%[m' | This month | '%[%a %d]'    | Thu 12  |
+    | '%[y' | This year  | '%[%b %d]'    | Dec 10  |
+    |       | Older      | '%[%m/%y ]'   | 06/15   |
+
+    The $index_format string would contain:
+
+        %<[y?%<[m?%<[d?%[%H:%M ]&%[%a %d]>&%[%b %d]>&%[%m/%y ]>
+
+    Reparsed a little, for clarity, you can see the test conditions and the
+    four format strings.
+
+        %<[y?                                       &%[%m/%y ]>  Older
+             %<[m?                        &%[%b %d]>             This year
+                  %<[d?         &%[%a %d]>                       This month
+                       %[%H:%M ]                                 Today
+
+    This a another view of the same example, with some whitespace for clarity.
+
+        %<[y? %<[m? %<[d? AAA & BBB > & CCC > & DDD >
+
+        AAA = %[%H:%M ]
+        BBB = %[%a %d]
+        CCC = %[%b %d]
+        DDD = %[%m/%y ]
+
+
+Variables
+---------
+
+    The "cond-date" patch doesn't have any config of its own. It modifies the
+    behavior of the format strings.
+
+See Also
+--------
+
+    * NeoMutt project
+    * $index_format
+    * nested-if patch
+    * 'strftime(3)'
+
+Known Bugs
+----------
+
+    Date parsing doesn't quite do what you expect. "1w" doesn't mean the "in
+    the last 7 days", but "*this* week". This doesn't match the normal Mutt
+    behaviour: for example '~d>1w' means emails dated in the last 7 days.
+
+Credits
+-------
+
+    * Aaron Schrab <aaron@schrab.com>
+    * Eric Davis <edavis@insanum.com>
+    * Richard Russon <rich@flatcap.org>
+

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index b90908f001610306861479d3bc7440f848d5e17c..8e7a2800ca60b3f4a1b9387cf748dead055d21fe 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -4701,6 +4701,27 @@ set index_format="%4C %Z %{%b %d} %-15.15L (%?l?%4l&amp;%4c?)%*  %s"</screen>
 
 </sect2>
 
+<sect2 id="formatstrings-conditional-dates">
+<title>Conditional Dates</title>
+<para>
+This patch allows the format of dates in the index to vary based on how recent
+the message is. This is especially useful in combination with David Champion's
+patch to allow if-else sequences to be nested.
+</para>
+
+<para>
+For example, using
+<literal>%&lt;[y?%&lt;[d?%[%H:%M]&amp;%[%m/%d]&gt;&amp;%[%y.%m]&gt;</literal>
+for the date in the <literal>$index_format</literal> will produce a display like:
+</para>
+
+<screen>
+   1   + 14.12 Grace Hall      (   13) Gulliver's Travels
+   2   + 10/02 Callum Harrison (   48) Huckleberry Finn
+   3     12:17 Rhys Lee        (   42) The Lord Of The Rings
+</screen>
+</sect2>
+
 </sect1>
 
 <sect1 id="mailto-allow">
@@ -8081,6 +8102,413 @@ please have a look at the mixmaster documentation.
 
 </sect1>
 
+<sect1 id="cond-date">
+       <title>Conditional Dates Patch</title>
+       <subtitle>Use rules to choose date format</subtitle>
+
+       <sect2 id="cond-date-patch">
+               <title>Patch</title>
+
+               <para>
+                       To check if Mutt supports <quote>Conditional Dates</quote>, look for
+                       <quote>patch-cond-date</quote> in the mutt version.
+                       See: <xref linkend="mutt-patches"/>.
+               </para>
+
+               <itemizedlist>
+                       <title>Dependencies:</title>
+                       <listitem><para>mutt-1.5.24</para></listitem>
+                       <listitem><para><link linkend="nested-if">nested-if patch</link></para></listitem>
+               </itemizedlist>
+
+               <para>
+                       This patch is part of the <ulink url="https://github.com/neomutt/neomutt/wiki">NeoMutt Project</ulink>.
+               </para>
+       </sect2>
+
+       <sect2 id="cond-date-intro">
+               <title>Introduction</title>
+
+               <para>
+               The <quote>cond-date</quote> patch allows you to construct
+               <link linkend="index-format">$index_format</link> expressions based on the age of the email.
+               </para>
+
+               <para>
+               Mutt's default <literal>$index_format</literal> displays email dates in the
+               form: abbreviated-month day-of-month &mdash; <quote>Jan 14</quote>.
+               </para>
+
+               <para>
+               The format is configurable but only per-mailbox.  This patch allows you
+               to configure the display depending on the age of the email.
+               </para>
+
+               <table id="table-cond-date-scheme">
+                       <title>Potential Formatting Scheme</title>
+                       <tgroup cols="3">
+                               <thead>
+                                       <row>
+                                               <entry>Email Sent</entry>
+                                               <entry>Format</entry>
+                                               <entry>Example</entry>
+                                       </row>
+                               </thead>
+                               <tbody>
+                                       <row>
+                                               <entry>Today</entry>
+                                               <entry><literal>%H:%M</literal></entry>
+                                               <entry>13:23</entry>
+                                       </row>
+                                       <row>
+                                               <entry>This Month</entry>
+                                               <entry><literal>%a %d</literal></entry>
+                                               <entry>Thu 17</entry>
+                                       </row>
+                                       <row>
+                                               <entry>This Year</entry>
+                                               <entry><literal>%b %d</literal></entry>
+                                               <entry>Dec 10</entry>
+                                       </row>
+                                       <row>
+                                               <entry>Older than 1 Year</entry>
+                                               <entry><literal>%m/%y</literal></entry>
+                                               <entry>06/14</entry>
+                                       </row>
+                               </tbody>
+                       </tgroup>
+               </table>
+
+               <para>
+        For an explanation of the date formatting strings, see
+        <literal>strftime(3).</literal>
+               </para>
+
+               <para>
+        By carefully picking your formats, the dates can remain
+        unambiguous and compact.
+               </para>
+
+               <para>
+               Mutt's conditional format strings have the form:
+               (whitespace introduced for clarity)
+               </para>
+
+               <screen>%? TEST ? TRUE &amp; FALSE ?</screen>
+
+               <para>
+               The examples below use the test <quote>%[</quote> &mdash; the date
+               of the message in the local timezone.  They will also work with
+               <quote>%(</quote> &mdash; the local time that the message arrived.
+               </para>
+
+               <para>
+               The date tests are of the form:
+               </para>
+
+               <screen>%[nX? TRUE &amp; FALSE ?</screen>
+
+               <itemizedlist>
+               <listitem><para><quote>n</quote> is an optional count (defaults to 1 if missing)</para></listitem>
+               <listitem><para><quote>X</quote> is the time period</para></listitem>
+               </itemizedlist>
+
+               <table id="table-cond-date-format-codes">
+                       <title>Date Formatting Codes</title>
+                       <tgroup cols="2">
+                               <thead>
+                                       <row>
+                                               <entry>Letter</entry>
+                                               <entry>Time Period</entry>
+                                       </row>
+                               </thead>
+                               <tbody>
+                                       <row>
+                                               <entry>y</entry>
+                                               <entry>Years</entry>
+                                       </row>
+                                       <row>
+                                               <entry>m</entry>
+                                               <entry>Months</entry>
+                                       </row>
+                                       <row>
+                                               <entry>w</entry>
+                                               <entry>Weeks</entry>
+                                       </row>
+                                       <row>
+                                               <entry>d</entry>
+                                               <entry>Days</entry>
+                                       </row>
+                                       <row>
+                                               <entry>H</entry>
+                                               <entry>Hours</entry>
+                                       </row>
+                                       <row>
+                                               <entry>M</entry>
+                                               <entry>Minutes</entry>
+                                       </row>
+                               </tbody>
+                       </tgroup>
+               </table>
+
+               <table id="table-cond-date-example-tests">
+                       <title>Example Date Tests</title>
+                       <tgroup cols="2">
+                               <thead>
+                                       <row>
+                                               <entry>Test</entry>
+                                               <entry>Meaning</entry>
+                                       </row>
+                               </thead>
+                               <tbody>
+                                       <row>
+                                               <entry><literal>%[y</literal></entry>
+                                               <entry>This year</entry>
+                                       </row>
+                                       <row>
+                                               <entry><literal>%[1y</literal></entry>
+                                               <entry>This year</entry>
+                                       </row>
+                                       <row>
+                                               <entry><literal>%[6m</literal></entry>
+                                               <entry>In the last 6 months</entry>
+                                       </row>
+                                       <row>
+                                               <entry><literal>%[w</literal></entry>
+                                               <entry>This week</entry>
+                                       </row>
+                                       <row>
+                                               <entry><literal>%[d</literal></entry>
+                                               <entry>Today</entry>
+                                       </row>
+                                       <row>
+                                               <entry><literal>%[4H</literal></entry>
+                                               <entry>In the last 4 hours</entry>
+                                       </row>
+                               </tbody>
+                       </tgroup>
+               </table>
+
+               <sect3 id="cond-date-example1">
+                       <title>Example 1</title>
+
+                       <para>We start with a one-condition test.</para>
+
+                       <table id="table-cond-date-example1">
+                               <title>Example 1</title>
+                               <tgroup cols="4">
+                                       <thead>
+                                               <row>
+                                                       <entry>Test</entry>
+                                                       <entry>Date Range</entry>
+                                                       <entry>Format String</entry>
+                                                       <entry>Example</entry>
+                                               </row>
+                                       </thead>
+                                       <tbody>
+                                               <row>
+                                                       <entry><literal>%[1m</literal></entry>
+                                                       <entry>This month</entry>
+                                                       <entry><literal>%[%b %d]</literal></entry>
+                                                       <entry>Dec 10</entry>
+                                               </row>
+                                               <row>
+                                                       <entry></entry>
+                                                       <entry>Older</entry>
+                                                       <entry><literal>%[%Y-%m-%d]</literal></entry>
+                                                       <entry>2015-04-23</entry>
+                                               </row>
+                                       </tbody>
+                               </tgroup>
+                       </table>
+
+                       <para>The $index_format string would contain:</para>
+<screen>
+%?[1m?%[%b %d]&amp;%[%Y-%m-%d]?
+</screen>
+ 
+                       <para>
+                               Reparsed a little, for clarity, you can see the
+                               test condition and the two format strings.
+                       </para>
+
+<screen>
+%?[1m?        &amp;           ?
+      %[%b %d] %[%Y-%m-%d]
+</screen>
+
+               </sect3>
+
+               <sect3 id="cond-date-example2">
+                       <title>Example 2</title>
+
+                       <para>
+                       This example contains three test conditions and four date formats.
+                       </para>
+
+                       <table id="table-cond-date-example2">
+                               <title>Example 2</title>
+                               <tgroup cols="4">
+                                       <thead>
+                                               <row>
+                                                       <entry>Test</entry>
+                                                       <entry>Date Range</entry>
+                                                       <entry>Format String</entry>
+                                                       <entry>Example</entry>
+                                               </row>
+                                       </thead>
+                                       <tbody>
+                                               <row>
+                                                       <entry><literal>%[d</literal></entry>
+                                                       <entry>Today</entry>
+                                                       <entry><literal>%[%H:%M ] </literal></entry>
+                                                       <entry>12:34</entry>
+                                               </row>
+                                               <row>
+                                                       <entry><literal>%[m</literal></entry>
+                                                       <entry>This month</entry>
+                                                       <entry><literal>%[%a %d]</literal></entry>
+                                                       <entry>Thu 12</entry>
+                                               </row>
+                                               <row>
+                                                       <entry><literal>%[y</literal></entry>
+                                                       <entry>This year</entry>
+                                                       <entry><literal>%[%b %d]</literal></entry>
+                                                       <entry>Dec 10</entry>
+                                               </row>
+                                               <row>
+                                                       <entry></entry>
+                                                       <entry>Older</entry>
+                                                       <entry><literal>%[%m/%y ]</literal></entry>
+                                                       <entry>06/15</entry>
+                                               </row>
+                                       </tbody>
+                               </tgroup>
+                       </table>
+
+                       <para>The $index_format string would contain:</para>
+ 
+<screen>
+%&lt;[y?%&lt;[m?%&lt;[d?%[%H:%M ]&amp;%[%a %d]&gt;&amp;%[%b %d]&gt;&amp;%[%m/%y ]&gt;
+</screen>
+
+                       <para>
+                               Reparsed a little, for clarity, you can see the
+                               test conditions and the four format strings.
+                       </para>
+
+<screen>
+%&lt;[y?                                       &amp;%[%m/%y ]&gt;  Older
+     %&lt;[m?                        &amp;%[%b %d]&gt;             This year
+          %&lt;[d?         &amp;%[%a %d]&gt;                       This month
+               %[%H:%M ]                                 Today
+</screen>
+
+                       <para>
+                       This a another view of the same example, with some whitespace
+                       for clarity.
+                       </para>
+
+<screen>
+%&lt;[y? %&lt;[m? %&lt;[d? AAA &amp; BBB &gt; &amp; CCC &gt; &amp; DDD &gt;
+</screen>
+
+                       <literallayout>
+AAA = %[%H:%M ]
+BBB = %[%a %d]
+CCC = %[%b %d]
+DDD = %[%m/%y ]
+                       </literallayout>
+               </sect3>
+       </sect2>
+
+       <sect2 id="cond-date-variables">
+               <title>Variables</title>
+
+        <para>
+               The <quote>cond-date</quote> patch doesn't have any config of its own.
+               It modifies the behavior of the format strings.
+        </para>
+       </sect2>
+
+<!--
+       <sect2 id="cond-date-functions">
+               <title>Functions</title>
+               <para>None</para>
+       </sect2>
+
+       <sect2 id="cond-date-commands">
+               <title>Commands</title>
+               <para>None</para>
+       </sect2>
+
+       <sect2 id="cond-date-colors">
+               <title>Colors</title>
+               <para>None</para>
+       </sect2>
+
+       <sect2 id="cond-date-sort">
+               <title>Sort</title>
+               <para>None</para>
+       </sect2>
+-->
+
+       <sect2 id="cond-date-muttrc">
+               <title>Muttrc</title>
+<screen>
+<emphasis role="comment"># Example Mutt config file for the 'index-color' feature.
+#
+# The default index_format is:
+#       '%4C %Z %{%b %d} %-15.15L (%?l?%4l&amp;%4c?) %s'
+#
+# We replace the date field '%{%b %d}', giving:</emphasis>
+set index_format='%4C %Z %&lt;[y?%&lt;[m?%&lt;[d?%[%H:%M ]&amp;%[%a %d]&gt;&amp;%[%b %d]&gt;&amp;%[%m/%y ]&gt; %-15.15L (%?l?%4l&amp;%4c?) %s'
+ 
+<emphasis role="comment"># Test  Date Range  Format String  Example
+# --------------------------------------------
+# %[d   Today       %[%H:%M ]      12:34
+# %[m   This month  %[%a %d]       Thu 12
+# %[y   This year   %[%b %d]       Dec 10
+# -     Older       %[%m/%y ]      06/15
+ 
+# vim: syntax=muttrc</emphasis>
+</screen>
+       </sect2>
+
+       <sect2 id="cond-date-see-also">
+               <title>See Also</title>
+
+               <itemizedlist>
+                       <listitem><para><ulink url="https://github.com/neomutt/neomutt/wiki">NeoMutt Project</ulink></para></listitem>
+                       <listitem><para><link linkend="index-format">$index_format</link></para></listitem>
+                       <listitem><para><link linkend="nested-if">nested-if patch</link></para></listitem>
+                       <listitem><para><literal>strftime(3)</literal></para></listitem>
+               </itemizedlist>
+       </sect2>
+
+       <sect2 id="cond-date-known-bugs">
+               <title>Known Bugs</title>
+
+               <para>
+                       Date parsing doesn't quite do what you expect.
+                       <quote>1w</quote> doesn't mean the <quote>in the last 7 days</quote>, but
+                       <quote><emphasis>this</emphasis> week</quote>.  This doesn't match
+                       the normal Mutt behaviour: for example <literal>~d>1w</literal>
+                       means emails dated in the last 7 days.
+               </para>
+
+       </sect2>
+
+       <sect2 id="cond-date-credits">
+               <title>Credits</title>
+               <itemizedlist>
+               <listitem><para>Aaron Schrab <email>aaron@schrab.com</email></para></listitem>
+               <listitem><para>Eric Davis <email>edavis@insanum.com</email></para></listitem>
+               <listitem><para>Richard Russon <email>rich@flatcap.org</email></para></listitem>
+               </itemizedlist>
+       </sect2>
+</sect1>
+
 </chapter>
 
 <chapter id="security">

diff --git a/doc/muttrc.cond-date b/doc/muttrc.cond-date
new file mode 100644 (file)
index 0000000..b580e4f
--- /dev/null
+++ b/doc/muttrc.cond-date
@@ -0,0 +1,16 @@
+# Example Mutt config file for the 'index-color' feature.
+#
+# The default index_format is:
+#       '%4C %Z %{%b %d} %-15.15L (%?l?%4l&%4c?) %s'
+#
+# We replace the date field '%{%b %d}', giving:
+set index_format='%4C %Z %<[y?%<[m?%<[d?%[%H:%M ]&%[%a %d]>&%[%b %d]>&%[%m/%y ]> %-15.15L (%?l?%4l&%4c?) %s'
+
+# Test  Date Range  Format String  Example
+# --------------------------------------------
+# %[d   Today       %[%H:%M ]      12:34
+# %[m   This month  %[%a %d]       Thu 12
+# %[y   This year   %[%b %d]       Dec 10
+# -     Older       %[%m/%y ]      06/15
+
+# vim: syntax=muttrc

diff --git a/init.h b/init.h
index 5a12ec0d06b7267b630e858b8393704ff85fb5cd..acf411ef3661fc406f69203825684cd72eb727fd 100644 (file)
--- a/init.h
+++ b/init.h
@@ -1361,6 +1361,10 @@ struct option_t MuttVars[] = {
   ** .dt %*X    .dd soft-fill with character ``X'' as pad
   ** .de
   ** .pp
+  ** Date format expressions can be constructed based on relative dates. Using
+  ** the date formatting operators along with nested conditionals, the date
+  ** format can be modified based on how old a message is.  See the section on
+  ** ``Conditional Dates'' for an explanation and examples
   ** ``Soft-fill'' deserves some explanation: Normal right-justification
   ** will print everything to the left of the ``%>'', displaying padding and
   ** whatever lies to the right only if there's room. By contrast,