From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id YMyjOUtPfmJBHQAAbAwnHQ (envelope-from ) for ; Fri, 13 May 2022 14:30:04 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id oAmfOUtPfmLyVgAA9RJhRA (envelope-from ) for ; Fri, 13 May 2022 14:30:03 +0200 Received: from mail.notmuchmail.org (yantan.tethera.net [135.181.149.255]) (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 3A78B3950D for ; Fri, 13 May 2022 14:30:03 +0200 (CEST) Received: from yantan.tethera.net (localhost [127.0.0.1]) by mail.notmuchmail.org (Postfix) with ESMTP id 41FE75F728; Fri, 13 May 2022 12:30:00 +0000 (UTC) Received: from fethera.tethera.net (fethera.tethera.net [IPv6:2607:5300:60:c5::1]) by mail.notmuchmail.org (Postfix) with ESMTP id 464985F70A for ; Fri, 13 May 2022 12:29:57 +0000 (UTC) Received: by fethera.tethera.net (Postfix, from userid 1001) id 299D45FBD7; Fri, 13 May 2022 08:29:56 -0400 (EDT) Received: (nullmailer pid 1981209 invoked by uid 1000); Fri, 13 May 2022 12:29:54 -0000 From: David Bremner To: notmuch@notmuchmail.org Subject: [PATCH] doc: define and use semantic markup for configuration items Date: Fri, 13 May 2022 09:29:29 -0300 Message-Id: <20220513122929.1981190-1-david@tethera.net> X-Mailer: git-send-email 2.35.2 MIME-Version: 1.0 Message-ID-Hash: 3ONJAUREPX3KKEDQAVVWU326JYM7BCGB X-Message-ID-Hash: 3ONJAUREPX3KKEDQAVVWU326JYM7BCGB 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; digests; suspicious-header X-Mailman-Version: 3.3.3 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: DE ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1652445003; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-owner:list-unsubscribe:list-subscribe:list-post; bh=HxzIltg9FWik1mUGFISc0KfUX0GfZl1rKL0/4bjaBEk=; b=N1v6cBHeDRseZrc95kUJ81lqI1Oka1PYWqOfwJ5Mzgk/MeLrpSmByvFm8biAGM0LBHVkVI 7L+AX+u3GrtEdyHJtsBcwvexxbGRmtKHbpc0yfEpODsXvAuj89OTzy6SFSusoSgNgDYyxu Ml6m/4oDRFXExYYDiurkmSmPd2e22zJ0Cj4mck+Leyezn+jGRBKKprelqgPE1TFSVoHfiw e/Yj5YUYikxs94WhSakBXmDou2hG94QIaAn+9Xgtx99jrYhpuUPcveJLU7AOSsv2tdwGpw eIRIY0q25kQU8aNhmL8wClZvkAFKu8/TQPhPwdsVu7FEWGULhislpVtPgBaJ8g== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1652445003; a=rsa-sha256; cv=none; b=Hh4/GHktibUqey9CvHHwGLiSzJBbP7AoxGw6RAvnxBWmNvPd9K0eQiI1+5BbN5z3Q9wCZa srrNcMFSm+yidZjfxZ6vLx0egw/kFPI6AymcM2ykKLw1VDDF67n61nICZreY8rah3JAIaa i/PkZZSM2ERGrtT1TIm2ZkSWq6ku4JBbNnhWCl7TrGbbOwuiLFo/4X402FSSYgTNPRIqdI 37XpoQ8gXZ/ifOBi+QxFtovUJyt+R3Co3ExT8D0/1zh5i2H2UxK3bI/TlHtz7fml+xgVr9 VLfGQp7s9ZEu2dGi37X/grOLXg4ObK9bR4Lm6A9qj5hVPKFDYiIH+nJZEANb4A== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 135.181.149.255 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Spam-Score: -1.42 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 135.181.149.255 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Queue-Id: 3A78B3950D X-Spam-Score: -1.42 X-Migadu-Scanner: scn0.migadu.com X-TUID: ghURkFfoII0P This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries. --- doc/conf.py | 7 +++++ doc/man1/notmuch-config.rst | 60 +++++++++++++++++++------------------ doc/man1/notmuch-insert.rst | 15 +++++----- doc/man1/notmuch-new.rst | 8 ++--- doc/man1/notmuch-show.rst | 2 +- 5 files changed, 50 insertions(+), 42 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index e46e1d4e..6afeac06 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -200,3 +200,10 @@ texinfo_documents += [ x[2], # description 'Miscellaneous' # category ) for x in man_pages] + +def setup(app): + import docutils.nodes + # define nmconfig role and directive for config items. + app.add_object_type('nmconfig','nmconfig', + indextemplate='pair: configuration item; %s', + ref_nodeclass=docutils.nodes.generated) diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst index acc5ecec..36d48725 100644 --- a/doc/man1/notmuch-config.rst +++ b/doc/man1/notmuch-config.rst @@ -55,13 +55,14 @@ The available configuration items are described below. Non-absolute paths are presumed relative to `$HOME` for items in section **database**. -built_with. +.. nmconfig:: 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.) -database.autocommit +.. nmconfig:: database.autocommit How often to commit transactions to disk. `0` means wait until command completes, otherwise an integer `n` specifies to commit to @@ -69,7 +70,8 @@ database.autocommit History: this configuration value was introduced in notmuch 0.33. -database.backup_dir +.. nmconfig:: database.backup_dir + Directory to store tag dumps when upgrading database. History: this configuration value was introduced in notmuch 0.32. @@ -77,7 +79,8 @@ database.backup_dir Default: A sibling directory of the Xapian database called `backups`. -database.hook_dir +.. nmconfig:: database.hook_dir + Directory containing hooks run by notmuch commands. See :any:`notmuch-hooks(5)`. @@ -85,9 +88,8 @@ database.hook_dir Default: See HOOKS, below. -.. _database.mail_root: +.. nmconfig:: 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. @@ -95,18 +97,18 @@ database.mail_root History: this configuration value was introduced in notmuch 0.32. Default: For compatibility with older configurations, the value of - database.path is used if **database.mail\_root** is unset. + database.path is used if :nmconfig:`database.mail_root` is unset. + +.. nmconfig:: database.path -database.path Notmuch will store its database here, (in - sub-directory named ``.notmuch`` if **database.mail\_root** + sub-directory named ``.notmuch`` if :nmconfig:`database.mail_root` is unset). Default: see :ref:`database` -.. _index.decrypt: +.. nmconfig:: index.decrypt -index.decrypt Policy for decrypting encrypted messages during indexing. Must be one of: ``false``, ``auto``, ``nostash``, or ``true``. @@ -161,7 +163,8 @@ index.decrypt .. _index.header: -index.header. +.. nmconfig:: 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 @@ -170,9 +173,8 @@ index.header. supported. See :any:`notmuch-search-terms(7)` for a list of existing prefixes, and an explanation of probabilistic prefixes. -.. _maildir.synchronize_flags: +.. nmconfig:: maildir.synchronize_flags -maildir.synchronize\_flags If true, then the following maildir flags (in message filenames) will be synchronized with the corresponding notmuch tags: @@ -205,9 +207,8 @@ maildir.synchronize\_flags Default: ``true``. -.. _new.ignore: +.. nmconfig:: 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: @@ -225,20 +226,21 @@ new.ignore Default: empty list. -.. _new.tags: +.. nmconfig:: new.tags -new.tags A list of tags that will be added to all messages incorporated by **notmuch new**. Default: ``unread;inbox``. -query. +.. nmconfig:: query. + Expansion for named query called . See :any:`notmuch-search-terms(7)` for more information about named queries. -search.exclude\_tags +.. nmconfig:: 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. @@ -246,9 +248,7 @@ search.exclude\_tags Default: empty list. Note that :any:`notmuch-setup(1)` puts ``deleted;spam`` here when creating new configuration file. -.. _show.extra_headers: - -show.extra\_headers +.. nmconfig:: show.extra_headers By default :any:`notmuch-show(1)` includes the following headers in structured output if they are present in the message: @@ -260,26 +260,28 @@ show.extra\_headers Default: empty list. -squery. +.. nmconfig:: squery. + Expansion for named query called , using s-expression syntax. See :any:`notmuch-sexp-queries(7)` for more information about s-expression queries. -user.name +.. nmconfig:: user.name + Your full name. Default: ``$NAME`` variable if set, otherwise read from ``/etc/passwd``. -user.other\_email +.. nmconfig:: user.other_email + A list of other email addresses at which you receive email - (see also, :ref:`user.primary_email `). + (see also, :nmconfig:`user.primary_email`) Default: not set. -.. _user.primary_email: +.. nmconfig:: user.primary_email -user.primary\_email Your primary email address. Default: ``$EMAIL`` variable if set, otherwise constructed from diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst index fe2bf26b..e05bd0b5 100644 --- a/doc/man1/notmuch-insert.rst +++ b/doc/man1/notmuch-insert.rst @@ -14,12 +14,12 @@ DESCRIPTION **notmuch insert** reads a message from standard input and delivers it into the maildir directory given by configuration option -:ref:`database.mail_root `, then incorporates the message into the notmuch +:nmconfig:`database.mail_root`, then incorporates the message into the notmuch database. It is an alternative to using a separate tool to deliver the message then running :any:`notmuch-new(1)` afterwards. The new message will be tagged with the tags specified by the -:ref:`new.tags ` configuration option, then by operations specified on the +:nmconfig:`new.tags` configuration option, then by operations specified on the command-line: tags prefixed by '+' are added while those prefixed by '-' are removed. @@ -38,7 +38,7 @@ Supported options for **insert** include .. option:: --folder= Deliver the message to the specified folder, relative to the - top-level directory given by the value of **database.mail_root**. The + top-level directory given by the value of :nmconfig:`database.mail_root`. The default is the empty string, which means delivering to the top-level directory. @@ -86,16 +86,15 @@ Supported options for **insert** include ``--decrypt=nostash`` without considering the security of your index. - See also :ref:`index.decrypt ` in :any:`notmuch-config(1)`. + See also :nmconfig:`index.decrypt` in :any:`notmuch-config(1)`. CONFIGURATION ============= Indexing is influenced by the configuration options -:ref:`index.decrypt ` and :ref:`index.header -`. Tagging -is controlled by :ref:`new.tags ` and -:ref:`maildir.synchronize_flags `. See +:nmconfig:`index.decrypt` and :nmconfig:`index.header.\`. Tagging +is controlled by options :nmconfig:`new.tags` and +:nmconfig:`maildir.synchronize_flags`. See :any:`notmuch-config(1)` for details. EXIT STATUS diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst index 398f8813..f0ed8eb8 100644 --- a/doc/man1/notmuch-new.rst +++ b/doc/man1/notmuch-new.rst @@ -82,10 +82,10 @@ CONFIGURATION ============= Indexing is influenced by the configuration options -:ref:`index.decrypt `, :ref:`index.header -`, and :ref:`new.ignore `. Tagging -is controlled by :ref:`new.tags ` and -:ref:`maildir.synchronize_flags `. See +:nmconfig:`index.decrypt`, :nmconfig:`index.header.\` +and :nmconfig:`new.ignore`. Tagging +is controlled by :nmconfig:`new.tags` and +:nmconfig:`maildir.synchronize_flags`. See :any:`notmuch-config(1)` for details. EXIT STATUS diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst index 1b02d407..55353921 100644 --- a/doc/man1/notmuch-show.rst +++ b/doc/man1/notmuch-show.rst @@ -225,7 +225,7 @@ CONFIGURATION ============= Structured output (json / sexp) is influenced by the configuration -option :ref:`show.extra_headers `. See +option :nmconfig:`show.extra_headers`. See :any:`notmuch-config(1)` for details. EXIT STATUS -- 2.35.2