Document format string pipes.

This is roughly the commit message only. Add a line to UPDATING (mark
it as a change rather than a new feature as it may break setups).

diff --git a/ChangeLog b/ChangeLog
index 32b70c6ba6035a7a9e64936c10d80ddcf2b1604c..b562657fd16ba6f4bdd2632a921e69de32db019a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2007-10-11 11:18 +0200  Rocco Rutte  <pdmef@gmx.net>  (efcd349fc9e0)
+
+       * init.h: Document that $indent_string actually is a format string.
+
+2007-10-11 11:03 +0200  Rocco Rutte  <pdmef@gmx.net>  (40f2c0f4c597)
+
+       * ChangeLog, muttlib.c: Do not consider empty pipes for filtering in
+       format strings. This fixes a crash with $indent_string="|" and
+       $text_flowed unset.
+
 2007-09-28 11:06 +0200  Rocco Rutte  <pdmef@gmx.net>  (709db707bcdf)
 
        * curs_lib.c, muttlib.c, protos.h: Make mutt_FormatString()'s string

diff --git a/UPDATING b/UPDATING
index c8f94fc21d884a4b44307e166bb20655db1df91f..21176c83054333ccd98605e7d4583b044366a8b3 100644 (file)
--- a/UPDATING
+++ b/UPDATING
@@ -17,6 +17,7 @@ The keys used are:
   + $save_history, $history_file (save history across sessions)
   + $smtp_url (ESMTP relay support)
   + $crypt_use_pka (use GPGME PKA signature verification)
+  ! format pipe support: format strings ending in | are filtered
 
 1.5.13 (2006-08-14):
 

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 60f1827de0fd6600b4496d819ee9882565579dd7..103f5aba9e86d4a4a0ebce3c951d15121b8842b5 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -3277,6 +3277,9 @@ something like <literal>unhook send-hook</literal>.
 <sect1 id="formatstrings">
 <title>Format Strings</title>
 
+<sect2>
+<title>Basic usage</title>
+
 <para>
 Format strings are a general concept you'll find in several locations
 through the mutt configuration, especially in the
@@ -3338,6 +3341,47 @@ expands in all lower case. And if you use a colon (``:''), it will
 replace all decimal points with underlines.
 </para>
 
+</sect2>
+
+<sect2>
+<title>Filters</title>
+
+<para>
+Any format string ending in a vertical bar (``&verbar;'') will be
+expanded and piped through the first word in the string, using spaces
+as separator. The string returned will be used for display.
+If the returned string ends in &percnt;, it will be passed through
+the formatter a second time. This allows the filter to generate a
+replacement format string including &percnt; expandos.
+</para>
+
+<para>
+All &percnt; expandos in a format string are expanded before the script
+is called so that:
+</para>
+
+<screen>
+set status_format="script.sh '%r %f (%L)'|"
+</screen>
+
+<para>
+will make mutt expand <literal>&percnt;r</literal>,
+<literal>&percnt;f</literal> and <literal>&percnt;L</literal>
+before calling the script. The example also shows that arguments can be
+quoted: the script will receive the expanded string between the single quotes
+as the only argument.
+</para>
+
+<para>
+A practical example is the <literal>mutt&lowbar;xtitle</literal>
+script installed in the <literal>samples</literal>
+subdirectory of the mutt documentation: it can be used as filter for
+<literal>&dollar;status&lowbar;format</literal> to set the current
+terminal's title, if supported.
+</para>
+
+</sect2>
+
 </sect1>
 
 </chapter>