From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms12 with LMTPS id 191jMou+TV8GPAAAsNZ9tg (envelope-from ) for ; Tue, 01 Sep 2020 03:22:51 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id KMKNLYu+TV+yFgAAB5/wlQ (envelope-from ) for ; Tue, 01 Sep 2020 03:22:51 +0000 Received: from pb-smtp21.pobox.com (pb-smtp21.pobox.com [173.228.157.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 82585940876 for ; Tue, 1 Sep 2020 03:22:50 +0000 (UTC) Received: from pb-smtp21.pobox.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id C679AEB3A5; Mon, 31 Aug 2020 23:22:47 -0400 (EDT) (envelope-from kyle@kyleam.com) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to :subject:date:message-id:mime-version:content-transfer-encoding; s=sasl; bh=NJdjcLHXwTBGaD9D9r1IMIR+qcE=; b=GqXi5B21ePwvf6ElZBQx Y2C2HM2IQWuxGZQA8sbnOVlGflNQeJy4Bbl46qdtMw0OlT6/L5nC5TAiVom0a03r nrUT/npeMBvUF0SO20he5qd3ITZ3vuKzrRFKU8hxllS5bjylr7k1/0Y4pcxfU5Jx 5/7ArS58MELXtnRLFS6h4Sc= Received: from pb-smtp21.sea.icgroup.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id BFCBEEB3A4; Mon, 31 Aug 2020 23:22:47 -0400 (EDT) (envelope-from kyle@kyleam.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=kyleam.com; h=from:to:subject:date:message-id:mime-version:content-transfer-encoding; s=mesmtp; bh=TNTcVz7ZkMujFHxyDtZ2pahmTozCx+lLTo6UubRSq3U=; b=q86YNUQOb6LKUKrUQrtZL17o9mWGhUl0Rw0UlDXe6DlmPAls2V/PaWIXP+NhYaFDfLXQPRhcNRC56+EJ76p/9eXZYN+AcqSx+l2QPjMpzZdsy3tCcFL2Ji5pMwRRwEgyB8zL5A+YXBa1rmeOdSYqbhDLv3bH8mwFqMzgEib+GyA= Received: from localhost (unknown [45.33.91.115]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp21.pobox.com (Postfix) with ESMTPSA id C02A2EB3A1; Mon, 31 Aug 2020 23:22:43 -0400 (EDT) (envelope-from kyle@kyleam.com) From: Kyle Meyer To: piem@inbox.kyleam.com Subject: [PATCH] manual: Clarify descriptions of b4-am commands Date: Mon, 31 Aug 2020 23:22:39 -0400 Message-Id: <20200901032239.25361-1-kyle@kyleam.com> X-Mailer: git-send-email 2.28.0 MIME-Version: 1.0 X-Pobox-Relay-ID: 66434EA0-EC02-11EA-9B64-843F439F7C89-24757444!pb-smtp21.pobox.com Content-Transfer-Encoding: quoted-printable X-Scanner: scn0 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=pobox.com header.s=sasl header.b=GqXi5B21; dkim=fail (body hash did not verify) header.d=kyleam.com header.s=mesmtp header.b=q86YNUQO; dmarc=none; spf=pass (aspmx1.migadu.com: domain of kyle@kyleam.com designates 173.228.157.53 as permitted sender) smtp.mailfrom=kyle@kyleam.com X-Spam-Score: 2.50 X-TUID: 2LyWzpDewy9g 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] --use-local-mbox=3DFILE'. 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. =20 @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 +URL. =20 @item b @itemx M-x piem-b4-am-ready-from-mbox base-commit: 07c8a449d27651a0603ae9f241b518030fbb1124 --=20 2.28.0