X-Git-Url: https://git.madduck.net/code/mailplate.git/blobdiff_plain/872a6c420ffb2a831287b00dfd991cbeebe233a7..a382cb10e13dc60580cddae71db029adaddef10d:/mailplate.xml

diff --git a/mailplate.xml b/mailplate.xml
index 992714f..b59b2e2 100644
--- a/mailplate.xml
+++ b/mailplate.xml
@@ -97,6 +97,23 @@ and docbook-xsl in your Build-Depends control field.
       <arg choice="plain"><replaceable>template-name</replaceable></arg>
       <arg choice="plain"><replaceable>message-file</replaceable></arg>
     </cmdsynopsis>
+    <cmdsynopsis>
+      <command>&dhpackage;</command>
+      <group>
+	<arg choice="plain"><option>--keep-unknown</option></arg>
+	<arg choice="plain"><option>-k</option></arg>
+      </group>
+      <group>
+	<arg choice="plain"><option>--verbose</option></arg>
+	<arg choice="plain"><option>-v</option></arg>
+      </group>
+      <group>
+	<arg choice="plain"><option>--debug</option></arg>
+	<arg choice="plain"><option>-d</option></arg>
+      </group>
+      <arg choice="plain"><replaceable>template-name</replaceable></arg>
+      <arg choice="plain">&lt; <replaceable>message-data</replaceable></arg>
+    </cmdsynopsis>
     <cmdsynopsis>
       <command>&dhpackage;</command>
       <group>
@@ -202,8 +219,9 @@ and docbook-xsl in your Build-Depends control field.
       parts: headers, body, and signature. </para>
 
     <para> When <option>--new</option> is given, an empty instantiation of the
-      template is written to stdout. At the moment, <option>--new</option>
-      cannot be combined with <option>--editor</option>.</para>
+      template is written to <filename>stdout</filename>. At the moment,
+      <option>--new</option> cannot be combined with
+      <option>--editor</option>.</para>
 
     <para> The template can define two types of headers: mandatory and
       preservatory. Mandatory headers take precedence over headers in the
@@ -222,16 +240,17 @@ and docbook-xsl in your Build-Depends control field.
     <para> This script can be run in multiple ways: </para>
 
     <itemizedlist>
-      <listitem><para> As a filter, it applies a template to data from stdin
-          and writes the result to stdout. </para></listitem>
+      <listitem><para> As a filter, it applies a template to data from
+          <filename>stdin</filename> and writes the result to
+          <filename>stdout</filename>. </para></listitem>
 
       <listitem><para> When <option>--editor</option> is passed, the script
           spawns <command>sensible-editor</command> on the result. It may thus
           be used as the editor for your mail user agent. </para></listitem>
 
       <listitem><para> Given a file, it modifies the file, unless it cannot
-          write to the file, in which case it writes to stdout.
-          </para></listitem>
+          write to the file, in which case it writes to
+          <filename>stdout</filename>. </para></listitem>
 
     </itemizedlist>
 
@@ -289,7 +308,7 @@ and docbook-xsl in your Build-Depends control field.
 	  <option>-v</option>
         </term>
         <listitem>
-	  <para>Write informational messages to stderr.</para>
+	  <para>Write informational messages to <filename>stderr</filename>.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -321,10 +340,68 @@ and docbook-xsl in your Build-Depends control field.
     </variablelist>
   </refsect1>
 
+  <refsect1>
+    <title>MUTT INTEGRATION</title>
+
+    <para>I use mailplate as my <varname>$editor</varname> for
+      <application>mutt</application>, with the following setting in my
+      <filename>~/.mutt/muttrc</filename>:</para>
+
+    <programlisting><![CDATA[
+      set editor="~/.bin/mail/mailplate --edit --auto --keep-unknown"
+    ]]></programlisting>
+
+    <para>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’s compose menu, it causes mailplate to reprocess the
+      message, which you may not want.</para>
+
+    <para>Similarly, if you find yourself editing messages from the index or
+      pager, you probably also don’t want mailplate to get in the way. For
+      these cases, I currently use the following two keybindings:</para>
+
+    <programlisting><![CDATA[
+      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"
+    ]]></programlisting>
+
+  </refsect1>
+
+  <refsect1>
+    <title>VIM INTEGRATION</title>
+
+    <para>I am often editing a message with <application>vim</application> and
+      find that I need to use a different identity. For this purpose, I have
+      the following keybindings in my
+      <filename>~/.vim/ftplugin/mail.vim</filename>:</para>
+
+    <programlisting><![CDATA[
+      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>
+    ]]></programlisting>
+
+    <para>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.</para>
+
+  </refsect1>
+
   <refsect1>
     <title>SEE ALSO</title>
-    <para>http://madduck.net/code/mailplate/</para>
-    <para>/usr/share/doc/mailplate/README</para>
+    <varlistentry>
+      <listitem>
+        <para>
+          <link>http://madduck.net/code/mailplate/</link>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <filename>/usr/share/doc/mailplate/README</filename>
+        </para>
+      </listitem>
+    </varlistentry>
   </refsect1>
 
   <refsect1>