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"><option>--keep-unknown</option></arg>
 104         <arg choice="plain"><option>-k</option></arg>
 105       </group>
 106       <group>
 107         <arg choice="plain"><option>--verbose</option></arg>
 108         <arg choice="plain"><option>-v</option></arg>
 109       </group>
 110       <group>
 111         <arg choice="plain"><option>--debug</option></arg>
 112         <arg choice="plain"><option>-d</option></arg>
 113       </group>
 114       <arg choice="plain"><replaceable>template-name</replaceable></arg>
 115       <arg choice="plain">&lt; <replaceable>message-data</replaceable></arg>
 116     </cmdsynopsis>
 117     <cmdsynopsis>
 118       <command>&dhpackage;</command>
 119       <group>
 120         <arg choice="plain">
 121           <group>
 122             <arg choice="plain"><option>--auto</option></arg>
 123             <arg choice="plain"><option>-a</option></arg>
 124           </group>
 125         </arg>
 126         <arg choice="plain">
 127           <group>
 128             <arg choice="plain"><option>--menu</option></arg>
 129             <arg choice="plain"><option>-m</option></arg>
 130           </group>
 131         </arg>
 132       </group>
 133       <group>
 134         <arg choice="plain">
 135           <group>
 136             <arg choice="plain"><option>--new</option></arg>
 137             <arg choice="plain"><option>-n</option></arg>
 138           </group>
 139         </arg>
 140         <arg choice="plain">
 141           <group>
 142             <arg choice="plain"><option>--editor</option></arg>
 143             <arg choice="plain"><option>-e</option></arg>
 144           </group>
 145         </arg>
 146       </group>
 147       <group>
 148         <arg choice="plain"><option>--keep-unknown</option></arg>
 149         <arg choice="plain"><option>-k</option></arg>
 150       </group>
 151       <group>
 152         <arg choice="plain"><option>--verbose</option></arg>
 153         <arg choice="plain"><option>-v</option></arg>
 154       </group>
 155       <group>
 156         <arg choice="plain"><option>--debug</option></arg>
 157         <arg choice="plain"><option>-d</option></arg>
 158       </group>
 159       <arg choice="plain"><replaceable>message-file</replaceable></arg>
 160     </cmdsynopsis>
 161     <cmdsynopsis>
 162       <command>&dhpackage;</command>
 163       <group>
 164         <arg choice="plain">
 165           <group>
 166             <arg choice="plain"><option>--auto</option></arg>
 167             <arg choice="plain"><option>-a</option></arg>
 168           </group>
 169         </arg>
 170         <arg choice="plain">
 171           <group>
 172             <arg choice="plain"><option>--menu</option></arg>
 173             <arg choice="plain"><option>-m</option></arg>
 174           </group>
 175         </arg>
 176       </group>
 177       <group>
 178         <arg choice="plain"><option>--keep-unknown</option></arg>
 179         <arg choice="plain"><option>-k</option></arg>
 180       </group>
 181       <group>
 182         <arg choice="plain"><option>--verbose</option></arg>
 183         <arg choice="plain"><option>-v</option></arg>
 184       </group>
 185       <group>
 186         <arg choice="plain"><option>--debug</option></arg>
 187         <arg choice="plain"><option>-d</option></arg>
 188       </group>
 189       <arg choice="plain">&lt; <replaceable>message data</replaceable></arg>
 190     </cmdsynopsis>
 191     <cmdsynopsis>
 192       <command>&dhpackage;</command>
 193       <group>
 194         <arg choice="plain"><option>--help</option></arg>
 195         <arg choice="plain"><option>-h</option></arg>
 196       </group>
 197     </cmdsynopsis>
 198     <cmdsynopsis>
 199       <command>&dhpackage;</command>
 200       <group>
 201         <arg choice="plain"><option>--version</option></arg>
 202         <arg choice="plain"><option>-V</option></arg>
 203       </group>
 204     </cmdsynopsis>
 205   </refsynopsisdiv>
 206   <refsect1>
 207     <title>DESCRIPTION</title>
 208
 209     <para><command>&dhpackage;</command> is a programme that reformats mail
 210       drafts according to a given template. The template may be specified on
 211       the command line, but mailplate can also use control information from
 212       the template files to automatically select an appropriate template
 213       (<option>--auto</option>). A selection menu feature is planned
 214       (<option>--menu</option>). </para>
 215
 216     <para> Applying a template means obtainined select data from an existing
 217       mail message (unless <option>--new</option> is specified) and to fill it
 218       into appropriate slots in the template. Messages are processed in three
 219       parts: headers, body, and signature. </para>
 220
 221     <para> When <option>--new</option> is given, an empty instantiation of the
 222       template is written to <filename>stdout</filename>. At the moment,
 223       <option>--new</option> cannot be combined with
 224       <option>--editor</option>.</para>
 225
 226     <para> The template can define two types of headers: mandatory and
 227       preservatory. Mandatory headers take precedence over headers in the
 228       existing message and thus overwrite them. Preservatory headers instruct
 229       mailplate to port their data from the existing mail message. Headers in
 230       the existing message but not defined in the template are dropped, unless
 231       <option>--keep-unknown</option> is given. </para>
 232
 233     <para> Body and signature are separated by '-- '. If this sentinel is not
 234       found, no signature is extracted. Templates can be interpolated and data
 235       filled into slots. Helper slots are filled with the output of helper
 236       commands (which must be defined in the configuration), environment
 237       variable slots are just that, and mail variable slots can be filled with
 238       data obtained by running regexps or commands over the message. </para>
 239
 240     <para> This script can be run in multiple ways: </para>
 241
 242     <itemizedlist>
 243       <listitem><para> As a filter, it applies a template to data from
 244           <filename>stdin</filename> and writes the result to
 245           <filename>stdout</filename>. </para></listitem>
 246
 247       <listitem><para> When <option>--editor</option> is passed, the script
 248           spawns <command>sensible-editor</command> on the result. It may thus
 249           be used as the editor for your mail user agent. </para></listitem>
 250
 251       <listitem><para> Given a file, it modifies the file, unless it cannot
 252           write to the file, in which case it writes to
 253           <filename>stdout</filename>. </para></listitem>
 254
 255     </itemizedlist>
 256
 257   </refsect1>
 258
 259   <refsect1>
 260     <title>OPTIONS</title>
 261
 262     <para> These programs follow the usual &gnu; command line syntax, with
 263       long options starting with two dashes (`--'): </para>
 264
 265     <variablelist>
 266       <varlistentry>
 267         <term><option>--auto</option>,
 268           <option>-a</option>
 269         </term>
 270         <listitem>
 271           <para>Turn on template auto-discovery.</para>
 272         </listitem>
 273       </varlistentry>
 274       <varlistentry>
 275         <term><option>--menu</option>,
 276           <option>-m</option>
 277         </term>
 278         <listitem>
 279           <para>Choose from a list of templates (not yet implemented)</para>
 280         </listitem>
 281       </varlistentry>
 282       <varlistentry>
 283         <term><option>--new</option>,
 284           <option>-n</option>
 285         </term>
 286         <listitem>
 287           <para>Create a new message.</para>
 288         </listitem>
 289       </varlistentry>
 290       <varlistentry>
 291         <term><option>--editor</option>,
 292           <option>-e</option>
 293         </term>
 294         <listitem>
 295           <para>Spawn editor once template is applied.</para>
 296         </listitem>
 297       </varlistentry>
 298       <varlistentry>
 299         <term><option>--keep-unknown</option>,
 300           <option>-k</option>
 301         </term>
 302         <listitem>
 303           <para>Preserve mail headers not specified in template.</para>
 304         </listitem>
 305       </varlistentry>
 306       <varlistentry>
 307         <term><option>--verbose</option>,
 308           <option>-v</option>
 309         </term>
 310         <listitem>
 311           <para>Write informational messages to <filename>stderr</filename>.</para>
 312         </listitem>
 313       </varlistentry>
 314       <varlistentry>
 315         <term><option>--debug</option>,
 316           <option>-d</option>
 317         </term>
 318         <listitem>
 319           <para>Start a debugger after initialisation.</para>
 320         </listitem>
 321       </varlistentry>
 322       <varlistentry>
 323         <term>
 324           <option>--help</option>,
 325           <option>-h</option>
 326         </term>
 327         <listitem>
 328           <para>Show summary of options.</para>
 329         </listitem>
 330       </varlistentry>
 331       <varlistentry>
 332         <term>
 333           <option>--version</option>,
 334           <option>-V</option>
 335         </term>
 336         <listitem>
 337           <para>Show version of program.</para>
 338         </listitem>
 339       </varlistentry>
 340     </variablelist>
 341   </refsect1>
 342
 343   <refsect1>
 344     <title>MUTT INTEGRATION</title>
 345
 346     <para>I use mailplate as my <varname>$editor</varname> for
 347       <application>mutt</application>, with the following setting in my
 348       <filename>~/.mutt/muttrc</filename>:</para>
 349
 350     <programlisting><![CDATA[
 351       set editor="~/.bin/mail/mailplate --edit --auto --keep-unknown"
 352     ]]></programlisting>
 353
 354     <para>mailplate currently has a bit of a limitation, or at least I have
 355       not figured out a way how to work around it sensibly yet. If you re-edit
 356       a message from mutt’s compose menu, it causes mailplate to reprocess the
 357       message, which you may not want.</para>
 358
 359     <para>Similarly, if you find yourself editing messages from the index or
 360       pager, you probably also don’t want mailplate to get in the way. For
 361       these cases, I currently use the following two keybindings:</para>
 362
 363     <programlisting><![CDATA[
 364       macro compose     e ':set my_editor="$editor"<enter>:set editor=sensible-editor<enter><edit-headers>:set editor="$my_editor"<enter>' "invoke normal editor to edit message"
 365       macro index,pager e ':set my_editor="$editor"<enter>:set editor=sensible-editor<enter><edit>:set editor="$my_editor"<enter>' "invoke normal editor to edit message"
 366     ]]></programlisting>
 367
 368   </refsect1>
 369
 370   <refsect1>
 371     <title>VIM INTEGRATION</title>
 372
 373     <para>I am often editing a message with <application>vim</application> and
 374       find that I need to use a different identity. For this purpose, I have
 375       the following keybindings in my
 376       <filename>~/.vim/ftplugin/mail.vim</filename>:</para>
 377
 378     <programlisting><![CDATA[
 379       nmap <buffer> <F1>      :w<CR>:%!mailplate --keep-unknown --auto<CR>
 380       nmap <buffer> <C-P><F1> :w<CR>:%!mailplate --keep-unknown private<CR>
 381       nmap <buffer> <C-P><F2> :w<CR>:%!mailplate --keep-unknown debian<CR>
 382     ]]></programlisting>
 383
 384     <para>Now when I reply to a message, mailplate automatically choses the
 385       right template, and if I later change my mind, I can press C-p, to
 386       override the choice and select the private template, or just hit to have
 387       it re-run the auto-detection.</para>
 388
 389   </refsect1>
 390
 391   <refsect1>
 392     <title>SEE ALSO</title>
 393     <varlistentry>
 394       <listitem>
 395         <para>
 396           <link>http://madduck.net/code/mailplate/</link>
 397         </para>
 398       </listitem>
 399       <listitem>
 400         <para>
 401           <filename>/usr/share/doc/mailplate/README</filename>
 402         </para>
 403       </listitem>
 404     </varlistentry>
 405   </refsect1>
 406
 407   <refsect1>
 408     <title>AUTHOR</title>
 409
 410     <para>This manual page was written by &dhusername; &dhemail; with help
 411       from Carl Fürstenberg.</para>
 412   </refsect1>
 413 </refentry>
 414