From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id A0nNE4o0ZGELdgEAgWs5BA (envelope-from ) for ; Mon, 11 Oct 2021 14:56:42 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id SCQnDYo0ZGFDXQAAB5/wlQ (envelope-from ) for ; Mon, 11 Oct 2021 12:56:42 +0000 Received: from mail.notmuchmail.org (nmbug.tethera.net [IPv6:2607:5300:201:3100::1657]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 7A06B4C87 for ; Mon, 11 Oct 2021 14:56:41 +0200 (CEST) Received: from nmbug.tethera.net (localhost [127.0.0.1]) by mail.notmuchmail.org (Postfix) with ESMTP id C555E29023; Mon, 11 Oct 2021 08:56:32 -0400 (EDT) Received: from fethera.tethera.net (fethera.tethera.net [198.245.60.197]) by mail.notmuchmail.org (Postfix) with ESMTP id D1D45268AB for ; Mon, 11 Oct 2021 08:56:28 -0400 (EDT) Received: by fethera.tethera.net (Postfix, from userid 1001) id C7D3C5FD5C; Mon, 11 Oct 2021 08:56:28 -0400 (EDT) Received: (nullmailer pid 1447662 invoked by uid 1000); Mon, 11 Oct 2021 12:56:27 -0000 From: David Bremner To: notmuch@notmuchmail.org Cc: David Bremner Subject: [PATCH 1/2] doc: remove explicit formatting of terms in definition lists Date: Mon, 11 Oct 2021 09:56:14 -0300 Message-Id: <20211011125615.1447351-2-david@tethera.net> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20211011125615.1447351-1-david@tethera.net> References: <20211011125615.1447351-1-david@tethera.net> MIME-Version: 1.0 Message-ID-Hash: RWEGJZE3Q4EOL6FO6D4QBVOQRJW6MAJ7 X-Message-ID-Hash: RWEGJZE3Q4EOL6FO6D4QBVOQRJW6MAJ7 X-MailFrom: bremner@tethera.net X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-notmuch.notmuchmail.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.1 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Help: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1633957001; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=liJsdVX2cuZjc0mnJ7OShAs4IMzzVsNn14iIOb97tIw=; b=WHh7og5uiJYfiCjFPK2xRwRjfY1RsZxYZKKhwBQZ+EwPP477KZKxsbc8/ZWppEh+ul1hue E4bUmBpLwVtGUTVkBF0wx/ItCogblomSSSLpjMsLDRg66su48Lvp7/e5A+r4UeFGpg0DNd vZh7BW34NMnMZ/RePZoelyg92QbKbsfAXouo4chWXv4uOas9a4QspnKyH0VTKjoaoYeVOV aqkBS3igJczz70dMWbrrwtxEr/6/B8RjYpD6cmW/vUYIIB2IujUx8AMetxevkjAKRGugtD 160NeUnf2q0YMR3asBD0w+oCnUvReI+JBFoBxBCbFAAyDCzLqKKYCc0jg91ILQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1633957001; a=rsa-sha256; cv=none; b=RRGVJoYmkg++N86zl9lHI6Z7A4sTKag4vDpELAfw74Hz5QMy2sdWz24tiJDBAfeTItgLTz XuEMA4RwrhbhkM08T8cBGsKQ3avP8hOPaafOOwroUvGTSMlHdR95xwA1vzH28Vg5vj0mPZ RA2HkrU3oKFZkSCC7BoqIWFmbP/stkF3cXq+EqJu99aGirMlcG1JqwJJPtgjNsPSyvBBOU HfP1Qkv4xbF6Etrc++p+LsN0x9hZIwo/3s7qrNmy4D7JBYDcrJMBuDt++Ze7ofriJMK4Y/ BWlECI8T1b2GSU6JjgbDhCYy+G9J20FiaAeZLH4x0wocjfuXaOHDw9YI21VWgg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 2607:5300:201:3100::1657 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Spam-Score: -1.19 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 2607:5300:201:3100::1657 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Queue-Id: 7A06B4C87 X-Spam-Score: -1.19 X-Migadu-Scanner: scn1.migadu.com X-TUID: hULKWOgFYyYz Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list. --- doc/man1/notmuch-address.rst | 14 +++++++------- doc/man1/notmuch-config.rst | 34 ++++++++++++++++----------------- doc/man1/notmuch-count.rst | 6 +++--- doc/man1/notmuch-dump.rst | 10 +++++----- doc/man1/notmuch-reply.rst | 12 ++++++------ doc/man1/notmuch-restore.rst | 12 ++++++------ doc/man1/notmuch-search.rst | 18 ++++++++--------- doc/man1/notmuch-show.rst | 10 +++++----- doc/man5/notmuch-hooks.rst | 6 +++--- doc/man7/notmuch-properties.rst | 8 +++----- 10 files changed, 64 insertions(+), 66 deletions(-) diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst index 7423b629..c70dde35 100644 --- a/doc/man1/notmuch-address.rst +++ b/doc/man1/notmuch-address.rst @@ -42,7 +42,7 @@ Supported options for **address** include neither ``--output=sender`` nor ``--output=recipients`` is given, ``--output=sender`` is implied. - **sender** + sender Output all addresses from the *From* header. Note: Searching for **sender** should be much faster than @@ -50,17 +50,17 @@ Supported options for **address** include cached directly in the database whereas other addresses need to be fetched from message files. - **recipients** + recipients Output all addresses from the *To*, *Cc* and *Bcc* headers. - **count** + count Print the count of how many times was the address encountered during search. Note: With this option, addresses are printed only after the whole search is finished. This may take long time. - **address** + address Output only the email addresses instead of the full mailboxes with names and email addresses. This option has no effect on the JSON or S-Expression output formats. @@ -69,17 +69,17 @@ Supported options for **address** include Control the deduplication of results. - **no** + no Output all occurrences of addresses in the matching messages. This is not applicable with ``--output=count``. - **mailbox** + mailbox Deduplicate addresses based on the full, case sensitive name and email address, or mailbox. This is effectively the same as piping the ``--deduplicate=no`` output to **sort | uniq**, except for the order of results. This is the default. - **address** + address Deduplicate addresses based on the case insensitive address part of the mailbox. Of all the variants (with different name or case), print the one occurring most frequently among the diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst index 7d901758..6f12c773 100644 --- a/doc/man1/notmuch-config.rst +++ b/doc/man1/notmuch-config.rst @@ -55,14 +55,14 @@ The available configuration items are described below. Non-absolute paths are presumed relative to `$HOME` for items in section **database**. -**database.path** +database.path Notmuch will store its database here, (in sub-directory named ``.notmuch`` if **database.mail\_root** is unset). Default: see :ref:`database` -**database.mail_root** +database.mail_root The top-level directory where your mail currently exists and to where mail will be delivered in the future. Files should be individual email messages. @@ -72,7 +72,7 @@ paths are presumed relative to `$HOME` for items in section Default: For compatibility with older configurations, the value of database.path is used if **database.mail\_root** is unset. -**database.backup_dir** +database.backup_dir Directory to store tag dumps when upgrading database. History: this configuration value was introduced in notmuch 0.32. @@ -80,7 +80,7 @@ paths are presumed relative to `$HOME` for items in section Default: A sibling directory of the Xapian database called `backups`. -**database.hook_dir** +database.hook_dir Directory containing hooks run by notmuch commands. See :any:`notmuch-hooks(5)`. @@ -88,7 +88,7 @@ paths are presumed relative to `$HOME` for items in section Default: See HOOKS, below. -**database.autocommit** +database.autocommit How often to commit transactions to disk. `0` means wait until command completes, otherwise an integer `n` specifies to commit to @@ -96,30 +96,30 @@ paths are presumed relative to `$HOME` for items in section History: this configuration value was introduced in notmuch 0.33. -**user.name** +user.name Your full name. Default: ``$NAME`` variable if set, otherwise read from ``/etc/passwd``. -**user.primary\_email** +user.primary\_email Your primary email address. Default: ``$EMAIL`` variable if set, otherwise constructed from the username and hostname of the current machine. -**user.other\_email** +user.other\_email A list of other email addresses at which you receive email. Default: not set. -**new.tags** +new.tags A list of tags that will be added to all messages incorporated by **notmuch new**. Default: ``unread;inbox``. -**new.ignore** +new.ignore A list to specify files and directories that will not be searched for messages by :any:`notmuch-new(1)`. Each entry in the list is either: @@ -137,7 +137,7 @@ paths are presumed relative to `$HOME` for items in section Default: empty list. -**search.exclude\_tags** +search.exclude\_tags A list of tags that will be excluded from search results by default. Using an excluded tag in a query will override that exclusion. @@ -145,7 +145,7 @@ paths are presumed relative to `$HOME` for items in section Default: empty list. Note that :any:`notmuch-setup(1)` puts ``deleted;spam`` here when creating new configuration file. -**maildir.synchronize\_flags** +maildir.synchronize\_flags If true, then the following maildir flags (in message filenames) will be synchronized with the corresponding notmuch tags: @@ -178,7 +178,7 @@ paths are presumed relative to `$HOME` for items in section Default: ``true``. -**index.decrypt** +index.decrypt Policy for decrypting encrypted messages during indexing. Must be one of: ``false``, ``auto``, ``nostash``, or ``true``. @@ -231,7 +231,7 @@ paths are presumed relative to `$HOME` for items in section Default: ``auto``. -**index.header.** +index.header. Define the query prefix , based on a mail header. For example ``index.header.List=List-Id`` will add a probabilistic prefix ``List:`` that searches the ``List-Id`` field. User @@ -240,18 +240,18 @@ paths are presumed relative to `$HOME` for items in section supported. See :any:`notmuch-search-terms(7)` for a list of existing prefixes, and an explanation of probabilistic prefixes. -**built_with.** +built_with. Compile time feature . Current possibilities include "retry_lock" (configure option, included by default). (since notmuch 0.30, "compact" and "field_processor" are always included.) -**query.** +query. Expansion for named query called . See :any:`notmuch-search-terms(7)` for more information about named queries. -**squery.** +squery. Expansion for named query called , using s-expression syntax. See :any:`notmuch-sexp-queries(7)` for more information about s-expression queries. diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst index 9a7e4bac..4c9c9a1c 100644 --- a/doc/man1/notmuch-count.rst +++ b/doc/man1/notmuch-count.rst @@ -28,13 +28,13 @@ Supported options for **count** include .. option:: --output=(messages|threads|files) - **messages** + messages Output the number of matching messages. This is the default. - **threads** + threads Output the number of matching threads. - **files** + files Output the number of files associated with matching messages. This may be bigger than the number of matching messages due to duplicates (i.e. multiple files having the diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst index 4319c5c3..a7ca39d0 100644 --- a/doc/man1/notmuch-dump.rst +++ b/doc/man1/notmuch-dump.rst @@ -39,7 +39,7 @@ Supported options for **dump** include Notmuch restore supports two plain text dump formats, both with one message-id per line, followed by a list of tags. - **batch-tag** + batch-tag The default **batch-tag** dump format is intended to more robust against malformed message-ids and tags containing whitespace or non-\ :manpage:`ascii(7)` characters. Each line @@ -58,7 +58,7 @@ Supported options for **dump** include :any:`notmuch-tag(1)`; note that the single message-id query is mandatory for :any:`notmuch-restore(1)`. - **sup** + sup The **sup** dump file format is specifically chosen to be compatible with the format of files produced by :manpage:`sup-dump(1)`. So if you've previously been using sup @@ -77,18 +77,18 @@ Supported options for **dump** include Control what kind of metadata is included in the output. - **config** + config Output configuration data stored in the database. Each line starts with "#@ ", followed by a space separated key-value pair. Both key and value are hex encoded if needed. - **properties** + properties Output per-message (key,value) metadata. Each line starts with "#= ", followed by a message id, and a space separated list of key=value pairs. Ids, keys and values are hex encoded if needed. See :any:`notmuch-properties(7)` for more details. - **tags** + tags Output per-message boolean metadata, namely tags. See *format* above for description of the output. diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst index 4a78a90b..fa0371f9 100644 --- a/doc/man1/notmuch-reply.rst +++ b/doc/man1/notmuch-reply.rst @@ -40,22 +40,22 @@ Supported options for **reply** include .. option:: --format=(default|json|sexp|headers-only) - **default** + default Includes subject and quoted message body as an RFC 2822 message. - **json** + json Produces JSON output containing headers for a reply message and the contents of the original message. This output can be used by a client to create a reply message intelligently. - **sexp** + sexp Produces S-Expression output containing headers for a reply message and the contents of the original message. This output can be used by a client to create a reply message intelligently. - **headers-only** + headers-only Only produces In-Reply-To, References, To, Cc, and Bcc headers. @@ -67,10 +67,10 @@ Supported options for **reply** include .. option:: --reply-to=(all|sender) - **all** (default) + all (default) Replies to all addresses. - **sender** + sender Replies only to the sender. If replying to user's own message (Reply-to: or From: header is one of the user's configured email addresses), try To:, Cc:, and Bcc: headers in this diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst index bd452475..ac6b4245 100644 --- a/doc/man1/notmuch-restore.rst +++ b/doc/man1/notmuch-restore.rst @@ -32,14 +32,14 @@ Supported options for **restore** include line specifying a message-id and a set of tags. For details of the actual formats, see :any:`notmuch-dump(1)`. - **sup** + sup The **sup** dump file format is specifically chosen to be compatible with the format of files produced by sup-dump. So if you've previously been using sup for mail, then the **notmuch restore** command provides you a way to import all of your tags (or labels as sup calls them). - **batch-tag** + batch-tag The **batch-tag** dump format is intended to more robust against malformed message-ids and tags containing whitespace or non-\ **ascii(7)** characters. See :any:`notmuch-dump(1)` for @@ -49,7 +49,7 @@ Supported options for **restore** include changes if the **maildir.synchronize\_flags** configuration option is enabled. See :any:`notmuch-config(1)` for details. - **auto** + auto This option (the default) tries to guess the format from the input. For correctly formed input in either supported format, this heuristic, based the fact that batch-tag format contains @@ -59,18 +59,18 @@ Supported options for **restore** include Control what kind of metadata is restored. - **config** + config Restore configuration data to the database. Each configuration line starts with "#@ ", followed by a space separated key-value pair. Both key and value are hex encoded if needed. - **properties** + properties Restore per-message (key,value) metadata. Each line starts with "#= ", followed by a message id, and a space separated list of key=value pairs. Ids, keys and values are hex encoded if needed. See :any:`notmuch-properties(7)` for more details. - **tags** + tags Restore per-message metadata, namely tags. See *format* above for more details. diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst index 2d9ca2d5..ad305efd 100644 --- a/doc/man1/notmuch-search.rst +++ b/doc/man1/notmuch-search.rst @@ -43,7 +43,7 @@ Supported options for **search** include .. option:: --output=(summary|threads|messages|files|tags) - **summary** + summary Output a summary of each thread with any message matching the search terms. The summary includes the thread ID, date, the number of messages in the thread (both the number matched and @@ -52,19 +52,19 @@ Supported options for **search** include for some messages, the total number of files is printed in parentheses (see below for an example). - **threads** + threads Output the thread IDs of all threads with any message matching the search terms, either one per line (``--format=text``), separated by null characters (``--format=text0``), as a JSON array (``--format=json``), or an S-Expression list (``--format=sexp``). - **messages** + messages Output the message IDs of all messages matching the search terms, either one per line (``--format=text``), separated by null characters (``--format=text0``), as a JSON array (``--format=json``), or as an S-Expression list (``--format=sexp``). - **files** + files Output the filenames of all messages matching the search terms, either one per line (``--format=text``), separated by null characters (``--format=text0``), as a JSON array (``--format=json``), @@ -78,7 +78,7 @@ Supported options for **search** include in other directories that are included in the output, although these files alone would not match the search. - **tags** + tags Output all tags that appear on any message matching the search terms, either one per line (``--format=text``), separated by null characters (``--format=text0``), as a JSON array (``--format=json``), @@ -115,20 +115,20 @@ Supported options for **search** include terms. This option specifies whether to omit excluded messages in the search process. - **true** (default) + true (default) Prevent excluded messages from matching the search terms. - **all** + all Additionally prevent excluded messages from appearing in displayed results, in effect behaving as though the excluded messages do not exist. - **false** + false Allow excluded messages to match search terms and appear in displayed results. Excluded messages are still marked in the relevant outputs. - **flag** + flag Only has an effect when ``--output=summary``. The output is almost identical to **false**, but the "match count" is the number of matching non-excluded messages in the thread, rather diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst index 64639174..3d2a2c41 100644 --- a/doc/man1/notmuch-show.rst +++ b/doc/man1/notmuch-show.rst @@ -36,7 +36,7 @@ Supported options for **show** include .. option:: --format=(text|json|sexp|mbox|raw) - **text** (default for messages) + text (default for messages) The default plain-text format has all text-content MIME parts decoded. Various components in the output, (**message**, **header**, **body**, **attachment**, and MIME **part**), will @@ -46,7 +46,7 @@ Supported options for **show** include '}'), to either open or close the component. For a multipart MIME message, these parts will be nested. - **json** + json The output is formatted with Javascript Object Notation (JSON). This format is more robust than the text format for automated processing. The nested structure of multipart MIME @@ -58,7 +58,7 @@ Supported options for **show** include as UTF-8 and any message content included in the output will be charset-converted to UTF-8. - **sexp** + sexp The output is formatted as the Lisp s-expression (sexp) equivalent of the JSON format above. Objects are formatted as property lists whose keys are keywords (symbols preceded by a @@ -66,7 +66,7 @@ Supported options for **show** include formatted as ``nil``. As for JSON, the s-expression output is always encoded as UTF-8. - **mbox** + mbox All matching messages are output in the traditional, Unix mbox format with each message being prefixed by a line beginning with "From " and a blank line separating each message. Lines @@ -77,7 +77,7 @@ Supported options for **show** include http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html - **raw** (default if ``--part`` is given) + raw (default if ``--part`` is given) Write the raw bytes of the given MIME part of a message to standard out. For this format, it is an error to specify a query that matches more than one message. diff --git a/doc/man5/notmuch-hooks.rst b/doc/man5/notmuch-hooks.rst index 268917cd..0ab5efbc 100644 --- a/doc/man5/notmuch-hooks.rst +++ b/doc/man5/notmuch-hooks.rst @@ -19,7 +19,7 @@ must have executable permissions. The currently available hooks are described below. -**pre-new** +pre-new This hook is invoked by the :any:`notmuch-new(1)` command before scanning or importing new messages into the database. If this hook exits with a non-zero status, notmuch will abort further @@ -28,7 +28,7 @@ The currently available hooks are described below. Typically this hook is used for fetching or delivering new mail to be imported into the database. -**post-new** +post-new This hook is invoked by the :any:`notmuch-new(1)` command after new messages have been imported into the database and initial tags have been applied. The hook will not be run if there have been any @@ -37,7 +37,7 @@ The currently available hooks are described below. Typically this hook is used to perform additional query-based tagging on the imported messages. -**post-insert** +post-insert This hook is invoked by the :any:`notmuch-insert(1)` command after the message has been delivered, added to the database, and initial tags have been applied. The hook will not be run if there have diff --git a/doc/man7/notmuch-properties.rst b/doc/man7/notmuch-properties.rst index 7f128b5c..ff79f4c2 100644 --- a/doc/man7/notmuch-properties.rst +++ b/doc/man7/notmuch-properties.rst @@ -55,7 +55,7 @@ MESSAGE PROPERTIES The following properties are set by notmuch internally in the course of its normal activity. -**index.decryption** +index.decryption If a message contains encrypted content, and notmuch tries to decrypt that content during indexing, it will add the property ``index.decryption=success`` when the cleartext was successfully @@ -75,8 +75,7 @@ of its normal activity. :any:`notmuch-config(1)`), then this property will not be set on that message. -**session-key** - +session-key When :any:`notmuch-show(1)` or :any:`notmuch-reply(1)` encounters a message with an encrypted part, if notmuch finds a ``session-key`` property associated with the message, it will try @@ -111,8 +110,7 @@ of its normal activity. example, an AES-128 key might be stashed in a notmuch property as: ``session-key=7:14B16AF65536C28AF209828DFE34C9E0``. -**index.repaired** - +index.repaired Some messages arrive in forms that are confusing to view; they can be mangled by mail transport agents, or the sending mail user agent may structure them in a way that is confusing. If notmuch -- 2.33.0