discussion and development of piem
 help / color / mirror / code / Atom feed
From: Kyle Meyer <kyle@kyleam.com>
To: piem@inbox.kyleam.com
Subject: [PATCH] manual: Clarify descriptions of b4-am commands
Date: Mon, 31 Aug 2020 23:22:39 -0400	[thread overview]
Message-ID: <20200901032239.25361-1-kyle@kyleam.com> (raw)

Avoid presenting the two am-ready variants as though they are early
stopping variants of piem-b4-am-from-mid.  That's inaccurate, as they
don't go through any of the handling in piem-b4--get-am-files and are
meant to map directly to `b4 am [options] MID' and `b4 am [options]

Also expand piem-b4-am-from-mid's description, hopefully providing a
better picture of what it's doing on top of a plain `b4 am' call.
 piem.texi | 31 +++++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/piem.texi b/piem.texi
index aea66f5..d5bc96d 100644
--- a/piem.texi
+++ b/piem.texi
@@ -298,16 +298,35 @@ for more information on using Transient.)
 @item a
 @itemx M-x piem-b4-am-from-mid
 @findex piem-b4-am-from-mid
-Generate or download a thread's mbox based on the specified message ID,
-process it into an am-ready mbox with b4, and then feed it to @code{git
-am} called within an associated Git repository
+@findex piem-mid
+Generate or download a thread's mbox for the current buffer's message
+ID, process it into an am-ready mbox with b4, and then feed it to
+@code{git am} called within an associated Git repository.  If a message
+ID of the current buffer is not known (i.e. @code{piem-mid} returns
+nil), one is read from the caller.  The caller is also queried for the
+branch name and base, as described for @code{piem-am} (@pxref{Applying
+patches contained in a message}).
+@findex piem-mid-to-thread-functions
+To generate the input thread, first any functions in
+@code{piem-mid-to-thread-functions} are tried.  This allows for a thread
+to be retrieved from a local store (e.g., the Notmuch database).  If
+that fails, the thread is downloaded from the public-inbox URL
+associated with the current buffer.  Finally, if an inbox's entry in
+@code{piem-inboxes} doesn't specify a URL, @code{b4 am} is called
+without a local mbox, letting it download the thread according to its
+own configuration.
 @item i
 @itemx M-x piem-b4-am-ready-from-mid
 @findex piem-b4-am-ready-from-mid
-Like @code{piem-b4-am-from-mid}, but stop before feeding the am-ready
-mbox to @code{git am}, ending at the same point that b4 does when called
-from the command line.
+Call @code{b4 am} with a given message ID.  This differs from
+@code{piem-b4-am-from-mid} in that it is a direct wrapper around a
+command-line call to @code{b4 am}.  The caller is always queried for the
+message ID, and the final product is an am-ready mbox.  @code{b4} is
+responsible for downloading the thread, so the caller must point b4's
+configuration option @code{b4.midmask} to the appropriate public-inbox
 @item b
 @itemx M-x piem-b4-am-ready-from-mbox

base-commit: 07c8a449d27651a0603ae9f241b518030fbb1124

                 reply	other threads:[~2020-09-01  3:22 UTC|newest]

Thread overview: [no followups] expand[flat|nested]  mbox.gz  Atom feed

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information: https://git.kyleam.com/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200901032239.25361-1-kyle@kyleam.com \
    --to=kyle@kyleam.com \
    --cc=piem@inbox.kyleam.com \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox


This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).