.\"     Title: MAILPLATE
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
.\"      Date: September 30, 2007
.\"    Manual: 
.\"    Source: 
.\"
.TH "MAILPLATE" "1" "September 30, 2007" "" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
mailplate \- reformat mail drafts according to templates
.SH "SYNOPSIS"
.HP 10
\fBmailplate\fR [[\fB\-\-new\fR\ |\ \fB\-n\fR] | [\fB\-\-editor\fR\ |\ \fB\-e\fR]] [\fB\-\-keep\-unknown\fR | \fB\-k\fR] [\fB\-\-verbose\fR | \fB\-v\fR] [\fB\-\-debug\fR | \fB\-d\fR] \fItemplate\-name\fR \fImessage\-file\fR
.HP 10
\fBmailplate\fR [\fB\-\-keep\-unknown\fR | \fB\-k\fR] [\fB\-\-verbose\fR | \fB\-v\fR] [\fB\-\-debug\fR | \fB\-d\fR] \fItemplate\-name\fR <\ \fImessage\-data\fR
.HP 10
\fBmailplate\fR [[\fB\-\-auto\fR\ |\ \fB\-a\fR] | [\fB\-\-menu\fR\ |\ \fB\-m\fR]] [[\fB\-\-new\fR\ |\ \fB\-n\fR] | [\fB\-\-editor\fR\ |\ \fB\-e\fR]] [\fB\-\-keep\-unknown\fR | \fB\-k\fR] [\fB\-\-verbose\fR | \fB\-v\fR] [\fB\-\-debug\fR | \fB\-d\fR] \fImessage\-file\fR
.HP 10
\fBmailplate\fR [[\fB\-\-auto\fR\ |\ \fB\-a\fR] | [\fB\-\-menu\fR\ |\ \fB\-m\fR]] [\fB\-\-keep\-unknown\fR | \fB\-k\fR] [\fB\-\-verbose\fR | \fB\-v\fR] [\fB\-\-debug\fR | \fB\-d\fR] <\ \fImessage\ data\fR
.HP 10
\fBmailplate\fR [\fB\-\-help\fR | \fB\-h\fR]
.HP 10
\fBmailplate\fR [\fB\-\-version\fR | \fB\-V\fR]
.SH "DESCRIPTION"
.PP
\fBmailplate\fR
is a programme that reformats mail drafts according to a given template\&. The template may be specified on the command line, but mailplate can also use control information from the template files to automatically select an appropriate template (\fB\-\-auto\fR)\&. A selection menu feature is planned (\fB\-\-menu\fR)\&.
.PP
Applying a template means obtainined select data from an existing mail message (unless
\fB\-\-new\fR
is specified) and to fill it into appropriate slots in the template\&. Messages are processed in three parts: headers, body, and signature\&.
.PP
When
\fB\-\-new\fR
is given, an empty instantiation of the template is written to
\fIstdout\fR\&. At the moment,
\fB\-\-new\fR
cannot be combined with
\fB\-\-editor\fR\&.
.PP
The template can define two types of headers: mandatory and preservatory\&. Mandatory headers take precedence over headers in the existing message and thus overwrite them\&. Preservatory headers instruct mailplate to port their data from the existing mail message\&. Headers in the existing message but not defined in the template are dropped, unless
\fB\-\-keep\-unknown\fR
is given\&.
.PP
Body and signature are separated by \'\-\- \'\&. If this sentinel is not found, no signature is extracted\&. Templates can be interpolated and data filled into slots\&. Helper slots are filled with the output of helper commands (which must be defined in the configuration), environment variable slots are just that, and mail variable slots can be filled with data obtained by running regexps or commands over the message\&.
.PP
This script can be run in multiple ways:
.sp
.RS 4
\h'-04'\(bu\h'+03'As a filter, it applies a template to data from
\fIstdin\fR
and writes the result to
\fIstdout\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'When
\fB\-\-editor\fR
is passed, the script spawns
\fBsensible\-editor\fR
on the result\&. It may thus be used as the editor for your mail user agent\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'Given a file, it modifies the file, unless it cannot write to the file, in which case it writes to
\fIstdout\fR\&.
.RE
.SH "OPTIONS"
.PP
These programs follow the usual
GNU
command line syntax, with long options starting with two dashes (`\-\-\'):
.PP
\fB\-\-auto\fR, \fB\-a\fR
.RS 4
Turn on template auto\-discovery\&.
.RE
.PP
\fB\-\-menu\fR, \fB\-m\fR
.RS 4
Choose from a list of templates (not yet implemented)
.RE
.PP
\fB\-\-new\fR, \fB\-n\fR
.RS 4
Create a new message\&.
.RE
.PP
\fB\-\-editor\fR, \fB\-e\fR
.RS 4
Spawn editor once template is applied\&.
.RE
.PP
\fB\-\-keep\-unknown\fR, \fB\-k\fR
.RS 4
Preserve mail headers not specified in template\&.
.RE
.PP
\fB\-\-verbose\fR, \fB\-v\fR
.RS 4
Write informational messages to
\fIstderr\fR\&.
.RE
.PP
\fB\-\-debug\fR, \fB\-d\fR
.RS 4
Start a debugger after initialisation\&.
.RE
.PP
\fB\-\-help\fR, \fB\-h\fR
.RS 4
Show summary of options\&.
.RE
.PP
\fB\-\-version\fR, \fB\-V\fR
.RS 4
Show version of program\&.
.RE
.SH "MUTT INTEGRATION"
.PP
I use mailplate as my
\fI$editor\fR
for
mutt, with the following setting in my
\fI~/\&.mutt/muttrc\fR:
.sp
.RS 4
.nf
      set editor="~/\&.bin/mail/mailplate \-\-edit \-\-auto \-\-keep\-unknown"
    
.fi
.RE
.PP
mailplate currently has a bit of a limitation, or at least I have not figured out a way how to work around it sensibly yet\&. If you re\-edit a message from mutt\(cqs compose menu, it causes mailplate to reprocess the message, which you may not want\&.
.PP
Similarly, if you find yourself editing messages from the index or pager, you probably also don\(cqt want mailplate to get in the way\&. For these cases, I currently use the following two keybindings:
.sp
.RS 4
.nf
      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"
      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"
    
.fi
.RE
.SH "VIM INTEGRATION"
.PP
I am often editing a message with
vim
and find that I need to use a different identity\&. For this purpose, I have the following keybindings in my
\fI~/\&.vim/ftplugin/mail\&.vim\fR:
.sp
.RS 4
.nf
      nmap <buffer> <F1>      :w<CR>:%!mailplate \-\-keep\-unknown \-\-auto<CR>
      nmap <buffer> <C\-P><F1> :w<CR>:%!mailplate \-\-keep\-unknown private<CR>
      nmap <buffer> <C\-P><F2> :w<CR>:%!mailplate \-\-keep\-unknown debian<CR>
    
.fi
.RE
.PP
Now when I reply to a message, mailplate automatically choses the right template, and if I later change my mind, I can press C\-p, to override the choice and select the private template, or just hit to have it re\-run the auto\-detection\&.
.SH "SEE ALSO"
.PP
.RS 4

http://madduck\&.net/code/mailplate/

\fI/usr/share/doc/mailplate/README\fR
.RE
.SH "AUTHOR"
.PP
This manual page was written by martin f\&. krafft
<madduck@madduck\&.net>
with help from Carl Fürstenberg\&.
.SH "COPYRIGHT"
Copyright \(co 2007 martin f. krafft
.br