X-Git-Url: https://git.madduck.net/code/mailplate.git/blobdiff_plain/b41f368d5a71f787d594880fd4ccf8425aafc79d..0f1acf006be83292400ef9f47103b5ecec65e1e9:/mailplate.xml

diff --git a/mailplate.xml b/mailplate.xml
index 7e7072c..b76723c 100644
--- a/mailplate.xml
+++ b/mailplate.xml
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding='ISO-8859-1'?>
+<?xml version='1.0' encoding='utf-8'?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
 
@@ -66,6 +66,54 @@ and docbook-xsl in your Build-Depends control field.
     <refpurpose>reformat mail drafts according to templates</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>&dhpackage;</command>
+      <group>
+        <arg choice="plain">
+          <group>
+	    <arg choice="plain"><option>--new</option></arg>
+	    <arg choice="plain"><option>-n</option></arg>
+          </group>
+        </arg>
+        <arg choice="plain">
+          <group>
+	    <arg choice="plain"><option>--editor</option></arg>
+	    <arg choice="plain"><option>-e</option></arg>
+          </group>
+        </arg>
+      </group>
+      <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"><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>
@@ -88,8 +136,8 @@ and docbook-xsl in your Build-Depends control field.
 	    <arg choice="plain"><option>--new</option></arg>
 	    <arg choice="plain"><option>-n</option></arg>
           </group>
-          <arg choice="plain">
-          </arg>
+        </arg>
+        <arg choice="plain">
           <group>
 	    <arg choice="plain"><option>--editor</option></arg>
 	    <arg choice="plain"><option>-e</option></arg>
@@ -108,7 +156,7 @@ and docbook-xsl in your Build-Depends control field.
 	<arg choice="plain"><option>--debug</option></arg>
 	<arg choice="plain"><option>-d</option></arg>
       </group>
-      <arg choice="plain"><replaceable>message file</replaceable></arg>
+      <arg choice="plain"><replaceable>message-file</replaceable></arg>
     </cmdsynopsis>
     <cmdsynopsis>
       <command>&dhpackage;</command>
@@ -138,7 +186,7 @@ and docbook-xsl in your Build-Depends control field.
 	<arg choice="plain"><option>--debug</option></arg>
 	<arg choice="plain"><option>-d</option></arg>
       </group>
-      <arg choice="plain"><replaceable>&lt; message data</replaceable></arg>
+      <arg choice="plain">&lt; <replaceable>message data</replaceable></arg>
     </cmdsynopsis>
     <cmdsynopsis>
       <command>&dhpackage;</command>
@@ -194,14 +242,14 @@ and docbook-xsl in your Build-Depends control field.
       <listitem><para> As a filter, it applies a template to data from stdin
           and writes the result to stdout. </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>
-
       <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>
+
     </itemizedlist>
 
   </refsect1>
@@ -290,8 +338,56 @@ and docbook-xsl in your Build-Depends control field.
     </variablelist>
   </refsect1>
 
+  <refsect1>
+    <title>MUTT INTEGRATION</title>
+
+    <para>I use mailplate as my <!--TODO: verbatim-->$editor for mutt, with the following setting
+      in my ~/.mutt/muttrc:</para>
+
+    <!--TODO: verbatim
+    <para>set editor="~/.bin/mail/mailplate -\-edit -\-auto -\-keep-unknown"</para>
+    -->
+
+    <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>
+
+    <!--TODO: verbatim
+    <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>
+    <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>
+    -->
+
+  </refsect1>
+
+  <refsect1>
+    <title>VIM INTEGRATION</title>
+
+    <para>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 ~/.vimrc:</para>
+
+    <!--TODO: verbatim
+    <para>nmap <buffer> <F1>      :w<CR>:%!mailplate -\-keep-unknown -\-auto<CR></para>
+    <para>nmap <buffer> <C-P><F1> :w<CR>:%!mailplate -\-keep-unknown private<CR></para>
+    <para>nmap <buffer> <C-P><F2> :w<CR>:%!mailplate -\-keep-unknown debian<CR></para>
+    -->
+
+    <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>
+    <!--TODO: format paths properly -->
+    <para>http://madduck.net/code/mailplate/</para>
     <para>/usr/share/doc/mailplate/README</para>
   </refsect1>