Changeset 5234:c15eeb44f139

Timestamp:

2007-10-11 03:10:49 (15 months ago)

Author:

Rocco Rutte <pdmef@…>

Branch:

HEAD

Message:

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).

Files:

• ChangeLog (modified) (1 diff)
• UPDATING (modified) (1 diff)
• doc/manual.xml.head (modified) (2 diffs)

ChangeLog

@@ +1 @@
+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)
 

UPDATING

@@ -18 +18 @@
   + $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):

doc/manual.xml.head

@@ -3278 +3278 @@
 <title>Format Strings</title>
 
+<sect2>
+<title>Basic usage</title>
+
 <para>
 Format strings are a general concept you'll find in several locations
@@ -3338 +3341 @@
 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>