[PATCH 0/3][DOCUMENTATION] Use @defvar for Scheme variables.

  • Done
  • quality assurance status badge
Details
2 participants
  • Ludovic Courtès
  • Bruno Victal
Owner
unassigned
Submitted by
Bruno Victal
Severity
normal
B
B
Bruno Victal wrote on 7 Jan 2023 20:39
(address . guix-patches@gnu.org)(name . Bruno Victal)(address . mirai@makinata.eu)
cover.1673119747.git.mirai@makinata.eu
It is implicit that most of the variables that are mentioned in
the Guix manual are Scheme variables, this patch-set normalizes
the @-commands used to describe them.

Bruno Victal (3):
doc: Fix incorrect use of @defvar.
doc: Use @defvar instead of @defvr for Scheme variables.
doc: Substitute @deffn usage with @defvar for Scheme variables.

doc/guix.texi | 1108 ++++++++++++++++++++++++-------------------------
1 file changed, 554 insertions(+), 554 deletions(-)


base-commit: 7f9672660733c0e1bda2bf4761cc0ae443ece824
--
2.38.1
B
B
Bruno Victal wrote on 7 Jan 2023 20:41
[PATCH 1/3] doc: Fix incorrect use of @defvar.
(address . 60634@debbugs.gnu.org)(name . Bruno Victal)(address . mirai@makinata.eu)
2294b578df97f9160a6a365664cbd01800f64a52.1673119748.git.mirai@makinata.eu
* doc/guix.texi (Monitoring Services) (VNC Services)
(Samba Services) (Game Services) (PAM Mount Service)
(Guix Services): Fix incorrect use of @defvar.
---
doc/guix.texi | 28 ++++++++++++++--------------
1 file changed, 14 insertions(+), 14 deletions(-)

