Changeset 5234:c15eeb44f139 for doc

Timestamp:

2007-10-11 03:10:49 (14 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:

• doc/manual.xml.head (modified) (2 diffs)

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>