From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id QCKdBcEbqGDbEQEAgWs5BA (envelope-from ) for ; Fri, 21 May 2021 22:44:49 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id kCZDAcEbqGA/MAAAbx9fmQ (envelope-from ) for ; Fri, 21 May 2021 20:44:49 +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) server-digest SHA256) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id A21681A4A6 for ; Fri, 21 May 2021 22:44:48 +0200 (CEST) Received: from nmbug.tethera.net (localhost [127.0.0.1]) by mail.notmuchmail.org (Postfix) with ESMTP id C5DB628D05; Fri, 21 May 2021 16:44:33 -0400 (EDT) Received: from mail-lj1-x22b.google.com (mail-lj1-x22b.google.com [IPv6:2a00:1450:4864:20::22b]) by mail.notmuchmail.org (Postfix) with ESMTPS id 2E11827169 for ; Fri, 21 May 2021 16:44:27 -0400 (EDT) Received: by mail-lj1-x22b.google.com with SMTP id w15so25448837ljo.10 for ; Fri, 21 May 2021 13:44:27 -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=hdNz/nUhhlXO25BvrSW4WjytBOMvOqandVOLwn6xih8=; b=injD6pCTBXz6roU0BRJQv8OLktHkctZog209Tn0QYTXnmS9SOVv5V3qnjNLHyp2xSq FNJW2sM2xdmOtGRZLcTFn8itrwtHeyVGMCjBBAtJ3C49tVFUEgweJLLEqUGYoVM/Z7hc 8/FwY/GM9SEGSVldGzlrRpP9ySmJ6zZXiAjerZhX7Nuq3f6BW1Y0Qim3ds881Aa+iWMq iQAprKk701Sz5ma3eOGKkW0oB0RYhP3YZ/YGbG+SB+LrsU2VcXpSTAq8qu57jKN21wU5 hfkW01zMVTnsKcnaGubs1zZZL2FMqmmW23mUtDXG8cdJsPZ5BG53Oas9uuLmQ/rhlc0s f7dA== 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=hdNz/nUhhlXO25BvrSW4WjytBOMvOqandVOLwn6xih8=; b=HLBafA3MaGMdAQQjIrj5dXqvhg7hndF/L8F9ij0UYxN7Epjv5uYwqvRcfwlvz2dCo4 dmerNCUbezrDlS/g0+EtsIxqNz5zfyjmGuRjNlqrWIlhFEeemohoYaZFGfaeeiFf6b+w mPiBii+7Q+hc6UexJtacyOfCgJnRbK+Vhh9jsMKAj2o7/xpFoVwVQyMbvNPGxXp8BZPG qZBMz0teTTAmNW3/N5dX/kDyCkPCX8cQMLm0nQWdB7IQ/Dcy6e5iJTxoaMQr3QKIOMQi IQmvMchvcVva9SOOVzZsWm8z9LrrGz0EKwmKxDrmkfTnQc7hXYDE2AmZZPeekJsTvEa5 uQuw== X-Gm-Message-State: AOAM530JQkKdmXXJcAOdN3h0ZYmCcdgvRMK+5YlA0blJPQmLf07D+NoO KSBfuGmdreSfSsH98WHSWVT4QqGSCmpXAhWcVyk= X-Google-Smtp-Source: ABdhPJy1lOK8k2uaf/uf7aj/drVw/AyVBU1JtJ6hejTz9T8HflfN1Fj74MBpED2Dqo+zW5D+n35pBA== X-Received: by 2002:a2e:9d59:: with SMTP id y25mr7875090ljj.399.1621629865260; Fri, 21 May 2021 13:44:25 -0700 (PDT) Received: from localhost (87-95-122-4.bb.dnainternet.fi. [87.95.122.4]) by smtp.gmail.com with ESMTPSA id x203sm721555lff.262.2021.05.21.13.44.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 21 May 2021 13:44:24 -0700 (PDT) From: Jani Nikula To: notmuch@notmuchmail.org Cc: jani@nikula.org Subject: [PATCH 3/5] doc: use envvar directive and role for environment variables Date: Fri, 21 May 2021 23:44:11 +0300 Message-Id: <20210521204413.554563-4-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: CXLECQU44FO63O4EZQC42HSYW7IHQIUH X-Message-ID-Hash: CXLECQU44FO63O4EZQC42HSYW7IHQIUH 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=1621629888; 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=AkCMagY1uSvtiUOgWSXSgWAnrk30WYOyGyb06fH0R/k=; b=cMTir1Bd4W5+nABJoeVQbH+kRCVp1kS+5rpzpQDKcbxnpeVsxf3pCNhFLHz9fgQ3kqSwHi fVpu3yL/QBOqcoeHx0H5doFNDThCgKfgj2MuGDqpQAb8wOloqu9dCEE9T8PQdwKG9ObStS RJu7Jnm3oZadc80FtGWiEZ1RZ0MaaPAhyBMuRyLUdRkI1S0TfiIkdRFtx44+0a0uF4gj4F D7AFF9v645qdRTaC6kpUGBo+JbP8itIndUizCM6cpuK98BaedjHFm5HILUXkLm+ZU4F5df XhhRtMTWIPl7qrN5drIoGTJFt7YoBh2FTzf30g61m2LSmAq2nrjkdzC1Smh5ZA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1621629888; a=rsa-sha256; cv=none; b=p8PkFFJMxS259rKNO9/N4omSiCTNDcf8XnoNue927YuO05BaGygSVbs2d6nx/QJrfQWq4A HNJvc1iUBFMtYeqAsSMqUUDu8uUF3jnNl188NE9uJLtUK/qS5GLwwa7yMiKlCK7EDVZ8M3 4FRnqoGHitp2LKrzxicxD+T8Q137ZJnEUBARniOqil3lAcJm3d9UZsqDrExTXu3Jgi7O/5 gjgROyMDdFpiPuTYmLMZZQgNLLrABaGDBe7+AuTRS5rbKF3RSiXK//x3/fI9My2EiVwA/e gYj0jagYRx3eDis9zKvnlYhqB7gkL3R0R7mV2VA1b7PaplSMb1mOA6i8W/beRg== 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=injD6pCT; 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=injD6pCT; 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: A21681A4A6 X-Spam-Score: -0.07 X-Migadu-Scanner: scn0.migadu.com X-TUID: N9ut3KIRmmWu Make man1/notmuch.rst the single point of truth for describing notmuch environment variables. Use the envvar directive for that, and reference them with the envvar role. Drive-by cleanup configuration file and hook directory search order documentation. --- doc/man1/notmuch-compact.rst | 10 -------- doc/man1/notmuch-config.rst | 42 +++++++++++++++++----------------- doc/man1/notmuch-emacs-mua.rst | 10 ++++---- doc/man1/notmuch.rst | 36 +++++++++++++++++------------ 4 files changed, 49 insertions(+), 49 deletions(-) diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst index 85f611bf44e5..3e3e70c532ca 100644 --- a/doc/man1/notmuch-compact.rst +++ b/doc/man1/notmuch-compact.rst @@ -35,16 +35,6 @@ Supported options for **compact** include ``--quiet`` Do not report database compaction progress to stdout. -ENVIRONMENT -=========== - -The following environment variables can be used to control the behavior -of notmuch. - -**NOTMUCH\_CONFIG** - Specifies the location of the notmuch configuration file. Notmuch - will use ${HOME}/.notmuch-config if this variable is not set. - SEE ALSO ======== diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst index 5c980a8a4bb8..129d4b810261 100644 --- a/doc/man1/notmuch-config.rst +++ b/doc/man1/notmuch-config.rst @@ -235,39 +235,39 @@ paths are presumed relative to `$HOME` for items in section :any:`notmuch-search-terms(7)` for more information about named queries. -ENVIRONMENT -=========== - -The following environment variables can be used to control the behavior -of notmuch. - -**NOTMUCH\_CONFIG** - Specifies the location of the notmuch configuration file. - -**NOTMUCH_PROFILE** - Selects among notmuch configurations. - FILES ===== CONFIGURATION ------------- -If ``NOTMUCH_CONFIG`` is unset, notmuch tries (in order) +Notmuch configuration file search order: -- ``$XDG_CONFIG_HOME/notmuch//config`` where ```` is - defined by ``$NOTMUCH_PROFILE`` or "default" -- ``${HOME}/.notmuch-config`` where ```` is - ``.$NOTMUCH_PROFILE`` or "" +1. File specified by ``--config=FILE`` global option; see + :any:`notmuch(1)`. + +2. File specified by :envvar:`NOTMUCH_CONFIG` environment variable. + +3. ``$XDG_CONFIG_HOME/notmuch//config`` where ```` + is defined by :envvar:`NOTMUCH_PROFILE` environment variable if + set, ``$XDG_CONFIG_HOME/notmuch/default/config`` otherwise. + +4. ``$HOME/.notmuch-config.`` where ```` is defined + by :envvar:`NOTMUCH_PROFILE` environment variable if set, + ``$HOME/.notmuch-config`` otherwise. Hooks ----- -If ``database.hook_dir`` is unset, notmuch tries (in order) +Notmuch hook directory search order: + +1. Directory specified by ``database.hook_dir`` configuration option. + +2. ``$XDG_CONFIG_HOME/notmuch//hooks`` where ```` + is defined by :envvar:`NOTMUCH_PROFILE` environment variable if + set, ``$XDG_CONFIG_HOME/notmuch/default/hooks`` otherwise. -- ``$XDG_CONFIG_HOME/notmuch//hooks`` where ```` is - defined by ``$NOTMUCH_PROFILE`` or "default" -- ``/.notmuch/hooks`` +3. ``/.notmuch/hooks`` SEE ALSO ======== diff --git a/doc/man1/notmuch-emacs-mua.rst b/doc/man1/notmuch-emacs-mua.rst index a599b6ebc7bf..c0d5b1a7c476 100644 --- a/doc/man1/notmuch-emacs-mua.rst +++ b/doc/man1/notmuch-emacs-mua.rst @@ -72,11 +72,13 @@ Options may be specified multiple times. ENVIRONMENT VARIABLES ===================== -**EMACS** - Name of emacs command to invoke. Defaults to "emacs". +.. envvar:: EMACS -**EMACSCLIENT** - Name of emacsclient command to invoke. Defaults to "emacsclient". + Name of emacs command to invoke. Defaults to "emacs". + +.. envvar:: EMACSCLIENT + + Name of emacsclient command to invoke. Defaults to "emacsclient". SEE ALSO ======== diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst index 7b84ef447935..93135bdd6abb 100644 --- a/doc/man1/notmuch.rst +++ b/doc/man1/notmuch.rst @@ -52,7 +52,7 @@ Supported global options for ``notmuch`` include ``--config=FILE`` Specify the configuration file to use. This overrides any - configuration file specified by ${NOTMUCH\_CONFIG}. The empty + configuration file specified by :envvar:`NOTMUCH_CONFIG`. The empty string is a permitted and sometimes useful value of *FILE*, which tells ``notmuch`` to use only configuration metadata from the database. @@ -79,7 +79,7 @@ use, (or to reconfigure it later). The setup command will prompt for your full name, your primary email address, any alternate email addresses you use, and the directory containing your email archives. Your answers will be written to a -configuration file in ${NOTMUCH\_CONFIG} (if set) or +configuration file in :envvar:`NOTMUCH_CONFIG` (if set) or ${HOME}/.notmuch-config . This configuration file will be created with descriptive comments, making it easy to edit by hand later to change the configuration. Or you can run **notmuch setup** again to change the @@ -128,8 +128,8 @@ CUSTOM COMMANDS --------------- If the given command is not known to notmuch, notmuch tries to execute -the external **notmuch-** in ${PATH} instead. This allows -users to have their own notmuch related tools to be run via the +the external **notmuch-** in :envvar:`PATH` instead. This +allows users to have their own notmuch related tools to be run via the notmuch command. By design, this does not allow notmuch's own commands to be overridden using external commands. @@ -153,18 +153,26 @@ ENVIRONMENT The following environment variables can be used to control the behavior of notmuch. -**NOTMUCH\_CONFIG** - Specifies the location of the notmuch configuration file. Notmuch - will use ${HOME}/.notmuch-config if this variable is not set. +.. envvar:: NOTMUCH_CONFIG -**NOTMUCH\_TALLOC\_REPORT** - Location to write a talloc memory usage report. See - **talloc\_enable\_leak\_report\_full** in :manpage:`talloc(3)` for more - information. + Specifies the location of the notmuch configuration file. See + :any:`notmuch-config(1)` for details. -**NOTMUCH\_DEBUG\_QUERY** - If set to a non-empty value, the notmuch library will print (to - stderr) Xapian queries it constructs. +.. envvar:: NOTMUCH_PROFILE + + Selects among notmuch configurations. See :any:`notmuch-config(1)` + for details. + +.. envvar:: NOTMUCH_TALLOC_REPORT + + Location to write a talloc memory usage report. See + **talloc\_enable\_leak\_report\_full** in :manpage:`talloc(3)` for more + information. + +.. envvar:: NOTMUCH_DEBUG_QUERY + + If set to a non-empty value, the notmuch library will print (to + stderr) Xapian queries it constructs. SEE ALSO ======== -- 2.30.2