Add "Message Composition Flow" section to manual.

This provides a brief overview of the steps during message
composition, and shows when the various hooks are executed.

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 105eb585a0fdfb25987b8efdf3e422fde082bfdd..9c9fda2d691f6b6e3cf9299c60e4da4005b7c4e4 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -5918,6 +5918,8 @@ option/command.  See:
 </itemizedlist>
 
 for specific details on each type of <emphasis>hook</emphasis> available.
+Also see <link linkend="compose-flow">Message Composition Flow</link> for
+an overview of the composition process.
 </para>
 
 <note>
@@ -6733,6 +6735,130 @@ macro index ,a "&lt;save-message&gt;=archive&lt;enter&gt;&lt;enter-command&gt;ec
 
 </sect1>
 
+<sect1 id="compose-flow">
+  <title>Message Composition Flow</title>
+
+  <para>
+    This is a brief overview of the steps Mutt takes during message
+    composition.  It also shows the order and timing of hook execution.
+  </para>
+
+  <itemizedlist>
+    <listitem>
+      <para>
+        Reply envelope settings.  <link
+        linkend="reverse-name">$reverse_name</link> processing.  To,
+        Cc, Subject, References header defaults.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="my-hdr">my_hdr</link> processing for To, Cc,
+        Bcc, Subject headers.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Prompts for To, Cc, Bcc, Subject headers.
+        See <link linkend="askcc">$askcc</link>,
+        <link linkend="askbcc">$askbcc</link>,
+        <link linkend="fast-reply">$fast_reply</link>.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        From header setting.  Note: this is so <link
+        linkend="send-hook">send-hook</link>s below can match ~P, but
+        From is re-set further below in case a send-hook changes the
+        value.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="reply-hook">reply-hook</link>
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="send-hook">send-hook</link>
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        From header setting.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="my-hdr">my_hdr</link> processing for From,
+        Reply-To, Message-ID and user-defined headers.  The To, Cc,
+        Bcc, Subject, and Return-Path headers are ignored at this
+        stage.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Message body and signature generation.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="send2-hook">send2-hook</link>
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="realname">$realname</link> part of From header setting.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="editor">$editor</link> invocation for the
+        message.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="send2-hook">send2-hook</link>
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Cryptographic settings.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="fcc-hook">fcc-hook</link>.  Fcc setting.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <link linkend="compose-menu">Compose menu</link>.  Note: <link
+        linkend="send2-hook">send2-hook</link> is evaluated each time
+        the headers are changed.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Message encryption and signing.  Key selection.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Message sending.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Fcc saving.  Note: prior to version 1.12, the Fcc was saved
+        before sending the message.  It is now saved afterwards, but
+        the if saving fails, the user is prompted.
+      </para>
+    </listitem>
+  </itemizedlist>
+</sect1>
+
 <sect1 id="misc-topics">
 <title>Miscellany</title>