]> git.madduck.net Git - code/mailplate.git/blob - mailplate.xml

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

rename to gitignore
[code/mailplate.git] / 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 stdout. At the moment, <option>--new</option>
223       cannot be combined with <option>--editor</option>.</para>
224
225     <para> The template can define two types of headers: mandatory and
226       preservatory. Mandatory headers take precedence over headers in the
227       existing message and thus overwrite them. Preservatory headers instruct
228       mailplate to port their data from the existing mail message. Headers in
229       the existing message but not defined in the template are dropped, unless
230       <option>--keep-unknown</option> is given. </para>
231
232     <para> Body and signature are separated by '-- '. If this sentinel is not
233       found, no signature is extracted. Templates can be interpolated and data
234       filled into slots. Helper slots are filled with the output of helper
235       commands (which must be defined in the configuration), environment
236       variable slots are just that, and mail variable slots can be filled with
237       data obtained by running regexps or commands over the message. </para>
238
239     <para> This script can be run in multiple ways: </para>
240
241     <itemizedlist>
242       <listitem><para> As a filter, it applies a template to data from stdin
243           and writes the result to stdout. </para></listitem>
244
245       <listitem><para> When <option>--editor</option> is passed, the script
246           spawns <command>sensible-editor</command> on the result. It may thus
247           be used as the editor for your mail user agent. </para></listitem>
248
249       <listitem><para> Given a file, it modifies the file, unless it cannot
250           write to the file, in which case it writes to stdout.
251           </para></listitem>
252
253     </itemizedlist>
254
255   </refsect1>
256
257   <refsect1>
258     <title>OPTIONS</title>
259
260     <para> These programs follow the usual &gnu; command line syntax, with
261       long options starting with two dashes (`--'): </para>
262
263     <variablelist>
264       <varlistentry>
265         <term><option>--auto</option>,
266           <option>-a</option>
267         </term>
268         <listitem>
269           <para>Turn on template auto-discovery.</para>
270         </listitem>
271       </varlistentry>
272       <varlistentry>
273         <term><option>--menu</option>,
274           <option>-m</option>
275         </term>
276         <listitem>
277           <para>Choose from a list of templates (not yet implemented)</para>
278         </listitem>
279       </varlistentry>
280       <varlistentry>
281         <term><option>--new</option>,
282           <option>-n</option>
283         </term>
284         <listitem>
285           <para>Create a new message.</para>
286         </listitem>
287       </varlistentry>
288       <varlistentry>
289         <term><option>--editor</option>,
290           <option>-e</option>
291         </term>
292         <listitem>
293           <para>Spawn editor once template is applied.</para>
294         </listitem>
295       </varlistentry>
296       <varlistentry>
297         <term><option>--keep-unknown</option>,
298           <option>-k</option>
299         </term>
300         <listitem>
301           <para>Preserve mail headers not specified in template.</para>
302         </listitem>
303       </varlistentry>
304       <varlistentry>
305         <term><option>--verbose</option>,
306           <option>-v</option>
307         </term>
308         <listitem>
309           <para>Write informational messages to stderr.</para>
310         </listitem>
311       </varlistentry>
312       <varlistentry>
313         <term><option>--debug</option>,
314           <option>-d</option>
315         </term>
316         <listitem>
317           <para>Start a debugger after initialisation.</para>
318         </listitem>
319       </varlistentry>
320       <varlistentry>
321         <term>
322           <option>--help</option>,
323           <option>-h</option>
324         </term>
325         <listitem>
326           <para>Show summary of options.</para>
327         </listitem>
328       </varlistentry>
329       <varlistentry>
330         <term>
331           <option>--version</option>,
332           <option>-V</option>
333         </term>
334         <listitem>
335           <para>Show version of program.</para>
336         </listitem>
337       </varlistentry>
338     </variablelist>
339   </refsect1>
340
341   <refsect1>
342     <title>MUTT INTEGRATION</title>
343
344     <para>I use mailplate as my <!--TODO: verbatim-->$editor for mutt, with the following setting
345       in my ~/.mutt/muttrc:</para>
346
347     <!--TODO: verbatim
348     <para>set editor="~/.bin/mail/mailplate -\-edit -\-auto -\-keep-unknown"</para>
349     -->
350
351     <para>mailplate currently has a bit of a limitation, or at least I have
352       not figured out a way how to work around it sensibly yet. If you re-edit
353       a message from mutt’s compose menu, it causes mailplate to reprocess the
354       message, which you may not want.</para>
355
356     <para>Similarly, if you find yourself editing messages from the index or
357       pager, you probably also don’t want mailplate to get in the way. For
358       these cases, I currently use the following two keybindings:</para>
359
360     <!--TODO: verbatim
361     <para>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"</para>
362     <para>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"</para>
363     -->
364
365   </refsect1>
366
367   <refsect1>
368     <title>VIM INTEGRATION</title>
369
370     <para>I am often editing a message with vim and find that I need to use
371       a different identity. For this purpose, I have the following keybindings
372       in my ~/.vimrc:</para>
373
374     <!--TODO: verbatim
375     <para>nmap <buffer> <F1>      :w<CR>:%!mailplate -\-keep-unknown -\-auto<CR></para>
376     <para>nmap <buffer> <C-P><F1> :w<CR>:%!mailplate -\-keep-unknown private<CR></para>
377     <para>nmap <buffer> <C-P><F2> :w<CR>:%!mailplate -\-keep-unknown debian<CR></para>
378     -->
379
380     <para>Now when I reply to a message, mailplate automatically choses the
381       right template, and if I later change my mind, I can press C-p, to
382       override the choice and select the private template, or just hit to have
383       it re-run the auto-detection.</para>
384
385   </refsect1>
386
387   <refsect1>
388     <title>SEE ALSO</title>
389     <!--TODO: format paths properly -->
390     <para>http://madduck.net/code/mailplate/</para>
391     <para>/usr/share/doc/mailplate/README</para>
392   </refsect1>
393
394   <refsect1>
395     <title>AUTHOR</title>
396
397     <para>This manual page was written by &dhusername; &dhemail; with help
398       from Carl Fürstenberg.</para>
399   </refsect1>
400 </refentry>
401