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.

Co-authored-by: Richard Russon <rich@flatcap.org>

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 486d0dc0a16aefc589509b7a70f1f4ba6ac30345..9b2261c347535b4417f8ba71c0ae7470fb4a21fb 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -8398,7 +8398,8 @@ set index_format="%4C %Z %{%b %d} %-15.15L (%?l?%4l&%4c?)%*  %s"
       </itemizedlist>
       <para>
         for specific details on each type of <emphasis>hook</emphasis>
-        available.
+        available.  Also see <link linkend="compose-flow">Message Composition
+        Flow</link> for an overview of the composition process.
       </para>
       <note>
         <para>
@@ -9171,6 +9172,111 @@ 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>
       <para>