docs: reorder, add some more stubs, and some content

I was going to write a lot more today, but *gestures widely at
everything*. Hopefully, more to come tomorrow.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

6 files changed, 277 insertions, 10 deletions

diff --git a/docs/getting-support.rst b/docs/getting-support.rst
deleted file mode 100644
index 5077a15..0000000
--- a/docs/getting-support.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-Getting support for b4
-======================
-
-Stub.
diff --git a/docs/index.rst b/docs/index.rst
index 13a796e..d69209c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,6 +1,5 @@
 B4 end-user documentation
 =========================
-
 B4 is a tool created to make it easier for project maintainers to use a
 distributed development workflow that relies on patches and distribution
 lists for code contributions and review.
@@ -16,6 +15,8 @@ For maintainers
    :maxdepth: 1
 
    maintainer/overview
+   maintainer/config
+   maintainer/mbox
    maintainer/patches
    maintainer/prs
    maintainer/thanks
@@ -37,5 +38,8 @@ Installation and support
    :maxdepth: 1
 
    installing
-   getting-support
 
+Getting help
+------------
+To report a problem or suggest a feature, please send plaintext email to
+tools@linux.kernel.org.
diff --git a/docs/maintainer/config.rst b/docs/maintainer/config.rst
new file mode 100644
index 0000000..2038640
--- /dev/null
+++ b/docs/maintainer/config.rst
@@ -0,0 +1,82 @@
+Configuration file
+==================
+B4 doesn't have a separate configuration file but will use
+``git-config`` to retrieve a set of b4-specific settings. This means
+that you can have three levels of b4 configuration:
+
+- system-wide, in ``/etc/gitconfig``
+- per-user, in ``$HOME/.gitconfig``
+- per-repo, in ``somerepo/.git/config``
+
+Since the purpose of b4 is to work with git repositories, this allows
+the usual fall-through configuration that can be overridden by more
+local settings on the repository level.
+
+Configuration options
+---------------------
+All settings are under the ``b4`` section.
+
+``b4.midmask``
+  Default: ``https://lore.kernel.org/%s``
+
+  When retrieving threads by message-id, b4 will use ``midmask`` to
+  figure out from which server they should be retrieved.
+
+``b4.linkmask``
+  Default: ``https://lore.kernel.org/%s``
+
+  When automatically generating ``Link:`` trailers, b4 will use this
+  setting to derive the destination URL. If you want a shorter option,
+  you can also use ``https://msgid.link/%s``, which is an alias for
+  lore.kernel.org.
+
+``b4.listid-preference``
+  Default: ``*.feeds.kernel.org, *.linux.dev,*.kernel.org,*``
+
+  Messages are frequently sent to multiple distribution lists, and some
+  servers may apply content munging to modify the headers or the message
+  content. B4 will deduplicate the results and this configuration option
+  defines the priority given to the ``List-Id`` header. It is a simple
+  comma-separated string with shell-style globbing.
+
+``b4.save-maildirs``
+  Default: ``no``
+
+  The "mbox" file format is actually several incompatible formats
+  ("mboxo" vs "mboxrd", for example). If you want to avoid dealing with
+  this problem, you can choose to always save retrieved messages as a
+  Maildir instead.
+
+``b4.trailer-order``
+  Default: ``*``
+
+  This lets you control the order of trailers that get added to your own
+  custody section of the commit message. By default, b4 will apply these
+  trailers in the order they were received (because this is mostly
+  consumed by tooling and the order does not matter). However, if you
+  wanted to list things in a specific order, you could try something
+  like::
+
+      trailer-order = link*,fixes*,acked*,reviewed*,tested*,*
+
+  The "chain of custody" is an important concept in patch-based code
+  review process, with each "Signed-off-by" trailer indicating where the
+  custody section of previous reviewer ends and the new one starts. Your
+  own custody section is anything between the previous-to-last
+  "Signed-off-by" trailer (if any) and the bottom of the trailer
+  section. E.g.::
+
+      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>
+
+  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).
diff --git a/docs/maintainer/mbox.rst b/docs/maintainer/mbox.rst
new file mode 100644
index 0000000..a3d60a8
--- /dev/null
+++ b/docs/maintainer/mbox.rst
@@ -0,0 +1,83 @@
+b4 mbox: retrieving threads
+===========================
+
+.. note::
+
+   If you are looking for a way to continuously retrieve full threads
+   (or even full search results) from a public-inbox server, the ``lei``
+   tool provides a much more robust way of doing that.
+
+Retrieving full discussion threads is the most basic use of b4. All you
+need to know is the message-id of any message in the thread::
+
+    b4 mbox 20200313231252.64999-1-keescook@chromium.org
+
+Alternatively, if you have found a thread on lore.kernel.org and you
+want to retrieve it in full, you can just use the full URL::
+
+    b4 mbox https://lore.kernel.org/lkml/20200313231252.64999-1-keescook@chromium.org/#t
+
+By default, b4 will save the thread in a mailbox format using the
+message-id of the message as the filename base::
+
+    $ b4 mbox 20200313231252.64999-1-keescook@chromium.org
+    Grabbing thread from lore.kernel.org/all/20200313231252.64999-1-keescook%40chromium.org/t.mbox.gz
+    5 messages in the thread
+    Saved ./20200313231252.64999-1-keescook@chromium.org.mbx
+
+Other flags
+~~~~~~~~~~~
+``-p USEPROJECT, --use-project USEPROJECT``
+  **DEPRECATED**: This is a legacy option that made sense before
+  public-inbox supported collating and retrieving threads from across
+  multiple lists. This flag will probably go away in the future.
+
+``-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.
+
+``-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
+  mbox or maildir location to have the results appended to that mailbox
+  instead (see also the ``-f`` flag below).
+
+``-c, --check-newer-revisions``
+  When retrieving patch series, check if a newer revision is available.
+  For example, if you are trying to retrieve a series titled ``[PATCH v2
+  0/3]``, b4 will use a number of mechanisms to check if a ``v3`` or
+  later revision is also available and will add these results to the
+  retrieved thread.
+
+``-n WANTNAME, --mbox-name WANTNAME``
+  By default, the resulting mailbox file will use the message-id as the
+  basis for its filename. This option lets you override this behaviour.
+
+``-M, --save-as-maildir``
+  By default, the retrieved thread will be saved as an mbox file.
+  However, due to subtle incompatibilities between various mbox formats
+  ("mboxo" vs "mboxrd", etc), you may want to instead save the results
+  as a Maildir directory.
+
+``-f, --filter-dupes``
+  When adding messages to existing mailbox or maildir (with ``-o``),
+  this will check all existing messages and will only add those messages
+  that aren't already present. Note, that this uses simple message-id
+  matching and no other checks for correctness are performed.
+
+Using with mutt
+~~~~~~~~~~~~~~~
+If you are a mutt or neomutt user and your mail is stored locally, you
+can define a quick macro that would let you quickly retrieve full
+threads and add them to your inbox. This is handy if you are cc'd in the
+middle of a conversation and you want to retrieve the rest of the thread
+for context.
+
+Add something like the following to your ``~/.muttrc``::
+
+    macro index 4 "<pipe-message>b4 mbox -fo ~/Mail<return>"
+
+Now selecting a message in the message index and pressing "4" will
+retrieve the rest of the thread from the public-inbox server and add
+them to the local maildir (``~/Mail`` in the example above).
diff --git a/docs/maintainer/overview.rst b/docs/maintainer/overview.rst
index feaa0ce..78b2b75 100644
--- a/docs/maintainer/overview.rst
+++ b/docs/maintainer/overview.rst
@@ -1,4 +1,27 @@
 Maintainer overview
 ===================
