From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id SDinBbcbqGBnDwEAgWs5BA (envelope-from ) for ; Fri, 21 May 2021 22:44:39 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id qIZcAbcbqGBUSQAA1q6Kng (envelope-from ) for ; Fri, 21 May 2021 20:44:39 +0000 Received: from mail.notmuchmail.org (nmbug.tethera.net [144.217.243.247]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 4A14C1B140 for ; Fri, 21 May 2021 22:44:38 +0200 (CEST) Received: from nmbug.tethera.net (localhost [127.0.0.1]) by mail.notmuchmail.org (Postfix) with ESMTP id 4E16427552; Fri, 21 May 2021 16:44:29 -0400 (EDT) Received: from mail-lf1-x132.google.com (mail-lf1-x132.google.com [IPv6:2a00:1450:4864:20::132]) by mail.notmuchmail.org (Postfix) with ESMTPS id A73A427169 for ; Fri, 21 May 2021 16:44:22 -0400 (EDT) Received: by mail-lf1-x132.google.com with SMTP id j6so28869779lfr.11 for ; Fri, 21 May 2021 13:44:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nikula-org.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=xFu6QcRsQH3shR3YhGiBg0BDzVRWxxXl2t10/v66bVY=; b=m7IKD42EBSkZf0aKC3w5zE00zErIuJHyVVBWRGQPh4nT1kup98EHLHmPN1Da/ZTpSy H3UrgK4NU0fJa0BW6K0Q1whfCSaEi3pa527d+S2uKTM5W1yN0Vova+MBNYMTCVI7oHBH Hy1L8So5kMmMeZi+wvL8ioIj8ufWUvHbTt8cGYX8uUlxqWWfA6T8fCsAKeIa1tZ/dAde mD70YjsrVD4ZK34URxlJK9t7LM28/DY36YH+R7Z2LC6FRUg72E+TzRW2ZPkoJHxxJ9U1 Udm828aAbVtbfK7JQcdk4c4hkPWmiNAAOEdDMGQc74pOZ2GdvG2dZnIOIr+8Emqg7fla xgtg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=xFu6QcRsQH3shR3YhGiBg0BDzVRWxxXl2t10/v66bVY=; b=klC0onZhx3cvJC2CMDY7vuFz0x8fquULa1GTBo5oBR6Um7R8jN44bAoU2HBFwQdMNX 5L8EQ1CPDzvwCSiEfenqSHdzI9bBfZEXbzaF4eRpNQEZXX1b14Dku90Qtc+V8kcVcZ2Q NY7LjaavkV0YKuo9wHAFBQixo2ulkQC6r+MFwUp+3Y2fiiNu363bVwKSleM+gvmobk5f YDIbvOifTjvC/4yYkBwosg/VyA90+SPbbDawtfjfsyuWoMu3TI7NulmMEaO3nM2+LcV2 zaBytIr5eJMwWR3UnYDQeT8KigoDvPw/MebGRY10UW3Yxba17THKJfGkfVKzdcLVRn9z sc9w== X-Gm-Message-State: AOAM5308RsSoe0C1brMz4A+9EvTkW/YAP11qx+RnQ02FkJiQaIICIOHE IjE5blDE5f8nw1hbRYf7vqcLRE0eU/u2L/XaH2I= X-Google-Smtp-Source: ABdhPJxny6RB7QAc2CQMBYhXhutyYzpoxkCQrCHk2Men6C+MmbIs+pcsYBOKgxJfbWW/xtSj6b1fOQ== X-Received: by 2002:ac2:554b:: with SMTP id l11mr3221830lfk.71.1621629860799; Fri, 21 May 2021 13:44:20 -0700 (PDT) Received: from localhost (87-95-122-4.bb.dnainternet.fi. [87.95.122.4]) by smtp.gmail.com with ESMTPSA id z20sm751849ljz.33.2021.05.21.13.44.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 21 May 2021 13:44:20 -0700 (PDT) From: Jani Nikula To: notmuch@notmuchmail.org Cc: jani@nikula.org Subject: [PATCH 1/5] doc: use manpage role references to external man pages Date: Fri, 21 May 2021 23:44:09 +0300 Message-Id: <20210521204413.554563-2-jani@nikula.org> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20210521204413.554563-1-jani@nikula.org> References: <20210521204413.554563-1-jani@nikula.org> MIME-Version: 1.0 Message-ID-Hash: KTXL6VA5CDQ2SAFXUPLN2JLDGNN6AT7Z X-Message-ID-Hash: KTXL6VA5CDQ2SAFXUPLN2JLDGNN6AT7Z X-MailFrom: jani@nikula.org 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=1621629878; 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:dkim-signature; bh=DlH3lH0FEmRYVjV87sDMQ6xIPAjWZpKRzgeb4i5OXF8=; b=SUHYhgGtRjuEsdkNG7xomwA0zA9FTkH+LX7rPLDF0floa40LbdNlYk3MkcQ2yPe6sI4TL2 WfUpojjEGNa0zN2qa9LZlOsYWULw2CEwQdUDpjCQqhSpmuVYg7OB2IeX4/4d/ifB19W8KV fh3LUlXq0fbx4qdu4+T8kKYX9KdeoP5lNzQ9GWuB/XVgxlAL1o9TElujbmMGbtPiVZo53c chRb21RrReOL77MXEf9TEFoVMfWuPBvMaQL4wQCqpOdyaFIuCUH6A9P9mDLjxaOZwJ43vX l+Lb/5u2NZC7JZ2Vm1veNH8nGsPLjIQRxPBjYihSZ94Ae5+dj2M0gXqDDJwMMg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1621629878; a=rsa-sha256; cv=none; b=jBlyl/ckP6o3KVDvRR17wT9bIASUaIM6AHKnw/jO2pBCexMcnR9s3YIToemMpnyzHp4s+w B/CwTV4mZ9j4mN7DzGSbspb+YmLYkmtug3urDNPEBCw9I73AVHN5plu1YX1eiUpZCqTB49 TcNCfMoQJwBg24kVkh5MEMNu8oy9JzBicXHmuZI8TT8P+6D9wZ1MTsU+lmAT0VGuQ1Q9rQ Mo0Ze4ToTZuf+EpGXOr2Lrr/wnnTMKF8zgBJRnQH4nbUsuZ8yP4K7Po8TB9OikVJR+xfC8 j5z/HdCKaxV2nb02HVfpKyk8+S+QY8VVLGf1It3v/BRjVS1tp/rgxUV+4QAMdw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("body hash did not verify") header.d=nikula-org.20150623.gappssmtp.com header.s=20150623 header.b=m7IKD42E; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 144.217.243.247 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Spam-Score: -0.07 Authentication-Results: aspmx1.migadu.com; dkim=fail ("body hash did not verify") header.d=nikula-org.20150623.gappssmtp.com header.s=20150623 header.b=m7IKD42E; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 144.217.243.247 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Queue-Id: 4A14C1B140 X-Spam-Score: -0.07 X-Migadu-Scanner: scn1.migadu.com X-TUID: SsgzaJ5X9Xht Using manpage role references generates helpful links in html documentation, while retaining the same boldface style in the man pages. The external man page site is configurable. The Debian manpage site seems like a good fit for Notmuch. --- doc/conf.py | 5 +++++ doc/man1/notmuch-address.rst | 4 ++-- doc/man1/notmuch-dump.rst | 16 ++++++++-------- doc/man1/notmuch-emacs-mua.rst | 15 +++++++++------ doc/man1/notmuch-reply.rst | 2 +- doc/man1/notmuch-restore.rst | 6 +++--- doc/man1/notmuch-search.rst | 4 ++-- doc/man1/notmuch-show.rst | 2 +- doc/man1/notmuch.rst | 5 +++-- doc/man7/notmuch-search-terms.rst | 2 +- 10 files changed, 35 insertions(+), 26 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index d0f7f66ce83e..4a4a34212cc3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -80,6 +80,11 @@ htmlhelp_basename = 'notmuchdoc' # Despite the name, this actually affects manual pages as well. html_use_smartypants = False +# See: +# - https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url +# - https://manpages.debian.org/ +manpages_url = 'https://manpages.debian.org/{page}.{section}.html' + # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst index 2a7df6f0d80f..9193aefe1db6 100644 --- a/doc/man1/notmuch-address.rst +++ b/doc/man1/notmuch-address.rst @@ -21,8 +21,8 @@ Supported options for **address** include ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) Presents the results in either JSON, S-Expressions, newline character separated plain-text (default), or null character - separated plain-text (compatible with **xargs(1)** -0 option where - available). + separated plain-text (compatible with :manpage:`xargs(1)` -0 + option where available). ``--format-version=N`` Use the specified structured output format version. This is diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst index ec6335b2febc..0a7a23876cf3 100644 --- a/doc/man1/notmuch-dump.rst +++ b/doc/man1/notmuch-dump.rst @@ -27,7 +27,7 @@ the remaining arguments are search terms. Supported options for **dump** include ``--gzip`` - Compress the output in a format compatible with **gzip(1)**. + Compress the output in a format compatible with :manpage:`gzip(1)`. ``--format=(sup|batch-tag)`` Notmuch restore supports two plain text dump formats, both with @@ -36,8 +36,8 @@ Supported options for **dump** include **batch-tag** The default **batch-tag** dump format is intended to more robust against malformed message-ids and tags containing - whitespace or non-\ **ascii(7)** characters. Each line has the - form:: + whitespace or non-\ :manpage:`ascii(7)` characters. Each line + has the form:: +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- id:<*quoted-message-id*\ > @@ -54,11 +54,11 @@ Supported options for **dump** include **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). Each line has the - following form:: + compatible with the format of files produced by + :manpage:`sup-dump(1)`. 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). Each line has the following form:: <*message-id*\ > **(** <*tag*\ > ... **)** diff --git a/doc/man1/notmuch-emacs-mua.rst b/doc/man1/notmuch-emacs-mua.rst index a0476136f503..a1e65eddd9f1 100644 --- a/doc/man1/notmuch-emacs-mua.rst +++ b/doc/man1/notmuch-emacs-mua.rst @@ -41,8 +41,9 @@ Supported options for **emacs-mua** include Even if a window system is available, use the current terminal. ``--client`` - Use **emacsclient**, rather than **emacs**. For **emacsclient** to - work, you need an already running Emacs with a server, or use + Use :manpage:`emacsclient(1)`, rather than + :manpage:`emacs(1)`. For :manpage:`emacsclient(1)` to work, you + need an already running Emacs with a server, or use ``--auto-daemon``. ``--auto-daemon`` @@ -60,9 +61,9 @@ Supported options for **emacs-mua** include Output the resulting elisp to stdout instead of evaluating it. The supported positional parameters and short options are a compatible -subset of the **mutt** MUA command-line options. The options and -positional parameters modifying the message can't be combined with the -mailto: URL. +subset of the :manpage:`mutt(1)` MUA command-line options. The options +and positional parameters modifying the message can't be combined with +the mailto: URL. Options may be specified multiple times. @@ -78,4 +79,6 @@ ENVIRONMENT VARIABLES SEE ALSO ======== -**notmuch(1)**, **emacsclient(1)**, **mutt(1)** +**notmuch(1)**, +:manpage:`emacsclient(1)`, +:manpage:`mutt(1)` diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst index 5c64c4a63b10..b1c3590b446a 100644 --- a/doc/man1/notmuch-reply.rst +++ b/doc/man1/notmuch-reply.rst @@ -86,7 +86,7 @@ Supported options for **reply** include Use ``false`` to avoid even automatic decryption. Non-automatic decryption expects a functioning - **gpg-agent(1)** to provide any needed credentials. Without + :manpage:`gpg-agent(1)` to provide any needed credentials. Without one, the decryption will likely fail. Default: ``auto`` diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst index c0f47f261372..e7d68c08d2ba 100644 --- a/doc/man1/notmuch-restore.rst +++ b/doc/man1/notmuch-restore.rst @@ -77,9 +77,9 @@ GZIPPED INPUT ============= \ **notmuch restore** will detect if the input is compressed in -**gzip(1)** format and automatically decompress it while reading. This -detection does not depend on file naming and in particular works for -standard input. +:manpage:`gzip(1)` format and automatically decompress it while +reading. This detection does not depend on file naming and in +particular works for standard input. SEE ALSO ======== diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst index ed9ff4e5b965..ee9d41182464 100644 --- a/doc/man1/notmuch-search.rst +++ b/doc/man1/notmuch-search.rst @@ -27,8 +27,8 @@ Supported options for **search** include ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) Presents the results in either JSON, S-Expressions, newline character separated plain-text (default), or null character - separated plain-text (compatible with **xargs(1)** -0 option where - available). + separated plain-text (compatible with :manpage:`xargs(1)` -0 + option where available). ``--format-version=N`` Use the specified structured output format version. This is diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst index becd3e799290..c2130e47568e 100644 --- a/doc/man1/notmuch-show.rst +++ b/doc/man1/notmuch-show.rst @@ -130,7 +130,7 @@ Supported options for **show** include Use ``false`` to avoid even automatic decryption. Non-automatic decryption (``stash`` or ``true``, in the absence of - a stashed session key) expects a functioning **gpg-agent(1)** to + a stashed session key) expects a functioning :manpage:`gpg-agent(1)` to provide any needed credentials. Without one, the decryption will fail. diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst index 48351588a3ea..7fdcc9dd57fb 100644 --- a/doc/man1/notmuch.rst +++ b/doc/man1/notmuch.rst @@ -90,7 +90,8 @@ will do its best to detect those and ignore them. Mail storage that uses mbox format, (where one mbox file contains many messages), will not work with notmuch. If that's how your mail is currently stored, it is recommended you first convert it to maildir -format with a utility such as mb2md before running **notmuch setup .** +format with a utility such as :manpage:`mb2md(1)` before running +**notmuch setup**. Invoking ``notmuch`` with no command argument will run **setup** if the setup command has not previously been completed. @@ -152,7 +153,7 @@ of notmuch. **NOTMUCH\_TALLOC\_REPORT** Location to write a talloc memory usage report. See - **talloc\_enable\_leak\_report\_full** in **talloc(3)** for more + **talloc\_enable\_leak\_report\_full** in :manpage:`talloc(3)` for more information. **NOTMUCH\_DEBUG\_QUERY** diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst index 28fca7379b7b..04413f81ac8c 100644 --- a/doc/man7/notmuch-search-terms.rst +++ b/doc/man7/notmuch-search-terms.rst @@ -39,7 +39,7 @@ indicate user-supplied values). Some of the prefixes with forms can be also used to restrict the results to those whose value matches a regular expression (see -**regex(7)**) delimited with //, for example:: +:manpage:`regex(7)`) delimited with //, for example:: notmuch search 'from:"/bob@.*[.]example[.]com/"' -- 2.30.2