Toggle diff (132 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 293c3016aa..7a86501e60 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -28123,7 +28123,7 @@ Monitoring Services
Darkstat is a packet sniffer that captures network traffic, calculates
statistics about usage, and serves reports over HTTP.
-@defvar {Scheme Variable} darkstat-service-type
+@defvar darkstat-service-type
This is the service type for the
@uref{https://unix4lyfe.org/darkstat/, darkstat}
service, its value must be a @code{darkstat-configuration} record as in
@@ -28168,7 +28168,7 @@ Monitoring Services
This service should be deployed on all physical nodes and virtual machines,
where monitoring these statistics is desirable.
-@defvar {Scheme variable} prometheus-node-exporter-service-type
+@defvar prometheus-node-exporter-service-type
This is the service type for the
@uref{https://github.com/prometheus/node_exporter/, prometheus-node-exporter}
service, its value must be a @code{prometheus-node-exporter-configuration}.
@@ -28213,7 +28213,7 @@ Monitoring Services
data sources are supported, such as @ref{prometheus-node-exporter,
Prometheus Node Exporter}).
-@defvar {Scheme variable} zabbix-server-service-type
+@defvar zabbix-server-service-type
This is the service type for the Zabbix server service. Its value must be a
@code{zabbix-server-configuration} record, shown below.
@end defvar
@@ -28299,7 +28299,7 @@ Monitoring Services
@uref{https://www.zabbix.com/documentation/current/en/manual/config/items/userparameters,
@dfn{user parameters}}.
-@defvar {Scheme variable} zabbix-agent-service-type
+@defvar zabbix-agent-service-type
This is the service type for the Zabbix agent service. Its value must be a
@code{zabbix-agent-configuration} record, shown below.
@end defvar
@@ -28376,7 +28376,7 @@ Monitoring Services
extending the @ref{PHP-FPM} and @ref{NGINX} services with the configuration
necessary for loading the Zabbix user interface.
-@defvar {Scheme variable} zabbix-front-end-service-type
+@defvar zabbix-front-end-service-type
This is the service type for the Zabbix web frontend. Its value must be a
@code{zabbix-front-end-configuration} record, shown below.
@end defvar
@@ -31396,7 +31396,7 @@ VNC Services
can run on headless servers. The Xvnc implementations provided by the
@code{tigervnc-server} and @code{turbovnc} aim to be fast and efficient.
-@defvar {Scheme Variable} xvnc-service-type
+@defvar xvnc-service-type
The @code{xvnc-server-type} service can be configured via the
@code{xvnc-configuration} record, documented below. A second virtual
@@ -32098,7 +32098,7 @@ Samba Services
hosts in an heterougenious network with different types of Computer
systems.
-@defvar {Scheme variable} samba-service-type
+@defvar samba-service-type
The service type to enable the samba services @code{samba}, @code{nmbd},
@code{smbd} and @code{winbindd}. By default this service type does not
@@ -36266,7 +36266,7 @@ Game Services
based tactical strategy game, with several single player campaigns, and
multiplayer games (both networked and local).
-@defvar {Scheme Variable} wesnothd-service-type
+@defvar wesnothd-service-type
Service type for the wesnothd service. Its value must be a
@code{wesnothd-configuration} object. To run wesnothd in the default
configuration, instantiate it as:
@@ -36297,7 +36297,7 @@ PAM Mount Service
users to mount volumes when they log in. It should be able to mount any
volume format supported by the system.
-@defvar {Scheme Variable} pam-mount-service-type
+@defvar pam-mount-service-type
Service type for PAM Mount support.
@end defvar
@@ -36392,7 +36392,7 @@ Guix Services
Coordinator, but the Guix service uses a custom Guile script instead, to
provide better integration with G-expressions used in the configuration.
-@defvar {Scheme Variable} guix-build-coordinator-service-type
+@defvar guix-build-coordinator-service-type
Service type for the Guix Build Coordinator. Its value must be a
@code{guix-build-coordinator-configuration} object.
@end defvar
@@ -36441,7 +36441,7 @@ Guix Services
@end table
@end deftp
-@defvar {Scheme Variable} guix-build-coordinator-agent-service-type
+@defvar guix-build-coordinator-agent-service-type
Service type for a Guix Build Coordinator agent. Its value must be a
@code{guix-build-coordinator-agent-configuration} object.
@end defvar
@@ -36567,7 +36567,7 @@ Guix Services
that may be useful when building derivations contained within an
instance of the Guix Data Service.
-@defvar {Scheme Variable} guix-build-coordinator-queue-builds-service-type
+@defvar guix-build-coordinator-queue-builds-service-type
Service type for the
guix-build-coordinator-queue-builds-from-guix-data-service script. Its
value must be a @code{guix-build-coordinator-queue-builds-configuration}
@@ -36620,7 +36620,7 @@ Guix Services
The data is stored in a PostgreSQL database, and available through a web
interface.
-@defvar {Scheme Variable} guix-data-service-type
+@defvar guix-data-service-type
Service type for the Guix Data Service. Its value must be a
@code{guix-data-service-configuration} object. The service optionally
extends the getmail service, as the guix-commits mailing list is used to
@@ -36668,7 +36668,7 @@ Guix Services
The @uref{https://git.cbaines.net/guix/nar-herder/about/,Nar Herder} is
a utility for managing a collection of nars.
-@defvar {Scheme Variable} nar-herder-type
+@defvar nar-herder-type
Service type for the Guix Data Service. Its value must be a
@code{nar-herder-configuration} object. The service optionally
extends the getmail service, as the guix-commits mailing list is used to
--
2.38.1
B
B
Bruno Victal wrote on 7 Jan 2023 20:41
[PATCH 3/3] doc: Substitute @deffn usage with @defvar for Scheme variables.
(address . 60634@debbugs.gnu.org)(name . Bruno Victal)(address . mirai@makinata.eu)
75b4bc8ae345581d94eb571663bf7d0a219f48cd.1673119748.git.mirai@makinata.eu
* doc/guix.texi (Base Services) (Networking Setup)
(Networking Services) (Printing Services) (Desktop Services)
(Sound Services) (Database Services) (Mail Services) (Messaging Services)
(File-Sharing Services) (Web Services) (DNS Services)
(Power Management Services) (Virtualization Services) (Linux Services)
(Miscellaneous Services): Substitute @deffn usage with @defvar for Scheme variables.
---
doc/guix.texi | 168 +++++++++++++++++++++++++-------------------------
1 file changed, 84 insertions(+), 84 deletions(-)

Toggle diff (568 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 4aeed8a76b..26851f7566 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -18651,7 +18651,7 @@ Base Services
@end deftp
@anchor{guix-publish-service-type}
-@deffn {Scheme Variable} guix-publish-service-type
+@defvar guix-publish-service-type
This is the service type for @command{guix publish} (@pxref{Invoking
guix publish}). Its value must be a @code{guix-publish-configuration}
object, as described below.
@@ -18659,7 +18659,7 @@ Base Services
This assumes that @file{/etc/guix} already contains a signing key pair as
created by @command{guix archive --generate-key} (@pxref{Invoking guix
archive}). If that is not the case, the service will fail to start.
-@end deffn
+@end defvar
@deftp {Data Type} guix-publish-configuration
Data type representing the configuration of the @code{guix publish}
@@ -19692,7 +19692,7 @@ Networking Setup
@end deftp
@cindex Connman
-@deffn {Scheme Variable} connman-service-type
+@defvar connman-service-type
This is the service type to run @url{https://01.org/connman,Connman},
a network connection manager.
@@ -19706,7 +19706,7 @@ Networking Setup
@end lisp
See below for details about @code{connman-configuration}.
-@end deffn
+@end defvar
@deftp {Data Type} connman-configuration
Data Type representing the configuration of connman.
@@ -20132,7 +20132,7 @@ Networking Services
@end deftp
@cindex inetd
-@deffn {Scheme variable} inetd-service-type
+@defvar inetd-service-type
This service runs the @command{inetd} (@pxref{inetd invocation,,,
inetutils, GNU Inetutils}) daemon. @command{inetd} listens for
connections on internet sockets, and lazily starts the specified server
@@ -20169,7 +20169,7 @@ Networking Services
@end lisp
See below for more details about @code{inetd-configuration}.
-@end deffn
+@end defvar
@deftp {Data Type} inetd-configuration
Data type representing the configuration of @command{inetd}.
@@ -20370,7 +20370,7 @@ Networking Services
so anyone (or just yourself) can download existing files or upload new
files.
-@deffn {Scheme Variable} rsync-service-type
+@defvar rsync-service-type
This is the service type for the @uref{https://rsync.samba.org, rsync} daemon,
The value for this service type is a
@command{rsync-configuration} record as in this example:
@@ -20390,7 +20390,7 @@ Networking Services
@end lisp
See below for details about @code{rsync-configuration}.
-@end deffn
+@end defvar
@deftp {Data Type} rsync-configuration
Data type representing the configuration for @code{rsync-service}.
@@ -20476,7 +20476,7 @@ Networking Services
computers and want to sync them in real time, safely protected from
prying eyes.
-@deffn {Scheme Variable} syncthing-service-type
+@defvar syncthing-service-type
This is the service type for the @uref{https://syncthing.net/,
syncthing} daemon, The value for this service type is a
@command{syncthing-configuration} record as in this example:
@@ -20516,7 +20516,7 @@ Networking Services
@end table
@end deftp
-@end deffn
+@end defvar
Furthermore, @code{(gnu services ssh)} provides the following services.
@cindex SSH
@@ -20560,7 +20560,7 @@ Networking Services
@cindex SSH
@cindex SSH server
-@deffn {Scheme Variable} openssh-service-type
+@defvar openssh-service-type
This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
shell daemon, @command{sshd}. Its value must be an
@code{openssh-configuration} record as in this example:
@@ -20585,7 +20585,7 @@ Networking Services
(const `(("charlie"
,(local-file "charlie.pub")))))
@end lisp
-@end deffn
+@end defvar
@deftp {Data Type} openssh-configuration
This is the configuration record for OpenSSH's @command{sshd}.
@@ -20792,7 +20792,7 @@ Networking Services
@end deftp
@cindex AutoSSH
-@deffn {Scheme Variable} autossh-service-type
+@defvar autossh-service-type
This is the type for the @uref{https://www.harding.motd.ca/autossh,
AutoSSH} program that runs a copy of @command{ssh} and monitors it,
restarting it as necessary should it die or stop passing traffic.
@@ -20816,7 +20816,7 @@ Networking Services
(user "pino")
(ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net"))))
@end lisp
-@end deffn
+@end defvar
@deftp {Data Type} autossh-configuration
This data type represents the configuration of an AutoSSH service.
@@ -20872,7 +20872,7 @@ Networking Services
@end deftp
@cindex WebSSH
-@deffn {Scheme Variable} webssh-service-type
+@defvar webssh-service-type
This is the type for the @uref{https://webssh.huashengdun.org/, WebSSH}
program that runs a web SSH client. WebSSH can be run manually from the
command-line by passing arguments to the binary @command{wssh} from the
@@ -20909,7 +20909,7 @@ Networking Services
(body '("root /var/www;")))
(nginx-server-configuration-locations %webssh-configuration-nginx))))))))
@end lisp
-@end deffn
+@end defvar
@deftp {Data Type} webssh-configuration
Data type representing the configuration for @code{webssh-service}.
@@ -21026,11 +21026,11 @@ Networking Services
@end table
@end deftp
-@deffn {Scheme Variable} openvswitch-service-type
+@defvar openvswitch-service-type
This is the type of the @uref{https://www.openvswitch.org, Open vSwitch}
service, whose value should be an @code{openvswitch-configuration}
object.
-@end deffn
+@end defvar
@deftp {Data Type} openvswitch-configuration
Data type representing the configuration of Open vSwitch, a multilayer
@@ -21210,7 +21210,7 @@ Networking Services
@end deftp
@cindex keepalived
-@deffn {Scheme Variable} keepalived-service-type
+@defvar keepalived-service-type
This is the type for the @uref{https://www.keepalived.org/, Keepalived}
routing software, @command{keepalived}. Its value must be an
@code{keepalived-configuration} record as in this example for master
@@ -21259,7 +21259,7 @@ Networking Services
@}
@}
@end example
-@end deffn
+@end defvar
@node Unattended Upgrades
@subsection Unattended Upgrades
@@ -22005,14 +22005,14 @@ Printing Services
for the CUPS printing service. To add printer support to a Guix
system, add a @code{cups-service} to the operating system definition:
-@deffn {Scheme Variable} cups-service-type
+@defvar cups-service-type
The service type for the CUPS print server. Its value should be a valid
CUPS configuration (see below). To use the default settings, simply
write:
@lisp
(service cups-service-type)
@end lisp
-@end deffn
+@end defvar
The CUPS configuration controls the basic things about your CUPS
installation: what interfaces it listens on, what to do if a print job
@@ -22962,7 +22962,7 @@ Desktop Services
@end table
@end deftp
-@deffn {Scheme Variable} mate-desktop-service-type
+@defvar mate-desktop-service-type
This is the type of the service that runs the @uref{https://mate-desktop.org/,
MATE desktop environment}. Its value is a @code{mate-desktop-configuration}
object (see below).
@@ -22970,7 +22970,7 @@ Desktop Services
This service adds the @code{mate} package to the system
profile, and extends polkit with the actions from
@code{mate-settings-daemon}.
-@end deffn
+@end defvar
@deftp {Data Type} mate-desktop-configuration
Configuration record for the MATE desktop environment.
@@ -22981,14 +22981,14 @@ Desktop Services
@end table
@end deftp
-@deffn {Scheme Variable} lxqt-desktop-service-type
+@defvar lxqt-desktop-service-type
This is the type of the service that runs the @uref{https://lxqt-project.org,
LXQt desktop environment}. Its value is a @code{lxqt-desktop-configuration}
object (see below).
This service adds the @code{lxqt} package to the system
profile.
-@end deffn
+@end defvar
@deftp {Data Type} lxqt-desktop-configuration
Configuration record for the LXQt desktop environment.
@@ -22999,10 +22999,10 @@ Desktop Services
@end table
@end deftp
-@deffn {Scheme Variable} enlightenment-desktop-service-type
+@defvar enlightenment-desktop-service-type
Return a service that adds the @code{enlightenment} package to the system
profile, and extends dbus with actions from @code{efl}.
-@end deffn
+@end defvar
@deftp {Data Type} enlightenment-desktop-service-configuration
@table @asis
@@ -23245,14 +23245,14 @@ Desktop Services
@code{ntfs-3g} installed system-wide.
@end deffn
-@deffn {Scheme Variable} colord-service-type
+@defvar colord-service-type
This is the type of the service that runs @command{colord}, a system
service with a D-Bus
interface to manage the color profiles of input and output devices such as
screens and scanners. It is notably used by the GNOME Color Manager graphical
tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web
site} for more information.
-@end deffn
+@end defvar
@cindex scanner access
@defvar sane-service-type
@@ -23340,7 +23340,7 @@ Desktop Services
bluetooth keyboard or mouse.
@end deffn
-@deffn {Scheme Variable} bluetooth-service-type
+@defvar bluetooth-service-type
This is the type for the @uref{https://bluez.org/, Linux Bluetooth Protocol
Stack} (BlueZ) system, which generates the @file{/etc/bluetooth/main.conf}
configuration file. The value for this type is a @command{bluetooth-configuration}
@@ -23351,7 +23351,7 @@ Desktop Services
@end lisp
See below for details about @code{bluetooth-configuration}.
-@end deffn
+@end defvar
@deftp {Data Type} bluetooth-configuration
Data type representing the configuration for @code{bluetooth-service}.
@@ -23894,7 +23894,7 @@ Sound Services
Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the
preferred ALSA output driver.
-@deffn {Scheme Variable} alsa-service-type
+@defvar alsa-service-type
This is the type for the @uref{https://alsa-project.org/, Advanced Linux Sound
Architecture} (ALSA) system, which generates the @file{/etc/asound.conf}
configuration file. The value for this type is a @command{alsa-configuration}
@@ -23905,7 +23905,7 @@ Sound Services
@end lisp
See below for details about @code{alsa-configuration}.
-@end deffn
+@end defvar
@deftp {Data Type} alsa-configuration
Data type representing the configuration for @code{alsa-service}.
@@ -23963,7 +23963,7 @@ Sound Services
See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
details.
-@deffn {Scheme Variable} pulseaudio-service-type
+@defvar pulseaudio-service-type
This is the type for the @uref{https://www.pulseaudio.org/, PulseAudio}
sound server. It exists to allow system overrides of the default settings
via @code{pulseaudio-configuration}, see below.
@@ -23982,7 +23982,7 @@ Sound Services
without a @code{pulseaudio} package, consider enabling it through the
@code{alsa-service-type} above.
@end quotation
-@end deffn
+@end defvar
@deftp {Data Type} pulseaudio-configuration
Data type representing the configuration for @code{pulseaudio-service}.
@@ -24039,7 +24039,7 @@ Sound Services
@end deftp
-@deffn {Scheme Variable} ladspa-service-type
+@defvar ladspa-service-type
This service sets the @var{LADSPA_PATH} variable, so that programs, which
respect it, e.g. PulseAudio, can load LADSPA plugins.
@@ -24054,7 +24054,7 @@ Sound Services
See @uref{http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html} for the
details.
-@end deffn
+@end defvar
@node Database Services
@subsection Database Services
@@ -24225,7 +24225,7 @@ Database Services
@end table
@end deftp
-@deffn {Scheme Variable} postgresql-role-service-type
+@defvar postgresql-role-service-type
This service allows to create PostgreSQL roles and databases after
PostgreSQL service start. Here is an example of its use.
@@ -24247,7 +24247,7 @@ Database Services
(name "alice")
(create-database? #t))))
@end lisp
-@end deffn
+@end defvar
@deftp {Data Type} postgresql-role
PostgreSQL manages database access permissions using the concept of
@@ -25810,7 +25810,7 @@ Mail Services
@subsubheading OpenSMTPD Service
-@deffn {Scheme Variable} opensmtpd-service-type
+@defvar opensmtpd-service-type
This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD}
service, whose value should be an @code{opensmtpd-configuration} object
as in this example:
@@ -25820,7 +25820,7 @@ Mail Services
(opensmtpd-configuration
(config-file (local-file "./my-smtpd.conf"))))
@end lisp
-@end deffn
+@end defvar
@deftp {Data Type} opensmtpd-configuration
Data type representing the configuration of opensmtpd.
@@ -25854,7 +25854,7 @@ Mail Services
@cindex MTA (mail transfer agent)
@cindex SMTP
-@deffn {Scheme Variable} exim-service-type
+@defvar exim-service-type
This is the type of the @uref{https://exim.org, Exim} mail transfer
agent (MTA), whose value should be an @code{exim-configuration} object
as in this example:
@@ -25864,7 +25864,7 @@ Mail Services
(exim-configuration
(config-file (local-file "./my-exim.conf"))))
@end lisp
-@end deffn
+@end defvar
In order to use an @code{exim-service-type} service you must also have a
@code{mail-aliases-service-type} service present in your
@@ -25892,10 +25892,10 @@ Mail Services
@cindex IMAP
@cindex POP
-@deffn {Scheme Variable} getmail-service-type
+@defvar getmail-service-type
This is the type of the @uref{http://pyropus.ca/software/getmail/, Getmail}
mail retriever, whose value should be an @code{getmail-configuration}.
-@end deffn
+@end defvar
Available @code{getmail-configuration} fields are:
@@ -26183,7 +26183,7 @@ Mail Services
@cindex email aliases
@cindex aliases, for email addresses
-@deffn {Scheme Variable} mail-aliases-service-type
+@defvar mail-aliases-service-type
This is the type of the service which provides @code{/etc/aliases},
specifying how to deliver mail to users on this system.
@@ -26192,7 +26192,7 @@ Mail Services
'(("postmaster" "bob")
("bob" "bob@@example.com" "bob@@example2.com")))
@end lisp
-@end deffn
+@end defvar
The configuration for a @code{mail-aliases-service-type} service is an
association list denoting how to deliver mail that comes to this
@@ -26209,7 +26209,7 @@ Mail Services
@subsubheading GNU Mailutils IMAP4 Daemon
@cindex GNU Mailutils IMAP4 Daemon
-@deffn {Scheme Variable} imap4d-service-type
+@defvar imap4d-service-type
This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,,
mailutils, GNU Mailutils Manual}), whose value should be an
@code{imap4d-configuration} object as in this example:
@@ -26219,7 +26219,7 @@ Mail Services
(imap4d-configuration
(config-file (local-file "imap4d.conf"))))
@end lisp
-@end deffn
+@end defvar
@deftp {Data Type} imap4d-configuration
Data type representing the configuration of @command{imap4d}.
@@ -26240,10 +26240,10 @@ Mail Services
@cindex CalDAV
@cindex CardDAV
-@deffn {Scheme Variable} radicale-service-type
+@defvar radicale-service-type
This is the type of the @uref{https://radicale.org, Radicale} CalDAV/CardDAV
server whose value should be a @code{radicale-configuration}.
-@end deffn
+@end defvar
@deftp {Data Type} radicale-configuration
Data type representing the configuration of @command{radicale}.
@@ -26272,7 +26272,7 @@ Messaging Services
@subsubheading Prosody Service
-@deffn {Scheme Variable} prosody-service-type
+@defvar prosody-service-type
This is the type for the @uref{https://prosody.im, Prosody XMPP
communication server}. Its value must be a @code{prosody-configuration}
record as in this example:
@@ -26295,7 +26295,7 @@ Messaging Services
See below for details about @code{prosody-configuration}.
-@end deffn
+@end defvar
By default, Prosody does not need much configuration. Only one
@code{virtualhosts} field is needed: it specifies the domain you wish
@@ -27224,7 +27224,7 @@ File-Sharing Services
system service, allowing users to share files via BitTorrent even when
they are not logged in.
-@deffn {Scheme Variable} transmission-daemon-service-type
+@defvar transmission-daemon-service-type
The service type for the Transmission Daemon BitTorrent client. Its
value must be a @code{transmission-daemon-configuration} object as in
this example:
@@ -27256,7 +27256,7 @@ File-Sharing Services
(alt-speed-time-end
(+ (* 60 (+ 12 5)) 30)))) ; 5:30 pm
@end lisp
-@end deffn
+@end defvar
Once the service is started, users can interact with the daemon through
its Web interface (at @code{http://localhost:9091/}) or by using the
@@ -29229,7 +29229,7 @@ Web Services
@subsubheading Apache HTTP Server
-@deffn {Scheme Variable} httpd-service-type
+@defvar httpd-service-type
Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server
(@dfn{httpd}). The value for this service type is a
@code{httpd-configuration} record.
@@ -29257,7 +29257,7 @@ Web Services
"DocumentRoot /srv/http/www.example.com")
"\n")))))
@end lisp
-@end deffn
+@end defvar
The details for the @code{httpd-configuration}, @code{httpd-module},
@code{httpd-config-file} and @code{httpd-virtualhost} record types are
@@ -29412,7 +29412,7 @@ Web Services
@anchor{NGINX}
@subsubheading NGINX
-@deffn {Scheme Variable} nginx-service-type
+@defvar nginx-service-type
Service type for the @uref{https://nginx.org/,NGinx} web server. The
value for this service type is a @code{<nginx-configuration>} record.
@@ -29437,7 +29437,7 @@ Web Services
(root "/srv/http/extra-website")
(try-files (list "$uri" "$uri/index.html")))))
@end lisp
-@end deffn
+@end defvar
At startup, @command{nginx} has not yet read its configuration file, so
it uses a default file to log error messages. If it fails to load its
@@ -30325,7 +30325,7 @@ Web Services
The @uref{https://git.sr.ht/~sircmpwn/gmnisrv, gmnisrv} program is a
simple @uref{https://gemini.circumlunar.space/, Gemini} protocol server.
-@deffn {Scheme Variable} gmnisrv-service-type
+@defvar gmnisrv-service-type
This is the type of the gmnisrv service, whose value should be a
@code{gmnisrv-configuration} object, as in this example:
@@ -30334,7 +30334,7 @@ Web Services
(gmnisrv-configuration
(config-file (local-file "./my-gmnisrv.ini"))))
@end lisp
-@end deffn
+@end defvar
@deftp {Data Type} gmnisrv-configuration
Data type representing the configuration of gmnisrv.
@@ -30361,7 +30361,7 @@ Web Services
program is a simple @uref{https://gemini.circumlunar.space/, Gemini}
protocol server written in Rust.
-@deffn {Scheme Variable} agate-service-type
+@defvar agate-service-type
This is the type of the agate service, whose value should be an
@code{agate-service-type} object, as in this example:
@@ -30389,7 +30389,7 @@ Web Services
name, and then point the Agate configuration towards the path of the
generated key and certificate.
-@end deffn
+@end defvar
@deftp {Data Type} agate-configuration
Data type representing the configuration of Agate.
@@ -30673,7 +30673,7 @@ DNS Services
%base-services)))
@end lisp
-@deffn {Scheme Variable} knot-service-type
+@defvar knot-service-type
This is the type for the Knot DNS server.
Knot DNS is an authoritative DNS server, meaning that it can serve multiple
@@ -30685,7 +30685
This message was truncated. Download the full message here.
B
B
Bruno Victal wrote on 7 Jan 2023 20:41
[PATCH 2/3] doc: Use @defvar instead of @defvr for Scheme variables.
(address . 60634@debbugs.gnu.org)(name . Bruno Victal)(address . mirai@makinata.eu)
15e0bb4bc2eecb63389316806aff4e1c51f2c62e.1673119748.git.mirai@makinata.eu
* doc/guix.texi (Build Systems) (Search Paths) (The Store)
(The Store Monad) (File Systems) (Mapped Devices) (User Accounts)
(Locales) (Base Services) (Scheduled Job Execution) (Log Rotation)
(Networking Setup) (Networking Services) (Unattended Upgrades)
(X Window) (Desktop Services) (Database Services) (Messaging Services)
(Kerberos Services) (Web Services) (Certificate Services) (VPN Services)
(Network File System) (Samba Services) (Power Management Services)
(Audio Services) (Virtualization Services) (Linux Services) (Hurd Services)
(Miscellaneous Services) (Setuid Programs) (Name Service Switch)
(Initial RAM Disk) (Service Reference) (Shepherd Services)
(Essential Home Services) (Mcron Home Service)
(Power Management Home Services) (Shepherd Home Service) (Secure Shell)
(Desktop Home Services) (Guix Home Services) (Supported Platforms)
(Instantiate an Image) (image-type Reference): Use @defvar instead of @defvr for Scheme variables.
---
doc/guix.texi | 912 +++++++++++++++++++++++++-------------------------
1 file changed, 456 insertions(+), 456 deletions(-)

Toggle diff (476 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 7a86501e60..4aeed8a76b 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -8637,7 +8637,7 @@ Build Systems
standard build procedure for GNU and many other packages. It
is provided by the @code{(guix build-system gnu)} module.
-@defvr {Scheme Variable} gnu-build-system
+@defvar gnu-build-system
@code{gnu-build-system} represents the GNU Build System, and variants
thereof (@pxref{Configuration, configuration and makefile conventions,,
standards, GNU Coding Standards}).
@@ -8728,7 +8728,7 @@ Build Systems
@end table
Most other build systems support these keyword arguments.
-@end defvr
+@end defvar
Other @code{<build-system>} objects are defined to support other
conventions and tools used by free software packages. They inherit most
@@ -8736,7 +8736,7 @@ Build Systems
implicitly added to the build process, and in the list of phases
executed. Some of these build systems are listed below.
-@defvr {Scheme Variable} ant-build-system
+@defvar ant-build-system
This variable is exported by @code{(guix build-system ant)}. It
implements the build procedure for Java packages that can be built with
@url{https://ant.apache.org/, Ant build tool}.
@@ -8764,9 +8764,9 @@ Build Systems
that should be run during the @code{build} phase. By default the
``jar'' task will be run.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} android-ndk-build-system
+@defvar android-ndk-build-system
@cindex Android distribution
@cindex Android NDK build system
This variable is exported by @code{(guix build-system android-ndk)}. It
@@ -8783,11 +8783,11 @@ Build Systems
For the time being, cross-compilation is not supported - so right now
the libraries and header files are assumed to be host tools.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} asdf-build-system/source
-@defvrx {Scheme Variable} asdf-build-system/sbcl
-@defvrx {Scheme Variable} asdf-build-system/ecl
+@defvar asdf-build-system/source
+@defvarx asdf-build-system/sbcl
+@defvarx asdf-build-system/ecl
These variables, exported by @code{(guix build-system asdf)}, implement
build procedures for Common Lisp packages using
@@ -8831,9 +8831,9 @@ Build Systems
@code{#:asd-systems} parameter can be used to specify the list of system
names.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} cargo-build-system
+@defvar cargo-build-system
@cindex Rust programming language
@cindex Cargo (Rust build system)
This variable is exported by @code{(guix build-system cargo)}. It
@@ -8862,9 +8862,9 @@ Build Systems
the binaries defined by the crate. Unless @code{install-source? #f} is
defined it will also install a source crate repository of itself and unpacked
sources, to ease in future hacking on rust packages.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} chicken-build-system
+@defvar chicken-build-system
This variable is exported by @code{(guix build-system chicken)}. It
builds @uref{https://call-cc.org/, CHICKEN Scheme} modules, also called
``eggs'' or ``extensions''. CHICKEN generates C source code, which then
@@ -8886,9 +8886,9 @@ Build Systems
Egg dependencies must be defined in @code{propagated-inputs}, not @code{inputs}
because CHICKEN doesn't embed absolute references in compiled eggs.
Test dependencies should go to @code{native-inputs}, as usual.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} copy-build-system
+@defvar copy-build-system
This variable is exported by @code{(guix build-system copy)}. It
supports builds of simple packages that don't require much compiling,
mostly just moving files around.
@@ -8947,12 +8947,12 @@ Build Systems
@item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to
@file{share/my-app/file}.
@end itemize
-@end defvr
+@end defvar
@cindex Clojure (programming language)
@cindex simple Clojure build system
-@defvr {Scheme Variable} clojure-build-system
+@defvar clojure-build-system
This variable is exported by @code{(guix build-system clojure)}. It implements
a simple build procedure for @uref{https://clojure.org/, Clojure} packages
using plain old @code{compile} in Clojure. Cross-compilation is not supported
@@ -9005,9 +9005,9 @@ Build Systems
@code{#:doc-regex} parameter. All files (recursively) inside the documentation
directories specified in @code{#:doc-dirs} are installed as well.
@end table
-@end defvr
+@end defvar
-@defvr {Scheme Variable} cmake-build-system
+@defvar cmake-build-system
This variable is exported by @code{(guix build-system cmake)}. It
implements the build procedure for packages using the
@url{https://www.cmake.org, CMake build tool}.
@@ -9022,9 +9022,9 @@ Build Systems
it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
debugging information''), which roughly means that code is compiled with
@code{-O2 -g}, as is the case for Autoconf-based packages by default.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} dune-build-system
+@defvar dune-build-system
This variable is exported by @code{(guix build-system dune)}. It
supports builds of packages using @uref{https://dune.build/, Dune}, a build
tool for the OCaml programming language. It is implemented as an extension
@@ -9049,9 +9049,9 @@ Build Systems
only one of them. This is equivalent to passing the @code{-p} argument to
@code{dune}.
-@end defvr
+@end defvar
-@defvr {Scheme variable} elm-build-system
+@defvar elm-build-system
This variable is exported by @code{(guix build-system elm)}. It implements a
build procedure for @url{https://elm-lang.org, Elm} packages similar to
@samp{elm install}.
@@ -9103,9 +9103,9 @@ Build Systems
Node.js-based @url{https://github.com/rtfeldman/node-test-runner,
@command{elm-test}} runner has been packaged for Guix yet.
@end itemize
-@end defvr
+@end defvar
-@defvr {Scheme Variable} go-build-system
+@defvar go-build-system
This variable is exported by @code{(guix build-system go)}. It
implements a build procedure for Go packages using the standard
@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,
@@ -9133,9 +9133,9 @@ Build Systems
operating system. The combinations known to Go can be found
@url{https://golang.org/doc/install/source#environment,
in their documentation}.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} glib-or-gtk-build-system
+@defvar glib-or-gtk-build-system
This variable is exported by @code{(guix build-system glib-or-gtk)}. It
is intended for use with packages making use of GLib or GTK+.
@@ -9169,9 +9169,9 @@ Build Systems
@end table
Both phases are executed after the @code{install} phase.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} guile-build-system
+@defvar guile-build-system
This build system is for Guile packages that consist exclusively of Scheme
code and that are so lean that they don't even have a makefile, let alone a
@file{configure} script. It compiles Scheme code using @command{guild
@@ -9184,9 +9184,9 @@ Build Systems
Packages built with @code{guile-build-system} must provide a Guile package in
their @code{native-inputs} field.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} julia-build-system
+@defvar julia-build-system
This variable is exported by @code{(guix build-system julia)}. It
implements the build procedure used by @uref{https://julialang.org/,
julia} packages, which essentially is similar to running @samp{julia -e
@@ -9229,9 +9229,9 @@ Build Systems
require this file to be created, too. It is internally done if the
arguments @code{#:julia-package-name} and @code{#:julia-package-uuid}
are provided.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} maven-build-system
+@defvar maven-build-system
This variable is exported by @code{(guix build-system maven)}. It implements
a build procedure for @uref{https://maven.apache.org, Maven} packages. Maven
is a dependency and lifecycle management tool for Java. A user of Maven
@@ -9271,17 +9271,17 @@ Build Systems
the build, with the same format as the @code{inputs} fields of the package
declaration. Its default value is @code{(default-maven-plugins)} which is
also exported.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} minetest-mod-build-system
+@defvar minetest-mod-build-system
This variable is exported by @code{(guix build-system minetest)}. It
implements a build procedure for @uref{https://www.minetest.net, Minetest}
mods, which consists of copying Lua code, images and other resources to
the location Minetest searches for mods. The build system also minimises
PNG images and verifies that Minetest can load the mod without errors.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} minify-build-system
+@defvar minify-build-system
This variable is exported by @code{(guix build-system minify)}. It
implements a minification procedure for simple JavaScript packages.
@@ -9294,9 +9294,9 @@ Build Systems
When the input JavaScript files are not all located in the @file{src}
directory, the parameter @code{#:javascript-files} can be used to
specify a list of file names to feed to the minifier.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} ocaml-build-system
+@defvar ocaml-build-system
This variable is exported by @code{(guix build-system ocaml)}. It implements
a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
of choosing the correct set of commands to run for each package. OCaml
@@ -9337,9 +9337,9 @@ Build Systems
libraries cannot be found and we use @env{CAML_LD_LIBRARY_PATH}. This
variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
@file{.so} libraries should be installed.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} python-build-system
+@defvar python-build-system
This variable is exported by @code{(guix build-system python)}. It
implements the more or less standard build procedure used by Python
packages, which consists in running @code{python setup.py build} and
@@ -9366,9 +9366,9 @@ Build Systems
include a Python package as only a part of the software, and thus want to
combine the phases of @code{python-build-system} with another build system.
Python bindings are a common usecase.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} pyproject-build-system
+@defvar pyproject-build-system
This is a variable exported by @code{guix build-system pyproject}. It
is based on @var{python-build-system}, and adds support for
@file{pyproject.toml} and @url{https://peps.python.org/pep-0517/, PEP 517}.
@@ -9397,9 +9397,9 @@ Build Systems
Eventually this build system will be deprecated and merged back into
@var{python-build-system}, probably some time in 2024.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} perl-build-system
+@defvar perl-build-system
This variable is exported by @code{(guix build-system perl)}. It
implements the standard build procedure for Perl packages, which either
consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
@@ -9417,9 +9417,9 @@ Build Systems
@code{#:module-build-flags} parameter, respectively.
Which Perl package is used can be specified with @code{#:perl}.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} renpy-build-system
+@defvar renpy-build-system
This variable is exported by @code{(guix build-system renpy)}. It implements
the more or less standard build procedure used by Ren'py games, which consists
of loading @code{#:game} once, thereby creating bytecode for it.
@@ -9430,9 +9430,9 @@ Build Systems
Which Ren'py package is used can be specified with @code{#:renpy}.
Games can also be installed in outputs other than ``out'' by using
@code{#:output}.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} qt-build-system
+@defvar qt-build-system
This variable is exported by @code{(guix build-system qt)}. It
is intended for use with applications using Qt or KDE.
@@ -9466,9 +9466,9 @@ Build Systems
This phase is added after the @code{install} phase.
@end table
-@end defvr
+@end defvar
-@defvr {Scheme Variable} r-build-system
+@defvar r-build-system
This variable is exported by @code{(guix build-system r)}. It
implements the build procedure used by @uref{https://r-project.org, R}
packages, which essentially is little more than running @samp{R CMD
@@ -9476,9 +9476,9 @@ Build Systems
@env{R_LIBS_SITE} contains the paths to all R package inputs. Tests are
run after installation using the R function
@code{tools::testInstalledPackage}.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} rakudo-build-system
+@defvar rakudo-build-system
This variable is exported by @code{(guix build-system rakudo)}. It
implements the build procedure used by @uref{https://rakudo.org/,
Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the
@@ -9494,9 +9494,9 @@ Build Systems
Which perl6-zef package used for tests and installing can be specified
with @code{#:zef} or removed by passing @code{#f} to the
@code{with-zef?} parameter.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} rebar-build-system
+@defvar rebar-build-system
This variable is exported by @code{(guix build-system rebar)}. It
implements a build procedure around @uref{https://rebar3.org,rebar3},
a build system for programs written in the Erlang language.
@@ -9537,9 +9537,9 @@ Build Systems
other profile specified with @code{#:install-profile}.
@end table
-@end defvr
+@end defvar
-@defvr {Scheme Variable} texlive-build-system
+@defvar texlive-build-system
This variable is exported by @code{(guix build-system texlive)}. It is
used to build TeX packages in batch mode with a specified engine. The
build system sets the @env{TEXINPUTS} variable to find all TeX source
@@ -9556,9 +9556,9 @@ Build Systems
The @code{#:tex-directory} parameter tells the build system where to
install the built files under the texmf tree.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} ruby-build-system
+@defvar ruby-build-system
This variable is exported by @code{(guix build-system ruby)}. It
implements the RubyGems build procedure used by Ruby packages, which
involves running @code{gem build} followed by @code{gem install}.
@@ -9574,9 +9574,9 @@ Build Systems
Which Ruby package is used can be specified with the @code{#:ruby}
parameter. A list of additional flags to be passed to the @command{gem}
command can be specified with the @code{#:gem-flags} parameter.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} waf-build-system
+@defvar waf-build-system
This variable is exported by @code{(guix build-system waf)}. It
implements a build procedure around the @code{waf} script. The common
phases---@code{configure}, @code{build}, and @code{install}---are
@@ -9586,9 +9586,9 @@ Build Systems
The @code{waf} script is executed by the Python interpreter. Which
Python package is used to run the script can be specified with the
@code{#:python} parameter.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} scons-build-system
+@defvar scons-build-system
This variable is exported by @code{(guix build-system scons)}. It
implements the build procedure used by the SCons software construction
tool. This build system runs @code{scons} to build the package,
@@ -9601,9 +9601,9 @@ Build Systems
@code{#:install-targets} respectively. The version of Python used to
run SCons can be specified by selecting the appropriate SCons package
with the @code{#:scons} parameter.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} haskell-build-system
+@defvar haskell-build-system
This variable is exported by @code{(guix build-system haskell)}. It
implements the Cabal build procedure used by Haskell packages, which
involves running @code{runhaskell Setup.hs configure
@@ -9620,9 +9620,9 @@ Build Systems
Which Haskell compiler is used can be specified with the @code{#:haskell}
parameter which defaults to @code{ghc}.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} dub-build-system
+@defvar dub-build-system
This variable is exported by @code{(guix build-system dub)}. It
implements the Dub build procedure used by D packages, which
involves running @code{dub build} and @code{dub run}.
@@ -9630,10 +9630,10 @@ Build Systems
Which D compiler is used can be specified with the @code{#:ldc}
parameter which defaults to @code{ldc}.
-@end defvr
+@end defvar
@anchor{emacs-build-system}
-@defvr {Scheme Variable} emacs-build-system
+@defvar emacs-build-system
This variable is exported by @code{(guix build-system emacs)}. It
implements an installation procedure similar to the packaging system
of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
@@ -9643,17 +9643,17 @@ Build Systems
packaging system, the Info documentation files are moved to the standard
documentation directory and the @file{dir} file is deleted. The Elisp
package files are installed directly under @file{share/emacs/site-lisp}.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} font-build-system
+@defvar font-build-system
This variable is exported by @code{(guix build-system font)}. It
implements an installation procedure for font packages where upstream
provides pre-compiled TrueType, OpenType, etc.@: font files that merely
need to be copied into place. It copies font files to standard
locations in the output directory.
-@end defvr
+@end defvar
-@defvr {Scheme Variable} meson-build-system
+@defvar meson-build-system
This variable is exported by @code{(guix build-system meson)}. It
implements the build procedure for packages that use
@url{https://mesonbuild.com, Meson} as their build system.
@@ -9707,9 +9707,9 @@ Build Systems
This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
@end table
-@end defvr
+@end defvar
-@defvr {Scheme Variable} linux-module-build-system
+@defvar linux-module-build-system
@code{linux-module-build-system} allows building Linux kernel modules.
@cindex build phases
@@ -9734,9 +9734,9 @@ Build Systems
It is possible and useful to specify the Linux kernel to use for building
the module (in the @code{arguments} form of a package using the
@code{linux-module-build-system}, use the key @code{#:linux} to specify it).
-@end defvr
+@end defvar
-@defvr {Scheme Variable} node-build-system
+@defvar node-build-system
This variable is exported by @code{(guix build-system node)}. It
implements the build procedure used by @uref{https://nodejs.org,
Node.js}, which implements an approximation of the @code{npm install}
@@ -9745,23 +9745,23 @@ Build Systems
Which Node.js package is used to interpret the @code{npm} commands can
be specified with the @code{#:node} parameter which defaults to
@code{node}.
-@end defvr
+@end defvar
Lastly, for packages that do not need anything as sophisticated, a
``trivial'' build system is provided. It is trivial in the
This message was truncated. Download the full message here.
L
L
Ludovic Courtès wrote on 23 Jan 2023 23:55
Re: bug#60634: [PATCH 0/3][DOCUMENTATION] Use @defvar for Scheme variables.
(name . Bruno Victal)(address . mirai@makinata.eu)(address . 60634-done@debbugs.gnu.org)
877cxcyi74.fsf@gnu.org
Hi,

Bruno Victal <mirai@makinata.eu> skribis:

Toggle quote (4 lines)
> It is implicit that most of the variables that are mentioned in
> the Guix manual are Scheme variables, this patch-set normalizes
> the @-commands used to describe them.

Yes, that makes sense to me; pushed!

f912d5c740 doc: Substitute @deffn usage with @defvar for Scheme variables.
f88e855f9f doc: Use @defvar instead of @defvr for Scheme variables.
d2454e91b3 doc: Fix incorrect use of @defvar.

Now we’ll have to adjust to the new convention…

Thanks,
Ludo’.
Closed
?
Your comment

This issue is archived.

To comment on this conversation send an email to 60634@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 60634
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch