mailplate.xml

   1 <?xml version='1.0' encoding='utf-8'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4
   5 <!--
   6
   7 Process this file with an XSLT processor: `xsltproc \
   8 -''-nonet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
   9 manpages/docbook.xsl manpage.dbk'.  A manual page
  10 <package>.<section> will be generated.  You may view the
  11 manual page with: nroff -man <package>.<section> | less'.  A
  12 typical entry in a Makefile or Makefile.am is:
  13
  14 DB2MAN=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
  15 manpages/docbook.xsl
  16 XP=xsltproc -''-nonet
  17
  18 manpage.1: manpage.dbk
  19         $(XP) $(DB2MAN) $<
  20
  21 The xsltproc binary is found in the xsltproc package.  The
  22 XSL files are in docbook-xsl.  Please remember that if you
  23 create the nroff version in one of the debian/rules file
  24 targets (such as build), you will need to include xsltproc
  25 and docbook-xsl in your Build-Depends control field.
  26
  27 -->
  28
  29   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  30   <!ENTITY dhfirstname "<firstname>Martin F.</firstname>">
  31   <!ENTITY dhsurname   "<surname>Krafft</surname>">
  32   <!-- Please adjust the date whenever revising the manpage. -->
  33   <!ENTITY dhdate      "<date>September 30, 2007</date>">
  34   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
  35        allowed: see man(7), man(1). -->
  36   <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  37   <!ENTITY dhemail     "<email>madduck@madduck.net</email>">
  38   <!ENTITY dhusername  "martin f. krafft">
  39   <!ENTITY dhucpackage "<refentrytitle>MAILPLATE</refentrytitle>">
  40   <!ENTITY dhpackage   "mailplate">
  41
  42   <!ENTITY debian      "<productname>Debian</productname>">
  43   <!ENTITY gnu         "<acronym>GNU</acronym>">
  44   <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
  45 ]>
  46
  47 <refentry>
  48   <refentryinfo>
  49     <address>
  50       &dhemail;
  51     </address>
  52     <copyright>
  53       <year>2007</year>
  54       <holder>&dhusername;</holder>
  55     </copyright>
  56     &dhdate;
  57   </refentryinfo>
  58   <refmeta>
  59     &dhucpackage;
  60
  61     &dhsection;
  62   </refmeta>
  63   <refnamediv>
  64     <refname>&dhpackage;</refname>
  65
  66     <refpurpose>reformat mail drafts according to templates</refpurpose>
  67   </refnamediv>
  68   <refsynopsisdiv>
  69     <cmdsynopsis>
  70       <command>&dhpackage;</command>
  71       <group>
  72         <arg choice="plain">
  73           <group>
  74             <arg choice="plain"><option>--new</option></arg>
  75             <arg choice="plain"><option>-n</option></arg>
  76           </group>
  77         </arg>
  78         <arg choice="plain">
  79           <group>
  80             <arg choice="plain"><option>--editor</option></arg>
  81             <arg choice="plain"><option>-e</option></arg>
  82           </group>
  83         </arg>
  84       </group>
  85       <group>
  86         <arg choice="plain"><option>--keep-unknown</option></arg>
  87         <arg choice="plain"><option>-k</option></arg>
  88       </group>
  89       <group>
  90         <arg choice="plain"><option>--verbose</option></arg>
  91         <arg choice="plain"><option>-v</option></arg>
  92       </group>
  93       <group>
  94         <arg choice="plain"><option>--debug</option></arg>
  95         <arg choice="plain"><option>-d</option></arg>
  96       </group>
  97       <arg choice="plain"><replaceable>template-name</replaceable></arg>
  98       <arg choice="plain"><replaceable>message-file</replaceable></arg>
  99     </cmdsynopsis>
 100     <cmdsynopsis>
 101       <command>&dhpackage;</command>
 102       <group>
 103         <arg choice="plain">
 104           <group>
 105             <arg choice="plain"><option>--auto</option></arg>
 106             <arg choice="plain"><option>-a</option></arg>
 107           </group>
 108         </arg>
 109         <arg choice="plain">
 110           <group>
 111             <arg choice="plain"><option>--menu</option></arg>
 112             <arg choice="plain"><option>-m</option></arg>
 113           </group>
 114         </arg>
 115       </group>
 116       <group>
 117         <arg choice="plain">
 118           <group>
 119             <arg choice="plain"><option>--new</option></arg>
 120             <arg choice="plain"><option>-n</option></arg>
 121           </group>
 122         </arg>
 123         <arg choice="plain">
 124           <group>
 125             <arg choice="plain"><option>--editor</option></arg>
 126             <arg choice="plain"><option>-e</option></arg>
 127           </group>
 128         </arg>
 129       </group>
 130       <group>
 131         <arg choice="plain"><option>--keep-unknown</option></arg>
 132         <arg choice="plain"><option>-k</option></arg>
 133       </group>
 134       <group>
 135         <arg choice="plain"><option>--verbose</option></arg>
 136         <arg choice="plain"><option>-v</option></arg>
 137       </group>
 138       <group>
 139         <arg choice="plain"><option>--debug</option></arg>
 140         <arg choice="plain"><option>-d</option></arg>
 141       </group>
 142       <arg choice="plain"><replaceable>message-file</replaceable></arg>
 143     </cmdsynopsis>
 144     <cmdsynopsis>
 145       <command>&dhpackage;</command>
 146       <group>
 147         <arg choice="plain">
 148           <group>
 149             <arg choice="plain"><option>--auto</option></arg>
 150             <arg choice="plain"><option>-a</option></arg>
 151           </group>
 152         </arg>
 153         <arg choice="plain">
 154           <group>
 155             <arg choice="plain"><option>--menu</option></arg>
 156             <arg choice="plain"><option>-m</option></arg>
 157           </group>
 158         </arg>
 159       </group>
 160       <group>
 161         <arg choice="plain"><option>--keep-unknown</option></arg>
 162         <arg choice="plain"><option>-k</option></arg>
 163       </group>
 164       <group>
 165         <arg choice="plain"><option>--verbose</option></arg>
 166         <arg choice="plain"><option>-v</option></arg>
 167       </group>
 168       <group>
 169         <arg choice="plain"><option>--debug</option></arg>
 170         <arg choice="plain"><option>-d</option></arg>
 171       </group>
 172       <arg choice="plain">&lt; <replaceable>message data</replaceable></arg>
 173     </cmdsynopsis>
 174     <cmdsynopsis>
 175       <command>&dhpackage;</command>
 176       <group>
 177         <arg choice="plain"><option>--help</option></arg>
 178         <arg choice="plain"><option>-h</option></arg>
 179       </group>
 180     </cmdsynopsis>
 181     <cmdsynopsis>
 182       <command>&dhpackage;</command>
 183       <group>
 184         <arg choice="plain"><option>--version</option></arg>
 185         <arg choice="plain"><option>-V</option></arg>
 186       </group>
 187     </cmdsynopsis>
 188   </refsynopsisdiv>
 189   <refsect1>
 190     <title>DESCRIPTION</title>
 191
 192     <para><command>&dhpackage;</command> is a programme that reformats mail
 193       drafts according to a given template. The template may be specified on
 194       the command line, but mailplate can also use control information from
 195       the template files to automatically select an appropriate template
 196       (<option>--auto</option>). A selection menu feature is planned
 197       (<option>--menu</option>). </para>
 198
 199     <para> Applying a template means obtainined select data from an existing
 200       mail message (unless <option>--new</option> is specified) and to fill it
 201       into appropriate slots in the template. Messages are processed in three
 202       parts: headers, body, and signature. </para>
 203
 204     <para> When <option>--new</option> is given, an empty instantiation of the
 205       template is written to stdout. At the moment, <option>--new</option>
 206       cannot be combined with <option>--editor</option>.</para>
 207
 208     <para> The template can define two types of headers: mandatory and
 209       preservatory. Mandatory headers take precedence over headers in the
 210       existing message and thus overwrite them. Preservatory headers instruct
 211       mailplate to port their data from the existing mail message. Headers in
 212       the existing message but not defined in the template are dropped, unless
 213       <option>--keep-unknown</option> is given. </para>
 214
 215     <para> Body and signature are separated by '-- '. If this sentinel is not
 216       found, no signature is extracted. Templates can be interpolated and data
 217       filled into slots. Helper slots are filled with the output of helper
 218       commands (which must be defined in the configuration), environment
 219       variable slots are just that, and mail variable slots can be filled with
 220       data obtained by running regexps or commands over the message. </para>
 221
 222     <para> This script can be run in multiple ways: </para>
 223
 224     <itemizedlist>
 225       <listitem><para> As a filter, it applies a template to data from stdin
 226           and writes the result to stdout. </para></listitem>
 227
 228       <listitem><para> When <option>--editor</option> is passed, the script
 229           spawns <command>sensible-editor</command> on the result. It may thus
 230           be used as the editor for your mail user agent. </para></listitem>
 231
 232       <listitem><para> Given a file, it modifies the file, unless it cannot
 233           write to the file, in which case it writes to stdout.
 234           </para></listitem>
 235
 236     </itemizedlist>
 237
 238   </refsect1>
 239
 240   <refsect1>
 241     <title>OPTIONS</title>
 242
 243     <para> These programs follow the usual &gnu; command line syntax, with
 244       long options starting with two dashes (`--'): </para>
 245
 246     <variablelist>
 247       <varlistentry>
 248         <term><option>--auto</option>,
 249           <option>-a</option>
 250         </term>
 251         <listitem>
 252           <para>Turn on template auto-discovery.</para>
 253         </listitem>
 254       </varlistentry>
 255       <varlistentry>
 256         <term><option>--menu</option>,
 257           <option>-m</option>
 258         </term>
 259         <listitem>
 260           <para>Choose from a list of templates (not yet implemented)</para>
 261         </listitem>
 262       </varlistentry>
 263       <varlistentry>
 264         <term><option>--new</option>,
 265           <option>-n</option>
 266         </term>
 267         <listitem>
 268           <para>Create a new message.</para>
 269         </listitem>
 270       </varlistentry>
 271       <varlistentry>
 272         <term><option>--editor</option>,
 273           <option>-e</option>
 274         </term>
 275         <listitem>
 276           <para>Spawn editor once template is applied.</para>
 277         </listitem>
 278       </varlistentry>
 279       <varlistentry>
 280         <term><option>--keep-unknown</option>,
 281           <option>-k</option>
 282         </term>
 283         <listitem>
 284           <para>Preserve mail headers not specified in template.</para>
 285         </listitem>
 286       </varlistentry>
 287       <varlistentry>
 288         <term><option>--verbose</option>,
 289           <option>-v</option>
 290         </term>
 291         <listitem>
 292           <para>Write informational messages to stderr.</para>
 293         </listitem>
 294       </varlistentry>
 295       <varlistentry>
 296         <term><option>--debug</option>,
 297           <option>-d</option>
 298         </term>
 299         <listitem>
 300           <para>Start a debugger after initialisation.</para>
 301         </listitem>
 302       </varlistentry>
 303       <varlistentry>
 304         <term>
 305           <option>--help</option>,
 306           <option>-h</option>
 307         </term>
 308         <listitem>
 309           <para>Show summary of options.</para>
 310         </listitem>
 311       </varlistentry>
 312       <varlistentry>
 313         <term>
 314           <option>--version</option>,
 315           <option>-V</option>
 316         </term>
 317         <listitem>
 318           <para>Show version of program.</para>
 319         </listitem>
 320       </varlistentry>
 321     </variablelist>
 322   </refsect1>
 323
 324   <refsect1>
 325     <title>SEE ALSO</title>
 326     <para>http://madduck.net/code/mailplate/</para>
 327     <para>/usr/share/doc/mailplate/README</para>
 328   </refsect1>
 329
 330   <refsect1>
 331     <title>AUTHOR</title>
 332
 333     <para>This manual page was written by &dhusername; &dhemail; with help
 334       from Carl Fürstenberg.</para>
 335   </refsect1>
 336 </refentry>
 337