]> 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:

fix urls
[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>--auto</option></arg>
75             <arg choice="plain"><option>-a</option></arg>
76           </group>
77         </arg>
78         <arg choice="plain">
79           <group>
80             <arg choice="plain"><option>--menu</option></arg>
81             <arg choice="plain"><option>-m</option></arg>
82           </group>
83         </arg>
84       </group>
85       <group>
86         <arg choice="plain">
87           <group>
88             <arg choice="plain"><option>--new</option></arg>
89             <arg choice="plain"><option>-n</option></arg>
90           </group>
91           <arg choice="plain">
92           </arg>
93           <group>
94             <arg choice="plain"><option>--editor</option></arg>
95             <arg choice="plain"><option>-e</option></arg>
96           </group>
97         </arg>
98       </group>
99       <group>
100         <arg choice="plain"><option>--keep-unknown</option></arg>
101         <arg choice="plain"><option>-k</option></arg>
102       </group>
103       <group>
104         <arg choice="plain"><option>--verbose</option></arg>
105         <arg choice="plain"><option>-v</option></arg>
106       </group>
107       <group>
108         <arg choice="plain"><option>--debug</option></arg>
109         <arg choice="plain"><option>-d</option></arg>
110       </group>
111       <arg choice="plain"><replaceable>message file</replaceable></arg>
112     </cmdsynopsis>
113     <cmdsynopsis>
114       <command>&dhpackage;</command>
115       <group>
116         <arg choice="plain">
117           <group>
118             <arg choice="plain"><option>--auto</option></arg>
119             <arg choice="plain"><option>-a</option></arg>
120           </group>
121         </arg>
122         <arg choice="plain">
123           <group>
124             <arg choice="plain"><option>--menu</option></arg>
125             <arg choice="plain"><option>-m</option></arg>
126           </group>
127         </arg>
128       </group>
129       <group>
130         <arg choice="plain"><option>--keep-unknown</option></arg>
131         <arg choice="plain"><option>-k</option></arg>
132       </group>
133       <group>
134         <arg choice="plain"><option>--verbose</option></arg>
135         <arg choice="plain"><option>-v</option></arg>
136       </group>
137       <group>
138         <arg choice="plain"><option>--debug</option></arg>
139         <arg choice="plain"><option>-d</option></arg>
140       </group>
141       <arg choice="plain"><replaceable>&lt; message data</replaceable></arg>
142     </cmdsynopsis>
143     <cmdsynopsis>
144       <command>&dhpackage;</command>
145       <group>
146         <arg choice="plain"><option>--help</option></arg>
147         <arg choice="plain"><option>-h</option></arg>
148       </group>
149     </cmdsynopsis>
150     <cmdsynopsis>
151       <command>&dhpackage;</command>
152       <group>
153         <arg choice="plain"><option>--version</option></arg>
154         <arg choice="plain"><option>-V</option></arg>
155       </group>
156     </cmdsynopsis>
157   </refsynopsisdiv>
158   <refsect1>
159     <title>DESCRIPTION</title>
160
161     <para><command>&dhpackage;</command> is a programme that reformats mail
162       drafts according to a given template. The template may be specified on
163       the command line, but mailplate can also use control information from
164       the template files to automatically select an appropriate template
165       (<option>--auto</option>). A selection menu feature is planned
166       (<option>--menu</option>). </para>
167
168     <para> Applying a template means obtainined select data from an existing
169       mail message (unless <option>--new</option> is specified) and to fill it
170       into appropriate slots in the template. Messages are processed in three
171       parts: headers, body, and signature. </para>
172
173     <para> When <option>--new</option> is given, an empty instantiation of the
174       template is written to stdout. At the moment, <option>--new</option>
175       cannot be combined with <option>--editor</option>.</para>
176
177     <para> The template can define two types of headers: mandatory and
178       preservatory. Mandatory headers take precedence over headers in the
179       existing message and thus overwrite them. Preservatory headers instruct
180       mailplate to port their data from the existing mail message. Headers in
181       the existing message but not defined in the template are dropped, unless
182       <option>--keep-unknown</option> is given. </para>
183
184     <para> Body and signature are separated by '-- '. If this sentinel is not
185       found, no signature is extracted. Templates can be interpolated and data
186       filled into slots. Helper slots are filled with the output of helper
187       commands (which must be defined in the configuration), environment
188       variable slots are just that, and mail variable slots can be filled with
189       data obtained by running regexps or commands over the message. </para>
190
191     <para> This script can be run in multiple ways: </para>
192
193     <itemizedlist>
194       <listitem><para> As a filter, it applies a template to data from stdin
195           and writes the result to stdout. </para></listitem>
196
197       <listitem><para> Given a file, it modifies the file, unless it cannot
198           write to the file, in which case it writes to stdout.
199           </para></listitem>
200
201       <listitem><para> When <option>--editor</option> is passed, the script
202           spawns <command>sensible-editor</command> on the result. It may thus
203           be used as the editor for your mail user agent. </para></listitem>
204
205     </itemizedlist>
206
207   </refsect1>
208
209   <refsect1>
210     <title>OPTIONS</title>
211
212     <para> These programs follow the usual &gnu; command line syntax, with
213       long options starting with two dashes (`--'): </para>
214
215     <variablelist>
216       <varlistentry>
217         <term><option>--auto</option>,
218           <option>-a</option>
219         </term>
220         <listitem>
221           <para>Turn on template auto-discovery.</para>
222         </listitem>
223       </varlistentry>
224       <varlistentry>
225         <term><option>--menu</option>,
226           <option>-m</option>
227         </term>
228         <listitem>
229           <para>Choose from a list of templates (not yet implemented)</para>
230         </listitem>
231       </varlistentry>
232       <varlistentry>
233         <term><option>--new</option>,
234           <option>-n</option>
235         </term>
236         <listitem>
237           <para>Create a new message.</para>
238         </listitem>
239       </varlistentry>
240       <varlistentry>
241         <term><option>--editor</option>,
242           <option>-e</option>
243         </term>
244         <listitem>
245           <para>Spawn editor once template is applied.</para>
246         </listitem>
247       </varlistentry>
248       <varlistentry>
249         <term><option>--keep-unknown</option>,
250           <option>-k</option>
251         </term>
252         <listitem>
253           <para>Preserve mail headers not specified in template.</para>
254         </listitem>
255       </varlistentry>
256       <varlistentry>
257         <term><option>--verbose</option>,
258           <option>-v</option>
259         </term>
260         <listitem>
261           <para>Write informational messages to stderr.</para>
262         </listitem>
263       </varlistentry>
264       <varlistentry>
265         <term><option>--debug</option>,
266           <option>-d</option>
267         </term>
268         <listitem>
269           <para>Start a debugger after initialisation.</para>
270         </listitem>
271       </varlistentry>
272       <varlistentry>
273         <term>
274           <option>--help</option>,
275           <option>-h</option>
276         </term>
277         <listitem>
278           <para>Show summary of options.</para>
279         </listitem>
280       </varlistentry>
281       <varlistentry>
282         <term>
283           <option>--version</option>,
284           <option>-V</option>
285         </term>
286         <listitem>
287           <para>Show version of program.</para>
288         </listitem>
289       </varlistentry>
290     </variablelist>
291   </refsect1>
292
293   <refsect1>
294     <title>SEE ALSO</title>
295     <para>/usr/share/doc/mailplate/README</para>
296   </refsect1>
297
298   <refsect1>
299     <title>AUTHOR</title>
300
301     <para>This manual page was written by &dhusername; &dhemail; with help
302       from Carl Fürstenberg.</para>
303   </refsect1>
304 </refentry>
305