+The primary goal of b4 is to make it easier for maintainers to retrieve
+patch series, verify their authenticity, apply any follow-up code review
+trailers, and apply the patches to their maintained git trees.
 
-Stub.
+This functionality works best when coupled with a `public-inbox`_
+aggregator service, such as the one running on lore.kernel.org, but can
+be used with local mailboxes and maildirs, thus providing fully
+decentralized, experience with robust end-to-end attestation.
+
+.. _`public-inbox`: https://public-inbox.org/README.html
+
+Working with patches sent to distribution lists
+-----------------------------------------------
+Patches sent to distribution lists remains the only widely used
+decentralized code review framework. RFC2822-conformant ("email")
+messages adhere to an established standard that ensures high level of
+interoperability between systems, and it remains one of the remaining
+few truly decentralized communication platforms.
+
+Note, that "distribution lists" may not necessarily mean "patches sent
+via email". In addition to SMTP, RFC2822 messages can be also delivered
+via any number of push and pull mechanisms, such as NNTP, web archives,
+public-inbox repositories, etc. In the case of lore.kernel.org, the
+messages are collated from a large number of sources then replicated
+across multiple frontends.
diff --git a/docs/maintainer/patches.rst b/docs/maintainer/patches.rst
index 6f30178..a3d60a8 100644
--- a/docs/maintainer/patches.rst
+++ b/docs/maintainer/patches.rst
@@ -1,4 +1,83 @@
-Working with patch series
-=========================
+b4 mbox: retrieving threads
+===========================
 
