me/guix
Archived
1
0
Fork 0
Code Activity

doc: Follow the 'disabled -> *unspecified* configuration refactor.

Browse source 
* doc/guix.texi (Networking Services)
(Messaging Services)
(Telephony Services)
(File-Sharing Services)
(VPN Services)
(Power Management Services)
(Complex Configurations)
(Desktop Home Services): Remove mentions of the 'disabled symbol or
replace them by *unspecified*, depending on context.

Signed-off-by: Ludovic Courtès <ludo@gnu.org>
This commit is contained in:
Attila Lendvai 2022-05-17 13:39:30 +02:00 • committed by Ludovic Courtès
parent 8cb1a49a39
commit 713d140750
No known key found for this signature in database
GPG key ID: 090B11993D9AEBB5
1 changed files with 43 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

85
doc/guix.texi
View file

@ -19329,15 +19329,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 network. A specific port value can be provided by appending the
@code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but @code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but
any host can be specified here. It's also possible to disable 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"}. Defaults to @samp{"bootstrap.jami.net:4222"}.
@end deftypevr @end deftypevr
@deftypevr {@code{opendht-configuration} parameter} maybe-number port @deftypevr {@code{opendht-configuration} parameter} maybe-number port
The UDP port to bind to. When set to @code{'disabled}, an available The UDP port to bind to. When explicitly set to @code{*unspecified*},
port is automatically selected. an available port is automatically selected.
Defaults to @samp{4222}. Defaults to @samp{4222}.
@ -25090,7 +25091,7 @@ The available configuration parameters follow. Each parameter
definition is preceded by its type; for example, @samp{string-list foo} 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 indicates that the @code{foo} parameter should be specified as a list of
strings. Types starting with @code{maybe-} denote parameters that won't 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 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 have an old @code{prosody.cfg.lua} file that you want to port over from
@ -25704,7 +25705,7 @@ Whether to enable debug level messages.
@item @code{auto-answer?} (default: @code{#f}) (type: boolean) @item @code{auto-answer?} (default: @code{#f}) (type: boolean)
Whether to force automatic answer to incoming calls. 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 A list of Jami accounts to be (re-)provisioned every time the Jami
daemon service starts. When providing this field, the account daemon service starts. When providing this field, the account
directories under @file{/var/lib/jami/} are recreated every time the directories under @file{/var/lib/jami/} are recreated every time the
@ -25726,39 +25727,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 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. 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 The list of allowed contacts for the account, entered as their 40
characters long fingerprint. Messages or calls from accounts not in characters long fingerprint. Messages or calls from accounts not in
that list will be rejected. When unspecified, the configuration of the that list will be rejected. When left specified, the configuration of
account archive is used as-is with respect to contacts and public the account archive is used as-is with respect to contacts and public
inbound calls/messaging allowance, which typically defaults to allow any inbound calls/messaging allowance, which typically defaults to allow any
contact to communicate with the account. 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, The list of contacts that should have moderation privileges (to ban,
mute, etc. other users) in rendezvous conferences, entered as their 40 mute, etc. other users) in rendezvous conferences, entered as their 40
characters long fingerprint. When unspecified, the configuration of the characters long fingerprint. When left unspecified, the configuration
account archive is used as-is with respect to moderation, which of the account archive is used as-is with respect to moderation, which
typically defaults to allow anyone to moderate. 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 Whether the account should operate in the rendezvous mode. In this
mode, all the incoming audio/video calls are mixed into a conference. mode, all the incoming audio/video calls are mixed into a conference.
When left unspecified, the value from the account archive prevails. 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 Whether peer discovery should be enabled. Peer discovery is used to
discover other OpenDHT nodes on the local network, which can be useful discover other OpenDHT nodes on the local network, which can be useful
to maintain communication between devices on such network even when the to maintain communication between devices on such network even when the
connection to the the Internet has been lost. When left unspecified, connection to the the Internet has been lost. When left unspecified,
the value from the account archive prevails. 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 A list of hostnames or IPs pointing to OpenDHT nodes, that should be
used to initially join the OpenDHT network. When left unspecified, the used to initially join the OpenDHT network. When left unspecified, the
value from the account archive prevails. 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 The URI of the name server to use, that can be used to retrieve the
account fingerprint for a registered username. account fingerprint for a registered username.
@ -26392,8 +26393,8 @@ Defaults to @samp{prefer-encrypted-connections}.
@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm
The TCP congestion-control algorithm to use for peer connections, The TCP congestion-control algorithm to use for peer connections,
specified using a string recognized by the operating system in calls to specified using a string recognized by the operating system in calls to
@code{setsockopt} (or set to @code{disabled}, in which case the @code{setsockopt}. When left unspecified, the operating-system default
operating-system default is used). is used.
Note that on GNU/Linux systems, the kernel must be configured to allow 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; processes to use a congestion-control algorithm not in the default set;
@ -30021,7 +30022,7 @@ Defaults to @samp{tun}.
If you do not have some of these files (eg.@: you use a username and 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 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 @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string ca
The certificate authority to check connections against. The certificate authority to check connections against.
@ -30095,7 +30096,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 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. would be added to the store and readable by any user.
Defaults to @samp{'disabled}.
@end deftypevr @end deftypevr
@deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage? @deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage?
@ -30176,7 +30176,7 @@ Defaults to @samp{tun}.
If you do not have some of these files (eg.@: you use a username and 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 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 @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string ca
The certificate authority to check connections against. The certificate authority to check connections against.
@ -30975,10 +30975,10 @@ content by adding a valid @code{tlp-configuration}:
@end deffn @end deffn
Each parameter definition is preceded by its type; for example, Each parameter definition is preceded by its type; for example,
@samp{boolean foo} indicates that the @code{foo} parameter @samp{boolean foo} indicates that the @code{foo} parameter should be
should be specified as a boolean. Types starting with specified as a boolean. Types starting with @code{maybe-} denote
@code{maybe-} denote parameters that won't show up in TLP config file parameters that won't show up in TLP config file when their value is
when their value is @code{'disabled}. left unset, or is explicitly set to the @code{*unspecified*} value.
@c The following documentation was initially generated by @c The following documentation was initially generated by
@c (generate-tlp-documentation) in (gnu services pm). Manually maintained @c (generate-tlp-documentation) in (gnu services pm). Manually maintained
@ -38573,15 +38573,16 @@ macro which is a shorthand of this.
@deffn {Scheme Syntax} define-maybe @var{type} @deffn {Scheme Syntax} define-maybe @var{type}
Sometimes a field should not be serialized if the user doesn’t specify a 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 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 define a ``maybe type''; if the value of a maybe type is left unset, or
@code{disabled}, it will not be serialized. is set to the @code{*unspecified*} value, then it will not be
serialized.
When defining a ``maybe type'', the corresponding serializer for the When defining a ``maybe type'', the corresponding serializer for the
regular type will be used by default. For example, a field of type regular type will be used by default. For example, a field of type
@code{maybe-string} will be serialized using the @code{serialize-string} @code{maybe-string} will be serialized using the @code{serialize-string}
procedure by default, you can of course change this by specifying a procedure by default, you can of course change this by specifying a
custom serializer procedure. Likewise, the type of the value would have 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 @lisp
(define-maybe string) (define-maybe string)
@ -38591,9 +38592,9 @@ to be a string, unless it is set to the @code{disabled} symbol.
(define-configuration baz-configuration (define-configuration baz-configuration
(name (name
;; Nothing will be serialized by default. If set to a string, the ;; If set to a string, the `serialize-string' procedure will be used
;; `serialize-string' procedure will be used to serialize the string. ;; to serialize the string. Otherwise this field is not serialized.
(maybe-string 'disabled) maybe-string ; equivalent to (maybe-string *unspecified*)
"The name of this module.")) "The name of this module."))
@end lisp @end lisp
@ -38610,7 +38611,7 @@ serializer name by using the @code{prefix} literal.
There is also the @code{no-serialization} literal, which when set means There is also the @code{no-serialization} literal, which when set means
that no serializer will be defined for the ``maybe type'', regardless of 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{define-maybe/no-serialization} is a shorthand for specifying the
@code{no-serialization} literal. @code{no-serialization} literal.
@ -38619,7 +38620,7 @@ its value is @code{disabled} or not.
(define-configuration/no-serialization test-configuration (define-configuration/no-serialization test-configuration
(mode (mode
(maybe-symbol 'disabled) maybe-symbol
"Docstring.")) "Docstring."))
@end lisp @end lisp
@end deffn @end deffn
@ -38751,10 +38752,10 @@ Below is an example of a record type created using
"The name of the contact." "The name of the contact."
serialize-contact-name) serialize-contact-name)
(phone-number (phone-number
(maybe-integer 'disabled) maybe-integer
"The person's phone number.") "The person's phone number.")
(email (email
(maybe-string 'disabled) maybe-string
"The person's email address.") "The person's email address.")
(married? (married?
(boolean) (boolean)
@ -39478,24 +39479,24 @@ Daytime color temperature (kelvins).
@item @code{nighttime-temperature} (default: @code{4500}) (type: integer) @item @code{nighttime-temperature} (default: @code{4500}) (type: integer)
Nighttime color temperature (kelvins). Nighttime color temperature (kelvins).
@item @code{daytime-brightness} (default: @code{disabled}) (type: maybe-inexact-number) @item @code{daytime-brightness} (type: maybe-inexact-number)
Daytime screen brightness, between 0.1 and 1.0. Daytime screen brightness, between 0.1 and 1.0, or left unspecified.
@item @code{nighttime-brightness} (default: @code{disabled}) (type: maybe-inexact-number) @item @code{nighttime-brightness} (type: maybe-inexact-number)
Nighttime screen brightness, between 0.1 and 1.0. 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}. 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}. 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 Custom time for the transition from night to day in the
morning---@code{"HH:MM"} format. When specified, solar elevation is not morning---@code{"HH:MM"} format. When specified, solar elevation is not
used to determine the daytime/nighttime period. 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 Likewise, custom time for the transition from day to night in the
evening. evening.