[PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings

[PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings

[Quentin Schulz]

This makes use of rST version admonitions for config settings in
anticipation to make each config setting a term such that we can
cross-reference them easily and have an anchor in the output for easier
link sharing. Then it migrates current "verbatim cross-references" to
actual cross-references using :term:.

This adds version admonitions for sections applicable only to some
versions and for program arguments.

This separates the b4.thanks-pr-template and b4.thanks-am-template as
well as include verbatim the example templates from the repo (for
b4.shazam-merge-template) instead of vaguely mentioning them.

This fixes various typos.

This adds external links to manpages.

This adds missing info on settings/options version deprecation and
addition.

This sorts the config settings per section (glossary), both by enforcing
it at the directive level and also in the text.

This adds missing b4.linkmask reference to b4 am/shazam --add-link.

I haven't changed the program options into a glossary, but this is
something I could do if there's interest.

Note: ``b4 send`` seems to be picking up
``Signed-off-by: Your Name <your.name@example.com>`` from the git
context in patch 11 and adds it to Cc recipients for some reason??

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
Quentin Schulz (21):
      docs: maintainer: ty: fix incorrect config name for templates
      docs: prep: add info on when range-diff-opts was added
      docs: diff: add info on when range-diff-opts was added
      docs: contributor: send: fix sendmail typo
      docs: config: separate b4.thanks-pr-template and b4.thanks-am-template
      docs: use rST version admonitions for command options
      docs: use versionadded admonition for sections
      docs: maintainer: use deprecated admonition
      docs: config: provide link to git-config conf file documentation
      docs: config: fix discrepancy between example strings
      docs: move sentence-ending dots from within the last quoted string to outside
      docs: config: add missing dot at end of sentence
      docs: config: provide link to patatt
      docs: config: provide link to git-send-email manpage
      docs: config: fix double colon typo
      docs: config: provide example content for template files
      docs: config: use rST version admonitions
      docs: config: migrate definition lists to glossaries
      docs: config: sort glossaries
      docs: cross-reference config options with :term:
      docs: maintainer: am-shazam: cross-reference b4.linkmask for --add-link

 docs/config.rst               | 615 +++++++++++++++++++++++-------------------
 docs/contributor/prep.rst     |  49 +++-
 docs/contributor/send.rst     |  34 ++-
 docs/maintainer/am-shazam.rst |  12 +-
 docs/maintainer/diff.rst      |  16 +-
 docs/maintainer/mbox.rst      |  12 +-
 docs/maintainer/pr.rst        |  13 +-
 docs/maintainer/ty.rst        |   8 +-
 8 files changed, 437 insertions(+), 322 deletions(-)
---
base-commit: 38c61e3d0a1b2b14ee75f3d763362fd63e162849
change-id: 20260203-misc-docs-1dca48ffccc0

Best regards,
--  
Quentin Schulz <quentin.schulz@cherry.de>

[PATCH b4 01/21] docs: maintainer: ty: fix incorrect config name for templates

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

The config options are named with dashes and not underscores, so let's
fix that oversight.

Fixes: 2ce1e619ddb4 ("docs: complete most of the maintainer docs")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/maintainer/ty.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/maintainer/ty.rst b/docs/maintainer/ty.rst
index fd69c7e..b445bb6 100644
--- a/docs/maintainer/ty.rst
+++ b/docs/maintainer/ty.rst
@@ -74,7 +74,7 @@ Editing the templates
 You can edit the default templates that are provided with b4 to
 customize the thank-you message. Once you have your own versions, you
 can specify the path to the template to use via the
-``b4.thanks_am_template`` and ``b4.thanks_pr_template`` configuration
+``b4.thanks-am-template`` and ``b4.thanks-pr-template`` configuration
 parameters. See :ref:`ty_settings` for details.
 
 Optional flags

-- 
2.52.0

[PATCH b4 02/21] docs: prep: add info on when range-diff-opts was added

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

This specifies since which release the range-diff-opts option is
available (which is not yet, hence v0.15).

Fixes: eb4a66b12bc4 ("prep: support passing arguments to git range-diff")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/contributor/prep.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 18c710d..4c26602 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -500,3 +500,5 @@ modifying defaults for some of these flags.
   ``--compare-to``. For example::
 
       b4 prep --compare-to v1 --range-diff-opts "--creation-factor=80 --no-dual-color"
+
+  .. versionadded:: v0.15

-- 
2.52.0

[PATCH b4 03/21] docs: diff: add info on when range-diff-opts was added

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

This specifies since which release the range-diff-opts option is
available (which is not yet, hence v0.15).

Fixes: 3c7fbc395fc6 ("diff: support passing arguments to git range-diff")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/maintainer/diff.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/maintainer/diff.rst b/docs/maintainer/diff.rst
index 7911cdc..4e3fac0 100644
--- a/docs/maintainer/diff.rst
+++ b/docs/maintainer/diff.rst
@@ -47,6 +47,8 @@ Optional flags
 
       b4 diff --range-diff-opts "--creation-factor=80 --no-dual-color" <url>
 
+  .. versionadded:: v0.15
+
 ``-o OUTDIFF, --output-diff OUTDIFF``
   **(DEPRECATED)** Sends ``range-diff`` output into a file. You should use
   ``-n`` instead and redirect output from the actual ``git range-diff``

-- 
2.52.0

[PATCH b4 04/21] docs: contributor: send: fix sendmail typo

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

There's a sendmail binary, but the git configuration settings are
sendemail and not sendmail (and you can use sendmail in sendemail to
make things more confusing), so let's fix that oversight.

Fixes: e8045d135316 ("ez: Add --use-web-endpoint arg to force web endpoint")
Fixes: 890fdc05400e ("docs: document pre-flight checks")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/contributor/send.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/contributor/send.rst b/docs/contributor/send.rst
index 54ed474..0de2aa5 100644
--- a/docs/contributor/send.rst
+++ b/docs/contributor/send.rst
@@ -141,9 +141,9 @@ with the following setting::
 
 Using your own SMTP server
 --------------------------
-If there is a ``sendmail`` section in your git configuration, B4 tries
+If there is a ``sendemail`` section in your git configuration, B4 tries
 to use that by default instead of going via the web endpoint. At this
-time, b4 only recognizes a subset of ``sendmail`` options supported by
+time, b4 only recognizes a subset of ``sendemail`` options supported by
 git itself. The vast majority of servers should only need the following
 settings::
 
@@ -156,7 +156,7 @@ settings::
 
 You can also set up ``msmtp`` or a similar tool and specify the path to
 the ``sendmail``-compliant binary as the value for ``smtpServer``. To
-force B4 to use the web endpoint even when a ``sendmail`` option is
+force B4 to use the web endpoint even when a ``sendemail`` option is
 present, use the ``--use-web-endpoint`` switch.
 
 Sending your patches

-- 
2.52.0

[PATCH b4 05/21] docs: config: separate b4.thanks-pr-template and b4.thanks-am-template

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

While their definition are identical (so far), they are for different
things and this way of presenting the configs may confuse the user into
thinking those are aliases for the same thing. They aren't, so split
them.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/config.rst b/docs/config.rst
index a1145af..a9006a5 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -236,7 +236,13 @@ Attestation settings
 
 ``ty`` settings
 ~~~~~~~~~~~~~~~
-``b4.thanks-pr-template``, ``b4.thanks-am-template``
+``b4.thanks-pr-template``
+  Full paths to the templates to use when generating thank-you messages
+  for contributors. See example templates provided with the project.
+
+  Default: ``None``
+
+``b4.thanks-am-template``
   Full paths to the templates to use when generating thank-you messages
   for contributors. See example templates provided with the project.
 

-- 
2.52.0

[PATCH b4 06/21] docs: use rST version admonitions for command options

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

rST provides directives[1] to specify for which version something was
added or modified, so let's use that.

This notably frees the definition list's term of the version string
which will be important in the next commit where the definition lists
are replaced by glossary terms such that they automatically provide an
anchor which makes it easier to share a link to the option or parameter
and also allows to link at the term definition with :term: across the
docs.

[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#describing-changes-between-versions
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/contributor/prep.rst     | 32 ++++++++++++++++++++++++--------
 docs/contributor/send.rst     |  8 ++++++--
 docs/maintainer/am-shazam.rst |  8 ++++++--
 docs/maintainer/mbox.rst      | 12 +++++++++---
 docs/maintainer/ty.rst        |  4 +++-
 5 files changed, 48 insertions(+), 16 deletions(-)

diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 4c26602..122e3cd 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -372,16 +372,20 @@ modifying defaults for some of these flags.
   don't like vim, you would have already set your ``$EDITOR`` to use
   some other command.
 
-``--edit-deps`` **(v0.14+)**
+``--edit-deps``
   Lets you edit the series dependencies using the editor command defined
   in git-config as ``core.editor``, the ``$EDITOR`` environment var if
   that isn't found, or ``vim``.
 
-``--check-deps`` **(v0.14+)**
+  .. versionadded:: v0.14
+
+``--check-deps``
   Verifies that b4 can resolve all specified dependencies and that
   everything cleanly applies to the base-commit specified.
 
-``--check`` **(v0.14+)**
+  .. versionadded:: v0.14
+
+``--check``
   Runs a set of checks on your series to identify some of the more
   common problems.
 
@@ -402,6 +406,8 @@ modifying defaults for some of these flags.
 
       ./scripts/checkpatch.pl --strict --git $(b4 prep --show-info series-range)
 
+  .. versionadded:: v0.14
+
 ``--show-revision``
   Shows the current series revision.
 
@@ -409,13 +415,15 @@ modifying defaults for some of these flags.
   Forces the revision to a different integer number. This modifies your
   cover letter and tracking information and makes this change permanent.
 
-``--compare-to vN`` **(v0.11+)**
+``--compare-to vN``
   This executes a ``git range-diff`` command that lets you compare the
   previously sent version of the series to what is currently in your
   working branch. This is very useful right before sending off a new
   revision to make sure that you didn't forget to include anything into
   changelogs.
 
+  .. versionadded:: v0.11
+
 ``--manual-reroll MSGID``
   Normally, your patch series should be automatically rerolled to the
   next version after a successful ``b4 send`` operation (see
@@ -425,7 +433,7 @@ modifying defaults for some of these flags.
   from the public-inbox server, so we can properly add the reference to
   the previously sent series to the cover letter changelog.
 
-``--set-prefixes PREFIX [PREFIX ...]`` **(v0.11+)**
+``--set-prefixes PREFIX [PREFIX ...]``
   If you want to mark your patch as ``RFC``, ``WIP``, or add any other
   subsystem identifiers, you can define them via this command. Do
   **not** add ``PATCH`` or ``v1`` here, as these are already
@@ -440,11 +448,15 @@ modifying defaults for some of these flags.
   When b4 sends the message, it should add ``PATCH``, ``vN``, to the
   subject as necessary.
 
-``--add-prefixes PREFIX [PREFIX ...]`` **(v0.14+)**
+  .. versionadded:: v0.11
+
+``--add-prefixes PREFIX [PREFIX ...]``
   Similar to ``--set-prefixes``, but will add prefixes to any ones
   currently defined, as opposed to completely replacing them.
 
-``--show-info [PARAM]`` **(v0.13+)**
+  .. versionadded:: v0.14
+
+``--show-info [PARAM]``
   Dumps information about the current series in a format suitable for
   parsing by other tools. Starting with v0.13, the parameter can be one
   of the following:
@@ -471,7 +483,9 @@ modifying defaults for some of these flags.
 
       b4 prep --show-info
 
-``--cleanup [BRANCHNAME]`` **(v0.13+)**
+  .. versionadded:: v0.13
+
+``--cleanup [BRANCHNAME]``
   Archive and delete obsolete prep-managed branches and all git objects
   related to them, such as sent tags. Run without parameters to list
   all known prep-managed branches in the repository. Rerun with the
@@ -479,6 +493,8 @@ modifying defaults for some of these flags.
   and tracking information, and then delete all git objects related to
   that series from the local repository.
 
+  .. versionadded:: v0.13
+
 ``-n NEW_SERIES_NAME, --new NEW_SERIES_NAME``
   Creates a new branch to start work on a new patch series.
 
diff --git a/docs/contributor/send.rst b/docs/contributor/send.rst
index 0de2aa5..f9fd9e4 100644
--- a/docs/contributor/send.rst
+++ b/docs/contributor/send.rst
@@ -279,19 +279,23 @@ Command line flags
   actually sending things out and lets you verify that all patches are
   looking good and all recipients are correctly set.
 
-``--preview-to`` **(v0.13+)**
+``--preview-to``
   Sometimes it's useful to send your series for a pre-review to a
   colleague, mentor, boss, etc. Using this option sends out the prepared
   patches to the addresses specified on the command line, but doesn't
   reroll your series, allowing you to send the actual submission at some
   later point.
 
-``--reflect`` **(v0.11+)**
+  .. versionadded:: v0.13
+
+``--reflect``
   Prepares everything for sending, but only emails yourself (the address
   in the ``From:`` header). Useful as a last step to make sure that
   everything is looking good, and especially useful when using the web
   endpoint, because it may rewrite your From: header for DMARC reasons.
 
+  .. versionadded:: v0.11
+
 ``--no-trailer-to-cc``
   Tells b4 not to add any addresses found in the cover or patch trailers
   to To: or Cc:. This is usually handy for testing purposes, in case you
diff --git a/docs/maintainer/am-shazam.rst b/docs/maintainer/am-shazam.rst
index b691706..1ca9b50 100644
--- a/docs/maintainer/am-shazam.rst
+++ b/docs/maintainer/am-shazam.rst
@@ -75,12 +75,14 @@ The following flags are common to both commands:
   This lets you force b4 to ignore cache and retrieve the latest
   results.
 
-``--single-message`` **(0.13+)**
+``--single-message``
   By default, b4 retrieves the entire thread, but sometimes you really
   just want a single message. This helps when someone posts a patch in
   the middle of a long thread and you just want that patch and ignore
   the rest of the messages.
 
+  .. versionadded:: v0.13
+
 ``-v WANTVER, --use-version WANTVER``
   If a thread (or threads, when used with ``-c``) contains multiple
   patch series revisions, b4 automatically picks the highest numbered
@@ -162,7 +164,7 @@ The following flags are common to both commands:
   translated into left-to-right languages), you can override the default
   behavior with this switch.
 
-``--check`` **(0.14+)**
+``--check``
   Tells b4 to run a series of local checks on each patch of the series
   and display any problems. When b4 finds a valid patchwork project
   definition in the configuration settings, it also looks up the CI
@@ -178,6 +180,8 @@ The following flags are common to both commands:
       [b4]
       am-perpatch-check-cmd = ./scripts/checkpatch.pl -q --terse --no-summary --mailback --strict
 
+  .. versionadded:: v0.14
+
 Flags only valid for ``b4 am``
 ------------------------------
 The following flags only make sense for ``b4 am``:
diff --git a/docs/maintainer/mbox.rst b/docs/maintainer/mbox.rst
index b4bba22..f3597a9 100644
--- a/docs/maintainer/mbox.rst
+++ b/docs/maintainer/mbox.rst
@@ -33,7 +33,7 @@ Option flags
   and you need to do some work while offline. You can pass ``-`` to read
   messages from stdin.
 
-``--stdin-pipe-sep STDIN_PIPE_SEP`` **(0.11+)**
+``--stdin-pipe-sep STDIN_PIPE_SEP``
   When reading input from stdin, split messages using the string passed
   as parameter. Otherwise, b4 expects stdin to be a single message or a
   valid mbox.
@@ -45,17 +45,21 @@ Option flags
 
   Then invoke b4 with ``-m - --stdin-pipe-sep='\n---randomstr---\n'``
 
+  .. versionadded:: v0.11
+
 ``-C, --no-cache``
   By default, b4 will cache the retrieved threads for about 10 minutes.
   This lets you force b4 to ignore cache and retrieve the latest
   results.
 
-``--single-message`` **(0.13+)**
+``--single-message``
   By default, b4 will retrieve the entire thread, but sometimes you
   really just want a single message. This helps when someone posts a
   patch in the middle of a long thread and you just want that patch and
   ignore the rest of what is going on.
 
+  .. versionadded:: v0.13
+
 ``-o OUTDIR, --outdir OUTDIR``
   Instead of writing the .mbox file to the current directory, write it
   to this location instead. You can also pass a path to an existing
@@ -85,7 +89,7 @@ Option flags
   that aren't already present. Note, that this uses simple message-id
   matching and no other checks for correctness are performed.
 
-``-r MBOX, --refetch MBOX`` **(v0.12+)**
+``-r MBOX, --refetch MBOX``
   This allows you to refetch all messages in the provided mailbox from
   the upstream public-inbox server. For example, this is useful when you
   have a .mbx file prepared by ``b4 am`` and you want to send a
@@ -93,6 +97,8 @@ Option flags
   original message headers that may have been dropped or modified by
   ``b4 am``.
 
+  .. versionadded:: v0.12
+
 Using with mutt
 ---------------
 If you are a mutt or neomutt user and your mail is stored locally, you
diff --git a/docs/maintainer/ty.rst b/docs/maintainer/ty.rst
index b445bb6..21c56de 100644
--- a/docs/maintainer/ty.rst
+++ b/docs/maintainer/ty.rst
@@ -130,6 +130,8 @@ Optional flags
   state instead of the default specified in config settings (use with
   -a, -t or -d). See :ref:`patchwork_settings` for more details.
 
-``--me-too`` **(v0.15+)**
+``--me-too``
   Include yourself in the thank-you message cc's. This is useful if you
   want to keep track of which patches you applied to your tree.
+
+  .. versionadded:: v0.15

-- 
2.52.0

[PATCH b4 07/21] docs: use versionadded admonition for sections

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

So that we use version admonitions consistently across the docs for
things that were added or modified in given releases.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/contributor/prep.rst |  9 +++++++--
 docs/contributor/send.rst | 14 ++++++++++----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 122e3cd..6e90b10 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -187,7 +187,9 @@ additional information about the intent of your entire series.
 Working with series dependencies
 --------------------------------
 
-.. warning:: new in **(v0.14+)**
+.. versionadded:: v0.14
+
+.. warning::
 
    This is an experimental set of features introduced in v0.14. It may
    have rough edges or unexpected bugs.
@@ -314,7 +316,10 @@ This may also be already set by the project, if they have a
 
 Checking your work
 ------------------
-.. warning:: new in **(v0.14+)**
+
+.. versionadded:: v0.14
+
+.. warning::
 
    This is a new feature in version 0.14 and you should consider it
    experimental.
diff --git a/docs/contributor/send.rst b/docs/contributor/send.rst
index f9fd9e4..f5a1ff1 100644
--- a/docs/contributor/send.rst
+++ b/docs/contributor/send.rst
@@ -170,8 +170,11 @@ sending your work.
   prep``, but future versions may support sending arbitrary patches
   generated with ``git format-patch``.
 
-Passing pre-flight checks **(v0.14+)**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Passing pre-flight checks
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: v0.14
+
 B4 defines some pre-flight checks that should be passing, or the command
 generates a warning:
 
@@ -230,8 +233,11 @@ When ``--reflect`` is on:
   public-inbox feed
 * your branch is **not** automatically rerolled to the next revision
 
-Checking things over with ``--preview-to`` **(v0.13+)**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Checking things over with ``--preview-to``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: v0.13
+
 Sometimes you want to ask your friend, colleague, boss, or mentor to
 give your submission a quick review. You can send them your series using
 ``--preview-to boss@example.com`` before you send things out to the

-- 
2.52.0

[PATCH b4 08/21] docs: maintainer: use deprecated admonition

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

Use the rST deprecated admonition[1] to specify since which release this
has been deprecated.

One can add information as to what to replace the option with, so that's
what's done wherever we have that information.

The version is the first one to have the commits which inserts the
deprecated string for the options, which is commit 2ce1e619ddb4 ("docs:
complete most of the maintainer docs") available in v0.10.

[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/maintainer/diff.rst | 14 +++++++++-----
 docs/maintainer/pr.rst   | 13 +++++++++----
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/docs/maintainer/diff.rst b/docs/maintainer/diff.rst
index 4e3fac0..f546fd6 100644
--- a/docs/maintainer/diff.rst
+++ b/docs/maintainer/diff.rst
@@ -50,10 +50,14 @@ Optional flags
   .. versionadded:: v0.15
 
 ``-o OUTDIFF, --output-diff OUTDIFF``
-  **(DEPRECATED)** Sends ``range-diff`` output into a file. You should use
-  ``-n`` instead and redirect output from the actual ``git range-diff``
-  command.
+  Sends ``range-diff`` output into a file.
+
+  .. deprecated:: v0.10
+     You should use ``-n`` instead and redirect output from the actual
+     ``git range-diff`` command.
 
 ``-c, --color``
-  **(DEPRECATED)** Show colour output even when outputting into a file.
-  You should use ``-n`` instead and modify flags to ``range-diff``.
+  Show colour output even when outputting into a file.
+
+  .. deprecated:: v0.10
+     You should use ``-n`` instead and modify flags to ``range-diff``.
diff --git a/docs/maintainer/pr.rst b/docs/maintainer/pr.rst
index 46db7ee..ca0310d 100644
--- a/docs/maintainer/pr.rst
+++ b/docs/maintainer/pr.rst
@@ -64,14 +64,19 @@ archival public-inbox so they can be analyzed by archivists at a later
 date if necessary.
 
 ``-f MAILFROM, --from-addr MAILFROM``
-  **(DEPRECATED)** When exploding pull requests, use this email address
+  When exploding pull requests, use this email address
   in the From header, instead of reusing the same From as in the pull
   request.
 
+  .. deprecated:: v0.10
+
 ``-s SENDIDENTITY, --send-as-identity SENDIDENTITY``
-  **(DEPRECATED)** When resending pull requests as patch series, use
+  When resending pull requests as patch series, use
   this sendemail identity.
 
-``--dry-run``
-  **(DEPRECATED)** Force a --dry-run on ``git-send-email`` invocation.
+  .. deprecated:: v0.10
 
+``--dry-run``
+  Force a --dry-run on ``git-send-email`` invocation.
+
+  .. deprecated:: v0.10

-- 
2.52.0

[PATCH b4 09/21] docs: config: provide link to git-config conf file documentation

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

So that it's easier to get access to the appropriate git-config
documentation.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/config.rst b/docs/config.rst
index a9006a5..594a857 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -1,6 +1,7 @@
 Configuration options
 =====================
-B4 doesn't have a separate configuration file but uses ``git-config`` to
+B4 doesn't have a separate configuration file but uses
+`git-config <https://git-scm.com/docs/git-config#_configuration_file>`__ to
 retrieve a set of b4-specific settings. This means that you can have three
 levels of b4 configuration:
 

-- 
2.52.0

[PATCH b4 10/21] docs: config: fix discrepancy between example strings

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

Commit 707da4b965ea ("am: add the -i/--add-message-id switch") updated
the example code-block but not the string in the sentence that precedes
the code-block, resulting in a mismatch. Let's fix this oversight.

Fixes: 707da4b965ea ("am: add the -i/--add-message-id switch")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config.rst b/docs/config.rst
index 594a857..6b33c33 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -61,7 +61,7 @@ These options control many of the core features of b4.
 ``b4.linktrailermask`` (v0.13+)
   Overrides the format of the ``Link:`` trailer, in case you want to
   call it something other than "Link." For example, some projects
-  use "Message-Id" trailers instead::
+  use "Message-ID" trailers instead::
 
       linktrailermask = Message-ID: <%s>
 

-- 
2.52.0

[PATCH b4 11/21] docs: move sentence-ending dots from within the last quoted string to outside

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

These dots aren't meant to be part of the quoted string but as
sentence-ending dots so let's fix that.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst           | 6 +++---
 docs/contributor/prep.rst | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/config.rst b/docs/config.rst
index 6b33c33..aff0ec3 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -60,7 +60,7 @@ These options control many of the core features of b4.
 
 ``b4.linktrailermask`` (v0.13+)
   Overrides the format of the ``Link:`` trailer, in case you want to
-  call it something other than "Link." For example, some projects
+  call it something other than "Link". For example, some projects
   use "Message-ID" trailers instead::
 
       linktrailermask = Message-ID: <%s>
@@ -85,7 +85,7 @@ These options control many of the core features of b4.
 
 ``b4.save-maildirs``
   The "mbox" file format is actually several incompatible standards,
-  such as "mboxo" vs. "mboxrd." Setting this option can avoid potential
+  such as "mboxo" vs. "mboxrd". Setting this option can avoid potential
   problems by saving retrieved threads as Maildirs.
 
   Default: ``no``
@@ -116,7 +116,7 @@ These options control many of the core features of b4.
       Signed-off-by: Your Name <your.name@example.com>
 
   Your custody section is beneath "Ezri Submaintainer," so the only
-  trailers considered for reordering are "Link" and "Tested-by." Your
+  trailers considered for reordering are "Link" and "Tested-by". Your
   own Signed-off-by trailer is always at the bottom of your own custody
   section.
 
diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 6e90b10..9c27b64 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -126,7 +126,7 @@ Enrolling an existing branch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If you've already started working on a set of commits without first
 running ``b4 prep -n``, you can enroll your existing branch to make it
-"prep-tracked."
+"prep-tracked".
 
 For example, if you have a branch called ``my-topical-branch`` that was
 forked from ``master``, you can enroll it with b4::

-- 
2.52.0

[PATCH b4 12/21] docs: config: add missing dot at end of sentence

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

The other definition lists always have an end-of-sentence dot, so let's
be consistent here.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config.rst b/docs/config.rst
index aff0ec3..5b1954d 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -151,7 +151,7 @@ These settings control ``b4 am`` and ``b4 shazam`` behavior.
 
 ``b4.shazam-merge-flags``
   Additional flags to pass to ``git merge`` when performing a merge with
-  ``b4 shazam -M``
+  ``b4 shazam -M``.
 
   Default: ``--signoff``
 

-- 
2.52.0

[PATCH b4 13/21] docs: config: provide link to patatt

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

We already provide a link to patatt in b4.attestation-policy so let's do
that for b4.keyringsrc as well.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config.rst b/docs/config.rst
index 5b1954d..2465ad0 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -220,7 +220,7 @@ Attestation settings
   Default: ``None``
 
 ``b4.keyringsrc``
-  See ``patatt`` for details on how to configure keyrings. For example,
+  See `patatt`_ for details on how to configure keyrings. For example,
   you can clone the kernel.org pgp keys repository and use it for
   attestation::
 

-- 
2.52.0

[PATCH b4 14/21] docs: config: provide link to git-send-email manpage

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

Makes it easier for users to have access to the manpage from the
browser.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/config.rst b/docs/config.rst
index 2465ad0..3abe80a 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -294,8 +294,9 @@ Attestation settings
 
 ``b4.sendemail-identity``
   The ``sendemail`` identity to use when sending mail directly with b4.
-  This setting applies to ``b4 send`` and ``b4 ty``. See ``man
-  git-send-email`` for info about sendemail identities.
+  This setting applies to ``b4 send`` and ``b4 ty``. See `man
+  git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
+  sendemail identities.
 
   Default: ``None``
 

-- 
2.52.0

[PATCH b4 15/21] docs: config: fix double colon typo

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

This currently renders as "Default::" in the build output, which is
wrong. Let's fix that by using the same style as everywhere else, that
is, one colon.

Fixes: cd43f60e6a49 ("docs: proofread and fixes")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config.rst b/docs/config.rst
index 3abe80a..9da8e32 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -402,7 +402,7 @@ Contributor-oriented settings
   stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
   it uses the command shown below by default.
 
-  Default:: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
+  Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
 
 ``b4.send-same-thread`` (v0.13+)
   When sending a new version of a series, send it in the same thread as

-- 
2.52.0

[PATCH b4 16/21] docs: config: provide example content for template files

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

Instead of telling user to have a look at example templates stored in
the repo, directly include them in the docs such that they don't have to
look for them.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/config.rst b/docs/config.rst
index 9da8e32..edd4678 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -156,8 +156,10 @@ These settings control ``b4 am`` and ``b4 shazam`` behavior.
   Default: ``--signoff``
 
 ``b4.shazam-merge-template``
-  Path to a template to use when creating a merge commit. See
-  ``shazam-merge-template.example`` for an example.
+  Path to a template to use when creating a merge commit. Take the following
+  as example content for this file:
+
+  .. literalinclude:: ../src/b4/templates/shazam-merge-template.example
 
   Default: ``None``
 
@@ -239,13 +241,17 @@ Attestation settings
 ~~~~~~~~~~~~~~~
 ``b4.thanks-pr-template``
   Full paths to the templates to use when generating thank-you messages
-  for contributors. See example templates provided with the project.
+  for contributors. Take the following as example content for this file:
+
+  .. literalinclude:: ../src/b4/templates/thanks-pr-template.example
 
   Default: ``None``
 
 ``b4.thanks-am-template``
   Full paths to the templates to use when generating thank-you messages
-  for contributors. See example templates provided with the project.
+  for contributors. Take the following as example content for this file:
+
+  .. literalinclude:: ../src/b4/templates/thanks-am-template.example
 
   Default: ``None``
 

-- 
2.52.0

[PATCH b4 17/21] docs: config: use rST version admonitions

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

rST provides directives[1] to specify for which version something was
added or modified, so let's use that.

This notably frees the definition list's term of the version string
which will be important in the next commit where the definition lists
are replaced by glossary terms such that they automatically provide an
anchor which makes it easier to share a link to the config setting and
also allows to link at the term definition with :term: across the docs.

[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#describing-changes-between-versions
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 52 +++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 37 insertions(+), 15 deletions(-)

diff --git a/docs/config.rst b/docs/config.rst
index edd4678..735684e 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -58,7 +58,7 @@ These options control many of the core features of b4.
 
   Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``
 
-``b4.linktrailermask`` (v0.13+)
+``b4.linktrailermask``
   Overrides the format of the ``Link:`` trailer, in case you want to
   call it something other than "Link". For example, some projects
   use "Message-ID" trailers instead::
@@ -67,12 +67,14 @@ These options control many of the core features of b4.
 
   The ``%s`` is the placeholder for the message-id.
 
-  Note: starting with version 0.14, you can pass the ``-i`` command-line
-  switch instead of ``-l`` to automatically insert the ``Message-ID``
-  trailer.
-
   Default: ``Link: https://lore.kernel.org/%s``
 
+  .. versionadded:: v0.13
+
+  .. versionchanged:: v0.14
+     You can now pass the ``-i`` command-line switch instead of ``-l`` to
+     automatically insert the ``Message-ID`` trailer.
+
 ``b4.listid-preference``
   Sometimes messages with the same message-id can have different
   contents, because some servers modify message bodies to inject list
@@ -163,7 +165,7 @@ These settings control ``b4 am`` and ``b4 shazam`` behavior.
 
   Default: ``None``
 
-``b4.am-perpatch-check-cmd`` (v0.14+)
+``b4.am-perpatch-check-cmd``
   The command to use when running ``--check``. The command is run once for each
   patch to check. The patch file to check is piped through stdin. If this
   config is defined multiple times, all commands will be run. If this config is
@@ -172,6 +174,8 @@ These settings control ``b4 am`` and ``b4 shazam`` behavior.
 
   Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
 
+  .. versionadded:: v0.14
+
 .. _attestation_settings:
 
 Attestation settings
@@ -193,7 +197,7 @@ Attestation settings
 
   Default: ``yes``
 
-``b4.attestation-dns-resolvers`` (v0.14+)
+``b4.attestation-dns-resolvers``
   You can specify your own DNS servers if you are on a company network
   and your OS-provided resolvers aren't able to perform domain key
   lookups. For example, to use Google DNS servers::
@@ -202,6 +206,8 @@ Attestation settings
 
   Default: ``None``
 
+  .. versionadded:: v0.14
+
 ``b4.attestation-staleness-days``
   Ignore attestation signatures that are more than this many days
   old. This helps avoid a class of attacks when someone re-sends old
@@ -269,7 +275,7 @@ Attestation settings
 
   Default: ``None``
 
-``b4.thanks-from-name`` (v0.13+)
+``b4.thanks-from-name``
   The name to use in the ``From:`` header when sending thank-you notes.
   By default, b4 uses ``user.name``. For example::
 
@@ -277,7 +283,9 @@ Attestation settings
 
   Default: ``None``
 
-``b4.thanks-from-email`` (v0.13+)
+  .. versionadded:: v0.13
+
+``b4.thanks-from-email``
   The email to use in the ``From:`` header when sending thank-you notes.
   By default, b4 uses ``user.email``. For example::
 
@@ -285,6 +293,8 @@ Attestation settings
 
   Default: ``None``
 
+  .. versionadded:: v0.13
+
 ``b4.thanks-treename``
   Name of the tree to use in the thank-you templates.
 
@@ -306,12 +316,14 @@ Attestation settings
 
   Default: ``None``
 
-``b4.ty-send-email`` (v0.11+)
+``b4.ty-send-email``
   When set, tells ``b4 ty`` to send email directly instead of writing
   out ``.thanks`` files.
 
   Default: ``no``
 
+  .. versionadded:: v0.11
+
 .. _patchwork_settings:
 
 Patchwork integration settings
@@ -410,19 +422,24 @@ Contributor-oriented settings
 
   Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
 
-``b4.send-same-thread`` (v0.13+)
+``b4.send-same-thread``
   When sending a new version of a series, send it in the same thread as
   the previous version. The config supports the following values:
 
   * ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
     reply to the previous version's cover letter.
   * ``shallow``: B4 sends the first message of the new series as a reply to the
-    first version's cover letter. (v0.15+)
+    first version's cover letter.
   * ``no``: B4 does not send the new version of the series in the same thread
     as any previous version.
 
   Default: ``no``
 
+  .. versionadded:: v0.13
+
+  .. versionchanged:: v0.15
+     Added ``shallow`` config value.
+
 ``b4.prep-cover-strategy``
   Alternative cover letter storage strategy to use, in case you don't
   want to use the default ``commit`` strategy. See
@@ -444,14 +461,16 @@ Contributor-oriented settings
 
   Default: ``None``
 
-``b4.send-prefixes`` (v0.11+)
+``b4.send-prefixes``
   Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).
 
   This setting can be replaced for a series with ``b4 prep --set-prefixes``.
 
   Default: ``None``
 
-``b4.prep-perpatch-check-cmd`` (v0.14+)
+  .. versionadded:: v0.11
+
+``b4.prep-perpatch-check-cmd``
   The command to use when running ``--check``. The command is run once for each
   patch to check. The patch file to check is piped through stdin. If this
   config is defined multiple times, all commands will be run. If this config is
@@ -460,7 +479,9 @@ Contributor-oriented settings
 
   Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback --showfile``
 
-``b4.prep-pre-flight-checks`` (v0.14+)
+  .. versionadded:: v0.14
+
+``b4.prep-pre-flight-checks``
   You can use this to turn off some or all pre-flight checks that b4 runs
   prior to sending out patches. To cancel all checks::
 
@@ -473,6 +494,7 @@ Contributor-oriented settings
       [b4]
       prep-pre-flight-checks = disable-needs-auto-to-cc, needs-checking
 
+  .. versionadded:: v0.14
 
 To document
 -----------

-- 
2.52.0

[PATCH b4 18/21] docs: config: migrate definition lists to glossaries

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

This allows us to have an anchor per config option which is convenient
when trying to send links to documentation of a specific config option.

The :term: cross-referencing is not necessary but it makes the option
string clickable instead of only having the ¶ character next to it to
click. This is what we use in the Yocto docs.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 607 +++++++++++++++++++++++++++++---------------------------
 1 file changed, 311 insertions(+), 296 deletions(-)

diff --git a/docs/config.rst b/docs/config.rst
index 735684e..cd205fd 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -38,107 +38,109 @@ Core options
 ~~~~~~~~~~~~
 These options control many of the core features of b4.
 
-``b4.midmask``
-  Specifies the server from where to retrieve the messages specified by
-  their message-id.
+.. glossary::
 
-  Default: ``https://lore.kernel.org/%s``
+   :term:`b4.midmask`
+     Specifies the server from where to retrieve the messages specified by
+     their message-id.
 
-``b4.linkmask``
-  B4 uses this setting to construct the URL in the ``Link:`` trailers.
-  If you want a shorter option, you can also use
-  ``https://msgid.link/%s``, which is an alias for lore.kernel.org.
+     Default: ``https://lore.kernel.org/%s``
 
-  Default: ``https://lore.kernel.org/%s``
+   :term:`b4.linkmask`
+     B4 uses this setting to construct the URL in the ``Link:`` trailers.
+     If you want a shorter option, you can also use
+     ``https://msgid.link/%s``, which is an alias for lore.kernel.org.
 
-``b4.searchmask``
-  B4 uses this setting to query and retrieve threads matching specific
-  search terms. For example, it can retrieve trailer updates using the
-  series ``change-id`` identifier.
+     Default: ``https://lore.kernel.org/%s``
 
-  Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``
+   :term:`b4.searchmask`
+     B4 uses this setting to query and retrieve threads matching specific
+     search terms. For example, it can retrieve trailer updates using the
+     series ``change-id`` identifier.
 
-``b4.linktrailermask``
-  Overrides the format of the ``Link:`` trailer, in case you want to
-  call it something other than "Link". For example, some projects
-  use "Message-ID" trailers instead::
+     Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``
 
-      linktrailermask = Message-ID: <%s>
+   :term:`b4.linktrailermask`
+     Overrides the format of the ``Link:`` trailer, in case you want to
+     call it something other than "Link". For example, some projects
+     use "Message-ID" trailers instead::
 
-  The ``%s`` is the placeholder for the message-id.
+         linktrailermask = Message-ID: <%s>
 
-  Default: ``Link: https://lore.kernel.org/%s``
+     The ``%s`` is the placeholder for the message-id.
 
-  .. versionadded:: v0.13
+     Default: ``Link: https://lore.kernel.org/%s``
 
-  .. versionchanged:: v0.14
-     You can now pass the ``-i`` command-line switch instead of ``-l`` to
-     automatically insert the ``Message-ID`` trailer.
+     .. versionadded:: v0.13
 
-``b4.listid-preference``
-  Sometimes messages with the same message-id can have different
-  contents, because some servers modify message bodies to inject list
-  subscription information. B4 attempts to de-duplicate the results
-  using the ``List-Id`` header. You may use this parameter to specify
-  the order of preference, using comma-separated strings with shell-style
-  wildcard globbing.
+     .. versionchanged:: v0.14
+        You can now pass the ``-i`` command-line switch instead of ``-l`` to
+        automatically insert the ``Message-ID`` trailer.
 
-  Default: ``*.feeds.kernel.org, *.linux.dev,*.kernel.org,*``
+   :term:`b4.listid-preference`
+     Sometimes messages with the same message-id can have different
+     contents, because some servers modify message bodies to inject list
+     subscription information. B4 attempts to de-duplicate the results
+     using the ``List-Id`` header. You may use this parameter to specify
+     the order of preference, using comma-separated strings with shell-style
+     wildcard globbing.
 
-``b4.save-maildirs``
-  The "mbox" file format is actually several incompatible standards,
-  such as "mboxo" vs. "mboxrd". Setting this option can avoid potential
-  problems by saving retrieved threads as Maildirs.
+     Default: ``*.feeds.kernel.org, *.linux.dev,*.kernel.org,*``
 
-  Default: ``no``
+   :term:`b4.save-maildirs`
+     The "mbox" file format is actually several incompatible standards,
+     such as "mboxo" vs. "mboxrd". Setting this option can avoid potential
+     problems by saving retrieved threads as Maildirs.
 
-``b4.trailer-order``
-  This lets you control the order of trailers that get added to your own
-  custody section of the commit message. By default, b4 applies these
-  trailers in the order received. However, if you want to list trailers
-  in a specific order, you can try something like::
+     Default: ``no``
 
-      trailer-order = link*,fixes*,acked*,reviewed*,tested*,*
+   :term:`b4.trailer-order`
+     This lets you control the order of trailers that get added to your own
+     custody section of the commit message. By default, b4 applies these
+     trailers in the order received. However, if you want to list trailers
+     in a specific order, you can try something like::
 
-  The "chain of custody" is an important concept in patch-based code
-  review process. Each "Signed-off-by" trailer indicates where the
-  custody section of previous reviewer ends and the new one starts. Your
-  own custody section is always between the previous-to-last
-  "Signed-off-by" trailer, if any, and the bottom of the trailer
-  section. For example::
+         trailer-order = link*,fixes*,acked*,reviewed*,tested*,*
 
-      Fixes: abcde (Commit info)
-      Suggested-by: Alex Reporter <alex.reporter@example.com>
-      Signed-off-by: Betty Developer <betty.developer@example.com>
-      Acked-by: Chandra Acker <chandra.acker@example.com>
-      Reviewed-by: Debby Reviewer <debby.reviewer@example.com>
-      Signed-off-by: Ezri Submaintainer <ezri.submaintainer@example.com>
-      Link: https://msgid.link/some@thing.foo
-      Tested-by: Finn Tester <finn.tester@example.com>
-      Signed-off-by: Your Name <your.name@example.com>
+     The "chain of custody" is an important concept in patch-based code
+     review process. Each "Signed-off-by" trailer indicates where the
+     custody section of previous reviewer ends and the new one starts. Your
+     own custody section is always between the previous-to-last
+     "Signed-off-by" trailer, if any, and the bottom of the trailer
+     section. For example::
 
-  Your custody section is beneath "Ezri Submaintainer," so the only
-  trailers considered for reordering are "Link" and "Tested-by". Your
-  own Signed-off-by trailer is always at the bottom of your own custody
-  section.
+         Fixes: abcde (Commit info)
+         Suggested-by: Alex Reporter <alex.reporter@example.com>
+         Signed-off-by: Betty Developer <betty.developer@example.com>
+         Acked-by: Chandra Acker <chandra.acker@example.com>
+         Reviewed-by: Debby Reviewer <debby.reviewer@example.com>
+         Signed-off-by: Ezri Submaintainer <ezri.submaintainer@example.com>
+         Link: https://msgid.link/some@thing.foo
+         Tested-by: Finn Tester <finn.tester@example.com>
+         Signed-off-by: Your Name <your.name@example.com>
 
-  Default: ``*``
+     Your custody section is beneath "Ezri Submaintainer," so the only
+     trailers considered for reordering are "Link" and "Tested-by". Your
+     own Signed-off-by trailer is always at the bottom of your own custody
+     section.
 
-``b4.trailers-ignore-from``
-  A comma-separated list of addresses that b4 should always ignore
-  when applying follow-up trailers. This is useful when dealing with
-  reports generated by some automated bots. For example::
+     Default: ``*``
 
-      trailers-ignore-from = lkp@intel.com, someotherbot@example.org
+   :term:`b4.trailers-ignore-from`
+     A comma-separated list of addresses that b4 should always ignore
+     when applying follow-up trailers. This is useful when dealing with
+     reports generated by some automated bots. For example::
 
-  Default: ``None``
+         trailers-ignore-from = lkp@intel.com, someotherbot@example.org
 
-``b4.cache-expire``
-  B4 caches retrieved threads for 10 minutes. This option allows
-  tweaking the time that the cache remains valid. Many commands also
-  allow a ``--no-cache`` flag to force b4 to perform remote lookups.
+     Default: ``None``
 
-  Default: ``10``
+   :term:`b4.cache-expire`
+     B4 caches retrieved threads for 10 minutes. This option allows
+     tweaking the time that the cache remains valid. Many commands also
+     allow a ``--no-cache`` flag to force b4 to perform remote lookups.
+
+     Default: ``10``
 
 .. _shazam_settings:
 
@@ -146,183 +148,189 @@ These options control many of the core features of b4.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 These settings control ``b4 am`` and ``b4 shazam`` behavior.
 
-``b4.shazam-am-flags``
-  Additional flags to pass to ``git am`` when applying patches.
+.. glossary::
 
-  Default: ``None``
+   :term:`b4.shazam-am-flags`
+     Additional flags to pass to ``git am`` when applying patches.
 
-``b4.shazam-merge-flags``
-  Additional flags to pass to ``git merge`` when performing a merge with
-  ``b4 shazam -M``.
+     Default: ``None``
 
-  Default: ``--signoff``
+   :term:`b4.shazam-merge-flags`
+     Additional flags to pass to ``git merge`` when performing a merge with
+     ``b4 shazam -M``.
 
-``b4.shazam-merge-template``
-  Path to a template to use when creating a merge commit. Take the following
-  as example content for this file:
+     Default: ``--signoff``
 
-  .. literalinclude:: ../src/b4/templates/shazam-merge-template.example
+   :term:`b4.shazam-merge-template`
+     Path to a template to use when creating a merge commit. Take the following
+     as example content for this file:
 
-  Default: ``None``
+     .. literalinclude:: ../src/b4/templates/shazam-merge-template.example
 
-``b4.am-perpatch-check-cmd``
-  The command to use when running ``--check``. The command is run once for each
-  patch to check. The patch file to check is piped through stdin. If this
-  config is defined multiple times, all commands will be run. If this config is
-  not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
-  tree, it uses the command shown below by default.
+     Default: ``None``
 
-  Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
+   :term:`b4.am-perpatch-check-cmd`
+     The command to use when running ``--check``. The command is run once for each
+     patch to check. The patch file to check is piped through stdin. If this
+     config is defined multiple times, all commands will be run. If this config is
+     not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
+     tree, it uses the command shown below by default.
 
-  .. versionadded:: v0.14
+     Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
+
+     .. versionadded:: v0.14
 
 .. _attestation_settings:
 
 Attestation settings
 ~~~~~~~~~~~~~~~~~~~~
-``b4.attestation-policy``
 
-  B4 supports domain-level and end-to-end attestation of patches using
-  the `patatt`_ library. There are four different operation modes:
+.. glossary::
 
-  * ``off``: don't bother checking attestation at all
-  * ``softfail``: print green marks when attestation is passing and
-    red marks when it's failing
-  * ``hardfail``: exit with an error when any attestation checks fail
+   :term:`b4.attestation-policy`
+     B4 supports domain-level and end-to-end attestation of patches using
+     the `patatt`_ library. There are four different operation modes:
 
-  Default: ``softfail``
+     * ``off``: don't bother checking attestation at all
+     * ``softfail``: print green marks when attestation is passing and
+       red marks when it's failing
+     * ``hardfail``: exit with an error when any attestation checks fail
 
-``b4.attestation-check-dkim``
-  Controls whether to perform DKIM attestation checks.
+     Default: ``softfail``
 
-  Default: ``yes``
+   :term:`b4.attestation-check-dkim`
+     Controls whether to perform DKIM attestation checks.
 
-``b4.attestation-dns-resolvers``
-  You can specify your own DNS servers if you are on a company network
-  and your OS-provided resolvers aren't able to perform domain key
-  lookups. For example, to use Google DNS servers::
+     Default: ``yes``
 
-      attestation-dns-resolvers = 8.8.8.8, 8.8.4.4
+   :term:`b4.attestation-dns-resolvers`
+     You can specify your own DNS servers if you are on a company network
+     and your OS-provided resolvers aren't able to perform domain key
+     lookups. For example, to use Google DNS servers::
 
-  Default: ``None``
+         attestation-dns-resolvers = 8.8.8.8, 8.8.4.4
 
-  .. versionadded:: v0.14
+     Default: ``None``
 
-``b4.attestation-staleness-days``
-  Ignore attestation signatures that are more than this many days
-  old. This helps avoid a class of attacks when someone re-sends old
-  patches that contain known security bugs.
+     .. versionadded:: v0.14
 
-  Default: ``30``
+   :term:`b4.attestation-staleness-days`
+     Ignore attestation signatures that are more than this many days
+     old. This helps avoid a class of attacks when someone re-sends old
+     patches that contain known security bugs.
 
-``b4.attestation-gnupghome``
-  Sets ``GNUPGHOME`` before running PGP attestation checks that rely on
-  GnuPG.
+     Default: ``30``
 
-  Default: ``None``
+   :term:`b4.attestation-gnupghome`
+     Sets ``GNUPGHOME`` before running PGP attestation checks that rely on
+     GnuPG.
 
-``b4.gpgbin``
-  Full path to a different binary to use for ``gpg``. B4 also checks the
-  ``gpg.program`` setting, and uses that value, if found.
+     Default: ``None``
 
-  Default: ``None``
+   :term:`b4.gpgbin`
+     Full path to a different binary to use for ``gpg``. B4 also checks the
+     ``gpg.program`` setting, and uses that value, if found.
 
-``b4.keyringsrc``
-  See `patatt`_ for details on how to configure keyrings. For example,
-  you can clone the kernel.org pgp keys repository and use it for
-  attestation::
+     Default: ``None``
 
-      git clone https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git
+   :term:`b4.keyringsrc`
+     See `patatt`_ for details on how to configure keyrings. For example,
+     you can clone the kernel.org pgp keys repository and use it for
+     attestation::
 
-  Then set the following in your ``~/.gitconfig``::
+         git clone https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git
 
-      [b4]
-        keyringsrc = ~/path/to/pgpkeys/.keyring
+     Then set the following in your ``~/.gitconfig``::
 
-  Default: ``None``
+         [b4]
+           keyringsrc = ~/path/to/pgpkeys/.keyring
+
+     Default: ``None``
 
 .. _ty_settings:
 
 ``ty`` settings
 ~~~~~~~~~~~~~~~
-``b4.thanks-pr-template``
-  Full paths to the templates to use when generating thank-you messages
-  for contributors. Take the following as example content for this file:
 
-  .. literalinclude:: ../src/b4/templates/thanks-pr-template.example
+.. glossary::
 
-  Default: ``None``
+   :term:`b4.thanks-pr-template`
+     Full paths to the templates to use when generating thank-you messages
+     for contributors. Take the following as example content for this file:
 
-``b4.thanks-am-template``
-  Full paths to the templates to use when generating thank-you messages
-  for contributors. Take the following as example content for this file:
+     .. literalinclude:: ../src/b4/templates/thanks-pr-template.example
 
-  .. literalinclude:: ../src/b4/templates/thanks-am-template.example
+     Default: ``None``
 
-  Default: ``None``
+   :term:`b4.thanks-am-template`
+     Full paths to the templates to use when generating thank-you messages
+     for contributors. Take the following as example content for this file:
 
-``b4.thanks-commit-url-mask``
-  Used when creating summaries for ``b4 ty``, and can be a value like::
+     .. literalinclude:: ../src/b4/templates/thanks-am-template.example
 
-      thanks-commit-url-mask = https://git.kernel.org/username/c/%.12s
+     Default: ``None``
 
-  If not set, b4 falls back to using commit hashes.
+   :term:`b4.thanks-commit-url-mask`
+     Used when creating summaries for ``b4 ty``, and can be a value like::
 
-  .. note::
+         thanks-commit-url-mask = https://git.kernel.org/username/c/%.12s
 
-     See this page for more info on convenient git.kernel.org short URLs:
-     https://korg.docs.kernel.org/git-url-shorteners.html
+     If not set, b4 falls back to using commit hashes.
 
-  Default: ``None``
+     .. note::
 
-``b4.thanks-from-name``
-  The name to use in the ``From:`` header when sending thank-you notes.
-  By default, b4 uses ``user.name``. For example::
+        See this page for more info on convenient git.kernel.org short URLs:
+        https://korg.docs.kernel.org/git-url-shorteners.html
 
-      thanks-from-name = Project Foo Thanks Bot
+     Default: ``None``
 
-  Default: ``None``
+   :term:`b4.thanks-from-name`
+     The name to use in the ``From:`` header when sending thank-you notes.
+     By default, b4 uses ``user.name``. For example::
 
-  .. versionadded:: v0.13
+         thanks-from-name = Project Foo Thanks Bot
 
-``b4.thanks-from-email``
-  The email to use in the ``From:`` header when sending thank-you notes.
-  By default, b4 uses ``user.email``. For example::
+     Default: ``None``
 
-      thanks-from-email = thanks-bot@example.com
+     .. versionadded:: v0.13
 
-  Default: ``None``
+   :term:`b4.thanks-from-email`
+     The email to use in the ``From:`` header when sending thank-you notes.
+     By default, b4 uses ``user.email``. For example::
 
-  .. versionadded:: v0.13
+         thanks-from-email = thanks-bot@example.com
 
-``b4.thanks-treename``
-  Name of the tree to use in the thank-you templates.
+     Default: ``None``
 
-  Default: ``None``
+     .. versionadded:: v0.13
 
-``b4.email-exclude``
-  A list of addresses to always exclude from the message recipients.
-  Expects a comma-separated list with shell-style globbing. E.g.::
+   :term:`b4.thanks-treename`
+     Name of the tree to use in the thank-you templates.
 
-      email-exclude = *@codeaurora.org, *@obsolete.example.com
+     Default: ``None``
 
-  Default: ``None``
+   :term:`b4.email-exclude`
+     A list of addresses to always exclude from the message recipients.
+     Expects a comma-separated list with shell-style globbing. E.g.::
 
-``b4.sendemail-identity``
-  The ``sendemail`` identity to use when sending mail directly with b4.
-  This setting applies to ``b4 send`` and ``b4 ty``. See `man
-  git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
-  sendemail identities.
+         email-exclude = *@codeaurora.org, *@obsolete.example.com
 
-  Default: ``None``
+     Default: ``None``
 
-``b4.ty-send-email``
-  When set, tells ``b4 ty`` to send email directly instead of writing
-  out ``.thanks`` files.
+   :term:`b4.sendemail-identity`
+     The ``sendemail`` identity to use when sending mail directly with b4.
+     This setting applies to ``b4 send`` and ``b4 ty``. See `man
+     git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
 
-  Default: ``no``
+     Default: ``None``
 
-  .. versionadded:: v0.11
+   :term:`b4.ty-send-email`
+     When set, tells ``b4 ty`` to send email directly instead of writing
+     out ``.thanks`` files.
+
+     Default: ``no``
+
+     .. versionadded:: v0.11
 
 .. _patchwork_settings:
 
@@ -331,175 +339,182 @@ Patchwork integration settings
 If your project uses a patchwork server, setting these allows you to
 integrate your b4 workflow with patchwork.
 
-``b4.pw-url``
-  The URL of your patchwork server. Note, that this should point at the
-  top-level of your patchwork installation and **not** at the project patch
-  listing. For example::
+.. glossary::
 
-      pw-url = https://patchwork.kernel.org/
+   :term:`b4.pw-url`
+     The URL of your patchwork server. Note, that this should point at the
+     top-level of your patchwork installation and **not** at the project patch
+     listing. For example::
 
-  Default: ``None``
+         pw-url = https://patchwork.kernel.org/
 
-``b4.pw-key``
-  The API key from your user profile to use when authenticating with the
-  patchwork server.
+     Default: ``None``
 
-  Default: ``None``
+   :term:`b4.pw-key`
+     The API key from your user profile to use when authenticating with the
+     patchwork server.
 
-``b4.pw-project``
-  The name of the patchwork project, exactly as seen in the URL
-  sub-path. For example::
+     Default: ``None``
 
-      pw-project = linux-usb
+   :term:`b4.pw-project`
+     The name of the patchwork project, exactly as seen in the URL
+     sub-path. For example::
 
-  Default: ``None``
+         pw-project = linux-usb
 
-``b4.pw-review-state``
-  Enabling this option makes ``b4 am`` or ``b4 shazam`` automatically set
-  the review status of the retrieved patches. For example::
+     Default: ``None``
 
-      pw-review-state = under-review
+   :term:`b4.pw-review-state`
+     Enabling this option makes ``b4 am`` or ``b4 shazam`` automatically set
+     the review status of the retrieved patches. For example::
 
-  Default: ``None``
+         pw-review-state = under-review
 
-``b4.pw-accept-state``
-  Enabling this option makes ``b4 ty`` set the status of any applied patches
-  to the specified state. For example::
+     Default: ``None``
 
-      pw-accept-state = accepted
+   :term:`b4.pw-accept-state`
+     Enabling this option makes ``b4 ty`` set the status of any applied patches
+     to the specified state. For example::
 
-  Default: ``None``
+         pw-accept-state = accepted
 
-``b4.pw-discard-state``
-  Enabling this option makes ``b4 ty -d`` set the status of any matching
-  patches to the specified state. For example::
+     Default: ``None``
 
-      pw-discard-state = rejected
+   :term:`b4.pw-discard-state`
+     Enabling this option makes ``b4 ty -d`` set the status of any matching
+     patches to the specified state. For example::
 
-  Default: ``None``
+         pw-discard-state = rejected
+
+     Default: ``None``
 
 .. _contributor_settings:
 
 Contributor-oriented settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``b4.send-endpoint-web``
-  The web submission endpoint to use. See :ref:`web_endpoint`.
+.. glossary::
 
-  Default: ``None``
+   :term:`b4.send-endpoint-web`
+     The web submission endpoint to use. See :ref:`web_endpoint`.
 
-``b4.send-series-to``
-  A comma-separated list of addresses to always add to the "To:" header.
-  See :ref:`prep_recipients`.
+     Default: ``None``
 
-  Default: ``None``
+   :term:`b4.send-series-to`
+     A comma-separated list of addresses to always add to the "To:" header.
+     See :ref:`prep_recipients`.
 
-``b4.send-series-cc``
-  A comma-separated list of addresses to always add to the "Cc:" header.
-  See :ref:`prep_recipients`.
+     Default: ``None``
 
-  Default: ``None``
+   :term:`b4.send-series-cc`
+     A comma-separated list of addresses to always add to the "Cc:" header.
+     See :ref:`prep_recipients`.
 
-``b4.send-no-patatt-sign``
-  Instructs b4 not to sign patches with patatt before sending them. Note, that
-  using the web submission endpoint requires using signed patches.
+     Default: ``None``
 
-  Default: ``no``
+   :term:`b4.send-no-patatt-sign`
+     Instructs b4 not to sign patches with patatt before sending them. Note, that
+     using the web submission endpoint requires using signed patches.
 
-``b4.send-auto-to-cmd``
-  The command to use for obtaining the list of "To:" recipients. The command is
-  run once for each patch in the series. Each patch file is piped through
-  stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
-  it uses the command shown below by default.
+     Default: ``no``
 
-  Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol``
+   :term:`b4.send-auto-to-cmd`
+     The command to use for obtaining the list of "To:" recipients. The command is
+     run once for each patch in the series. Each patch file is piped through
+     stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
+     it uses the command shown below by default.
 
-``b4.send-auto-cc-cmd``
-  The command to use for obtaining the list of "Cc:" recipients. The command is
-  run once for each patch in the series. Each patch file is piped through
-  stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
-  it uses the command shown below by default.
+     Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol``
 
-  Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
+   :term:`b4.send-auto-cc-cmd`
+     The command to use for obtaining the list of "Cc:" recipients. The command is
+     run once for each patch in the series. Each patch file is piped through
+     stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
+     it uses the command shown below by default.
 
-``b4.send-same-thread``
-  When sending a new version of a series, send it in the same thread as
-  the previous version. The config supports the following values:
+     Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
 
-  * ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
-    reply to the previous version's cover letter.
-  * ``shallow``: B4 sends the first message of the new series as a reply to the
-    first version's cover letter.
-  * ``no``: B4 does not send the new version of the series in the same thread
-    as any previous version.
+   :term:`b4.send-same-thread`
+     When sending a new version of a series, send it in the same thread as
+     the previous version. The config supports the following values:
 
-  Default: ``no``
+     * ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
+       reply to the previous version's cover letter.
+     * ``shallow``: B4 sends the first message of the new series as a reply to the
+       first version's cover letter.
+     * ``no``: B4 does not send the new version of the series in the same thread
+       as any previous version.
 
-  .. versionadded:: v0.13
+     Default: ``no``
 
-  .. versionchanged:: v0.15
-     Added ``shallow`` config value.
+     .. versionadded:: v0.13
 
-``b4.prep-cover-strategy``
-  Alternative cover letter storage strategy to use, in case you don't
-  want to use the default ``commit`` strategy. See
-  :ref:`prep_cover_strategies`.
+     .. versionchanged:: v0.15
+        Added ``shallow`` config value.
 
-  Default: ``commit``
+   :term:`b4.prep-cover-strategy`
+     Alternative cover letter storage strategy to use, in case you don't
+     want to use the default ``commit`` strategy. See
+     :ref:`prep_cover_strategies`.
 
-``b4.prep-cover-template``
-  Path to the template to use for the cover letter. The template supports the
-  following tokens:
+     Default: ``commit``
 
-  * ``${cover}``: the content of the cover letter itself
-  * ``${shortlog}``: the ``git shortlog`` output for the series
-  * ``${diffstat}``: the ``git diff --stat`` output for the series
-  * ``${range_diff}``: the ``git range-diff`` output against the previous revision of the series
-  * ``${base_commit}``: the base commit of the series
-  * ``${change_id}``: the change-id of the series
-  * ``${signature}``: your signature, either from ``~/.signature`` if found, or from your Git config
+   :term:`b4.prep-cover-template`
+     Path to the template to use for the cover letter. The template supports the
+     following tokens:
 
-  Default: ``None``
+     * ``${cover}``: the content of the cover letter itself
+     * ``${shortlog}``: the ``git shortlog`` output for the series
+     * ``${diffstat}``: the ``git diff --stat`` output for the series
+     * ``${range_diff}``: the ``git range-diff`` output against the previous revision of the series
+     * ``${base_commit}``: the base commit of the series
+     * ``${change_id}``: the change-id of the series
+     * ``${signature}``: your signature, either from ``~/.signature`` if found, or from your Git config
 
-``b4.send-prefixes``
-  Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).
+     Default: ``None``
 
-  This setting can be replaced for a series with ``b4 prep --set-prefixes``.
+   :term:`b4.send-prefixes`
+     Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).
 
-  Default: ``None``
+     This setting can be replaced for a series with ``b4 prep --set-prefixes``.
 
-  .. versionadded:: v0.11
+     Default: ``None``
 
-``b4.prep-perpatch-check-cmd``
-  The command to use when running ``--check``. The command is run once for each
-  patch to check. The patch file to check is piped through stdin. If this
-  config is defined multiple times, all commands will be run. If this config is
-  not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
-  tree, it uses the command shown below by default.
+     .. versionadded:: v0.11
 
-  Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback --showfile``
+   :term:`b4.prep-perpatch-check-cmd`
+     The command to use when running ``--check``. The command is run once for each
+     patch to check. The patch file to check is piped through stdin. If this
+     config is defined multiple times, all commands will be run. If this config is
+     not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
+     tree, it uses the command shown below by default.
 
-  .. versionadded:: v0.14
+     Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback --showfile``
 
-``b4.prep-pre-flight-checks``
-  You can use this to turn off some or all pre-flight checks that b4 runs
-  prior to sending out patches. To cancel all checks::
+     .. versionadded:: v0.14
 
-      [b4]
-      prep-pre-flight-checks = disable-all
+   :term:`b4.prep-pre-flight-checks`
+     You can use this to turn off some or all pre-flight checks that b4 runs
+     prior to sending out patches. To cancel all checks::
 
-  To turn off specific checks, list each one of them, separated by
-  comma::
+         [b4]
+         prep-pre-flight-checks = disable-all
 
-      [b4]
-      prep-pre-flight-checks = disable-needs-auto-to-cc, needs-checking
+     To turn off specific checks, list each one of them, separated by
+     comma::
 
-  .. versionadded:: v0.14
+         [b4]
+         prep-pre-flight-checks = disable-needs-auto-to-cc, needs-checking
+
+     .. versionadded:: v0.14
 
 To document
 -----------
-``b4.gh-api-key``
-  Deliberately undocumented because the feature is incomplete and poorly
-  tested.
+
+.. glossary::
+
+   :term:`b4.gh-api-key`
+     Deliberately undocumented because the feature is incomplete and poorly
+     tested.
 
 .. _`patatt`: https://pypi.org/project/patatt/

-- 
2.52.0

[PATCH b4 19/21] docs: config: sort glossaries

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

This sorts the term defined in glossaries such that they appear
alphabetically in the docs.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst | 324 +++++++++++++++++++++++++++++---------------------------
 1 file changed, 166 insertions(+), 158 deletions(-)

diff --git a/docs/config.rst b/docs/config.rst
index cd205fd..f2ed519 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -39,12 +39,14 @@ Core options
 These options control many of the core features of b4.
 
 .. glossary::
+   :sorted:
 
-   :term:`b4.midmask`
-     Specifies the server from where to retrieve the messages specified by
-     their message-id.
+   :term:`b4.cache-expire`
+     B4 caches retrieved threads for 10 minutes. This option allows
+     tweaking the time that the cache remains valid. Many commands also
+     allow a ``--no-cache`` flag to force b4 to perform remote lookups.
 
-     Default: ``https://lore.kernel.org/%s``
+     Default: ``10``
 
    :term:`b4.linkmask`
      B4 uses this setting to construct the URL in the ``Link:`` trailers.
@@ -53,13 +55,6 @@ These options control many of the core features of b4.
 
      Default: ``https://lore.kernel.org/%s``
 
-   :term:`b4.searchmask`
-     B4 uses this setting to query and retrieve threads matching specific
-     search terms. For example, it can retrieve trailer updates using the
-     series ``change-id`` identifier.
-
-     Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``
-
    :term:`b4.linktrailermask`
      Overrides the format of the ``Link:`` trailer, in case you want to
      call it something other than "Link". For example, some projects
@@ -87,6 +82,12 @@ These options control many of the core features of b4.
 
      Default: ``*.feeds.kernel.org, *.linux.dev,*.kernel.org,*``
 
+   :term:`b4.midmask`
+     Specifies the server from where to retrieve the messages specified by
+     their message-id.
+
+     Default: ``https://lore.kernel.org/%s``
+
    :term:`b4.save-maildirs`
      The "mbox" file format is actually several incompatible standards,
      such as "mboxo" vs. "mboxrd". Setting this option can avoid potential
@@ -94,6 +95,13 @@ These options control many of the core features of b4.
 
      Default: ``no``
 
+   :term:`b4.searchmask`
+     B4 uses this setting to query and retrieve threads matching specific
+     search terms. For example, it can retrieve trailer updates using the
+     series ``change-id`` identifier.
+
+     Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``
+
    :term:`b4.trailer-order`
      This lets you control the order of trailers that get added to your own
      custody section of the commit message. By default, b4 applies these
@@ -135,13 +143,6 @@ These options control many of the core features of b4.
 
      Default: ``None``
 
-   :term:`b4.cache-expire`
-     B4 caches retrieved threads for 10 minutes. This option allows
-     tweaking the time that the cache remains valid. Many commands also
-     allow a ``--no-cache`` flag to force b4 to perform remote lookups.
-
-     Default: ``10``
-
 .. _shazam_settings:
 
 ``am`` and ``shazam`` settings
@@ -149,6 +150,18 @@ These options control many of the core features of b4.
 These settings control ``b4 am`` and ``b4 shazam`` behavior.
 
 .. glossary::
+   :sorted:
+
+   :term:`b4.am-perpatch-check-cmd`
+     The command to use when running ``--check``. The command is run once for each
+     patch to check. The patch file to check is piped through stdin. If this
+     config is defined multiple times, all commands will be run. If this config is
+     not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
+     tree, it uses the command shown below by default.
+
+     Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
+
+     .. versionadded:: v0.14
 
    :term:`b4.shazam-am-flags`
      Additional flags to pass to ``git am`` when applying patches.
@@ -169,34 +182,13 @@ These settings control ``b4 am`` and ``b4 shazam`` behavior.
 
      Default: ``None``
 
-   :term:`b4.am-perpatch-check-cmd`
-     The command to use when running ``--check``. The command is run once for each
-     patch to check. The patch file to check is piped through stdin. If this
-     config is defined multiple times, all commands will be run. If this config is
-     not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
-     tree, it uses the command shown below by default.
-
-     Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
-
-     .. versionadded:: v0.14
-
 .. _attestation_settings:
 
 Attestation settings
 ~~~~~~~~~~~~~~~~~~~~
 
 .. glossary::
-
-   :term:`b4.attestation-policy`
-     B4 supports domain-level and end-to-end attestation of patches using
-     the `patatt`_ library. There are four different operation modes:
-
-     * ``off``: don't bother checking attestation at all
-     * ``softfail``: print green marks when attestation is passing and
-       red marks when it's failing
-     * ``hardfail``: exit with an error when any attestation checks fail
-
-     Default: ``softfail``
+   :sorted:
 
    :term:`b4.attestation-check-dkim`
      Controls whether to perform DKIM attestation checks.
@@ -214,6 +206,23 @@ Attestation settings
 
      .. versionadded:: v0.14
 
+   :term:`b4.attestation-gnupghome`
+     Sets ``GNUPGHOME`` before running PGP attestation checks that rely on
+     GnuPG.
+
+     Default: ``None``
+
+   :term:`b4.attestation-policy`
+     B4 supports domain-level and end-to-end attestation of patches using
+     the `patatt`_ library. There are four different operation modes:
+
+     * ``off``: don't bother checking attestation at all
+     * ``softfail``: print green marks when attestation is passing and
+       red marks when it's failing
+     * ``hardfail``: exit with an error when any attestation checks fail
+
+     Default: ``softfail``
+
    :term:`b4.attestation-staleness-days`
      Ignore attestation signatures that are more than this many days
      old. This helps avoid a class of attacks when someone re-sends old
@@ -221,12 +230,6 @@ Attestation settings
 
      Default: ``30``
 
-   :term:`b4.attestation-gnupghome`
-     Sets ``GNUPGHOME`` before running PGP attestation checks that rely on
-     GnuPG.
-
-     Default: ``None``
-
    :term:`b4.gpgbin`
      Full path to a different binary to use for ``gpg``. B4 also checks the
      ``gpg.program`` setting, and uses that value, if found.
@@ -253,12 +256,21 @@ Attestation settings
 ~~~~~~~~~~~~~~~
 
 .. glossary::
+   :sorted:
 
-   :term:`b4.thanks-pr-template`
-     Full paths to the templates to use when generating thank-you messages
-     for contributors. Take the following as example content for this file:
+   :term:`b4.email-exclude`
+     A list of addresses to always exclude from the message recipients.
+     Expects a comma-separated list with shell-style globbing. E.g.::
 
-     .. literalinclude:: ../src/b4/templates/thanks-pr-template.example
+         email-exclude = *@codeaurora.org, *@obsolete.example.com
+
+     Default: ``None``
+
+   :term:`b4.sendemail-identity`
+     The ``sendemail`` identity to use when sending mail directly with b4.
+     This setting applies to ``b4 send`` and ``b4 ty``. See `man
+     git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
+     sendemail identities.
 
      Default: ``None``
 
@@ -284,16 +296,6 @@ Attestation settings
 
      Default: ``None``
 
-   :term:`b4.thanks-from-name`
-     The name to use in the ``From:`` header when sending thank-you notes.
-     By default, b4 uses ``user.name``. For example::
-
-         thanks-from-name = Project Foo Thanks Bot
-
-     Default: ``None``
-
-     .. versionadded:: v0.13
-
    :term:`b4.thanks-from-email`
      The email to use in the ``From:`` header when sending thank-you notes.
      By default, b4 uses ``user.email``. For example::
@@ -304,26 +306,29 @@ Attestation settings
 
      .. versionadded:: v0.13
 
+   :term:`b4.thanks-from-name`
+     The name to use in the ``From:`` header when sending thank-you notes.
+     By default, b4 uses ``user.name``. For example::
+
+         thanks-from-name = Project Foo Thanks Bot
+
+     Default: ``None``
+
+     .. versionadded:: v0.13
+
+   :term:`b4.thanks-pr-template`
+     Full paths to the templates to use when generating thank-you messages
+     for contributors. Take the following as example content for this file:
+
+     .. literalinclude:: ../src/b4/templates/thanks-pr-template.example
+
+     Default: ``None``
+
    :term:`b4.thanks-treename`
      Name of the tree to use in the thank-you templates.
 
      Default: ``None``
 
-   :term:`b4.email-exclude`
-     A list of addresses to always exclude from the message recipients.
-     Expects a comma-separated list with shell-style globbing. E.g.::
-
-         email-exclude = *@codeaurora.org, *@obsolete.example.com
-
-     Default: ``None``
-
-   :term:`b4.sendemail-identity`
-     The ``sendemail`` identity to use when sending mail directly with b4.
-     This setting applies to ``b4 send`` and ``b4 ty``. See `man
-     git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
-
-     Default: ``None``
-
    :term:`b4.ty-send-email`
      When set, tells ``b4 ty`` to send email directly instead of writing
      out ``.thanks`` files.
@@ -340,13 +345,21 @@ If your project uses a patchwork server, setting these allows you to
 integrate your b4 workflow with patchwork.
 
 .. glossary::
+   :sorted:
 
-   :term:`b4.pw-url`
-     The URL of your patchwork server. Note, that this should point at the
-     top-level of your patchwork installation and **not** at the project patch
-     listing. For example::
+   :term:`b4.pw-accept-state`
+     Enabling this option makes ``b4 ty`` set the status of any applied patches
+     to the specified state. For example::
 
-         pw-url = https://patchwork.kernel.org/
+         pw-accept-state = accepted
+
+     Default: ``None``
+
+   :term:`b4.pw-discard-state`
+     Enabling this option makes ``b4 ty -d`` set the status of any matching
+     patches to the specified state. For example::
+
+         pw-discard-state = rejected
 
      Default: ``None``
 
@@ -372,19 +385,12 @@ integrate your b4 workflow with patchwork.
 
      Default: ``None``
 
-   :term:`b4.pw-accept-state`
-     Enabling this option makes ``b4 ty`` set the status of any applied patches
-     to the specified state. For example::
+   :term:`b4.pw-url`
+     The URL of your patchwork server. Note, that this should point at the
+     top-level of your patchwork installation and **not** at the project patch
+     listing. For example::
 
-         pw-accept-state = accepted
-
-     Default: ``None``
-
-   :term:`b4.pw-discard-state`
-     Enabling this option makes ``b4 ty -d`` set the status of any matching
-     patches to the specified state. For example::
-
-         pw-discard-state = rejected
+         pw-url = https://patchwork.kernel.org/
 
      Default: ``None``
 
@@ -394,63 +400,7 @@ Contributor-oriented settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. glossary::
-
-   :term:`b4.send-endpoint-web`
-     The web submission endpoint to use. See :ref:`web_endpoint`.
-
-     Default: ``None``
-
-   :term:`b4.send-series-to`
-     A comma-separated list of addresses to always add to the "To:" header.
-     See :ref:`prep_recipients`.
-
-     Default: ``None``
-
-   :term:`b4.send-series-cc`
-     A comma-separated list of addresses to always add to the "Cc:" header.
-     See :ref:`prep_recipients`.
-
-     Default: ``None``
-
-   :term:`b4.send-no-patatt-sign`
-     Instructs b4 not to sign patches with patatt before sending them. Note, that
-     using the web submission endpoint requires using signed patches.
-
-     Default: ``no``
-
-   :term:`b4.send-auto-to-cmd`
-     The command to use for obtaining the list of "To:" recipients. The command is
-     run once for each patch in the series. Each patch file is piped through
-     stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
-     it uses the command shown below by default.
-
-     Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol``
-
-   :term:`b4.send-auto-cc-cmd`
-     The command to use for obtaining the list of "Cc:" recipients. The command is
-     run once for each patch in the series. Each patch file is piped through
-     stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
-     it uses the command shown below by default.
-
-     Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
-
-   :term:`b4.send-same-thread`
-     When sending a new version of a series, send it in the same thread as
-     the previous version. The config supports the following values:
-
-     * ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
-       reply to the previous version's cover letter.
-     * ``shallow``: B4 sends the first message of the new series as a reply to the
-       first version's cover letter.
-     * ``no``: B4 does not send the new version of the series in the same thread
-       as any previous version.
-
-     Default: ``no``
-
-     .. versionadded:: v0.13
-
-     .. versionchanged:: v0.15
-        Added ``shallow`` config value.
+   :sorted:
 
    :term:`b4.prep-cover-strategy`
      Alternative cover letter storage strategy to use, in case you don't
@@ -473,15 +423,6 @@ Contributor-oriented settings
 
      Default: ``None``
 
-   :term:`b4.send-prefixes`
-     Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).
-
-     This setting can be replaced for a series with ``b4 prep --set-prefixes``.
-
-     Default: ``None``
-
-     .. versionadded:: v0.11
-
    :term:`b4.prep-perpatch-check-cmd`
      The command to use when running ``--check``. The command is run once for each
      patch to check. The patch file to check is piped through stdin. If this
@@ -508,10 +449,77 @@ Contributor-oriented settings
 
      .. versionadded:: v0.14
 
+   :term:`b4.send-auto-cc-cmd`
+     The command to use for obtaining the list of "Cc:" recipients. The command is
+     run once for each patch in the series. Each patch file is piped through
+     stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
+     it uses the command shown below by default.
+
+     Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
+
+   :term:`b4.send-auto-to-cmd`
+     The command to use for obtaining the list of "To:" recipients. The command is
+     run once for each patch in the series. Each patch file is piped through
+     stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
+     it uses the command shown below by default.
+
+     Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol``
+
+   :term:`b4.send-endpoint-web`
+     The web submission endpoint to use. See :ref:`web_endpoint`.
+
+     Default: ``None``
+
+   :term:`b4.send-no-patatt-sign`
+     Instructs b4 not to sign patches with patatt before sending them. Note, that
+     using the web submission endpoint requires using signed patches.
+
+     Default: ``no``
+
+   :term:`b4.send-prefixes`
+     Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).
+
+     This setting can be replaced for a series with ``b4 prep --set-prefixes``.
+
+     Default: ``None``
+
+     .. versionadded:: v0.11
+
+   :term:`b4.send-same-thread`
+     When sending a new version of a series, send it in the same thread as
+     the previous version. The config supports the following values:
+
+     * ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
+       reply to the previous version's cover letter.
+     * ``shallow``: B4 sends the first message of the new series as a reply to the
+       first version's cover letter.
+     * ``no``: B4 does not send the new version of the series in the same thread
+       as any previous version.
+
+     Default: ``no``
+
+     .. versionadded:: v0.13
+
+     .. versionchanged:: v0.15
+        Added ``shallow`` config value.
+
+   :term:`b4.send-series-cc`
+     A comma-separated list of addresses to always add to the "Cc:" header.
+     See :ref:`prep_recipients`.
+
+     Default: ``None``
+
+   :term:`b4.send-series-to`
+     A comma-separated list of addresses to always add to the "To:" header.
+     See :ref:`prep_recipients`.
+
+     Default: ``None``
+
 To document
 -----------
 
 .. glossary::
+   :sorted:
 
    :term:`b4.gh-api-key`
      Deliberately undocumented because the feature is incomplete and poorly

-- 
2.52.0

[PATCH b4 20/21] docs: cross-reference config options with :term:

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

This inserts a link to the definition of the config option such that
it's either to find it.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/config.rst               | 2 +-
 docs/contributor/prep.rst     | 4 ++--
 docs/contributor/send.rst     | 6 +++---
 docs/maintainer/am-shazam.rst | 2 +-
 docs/maintainer/ty.rst        | 4 ++--
 5 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/config.rst b/docs/config.rst
index f2ed519..d2a80c2 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -28,7 +28,7 @@ file in the repository you're currently using.
 Configuration options
 ---------------------
 All settings are under the ``b4`` section. For example, to set the
-``b4.midmask`` option, add the following section to the relevant git
+:term:`b4.midmask` option, add the following section to the relevant git
 config file::
 
     [b4]
diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 9c27b64..e6b45c7 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -65,7 +65,7 @@ disadvantages in some less-common situations:
 
 For this reason, b4 supports alternative strategies for storing the
 cover letter. You can tell ``b4`` which strategy to use using the
-``b4.prep-cover-strategy`` configuration variable.
+:term:`b4.prep-cover-strategy` configuration variable.
 
 ``commit`` strategy (default)
   This is the default strategy that keeps the cover letter and all
@@ -400,7 +400,7 @@ modifying defaults for some of these flags.
   ``./scripts/checkpatch.pl --terse --no-summary --mailback --showfile``
 
   You can specify your own command by setting the
-  ``b4.prep-perpatch-check-cmd`` configuration parameter. For example
+  :term:`b4.prep-perpatch-check-cmd` configuration parameter. For example
   you can make it more strict::
 
       [b4]
diff --git a/docs/contributor/send.rst b/docs/contributor/send.rst
index f5a1ff1..ba18ef5 100644
--- a/docs/contributor/send.rst
+++ b/docs/contributor/send.rst
@@ -311,13 +311,13 @@ Command line flags
 ``--to``
   Additional email addresses to include into the To: header. Separate
   multiple entries with a comma. You can also set this in the
-  configuration file using the ``b4.send-series-to`` option (see
+  configuration file using the :term:`b4.send-series-to` option (see
   :ref:`contributor_settings`).
 
 ``--cc``
   Additional email addresses to include into the Cc: header. Separate
   multiple entries with a comma. You can also set this in the
-  configuration file using the ``b4.send-series-cc`` option (see
+  configuration file using the :term:`b4.send-series-cc` option (see
   :ref:`contributor_settings`).
 
 ``--not-me-too``
@@ -328,7 +328,7 @@ Command line flags
   Note, that sending via the web submission endpoint requires
   cryptographic signatures at all times, so this is only a valid option
   to use with ``-o`` or when using your own SMTP server. This can be set
-  in the configuration using the ``b4.send-no-patatt-sign`` (see
+  in the configuration using the :term:`b4.send-no-patatt-sign` (see
   :ref:`contributor_settings`).
 
 ``--resend V``
diff --git a/docs/maintainer/am-shazam.rst b/docs/maintainer/am-shazam.rst
index 1ca9b50..5c3fb75 100644
--- a/docs/maintainer/am-shazam.rst
+++ b/docs/maintainer/am-shazam.rst
@@ -175,7 +175,7 @@ The following flags are common to both commands:
       ./scripts/checkpatch.pl -q --terse --no-summary --mailback
 
   You can specify a different command to run by setting the
-  ``b4.am-perpatch-check-cmd`` configuration setting, e.g.::
+  :term:`b4.am-perpatch-check-cmd` configuration setting, e.g.::
 
       [b4]
       am-perpatch-check-cmd = ./scripts/checkpatch.pl -q --terse --no-summary --mailback --strict
diff --git a/docs/maintainer/ty.rst b/docs/maintainer/ty.rst
index 21c56de..c1b79b5 100644
--- a/docs/maintainer/ty.rst
+++ b/docs/maintainer/ty.rst
@@ -66,7 +66,7 @@ happy with the results, you can omit the ``--dry-run`` switch to
 actually send the mail.
 
 If you want ``b4 ty`` to always send mail, you can make the ``-S``
-switch permanent by setting the ``b4.ty-send-email`` config variable to
+switch permanent by setting the :term:`b4.ty-send-email` config variable to
 ``yes``.
 
 Editing the templates
@@ -74,7 +74,7 @@ Editing the templates
 You can edit the default templates that are provided with b4 to
 customize the thank-you message. Once you have your own versions, you
 can specify the path to the template to use via the
-``b4.thanks-am-template`` and ``b4.thanks-pr-template`` configuration
+:term:`b4.thanks-am-template` and :term:`b4.thanks-pr-template` configuration
 parameters. See :ref:`ty_settings` for details.
 
 Optional flags

-- 
2.52.0

[PATCH b4 21/21] docs: maintainer: am-shazam: cross-reference b4.linkmask for --add-link

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

The --add-link boolean option will be using the linkmask b4 setting so
let's make that clear how to specify a different template.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 docs/maintainer/am-shazam.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/maintainer/am-shazam.rst b/docs/maintainer/am-shazam.rst
index 5c3fb75..54b6fc4 100644
--- a/docs/maintainer/am-shazam.rst
+++ b/docs/maintainer/am-shazam.rst
@@ -115,7 +115,7 @@ The following flags are common to both commands:
 
 ``-l, --add-link``
   Adds a ``Link:`` trailer with the URL of the retrieved message using
-  the ``linkmask`` template.
+  the :term:`b4.linkmask` template.
 
 ``-i, --add-message-id``
   Adds a ``Message-ID:`` trailer with the Message-ID of the retrieved

-- 
2.52.0

Re: [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings

[Konstantin Ryabitsev]

On Tue, 03 Feb 2026 14:30:59 +0100, Quentin Schulz <foss+kernel@0leil.net> wrote:
> This makes use of rST version admonitions for config settings in
> anticipation to make each config setting a term such that we can
> cross-reference them easily and have an anchor in the output for easier
> link sharing. Then it migrates current "verbatim cross-references" to
> actual cross-references using :term:.

Great work, thank you for sending that in. I'm holding off on this only 
because I want to try merging it using the new review ui, to test the 
full review-merge-thanks cycle.

I noticed that there is no attestation on your patches, not even a DKIM 
signature. Do you mind setting that up -- this is probably not the last 
series you're sending in.

> Note: ``b4 send`` seems to be picking up
> ``Signed-off-by: Your Name <your.name@example.com>`` from the git
> context in patch 11 and adds it to Cc recipients for some reason??

Hm... definitely a bug that I'll look into. I also see it added to the 
CC list, so you probably got a bounce for that as well.

Thanks!

-- 
KR

Re: [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings

[Quentin Schulz]

Hi Konstantin,

On 2/3/26 11:00 PM, Konstantin Ryabitsev wrote:
> On Tue, 03 Feb 2026 14:30:59 +0100, Quentin Schulz <foss+kernel@0leil.net> wrote:
>> This makes use of rST version admonitions for config settings in
>> anticipation to make each config setting a term such that we can
>> cross-reference them easily and have an anchor in the output for easier
>> link sharing. Then it migrates current "verbatim cross-references" to
>> actual cross-references using :term:.
> 
> Great work, thank you for sending that in. I'm holding off on this only
> because I want to try merging it using the new review ui, to test the
> full review-merge-thanks cycle.
> 

Ack.

> I noticed that there is no attestation on your patches, not even a DKIM
> signature. Do you mind setting that up -- this is probably not the last
> series you're sending in.
> 

Not the first even ;)

I should have fixed this oversight now. Would you rather have a v2 or a 
RESEND for the added DKIM signature?

>> Note: ``b4 send`` seems to be picking up
>> ``Signed-off-by: Your Name <your.name@example.com>`` from the git
>> context in patch 11 and adds it to Cc recipients for some reason??
> 
> Hm... definitely a bug that I'll look into. I also see it added to the
> CC list, so you probably got a bounce for that as well.
> 

Do you want a separate mail thread on the ML such that one can do a 
Closes: in a commit log fixing it? (I vaguely remember something about a 
"bugspray" tool?)

Cheers,
Quentin

Re: [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings

[Konstantin Ryabitsev]

On Tue, 03 Feb 2026 14:30:59 +0100, Quentin Schulz wrote:
> docs: various fixes + migration from definition lists to glossaries for config settings
> 
> This makes use of rST version admonitions for config settings in
> anticipation to make each config setting a term such that we can
> cross-reference them easily and have an anchor in the output for easier
> link sharing. Then it migrates current "verbatim cross-references" to
> actual cross-references using :term:.
> 
> [...]

Applied, thanks!

[01/21] docs: maintainer: ty: fix incorrect config name for templates
        commit: 075798a3853e6e36ef24579162cfa57b4f68bee5
[02/21] docs: prep: add info on when range-diff-opts was added
        commit: ba986b23bf5c9cd3639d8755e2beec47e0e6ab9c
[03/21] docs: diff: add info on when range-diff-opts was added
        commit: 8decfc81783cc755227d4a3ac2eedd636ce15be8
[04/21] docs: contributor: send: fix sendmail typo
        commit: b1102e55390db0c37b55817726fb4063a2d77c0b
[05/21] docs: config: separate b4.thanks-pr-template and b4.thanks-am-template
        commit: 6d5ea09b1afb9696bb51a843ac45c74a6ab2daed
[06/21] docs: use rST version admonitions for command options
        commit: 787d38ea47cfb368a5ce3495b1b7c0cf283b27a8
[07/21] docs: use versionadded admonition for sections
        commit: 516b83309278457d93844433d8f091e08cc734d5
[08/21] docs: maintainer: use deprecated admonition
        commit: 1e8781aa3877549865a60f39d298e124b47ad361
[09/21] docs: config: provide link to git-config conf file documentation
        commit: e1478411056d6af9b00efa520ee6f6f23bbe0523
[10/21] docs: config: fix discrepancy between example strings
        commit: e0c3dd312f323f2c12e4ca6959f501bb52641c4d
[11/21] docs: move sentence-ending dots from within the last quoted string to outside
        commit: 1f2991f5fd6f824b977a6be72224b31f8ee3437d
[12/21] docs: config: add missing dot at end of sentence
        commit: 78f186e0059ec161456e78dc90c1bd18dde6410b
[13/21] docs: config: provide link to patatt
        commit: 7e2ada10d95412b18022a5ffad6b433845d70f62
[14/21] docs: config: provide link to git-send-email manpage
        commit: ce6d1d94581750993add06994765ea7b23df1e8c
[15/21] docs: config: fix double colon typo
        commit: 21c51381472723a5e10c09501efe13f7ae999e53
[16/21] docs: config: provide example content for template files
        commit: bd9fe265c68a6608d6f481c0a142d34e37c6b66b
[17/21] docs: config: use rST version admonitions
        commit: dd516611af3944c0ea24e897f8aafbf524aff5f8
[18/21] docs: config: migrate definition lists to glossaries
        commit: c7feb0050730d911dffdee65c8c89589cb0f8ec2
[19/21] docs: config: sort glossaries
        commit: af1c83586198f595223873d0bb1c6ac67f4f560d
[20/21] docs: cross-reference config options with :term:
        commit: f3863312bb98adf0ce179e105cb673eed82e8cd9
[21/21] docs: maintainer: am-shazam: cross-reference b4.linkmask for --add-link
        commit: 00c1aa82af335d1c1aa2cb881d50f3f4ffee4dcd

Best regards,
-- 
KR