[PATCH] b4: Better describe how piem-b4-am-ready-from-mid gets the thread

[PATCH] b4: Better describe how piem-b4-am-ready-from-mid gets the thread

[Kyle Meyer]

piem-b4-am-ready-from-mid's docstring doesn't mention that it tries to
download the thread from a piem-inboxes URL before falling back to
letting b4 handle the download.  The manual's description is better,
though it makes it sound like the b4 fallback depends on not finding a
URL in piem-inboxes rather than the download being unsuccessful for
whatever reason.  Reword the docstring and manual text to hopefully
make things clearer.
---
 Documentation/piem.texi | 10 +++++-----
 piem-b4.el              | 13 +++++++++----
 2 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/Documentation/piem.texi b/Documentation/piem.texi
index ca6a97b..f4bbabc 100644
--- a/Documentation/piem.texi
+++ b/Documentation/piem.texi
@@ -341,11 +341,11 @@ Using b4 to apply patches
 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.
+that fails, try to download the thread from the @code{piem-inboxes} URL
+associated with the current buffer, provided the current buffer's
+message ID matches the one @code{piem-b4-am-from-mid} was called with.
+As a last resort, call @code{b4 am} without a local mbox to let it
+download the thread according to its own configuration.
 
 @item i
 @itemx M-x piem-b4-am-ready-from-mid
diff --git a/piem-b4.el b/piem-b4.el
index e76953e..ddb18d5 100644
--- a/piem-b4.el
+++ b/piem-b4.el
@@ -131,10 +131,15 @@ (defun piem-b4-am-ready-from-mid (mid &optional args)
 (defun piem-b4-am-from-mid (mid &optional args toggle-worktree)
   "Get the thread for MID, extract an am-ready mbox, and apply it.
 
-Try to get a thread for the Message-Id MID with
-`piem-mid-to-thread-functions', falling back to letting b4
-download it.  After calling `b4 am' with ARGS to prepare an
-am-ready mbox, feed the result to `git am'.
+Try to generate a thread for the Message-Id MID with
+`piem-mid-to-thread-functions'.  If that fails, try to download
+the thread from the `piem-inboxes' URL associated with the
+current buffer, provided that the current buffer's message ID
+matches MID.  And if that doesn't work, let `b4 am' download the
+thread according to its own configuration.
+
+After calling `b4 am' with ARGS to prepare an am-ready mbox, feed
+the result to `git am'.
 
 When prefix argument TOGGLE-WORKTREE is non-nil, invert the
 meaning of `piem-am-create-worktree'.  With the default value,

base-commit: 3cf9a8213ff78b9226dba0ad0c045c7de41f3c96
-- 
2.31.1