From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id IP3MKW7TZWItqwAAbAwnHQ (envelope-from ) for ; Mon, 25 Apr 2022 00:47:10 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id qPb6KW7TZWLUKgAA9RJhRA (envelope-from ) for ; Mon, 25 Apr 2022 00:47:10 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 2AD32139D6 for ; Mon, 25 Apr 2022 00:47:10 +0200 (CEST) Received: from localhost ([::1]:54124 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nil0U-00042Y-RR for larch@yhetil.org; Sun, 24 Apr 2022 18:47:06 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:54504) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nil0P-000428-VM for guix-patches@gnu.org; Sun, 24 Apr 2022 18:47:01 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:38179) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nil0P-0007aB-Mm for guix-patches@gnu.org; Sun, 24 Apr 2022 18:47:01 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nil0P-00069q-Jg for guix-patches@gnu.org; Sun, 24 Apr 2022 18:47:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#54674] [PATCH] doc: Follow the 'disabled -> *unspecified* configuration refactor. References: <20220401191957.16624-1-attila@lendvai.name> In-Reply-To: <20220401191957.16624-1-attila@lendvai.name> Resent-From: Attila Lendvai Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Sun, 24 Apr 2022 22:47:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 54674 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 54674@debbugs.gnu.org Cc: Attila Lendvai Received: via spool by 54674-submit@debbugs.gnu.org id=B54674.165084039223632 (code B ref 54674); Sun, 24 Apr 2022 22:47:01 +0000 Received: (at 54674) by debbugs.gnu.org; 24 Apr 2022 22:46:32 +0000 Received: from localhost ([127.0.0.1]:60309 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nikzw-000695-4m for submit@debbugs.gnu.org; Sun, 24 Apr 2022 18:46:32 -0400 Received: from mail-ej1-f45.google.com ([209.85.218.45]:42645) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nikzt-00068p-Mg for 54674@debbugs.gnu.org; Sun, 24 Apr 2022 18:46:30 -0400 Received: by mail-ej1-f45.google.com with SMTP id i27so26344388ejd.9 for <54674@debbugs.gnu.org>; Sun, 24 Apr 2022 15:46:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=sender:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=htolp5+3Q5z1Kb0BB46Rrofh4a7IPRllPinynQfjEPU=; b=UfojvFe/h2qmQVKXCJAcH/jEbmYRgMcbsaFBSGeA3zrBKUvnc8+WlWIlefuRY3B9yj 5IcIO64OIfRKANJ5LkiyOaYuewrwhGmyCnYM2Xk9rAuR8nOCxQ6TzY5XbQtLNXrOCuli FgykC5dYYghSmCFOAXPbggcIH/75IwFulWIuVlVNIAQT2vgFviaGG9yPuiyRksprJn3r SpbXV2Ef6Ew0W9O9FsqNPV8IjdUCKXBBWitSNjPvT6Kwyo764j2m4IDMepekCMWD75+x 6YlOwW6892uQfYFtIjTbIOMFUeDAlDbu3UfhRltAoVUKHjNC+jYtGFpBbpV5fYTsFa8R 59kg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :mime-version:content-transfer-encoding; bh=htolp5+3Q5z1Kb0BB46Rrofh4a7IPRllPinynQfjEPU=; b=5YH+tkk0ssFdcNOdjxdDPe3+0bxLBOXUsyw0mYOseu/QBCROGKko0385dKPeHuDw5t MhbDr9UYYNft1r3EQoX2WiW+sz3YzFQbhKtAP8bVv6MqXf7S2DFUaBj7WtpE3DynXpKr liQL8ohOdFA/MWTjiXMw1qzkIuca37qs0t1Om1toOlO699QXxwYQ/y6uweiaaUemaoAJ eOMSbUNUz5Mreisa5P7IILBBfcMKqyHizy6RyzihxGPyG4vjFFI86GB4jIVtErCpLWpC 6QUjMxOnjVJqkbqURQhEA1x8hKBygbthTyPGL7T1umwLyfbwFTwEzHoTpE8wQBr+Zp+4 Kt0w== X-Gm-Message-State: AOAM532P0KhI/+NQ8w01KhxvyIbYxxcylHIZleIBcbvj5TXTub0X7DJE 0pb9+aPWimaFlNndu/+7ou+d5KB+DdoRkw== X-Google-Smtp-Source: ABdhPJyjx9rFKPHTzzczXT6rjLQ6kg2e0HG9IchO6TPeA5itf7LYL5FPPPhpYW4Y2oKe5QcESP5U5Q== X-Received: by 2002:a17:906:1692:b0:6e8:d245:44a9 with SMTP id s18-20020a170906169200b006e8d24544a9mr13545948ejd.639.1650840383514; Sun, 24 Apr 2022 15:46:23 -0700 (PDT) Received: from localhost.localdomain (82-99-152-25.static.bluetone.cz. [82.99.152.25]) by smtp.gmail.com with ESMTPSA id q11-20020a170906144b00b006cf61dfb03esm2991426ejc.62.2022.04.24.15.46.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 24 Apr 2022 15:46:23 -0700 (PDT) From: Attila Lendvai Date: Mon, 25 Apr 2022 00:41:25 +0200 Message-Id: <20220424224124.6823-1-attila@lendvai.name> X-Mailer: git-send-email 2.35.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1650840430; h=from:from:sender:sender: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:resent-cc: resent-from:resent-sender:resent-message-id:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=htolp5+3Q5z1Kb0BB46Rrofh4a7IPRllPinynQfjEPU=; b=WMbbcy3ercYgf4aOSucxGxccswpaK0udwbC0zTUHFnGWj9/QcqkssXWkNBftsihbgodyt7 xkyaWhAcyLG5O3QaWszmyG1IuXfbdG8qa3IWl2ESr6tOTKJj/ueqIe32nR50a20NgrgIEv Fd8kZrqejlobsxRvT6Li11Ouhjz2RHmiWt5VaFjysY6+QIoODx0seU69og/NndjCrAnmAk luvknPINCczy1yC+QJ84dThXp3HCalBaVs7cOM0NeT0rmmnGWgDkAPMqFd+xRjIvBDnnAc iLAoOTEmP5S4+zmgDAb73V3ba7MJusHqdkrZplcS2e0ybG/bobUIPU7xpRUwPg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1650840430; a=rsa-sha256; cv=none; b=Pm6tSk3lSinyaHbHlATn6AnlaGrl7e7lbIyyjYRfSGXnWI6165iO4N+6BMKkkHjMLxgNct w9uEwyemdXKIWR+qfC53c9ukyIkmivBZfLKIQ0Rk110+U65qhIhXYQ/gx08qKKOVx+Zocs kCe7pVuySfjtmkWBFr0jJ/7VmfU8Y9JHOE4Egv2+MIxTWZwziFJmuMiKf6mwbMZx7i6FLY 3W225wDu7d0AnQ3DOnLojVmocZAXv5g/Dne3QHel+7oymdJHBARENslEQFj1MynNQ1DONp WOEwI5ah8w4cREpdi60E8mmbwYW/+pM2GuqTgDgT7twSPTfIMr+OdaJaS0JjKg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b="UfojvFe/"; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: 2.69 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b="UfojvFe/"; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 2AD32139D6 X-Spam-Score: 2.69 X-Migadu-Scanner: scn0.migadu.com X-TUID: /XKv36tv8ElJ --- update the doc in a separate commit. you may want to squash it on the refactor commit, depending on what trade off the project prefers. doc/guix.texi | 85 ++++++++++++++++++++++++++------------------------- 1 file changed, 43 insertions(+), 42 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index a865b2e2e4..ac1b4d1d37 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18623,15 +18623,16 @@ The node host name that is used to make the first connection to the network. A specific port value can be provided by appending the @code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but any host can be specified here. It's also possible to disable -bootsrapping by setting this to the @code{'disabled} symbol. +bootsrapping by explicitly setting this to the @code{*unspecified*} +value. Defaults to @samp{"bootstrap.jami.net:4222"}. @end deftypevr @deftypevr {@code{opendht-configuration} parameter} maybe-number port -The UDP port to bind to. When set to @code{'disabled}, an available -port is automatically selected. +The UDP port to bind to. When explicitly set to @code{*unspecified*}, +an available port is automatically selected. Defaults to @samp{4222}. @@ -24396,7 +24397,7 @@ The available configuration parameters follow. Each parameter definition is preceded by its type; for example, @samp{string-list foo} indicates that the @code{foo} parameter should be specified as a list of strings. Types starting with @code{maybe-} denote parameters that won't -show up in @code{prosody.cfg.lua} when their value is @code{'disabled}. +show up in @code{prosody.cfg.lua} when their value is left unspecified. There is also a way to specify the configuration as a string, if you have an old @code{prosody.cfg.lua} file that you want to port over from @@ -25010,7 +25011,7 @@ Whether to enable debug level messages. @item @code{auto-answer?} (default: @code{#f}) (type: boolean) Whether to force automatic answer to incoming calls. -@item @code{accounts} (default: @code{disabled}) (type: maybe-jami-account-list) +@item @code{accounts} (type: maybe-jami-account-list) A list of Jami accounts to be (re-)provisioned every time the Jami daemon service starts. When providing this field, the account directories under @file{/var/lib/jami/} are recreated every time the @@ -25032,39 +25033,39 @@ should @emph{not} be encrypted. It is highly recommended to make it readable only to the @samp{root} user (i.e., not in the store), to guard against leaking the secret key material of the Jami account it contains. -@item @code{allowed-contacts} (default: @code{disabled}) (type: maybe-account-fingerprint-list) +@item @code{allowed-contacts} (type: maybe-account-fingerprint-list) The list of allowed contacts for the account, entered as their 40 characters long fingerprint. Messages or calls from accounts not in -that list will be rejected. When unspecified, the configuration of the -account archive is used as-is with respect to contacts and public +that list will be rejected. When left specified, the configuration of +the account archive is used as-is with respect to contacts and public inbound calls/messaging allowance, which typically defaults to allow any contact to communicate with the account. -@item @code{moderators} (default: @code{disabled}) (type: maybe-account-fingerprint-list) +@item @code{moderators} (type: maybe-account-fingerprint-list) The list of contacts that should have moderation privileges (to ban, mute, etc. other users) in rendezvous conferences, entered as their 40 -characters long fingerprint. When unspecified, the configuration of the -account archive is used as-is with respect to moderation, which +characters long fingerprint. When left unspecified, the configuration +of the account archive is used as-is with respect to moderation, which typically defaults to allow anyone to moderate. -@item @code{rendezvous-point?} (default: @code{disabled}) (type: maybe-boolean) +@item @code{rendezvous-point?} (type: maybe-boolean) Whether the account should operate in the rendezvous mode. In this mode, all the incoming audio/video calls are mixed into a conference. When left unspecified, the value from the account archive prevails. -@item @code{peer-discovery?} (default: @code{disabled}) (type: maybe-boolean) +@item @code{peer-discovery?} (type: maybe-boolean) Whether peer discovery should be enabled. Peer discovery is used to discover other OpenDHT nodes on the local network, which can be useful to maintain communication between devices on such network even when the connection to the the Internet has been lost. When left unspecified, the value from the account archive prevails. -@item @code{bootstrap-hostnames} (default: @code{disabled}) (type: maybe-string-list) +@item @code{bootstrap-hostnames} (type: maybe-string-list) A list of hostnames or IPs pointing to OpenDHT nodes, that should be used to initially join the OpenDHT network. When left unspecified, the value from the account archive prevails. -@item @code{name-server-uri} (default: @code{disabled}) (type: maybe-string) +@item @code{name-server-uri} (type: maybe-string) The URI of the name server to use, that can be used to retrieve the account fingerprint for a registered username. @@ -25698,8 +25699,8 @@ Defaults to @samp{prefer-encrypted-connections}. @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm The TCP congestion-control algorithm to use for peer connections, specified using a string recognized by the operating system in calls to -@code{setsockopt} (or set to @code{disabled}, in which case the -operating-system default is used). +@code{setsockopt}. When left unspecified, the operating-system default +is used. Note that on GNU/Linux systems, the kernel must be configured to allow processes to use a congestion-control algorithm not in the default set; @@ -29327,7 +29328,7 @@ Defaults to @samp{tun}. If you do not have some of these files (eg.@: you use a username and password), you can disable any of the following three fields by setting -it to @code{'disabled}. +it to @code{*unspecified*}. @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string ca The certificate authority to check connections against. @@ -29401,7 +29402,6 @@ Authenticate with server using username/password. The option is a file containing username/password on 2 lines. Do not use a file-like object as it would be added to the store and readable by any user. -Defaults to @samp{'disabled}. @end deftypevr @deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage? @@ -29482,7 +29482,7 @@ Defaults to @samp{tun}. If you do not have some of these files (eg.@: you use a username and password), you can disable any of the following three fields by setting -it to @code{'disabled}. +it to @code{*unspecified*}. @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string ca The certificate authority to check connections against. @@ -30281,10 +30281,10 @@ content by adding a valid @code{tlp-configuration}: @end deffn Each parameter definition is preceded by its type; for example, -@samp{boolean foo} indicates that the @code{foo} parameter -should be specified as a boolean. Types starting with -@code{maybe-} denote parameters that won't show up in TLP config file -when their value is @code{'disabled}. +@samp{boolean foo} indicates that the @code{foo} parameter should be +specified as a boolean. Types starting with @code{maybe-} denote +parameters that won't show up in TLP config file when their value is +left unset, or is explicitly set to the @code{*unspecified*} value. @c The following documentation was initially generated by @c (generate-tlp-documentation) in (gnu services pm). Manually maintained @@ -37840,15 +37840,16 @@ macro which is a shorthand of this. @deffn {Scheme Syntax} define-maybe @var{type} Sometimes a field should not be serialized if the user doesn’t specify a value. To achieve this, you can use the @code{define-maybe} macro to -define a ``maybe type''; if the value of a maybe type is set to the -@code{disabled}, it will not be serialized. +define a ``maybe type''; if the value of a maybe type is left unset, or +is set to the @code{*unspecified*} value, then it will not be +serialized. When defining a ``maybe type'', the corresponding serializer for the regular type will be used by default. For example, a field of type @code{maybe-string} will be serialized using the @code{serialize-string} procedure by default, you can of course change this by specifying a custom serializer procedure. Likewise, the type of the value would have -to be a string, unless it is set to the @code{disabled} symbol. +to be a string, or left unspecified. @lisp (define-maybe string) @@ -37858,9 +37859,9 @@ to be a string, unless it is set to the @code{disabled} symbol. (define-configuration baz-configuration (name - ;; Nothing will be serialized by default. If set to a string, the - ;; `serialize-string' procedure will be used to serialize the string. - (maybe-string 'disabled) + ;; If set to a string, the `serialize-string' procedure will be used + ;; to serialize the string. Otherwise this field is not serialized. + maybe-string ; equivalent to (maybe-string *unspecified*) "The name of this module.")) @end lisp @@ -37877,7 +37878,7 @@ serializer name by using the @code{prefix} literal. There is also the @code{no-serialization} literal, which when set means that no serializer will be defined for the ``maybe type'', regardless of -its value is @code{disabled} or not. +whether its value is set or not. @code{define-maybe/no-serialization} is a shorthand for specifying the @code{no-serialization} literal. @@ -37886,7 +37887,7 @@ its value is @code{disabled} or not. (define-configuration/no-serialization test-configuration (mode - (maybe-symbol 'disabled) + maybe-symbol "Docstring.")) @end lisp @end deffn @@ -38018,10 +38019,10 @@ Below is an example of a record type created using "The name of the contact." serialize-contact-name) (phone-number - (maybe-integer 'disabled) + maybe-integer "The person's phone number.") (email - (maybe-string 'disabled) + maybe-string "The person's email address.") (married? (boolean) @@ -38745,24 +38746,24 @@ Daytime color temperature (kelvins). @item @code{nighttime-temperature} (default: @code{4500}) (type: integer) Nighttime color temperature (kelvins). -@item @code{daytime-brightness} (default: @code{disabled}) (type: maybe-inexact-number) -Daytime screen brightness, between 0.1 and 1.0. +@item @code{daytime-brightness} (type: maybe-inexact-number) +Daytime screen brightness, between 0.1 and 1.0, or left unspecified. -@item @code{nighttime-brightness} (default: @code{disabled}) (type: maybe-inexact-number) -Nighttime screen brightness, between 0.1 and 1.0. +@item @code{nighttime-brightness} (type: maybe-inexact-number) +Nighttime screen brightness, between 0.1 and 1.0, or left unspecified. -@item @code{latitude} (default: @code{disabled}) (type: maybe-inexact-number) +@item @code{latitude} (type: maybe-inexact-number) Latitude, when @code{location-provider} is @code{'manual}. -@item @code{longitude} (default: @code{disabled}) (type: maybe-inexact-number) +@item @code{longitude} (type: maybe-inexact-number) Longitude, when @code{location-provider} is @code{'manual}. -@item @code{dawn-time} (default: @code{disabled}) (type: maybe-string) +@item @code{dawn-time} (type: maybe-string) Custom time for the transition from night to day in the morning---@code{"HH:MM"} format. When specified, solar elevation is not used to determine the daytime/nighttime period. -@item @code{dusk-time} (default: @code{disabled}) (type: maybe-string) +@item @code{dusk-time} (type: maybe-string) Likewise, custom time for the transition from day to night in the evening. -- 2.35.1