-Stub.
+.. note::
+
+   If you are looking for a way to continuously retrieve full threads
+   (or even full search results) from a public-inbox server, the ``lei``
+   tool provides a much more robust way of doing that.
+
+Retrieving full discussion threads is the most basic use of b4. All you
+need to know is the message-id of any message in the thread::
+
+    b4 mbox 20200313231252.64999-1-keescook@chromium.org
+
+Alternatively, if you have found a thread on lore.kernel.org and you
+want to retrieve it in full, you can just use the full URL::
+
+    b4 mbox https://lore.kernel.org/lkml/20200313231252.64999-1-keescook@chromium.org/#t
+
+By default, b4 will save the thread in a mailbox format using the
+message-id of the message as the filename base::
+
+    $ b4 mbox 20200313231252.64999-1-keescook@chromium.org
+    Grabbing thread from lore.kernel.org/all/20200313231252.64999-1-keescook%40chromium.org/t.mbox.gz
+    5 messages in the thread
+    Saved ./20200313231252.64999-1-keescook@chromium.org.mbx
+
+Other flags
+~~~~~~~~~~~
+``-p USEPROJECT, --use-project USEPROJECT``
+  **DEPRECATED**: This is a legacy option that made sense before
+  public-inbox supported collating and retrieving threads from across
+  multiple lists. This flag will probably go away in the future.
+
+``-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.
+
+``-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
+  mbox or maildir location to have the results appended to that mailbox
+  instead (see also the ``-f`` flag below).
+
+``-c, --check-newer-revisions``
+  When retrieving patch series, check if a newer revision is available.
+  For example, if you are trying to retrieve a series titled ``[PATCH v2
+  0/3]``, b4 will use a number of mechanisms to check if a ``v3`` or
+  later revision is also available and will add these results to the
+  retrieved thread.
+
+``-n WANTNAME, --mbox-name WANTNAME``
+  By default, the resulting mailbox file will use the message-id as the
+  basis for its filename. This option lets you override this behaviour.
+
+``-M, --save-as-maildir``
+  By default, the retrieved thread will be saved as an mbox file.
+  However, due to subtle incompatibilities between various mbox formats
+  ("mboxo" vs "mboxrd", etc), you may want to instead save the results
+  as a Maildir directory.
+
+``-f, --filter-dupes``
+  When adding messages to existing mailbox or maildir (with ``-o``),
+  this will check all existing messages and will only add those messages
+  that aren't already present. Note, that this uses simple message-id
+  matching and no other checks for correctness are performed.
+
+Using with mutt
+~~~~~~~~~~~~~~~
+If you are a mutt or neomutt user and your mail is stored locally, you
+can define a quick macro that would let you quickly retrieve full
+threads and add them to your inbox. This is handy if you are cc'd in the
+middle of a conversation and you want to retrieve the rest of the thread
+for context.
+
+Add something like the following to your ``~/.muttrc``::
+
+    macro index 4 "<pipe-message>b4 mbox -fo ~/Mail<return>"
+
+Now selecting a message in the message index and pressing "4" will
+retrieve the rest of the thread from the public-inbox server and add
+them to the local maildir (``~/Mail`` in the example above).