* [bug#62042] [PATCH 3/4] doc: Use @defun for procedures.
2023-03-08 1:19 [bug#62042] [PATCH 0/4] Harmonize @-commands used in doc/guix.texi Bruno Victal
2023-03-08 1:22 ` [bug#62042] [PATCH 1/4] doc: Fix incorrect @deffn usage for service-types Bruno Victal
2023-03-08 1:22 ` [bug#62042] [PATCH 2/4] doc: Fix incorrect @deffn usage for data types Bruno Victal
@ 2023-03-08 1:22 ` Bruno Victal
2023-03-08 1:22 ` [bug#62042] [PATCH 4/4] doc: Use @defmac and @defspec for macros Bruno Victal
2023-03-13 14:06 ` bug#62042: [PATCH 0/4] Harmonize @-commands used in doc/guix.texi Ludovic Courtès
4 siblings, 0 replies; 6+ messages in thread
From: Bruno Victal @ 2023-03-08 1:22 UTC (permalink / raw)
To: 62042; +Cc: Bruno Victal
* doc/guix.texi (Inferiors, Defining Packages, package Reference)
(origin Reference, Defining Package Variants, Writing Manifests)
(Build Utilities, Search Paths, The Store, Derivations, The Store Monad)
(G-Expressions, File Systems, Keyboard Layout, Base Services, X Window)
(Desktop Services, File-Sharing Services, Web Services, Virtualization Services)
(Version Control Services, Miscellaneous Services, Initial RAM Disk)
(Bootloader Configuration, Service Reference, Shepherd Services)
(Complex Configurations): Use @defun for procedures.
---
doc/guix.texi | 508 ++++++++++++++++++++++++--------------------------
1 file changed, 240 insertions(+), 268 deletions(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index bf294046db..ed9994a41b 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4958,60 +4958,57 @@ Inferiors
The @code{(guix inferior)} module provides the following procedures to open an
inferior:
-@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
- [#:cache-directory] [#:ttl]
+@defun inferior-for-channels channels [#:cache-directory] [#:ttl]
Return an inferior for @var{channels}, a list of channels. Use the cache at
@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
This procedure opens a new connection to the build daemon.
As a side effect, this procedure may build or substitute binaries for
@var{channels}, which can take time.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} open-inferior @var{directory} @
- [#:command "bin/guix"]
+@defun open-inferior directory [#:command "bin/guix"]
Open the inferior Guix in @var{directory}, running
@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if
the inferior could not be launched.
-@end deffn
+@end defun
@cindex inferior packages
The procedures listed below allow you to obtain and manipulate inferior
packages.
-@deffn {Scheme Procedure} inferior-packages @var{inferior}
+@defun inferior-packages inferior
Return the list of packages known to @var{inferior}.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
- [@var{version}]
+@defun lookup-inferior-packages inferior name [version]
Return the sorted list of inferior packages matching @var{name} in
@var{inferior}, with highest version numbers first. If @var{version} is true,
return only packages with a version number prefixed by @var{version}.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} inferior-package? @var{obj}
+@defun inferior-package? obj
Return true if @var{obj} is an inferior package.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} inferior-package-name @var{package}
-@deffnx {Scheme Procedure} inferior-package-version @var{package}
-@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
-@deffnx {Scheme Procedure} inferior-package-description @var{package}
-@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
-@deffnx {Scheme Procedure} inferior-package-location @var{package}
-@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
-@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
-@deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
+@defun inferior-package-name package
+@defunx inferior-package-version package
+@defunx inferior-package-synopsis package
+@defunx inferior-package-description package
+@defunx inferior-package-home-page package
+@defunx inferior-package-location package
+@defunx inferior-package-inputs package
+@defunx inferior-package-native-inputs package
+@defunx inferior-package-propagated-inputs package
+@defunx inferior-package-transitive-propagated-inputs package
+@defunx inferior-package-native-search-paths package
+@defunx inferior-package-transitive-native-search-paths package
+@defunx inferior-package-search-paths package
These procedures are the counterpart of package record accessors
(@pxref{package Reference}). Most of them work by querying the inferior
@var{package} comes from, so the inferior must still be live when you call
these procedures.
-@end deffn
+@end defun
Inferior packages can be used transparently like any other package or
file-like object in G-expressions (@pxref{G-Expressions}). They are also
@@ -7575,7 +7572,7 @@ Defining Packages
The build actions it prescribes may then be realized by using the
@code{build-derivations} procedure (@pxref{The Store}).
-@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
+@defun package-derivation store package [system]
Return the @code{<derivation>} object of @var{package} for @var{system}
(@pxref{Derivations}).
@@ -7584,22 +7581,21 @@ Defining Packages
@code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
must be a connection to the daemon, which operates on the store
(@pxref{The Store}).
-@end deffn
+@end defun
@noindent
@cindex cross-compilation
Similarly, it is possible to compute a derivation that cross-builds a
package for some other system:
-@deffn {Scheme Procedure} package-cross-derivation @var{store} @
- @var{package} @var{target} [@var{system}]
+@defun package-cross-derivation store package target [system]
Return the @code{<derivation>} object of @var{package} cross-built from
@var{system} to @var{target}.
@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"aarch64-linux-gnu"}
(@pxref{Specifying Target Triplets,,, autoconf, Autoconf}).
-@end deffn
+@end defun
Once you have package definitions, you can easily define @emph{variants}
of those packages. @xref{Defining Package Variants}, for more on that.
@@ -7810,10 +7806,10 @@ package Reference
The following helper procedures are provided to help deal with package
inputs.
-@deffn {Scheme Procedure} lookup-package-input @var{package} @var{name}
-@deffnx {Scheme Procedure} lookup-package-native-input @var{package} @var{name}
-@deffnx {Scheme Procedure} lookup-package-propagated-input @var{package} @var{name}
-@deffnx {Scheme Procedure} lookup-package-direct-input @var{package} @var{name}
+@defun lookup-package-input package name
+@defunx lookup-package-native-input package name
+@defunx lookup-package-propagated-input package name
+@defunx lookup-package-direct-input package name
Look up @var{name} among @var{package}'s inputs (or native, propagated,
or direct inputs). Return it if found, @code{#f} otherwise.
@@ -7829,7 +7825,7 @@ package Reference
In this example we obtain the @code{gmp} package that is among the
direct inputs of @code{coreutils}.
-@end deffn
+@end defun
@cindex development inputs, of a package
@cindex implicit inputs, of a package
@@ -7838,8 +7834,7 @@ package Reference
package is compiled. This is what the @code{package-development-inputs}
procedure returns.
-@deffn {Scheme Procedure} package-development-inputs @var{package} @
- [@var{system}] [#:target #f]
+@defun package-development-inputs package [system] [#:target #f]
Return the list of inputs required by @var{package} for development
purposes on @var{system}. When @var{target} is true, return the inputs
needed to cross-compile @var{package} from @var{system} to
@@ -7870,7 +7865,7 @@ package Reference
gzip, GCC, libc, Bash, and more. To visualize it, @command{guix graph
hello} would show you explicit inputs, whereas @command{guix graph -t
bag hello} would include implicit inputs (@pxref{Invoking guix graph}).
-@end deffn
+@end defun
Because packages are regular Scheme objects that capture a complete
dependency graph and associated build procedures, it is often useful to
@@ -7878,7 +7873,7 @@ package Reference
thereof according to some parameters. Below are a few examples.
@cindex tool chain, choosing a package's tool chain
-@deffn {Scheme Procedure} package-with-c-toolchain @var{package} @var{toolchain}
+@defun package-with-c-toolchain package toolchain
Return a variant of @var{package} that uses @var{toolchain} instead of
the default GNU C/C++ toolchain. @var{toolchain} must be a list of
inputs (label/package tuples) providing equivalent functionality, such
@@ -7899,7 +7894,7 @@ package Reference
procedure works by changing the build system of @var{package} so that it
pulls in @var{toolchain} instead of the defaults. @ref{Build Systems},
for more on build systems.
-@end deffn
+@end defun
@node origin Reference
@subsection @code{origin} Reference
@@ -8016,8 +8011,7 @@ origin Reference
download)} module provides the most common method, @code{url-fetch},
described below.
-@deffn {Scheme Procedure} url-fetch @var{url} @var{hash-algo} @var{hash} @
- [name] [#:executable? #f]
+@defun url-fetch url hash-algo hash [name] [#:executable? #f]
Return a fixed-output derivation that fetches data from @var{url} (a
string, or a list of strings denoting alternate URLs), which is expected
to have hash @var{hash} of type @var{hash-algo} (a symbol). By default,
@@ -8030,19 +8024,19 @@ origin Reference
Alternatively, when URL starts with @code{file://}, return the
corresponding file name in the store.
-@end deffn
+@end defun
Likewise, the @code{(guix git-download)} module defines the
@code{git-fetch} origin method, which fetches data from a Git version
control repository, and the @code{git-reference} data type to describe
the repository and revision to fetch.
-@deffn {Scheme Procedure} git-fetch @var{ref} @var{hash-algo} @var{hash}
+@defun git-fetch ref hash-algo hash
Return a fixed-output derivation that fetches @var{ref}, a
@code{<git-reference>} object. The output is expected to have recursive
hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
the file name, or a generic name if @code{#f}.
-@end deffn
+@end defun
@deftp {Data Type} git-reference
This data type represents a Git reference for @code{git-fetch} to
@@ -8085,13 +8079,12 @@ origin Reference
the @code{hg-fetch} origin method and @code{hg-reference} data type for
support of the Mercurial version control system.
-@deffn {Scheme Procedure} hg-fetch @var{ref} @var{hash-algo} @var{hash} @
- [name]
+@defun hg-fetch ref hash-algo hash [name]
Return a fixed-output derivation that fetches @var{ref}, a
@code{<hg-reference>} object. The output is expected to have recursive
hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
the file name, or a generic name if @code{#false}.
-@end deffn
+@end defun
@node Defining Package Variants
@section Defining Package Variants
@@ -8242,7 +8235,7 @@ Defining Package Variants
that directly maps to the more sophisticated package transformation
options (@pxref{Package Transformation Options}):
-@deffn {Scheme Procedure} options->transformation @var{opts}
+@defun options->transformation opts
Return a procedure that, when passed an object to build (package,
derivation, etc.), applies the transformations specified by @var{opts} and returns
the resulting objects. @var{opts} must be a list of symbol/string pairs such as:
@@ -8254,7 +8247,7 @@ Defining Package Variants
Each symbol names a transformation and the corresponding string is an argument
to that transformation.
-@end deffn
+@end defun
For instance, a manifest equivalent to this command:
@@ -8293,8 +8286,7 @@ Defining Package Variants
graph, is what the @code{package-input-rewriting} procedure in
@code{(guix packages)} implements.
-@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
- [@var{rewrite-name}] [#:deep? #t]
+@defun package-input-rewriting replacements [rewrite-name] [#:deep? #t]
Return a procedure that, when passed a package, replaces its direct and
indirect dependencies, including implicit inputs when @var{deep?} is
true, according to @var{replacements}. @var{replacements} is a list of
@@ -8303,7 +8295,7 @@ Defining Package Variants
Optionally, @var{rewrite-name} is a one-argument procedure that takes
the name of a package and returns its new name after rewrite.
-@end deffn
+@end defun
@noindent
Consider this example:
@@ -8328,14 +8320,14 @@ Defining Package Variants
The following variant of @code{package-input-rewriting} can match packages to
be replaced by name rather than by identity.
-@deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t]
+@defun package-input-rewriting/spec replacements [#:deep? #t]
Return a procedure that, given a package, applies the given
@var{replacements} to all the package graph, including implicit inputs
unless @var{deep?} is false. @var{replacements} is a list of
spec/procedures pair; each spec is a package specification such as
@code{"gcc"} or @code{"guile@@2"}, and each procedure takes a matching
package and returns a replacement for that package.
-@end deffn
+@end defun
The example above could be rewritten this way:
@@ -8353,12 +8345,12 @@ Defining Package Variants
@code{package-mapping}: it supports arbitrary changes to nodes in the
graph.
-@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}] [#:deep? #f]
+@defun package-mapping proc [cut?] [#:deep? #f]
Return a procedure that, given a package, applies @var{proc} to all the packages
depended on and returns the resulting package. The procedure stops recursion
when @var{cut?} returns true for a given package. When @var{deep?} is true, @var{proc} is
applied to implicit inputs as well.
-@end deffn
+@end defun
@node Writing Manifests
@section Writing Manifests
@@ -8563,15 +8555,14 @@ Writing Manifests
@end table
@end deftp
-@deffn {Scheme Procedure} concatenate-manifests @var{lst}
+@defun concatenate-manifests lst
Concatenate the manifests listed in @var{lst} and return the resulting
manifest.
-@end deffn
+@end defun
@c TODO: <manifest-pattern>, manifest-lookup, manifest-remove, etc.
-@deffn {Scheme Procedure} package->manifest-entry @var{package} @
- [@var{output}] [#:properties]
+@defun package->manifest-entry package [output] [#:properties]
Return a manifest entry for the @var{output} of package @var{package},
where @var{output} defaults to @code{"out"}, and with the given
@var{properties}. By default @var{properties} is the empty list or, if
@@ -8589,9 +8580,9 @@ Writing Manifests
(manifest (list (package->manifest-entry git)
(package->manifest-entry git "send-email")))
@end lisp
-@end deffn
+@end defun
-@deffn {Scheme Procedure} packages->manifest @var{packages}
+@defun packages->manifest packages
Return a list of manifest entries, one for each item listed in
@var{packages}. Elements of @var{packages} can be either package
objects or package/string tuples denoting a specific output of a
@@ -8605,11 +8596,10 @@ Writing Manifests
(packages->manifest (list git `(,git "send-email")))
@end lisp
-@end deffn
+@end defun
@anchor{package-development-manifest}
-@deffn {Scheme Procedure} package->development-manifest @var{package} @
- [@var{system}] [#:target]
+@defun package->development-manifest package [system] [#:target]
Return a manifest for the @dfn{development inputs} of @var{package} for
@var{system}, optionally when cross-compiling to @var{target}.
Development inputs include both explicit and implicit inputs of
@@ -8637,7 +8627,7 @@ Writing Manifests
(GCC), the many supporting libraries (Boost, GLib, GTK, etc.), and a
couple of additional development tools---these are the dependencies
@command{guix show inkscape} lists.
-@end deffn
+@end defun
@c TODO: Move (gnu packages) interface to a section of its own.
@@ -8645,7 +8635,7 @@ Writing Manifests
to build manifests. In particular, it lets you look up packages by
name---see below.
-@deffn {Scheme Procedure} specifications->manifest @var{specs}
+@defun specifications->manifest specs
Given @var{specs}, a list of specifications such as @code{"emacs@@25.2"}
or @code{"guile:debug"}, return a manifest. Specs have the format that
command-line tools such as @command{guix install} and @command{guix
@@ -8662,7 +8652,7 @@ Writing Manifests
the right set of modules, and referring to the right variables.
Instead, we directly refer to packages in the same way as on the command
line, which can often be more convenient.
-@end deffn
+@end defun
@c TODO: specifications->package, etc.
@@ -10114,54 +10104,54 @@ Build Utilities
This section documents procedures that deal with store file names.
-@deffn {Scheme Procedure} %store-directory
+@defun %store-directory
Return the directory name of the store.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} store-file-name? @var{file}
+@defun store-file-name? file
Return true if @var{file} is in the store.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} strip-store-file-name @var{file}
+@defun strip-store-file-name file
Strip the @file{/gnu/store} and hash from @var{file}, a store file name.
The result is typically a @code{"@var{package}-@var{version}"} string.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} package-name->name+version @var{name}
+@defun package-name->name+version name
Given @var{name}, a package name like @code{"foo-0.9.1b"}, return two
values: @code{"foo"} and @code{"0.9.1b"}. When the version part is
unavailable, @var{name} and @code{#f} are returned. The first hyphen
followed by a digit is considered to introduce the version part.
-@end deffn
+@end defun
@subsection File Types
The procedures below deal with files and file types.
-@deffn {Scheme Procedure} directory-exists? @var{dir}
+@defun directory-exists? dir
Return @code{#t} if @var{dir} exists and is a directory.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} executable-file? @var{file}
+@defun executable-file? file
Return @code{#t} if @var{file} exists and is executable.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} symbolic-link? @var{file}
+@defun symbolic-link? file
Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink'').
-@end deffn
+@end defun
-@deffn {Scheme Procedure} elf-file? @var{file}
-@deffnx {Scheme Procedure} ar-file? @var{file}
-@deffnx {Scheme Procedure} gzip-file? @var{file}
+@defun elf-file? file
+@defunx ar-file? file
+@defunx gzip-file? file
Return @code{#t} if @var{file} is, respectively, an ELF file, an
@code{ar} archive (such as a @file{.a} static library), or a gzip file.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} reset-gzip-timestamp @var{file} [#:keep-mtime? #t]
+@defun reset-gzip-timestamp file [#:keep-mtime? #t]
If @var{file} is a gzip file, reset its embedded timestamp (as with
@command{gzip --no-name}) and return true. Otherwise return @code{#f}.
When @var{keep-mtime?} is true, preserve @var{file}'s modification time.
-@end deffn
+@end defun
@subsection File Manipulation
@@ -10182,20 +10172,20 @@ Build Utilities
exception.
@end deffn
-@deffn {Scheme Procedure} mkdir-p @var{dir}
+@defun mkdir-p dir
Create directory @var{dir} and all its ancestors.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} install-file @var{file} @var{directory}
+@defun install-file file directory
Create @var{directory} if it does not exist and copy @var{file} in there
under the same name.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} make-file-writable @var{file}
+@defun make-file-writable file
Make @var{file} writable for its owner.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} copy-recursively @var{source} @var{destination} @
+@defun copy-recursively source destination @
[#:log (current-output-port)] [#:follow-symlinks? #f] @
[#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t]
Copy @var{source} directory to @var{destination}. Follow symlinks if
@@ -10204,14 +10194,13 @@ Build Utilities
keep the modification time of the files in @var{source} on those of
@var{destination}. When @var{keep-permissions?} is true, preserve file
permissions. Write verbose output to the @var{log} port.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} delete-file-recursively @var{dir} @
- [#:follow-mounts? #f]
+@defun delete-file-recursively dir [#:follow-mounts? #f]
Delete @var{dir} recursively, like @command{rm -rf}, without following
symlinks. Don't follow mount points either, unless @var{follow-mounts?}
is true. Report but ignore errors.
-@end deffn
+@end defun
@deffn {Scheme Syntax} substitute* @var{file} @
((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{}
@@ -10247,12 +10236,12 @@ Build Utilities
@cindex file, searching
This section documents procedures to search and filter files.
-@deffn {Scheme Procedure} file-name-predicate @var{regexp}
+@defun file-name-predicate regexp
Return a predicate that returns true when passed a file name whose base
name matches @var{regexp}.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} find-files @var{dir} [@var{pred}] @
+@defun find-files dir [pred] @
[#:stat lstat] [#:directories? #f] [#:fail-on-error? #f]
Return the lexicographically sorted list of files under @var{dir} for
which @var{pred} returns true. @var{pred} is passed two arguments: the
@@ -10263,7 +10252,7 @@ Build Utilities
that symlinks are not followed. If @var{directories?} is true, then
directories will also be included. If @var{fail-on-error?} is true,
raise an exception upon error.
-@end deffn
+@end defun
Here are a few examples where we assume that the current directory is
the root of the Guix source tree:
@@ -10282,13 +10271,13 @@ Build Utilities
@result{} ("./libformat.a" "./libstore.a" @dots{})
@end lisp
-@deffn {Scheme Procedure} which @var{program}
+@defun which program
Return the complete file name for @var{program} as found in
@code{$PATH}, or @code{#f} if @var{program} could not be found.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} search-input-file @var{inputs} @var{name}
-@deffnx {Scheme Procedure} search-input-directory @var{inputs} @var{name}
+@defun search-input-file inputs name
+@defunx search-input-directory inputs name
Return the complete file name for @var{name} as found in @var{inputs};
@code{search-input-file} searches for a regular file and
@code{search-input-directory} searches for a directory. If @var{name}
@@ -10297,7 +10286,7 @@ Build Utilities
Here, @var{inputs} must be an association list like @code{inputs} and
@code{native-inputs} as available to build phases (@pxref{Build
Phases}).
-@end deffn
+@end defun
Here is a (simplified) example of how @code{search-input-file} is used
in a build phase of the @code{wireguard-tools} package:
@@ -10320,7 +10309,7 @@ Build Utilities
essentially convenient wrappers around Guile's @code{system*}
(@pxref{Processes, @code{system*},, guile, GNU Guile Reference Manual}).
-@deffn {Scheme Procedure} invoke @var{program} @var{args}@dots{}
+@defun invoke program args@dots{}
Invoke @var{program} with the given @var{args}. Raise an
@code{&invoke-error} exception if the exit code is non-zero; otherwise
return @code{#t}.
@@ -10328,21 +10317,21 @@ Build Utilities
The advantage compared to @code{system*} is that you do not need to
check the return value. This reduces boilerplate in shell-script-like
snippets for instance in package build phases.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} invoke-error? @var{c}
+@defun invoke-error? c
Return true if @var{c} is an @code{&invoke-error} condition.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} invoke-error-program @var{c}
-@deffnx {Scheme Procedure} invoke-error-arguments @var{c}
-@deffnx {Scheme Procedure} invoke-error-exit-status @var{c}
-@deffnx {Scheme Procedure} invoke-error-term-signal @var{c}
-@deffnx {Scheme Procedure} invoke-error-stop-signal @var{c}
+@defun invoke-error-program c
+@defunx invoke-error-arguments c
+@defunx invoke-error-exit-status c
+@defunx invoke-error-term-signal c
+@defunx invoke-error-stop-signal c
Access specific fields of @var{c}, an @code{&invoke-error} condition.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} report-invoke-error @var{c} [@var{port}]
+@defun report-invoke-error c [port]
Report to @var{port} (by default the current error port) about @var{c},
an @code{&invoke-error} condition, in a human-friendly way.
@@ -10358,9 +10347,9 @@ Build Utilities
@print{} command "date" "--imaginary-option" failed with status 1
@end lisp
-@end deffn
+@end defun
-@deffn {Scheme Procedure} invoke/quiet @var{program} @var{args}@dots{}
+@defun invoke/quiet program args@dots{}
Invoke @var{program} with @var{args} and capture @var{program}'s
standard output and standard error. If @var{program} succeeds, print
nothing and return the unspecified value; otherwise, raise a
@@ -10384,7 +10373,7 @@ Build Utilities
date: unrecognized option '--imaginary-option'
Try 'date --help' for more information.
@end lisp
-@end deffn
+@end defun
@subsection Build Phases
@@ -10494,8 +10483,7 @@ Build Utilities
To ease that task, the @code{(guix build utils)} module provides a
couple of helpers to wrap commands.
-@deffn {Scheme Procedure} wrap-program @var{program} @
- [#:sh @var{sh}] [#:rest @var{variables}]
+@defun wrap-program program [#:sh sh] [#:rest variables]
Make a wrapper for @var{program}. @var{variables} should look like this:
@lisp
@@ -10527,10 +10515,9 @@ Build Utilities
If @var{program} has previously been wrapped by @code{wrap-program}, the
wrapper is extended with definitions for @var{variables}. If it is not,
@var{sh} will be used as the interpreter.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} wrap-script @var{program} @
- [#:guile @var{guile}] [#:rest @var{variables}]
+@defun wrap-script program [#:guile guile] [#:rest variables]
Wrap the script @var{program} such that @var{variables} are set first.
The format of @var{variables} is the same as in the @code{wrap-program}
procedure. This procedure differs from @code{wrap-program} in that it
@@ -10543,7 +10530,7 @@ Build Utilities
Note that this procedure can only be used once per file as Guile scripts are
not supported.
-@end deffn
+@end defun
@node Search Paths
@section Search Paths
@@ -10732,13 +10719,12 @@ Search Paths
directories on the other hand in a set of environment variable
definitions? That's the job of @code{evaluate-search-paths}.
-@deffn {Scheme Procedure} evaluate-search-paths @var{search-paths} @
- @var{directories} [@var{getenv}]
+@defun evaluate-search-paths search-paths directories [getenv]
Evaluate @var{search-paths}, a list of search-path specifications, for
@var{directories}, a list of directory names, and return a list of
specification/value pairs. Use @var{getenv} to determine the current
settings and report only settings not already effective.
-@end deffn
+@end defun
The @code{(guix profiles)} provides a higher-level helper procedure,
@code{load-profile}, that sets the environment variables of a profile.
@@ -10842,7 +10828,7 @@ The Store
@end quotation
@end defvr
-@deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t]
+@defun open-connection [uri] [#:reserve-space? #t]
Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When
@var{reserve-space?} is true, instruct it to reserve a little bit of
extra space on the file system so that the garbage collector can still
@@ -10850,11 +10836,11 @@ The Store
@var{file} defaults to @code{%default-socket-path}, which is the normal
location given the options that were passed to @command{configure}.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} close-connection @var{server}
+@defun close-connection server
Close the connection to @var{server}.
-@end deffn
+@end defun
@defvar current-build-output-port
This variable is bound to a SRFI-39 parameter, which refers to the port
@@ -10864,8 +10850,8 @@ The Store
Procedures that make RPCs all take a server object as their first
argument.
-@deffn {Scheme Procedure} valid-path? @var{server} @var{path}
@cindex invalid store items
+@defun valid-path? server path
Return @code{#t} when @var{path} designates a valid store item and
@code{#f} otherwise (an invalid item may exist on disk but still be
invalid, for instance because it is the result of an aborted or failed
@@ -10873,20 +10859,19 @@ The Store
A @code{&store-protocol-error} condition is raised if @var{path} is not
prefixed by the store directory (@file{/gnu/store}).
-@end deffn
+@end defun
-@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
+@defun add-text-to-store server name text [references]
Add @var{text} under file @var{name} in the store, and return its store
path. @var{references} is the list of store paths referred to by the
resulting store path.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} build-derivations @var{store} @var{derivations} @
- [@var{mode}]
+@defun build-derivations store derivations [mode]
Build @var{derivations}, a list of @code{<derivation>} objects, @file{.drv}
file names, or derivation/output pairs, using the specified
@var{mode}---@code{(build-mode normal)} by default.
-@end deffn
+@end defun
Note that the @code{(guix monads)} module provides a monad as well as
monadic versions of the above procedures, with the goal of making it
@@ -10960,8 +10945,8 @@ Derivations
otherwise manipulate derivations. The lowest-level primitive to create
a derivation is the @code{derivation} procedure:
-@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
- @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
+@defun derivation store name builder args @
+ [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
[#:system (%current-system)] [#:references-graphs #f] @
[#:allowed-references #f] [#:disallowed-references #f] @
@@ -11006,7 +10991,7 @@ Derivations
@var{properties} must be an association list describing ``properties'' of the
derivation. It is kept as-is, uninterpreted, in the derivation.
-@end deffn
+@end defun
@noindent
Here's an example with a shell script as its builder, assuming
@@ -11039,8 +11024,7 @@ Derivations
@code{build-expression->derivation}, documented below. This procedure
is now deprecated in favor of the much nicer @code{gexp->derivation}.
-@deffn {Scheme Procedure} build-expression->derivation @var{store} @
- @var{name} @var{exp} @
+@defun build-expression->derivation store name exp @
[#:system (%current-system)] [#:inputs '()] @
[#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
@@ -11072,7 +11056,7 @@ Derivations
@var{references-graphs}, @var{allowed-references},
@var{disallowed-references}, @var{local-build?}, and
@var{substitutable?}.
-@end deffn
+@end defun
@noindent
Here's an example of a single-output derivation that creates a directory
@@ -11327,10 +11311,10 @@ The Store Monad
The state is assumed to be a list.
@end deffn
-@deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
+@defun run-with-state mval [state]
Run monadic value @var{mval} starting with @var{state} as the initial
state. Return two values: the resulting value, and the resulting state.
-@end deffn
+@end defun
The main interface to the store monad, provided by the @code{(guix
store)} module, is as follows.
@@ -11343,10 +11327,11 @@ The Store Monad
passing it to the @code{run-with-store} procedure (see below).
@end defvar
-@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
+@defun run-with-store store mval @
+ [#:guile-for-build] [#:system (%current-system)]
Run @var{mval}, a monadic value in the store monad, in @var{store}, an
open store connection.
-@end deffn
+@end defun
@deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
Return as a monadic value the absolute file name in the store of the file
@@ -11690,9 +11675,9 @@ G-Expressions
@var{body}@dots{}.
@end deffn
-@deffn {Scheme Procedure} gexp? @var{obj}
+@defun gexp? obj
Return @code{#t} if @var{obj} is a G-expression.
-@end deffn
+@end defun
G-expressions are meant to be written to disk, either as code building
some derivation, or as plain files in the store. The monadic procedures
@@ -11779,8 +11764,7 @@ G-Expressions
@code{plain-file} can be used similarly; it differs in that the file
content is directly passed as a string.
-@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
- [#:recursive? #f] [#:select? (const #t)]
+@defun local-file file [name] [#:recursive? #f] [#:select? (const #t)]
Return an object representing local file @var{file} to add to the store;
this object can be used in a gexp. If @var{file} is a literal string
denoting a relative file name, it is looked up relative to the source
@@ -11800,24 +11784,23 @@ G-Expressions
This is the declarative counterpart of the @code{interned-file} monadic
procedure (@pxref{The Store Monad, @code{interned-file}}).
-@end deffn
+@end defun
-@deffn {Scheme Procedure} plain-file @var{name} @var{content}
+@defun plain-file name content
Return an object representing a text file called @var{name} with the given
@var{content} (a string or a bytevector) to be added to the store.
This is the declarative counterpart of @code{text-file}.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
- [#:local-build? #t] [#:options '()]
+@defun computed-file name gexp [#:local-build? #t] [#:options '()]
Return an object representing the store item @var{name}, a file or
directory computed by @var{gexp}. When @var{local-build?} is true (the
default), the derivation is built locally. @var{options} is a list of
additional arguments to pass to @code{gexp->derivation}.
This is the declarative counterpart of @code{gexp->derivation}.
-@end deffn
+@end defun
@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
[#:guile (default-guile)] [#:module-path %load-path] @
@@ -11848,14 +11831,13 @@ G-Expressions
@end example
@end deffn
-@deffn {Scheme Procedure} program-file @var{name} @var{exp} @
- [#:guile #f] [#:module-path %load-path]
+@defun program-file name exp [#:guile #f] [#:module-path %load-path]
Return an object representing the executable store item @var{name} that
runs @var{gexp}. @var{guile} is the Guile package used to execute that
script. Imported modules of @var{gexp} are looked up in @var{module-path}.
This is the declarative counterpart of @code{gexp->script}.
-@end deffn
+@end defun
@deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
[#:set-load-path? #t] [#:module-path %load-path] @
@@ -11874,13 +11856,12 @@ G-Expressions
or a subset thereof.
@end deffn
-@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} @
- [#:splice? #f] [#:set-load-path? #t]
+@defun scheme-file name exp [#:splice? #f] [#:set-load-path? #t]
Return an object representing the Scheme file @var{name} that contains
@var{exp}.
This is the declarative counterpart of @code{gexp->file}.
-@end deffn
+@end defun
@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
Return as a monadic value a derivation that builds a text file
@@ -11908,7 +11889,7 @@ G-Expressions
preventing them from being garbage-collected during its lifetime.
@end deffn
-@deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
+@defun mixed-text-file name text @dots{}
Return an object representing store file @var{name} containing
@var{text}. @var{text} is a sequence of strings and file-like objects,
as in:
@@ -11919,9 +11900,9 @@ G-Expressions
@end lisp
This is the declarative counterpart of @code{text-file*}.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} file-union @var{name} @var{files}
+@defun file-union name files
Return a @code{<computed-file>} that builds a directory containing all of @var{files}.
Each item in @var{files} must be a two-element list where the first element is the
file name to use in the new directory, and the second element is a gexp
@@ -11936,9 +11917,9 @@ G-Expressions
@end lisp
This yields an @code{etc} directory containing these two files.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} directory-union @var{name} @var{things}
+@defun directory-union name things
Return a directory that is the union of @var{things}, where @var{things} is a list of
file-like objects denoting directories. For example:
@@ -11947,9 +11928,9 @@ G-Expressions
@end lisp
yields a directory that is the union of the @code{guile} and @code{emacs} packages.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
+@defun file-append obj suffix @dots{}
Return a file-like object that expands to the concatenation of @var{obj}
and @var{suffix}, where @var{obj} is a lowerable object and each
@var{suffix} is a string.
@@ -11974,7 +11955,7 @@ G-Expressions
resulting script contains the absolute file name as a string, whereas in
the second case, the resulting script contains a @code{(string-append
@dots{})} expression to construct the file name @emph{at run time}.
-@end deffn
+@end defun
@deffn {Scheme Syntax} let-system @var{system} @var{body}@dots{}
@deffnx {Scheme Syntax} let-system (@var{system} @var{target}) @var{body}@dots{}
@@ -12041,7 +12022,7 @@ G-Expressions
has an associated gexp compiler, such as a @code{<package>}.
@end deffn
-@deffn {Procedure} gexp->approximate-sexp @var{gexp}
+@defun gexp->approximate-sexp gexp
Sometimes, it may be useful to convert a G-exp into a S-exp. For
example, some linters (@pxref{Invoking guix lint}) peek into the build
phases of a package to detect potential problems. This conversion can
@@ -12049,7 +12030,7 @@ G-Expressions
in the process. More specifically, lowerable objects will be silently
replaced with some arbitrary object -- currently the list
@code{(*approximate*)}, but this may change.
-@end deffn
+@end defun
@node Invoking guix repl
@section Invoking @command{guix repl}
@@ -16865,7 +16846,7 @@ File Systems
@end table
@end deftp
-@deffn {Scheme Procedure} file-system-label @var{str}
+@defun file-system-label str
This procedure returns an opaque file system label from @var{str}, a
string:
@@ -16876,7 +16857,7 @@ File Systems
File system labels are used to refer to file systems by label rather
than by device name. See above for examples.
-@end deffn
+@end defun
The @code{(gnu system file-systems)} exports the following useful
variables.
@@ -16927,7 +16908,7 @@ File Systems
The @code{(gnu system uuid)} module provides tools to deal with file
system ``unique identifiers'' (UUIDs).
-@deffn {Scheme Procedure} uuid @var{str} [@var{type}]
+@defun uuid str [type]
Return an opaque UUID (unique identifier) object of the given @var{type}
(a symbol) by parsing @var{str} (a string):
@@ -16944,7 +16925,7 @@ File Systems
UUIDs are another way to unambiguously refer to file systems in
operating system configuration. See the examples above.
-@end deffn
+@end defun
@node Btrfs file system
@@ -17607,14 +17588,13 @@ Keyboard Layout
list of additional options. In most cases the layout name is all you care
about.
-@deffn {Scheme Procedure} keyboard-layout @var{name} [@var{variant}] @
- [#:model] [#:options '()]
+@defun keyboard-layout name [variant] [#:model] [#:options '()]
Return a new keyboard layout with the given @var{name} and @var{variant}.
@var{name} must be a string such as @code{"fr"}; @var{variant} must be a
string such as @code{"bepo"} or @code{"nodeadkeys"}. See the
@code{xkeyboard-config} package for valid options.
-@end deffn
+@end defun
Here are a few examples:
@@ -18006,7 +17986,7 @@ Base Services
(see below).
@end defvar
-@deffn {Scheme Procedure} extra-special-file @var{file} @var{target}
+@defun extra-special-file file target
Use @var{target} as the ``special file'' @var{file}.
For example, adding the following lines to the @code{services} field of
@@ -18017,7 +17997,7 @@ Base Services
(extra-special-file "/usr/bin/env"
(file-append coreutils "/bin/env"))
@end lisp
-@end deffn
+@end defun
@defvar host-name-service-type
Type of the service that sets the system host name, whose value
@@ -22187,23 +22167,22 @@ X Window
@end table
@end deftp
-@deffn {Scheme Procedure} set-xorg-configuration @var{config} @
- [@var{login-manager-service-type}]
+@defun set-xorg-configuration config [login-manager-service-type]
Tell the log-in manager (of type @var{login-manager-service-type}) to use
@var{config}, an @code{<xorg-configuration>} record.
Since the Xorg configuration is embedded in the log-in manager's
configuration---e.g., @code{gdm-configuration}---this procedure provides a
shorthand to set the Xorg configuration.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} xorg-start-command [@var{config}]
+@defun xorg-start-command [config]
Return a @code{startx} script in which the modules, fonts, etc. specified
in @var{config}, are available. The result should be used in place of
@code{startx}.
Usually the X server is started by a login manager.
-@end deffn
+@end defun
@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
@@ -23626,7 +23605,7 @@ Desktop Services
@end lisp
@end defvar
-@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
+@defun geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
Return a configuration allowing an application to access GeoClue
location data. @var{name} is the Desktop ID of the application, without
the @code{.desktop} part. If @var{allowed?} is true, the application
@@ -23635,7 +23614,7 @@ Desktop Services
or not. Finally @var{users} is a list of UIDs of all users for which
this application is allowed location info access. An empty users list
means that all users are allowed.
-@end deffn
+@end defun
@defvar %standard-geoclue-applications
The standard list of well-known GeoClue application configurations,
@@ -27597,7 +27576,7 @@ File-Sharing Services
procedures provided by this module can be used to obtain a suitable hash
value.
-@deffn {Scheme Procedure} transmission-password-hash @var{password} @var{salt}
+@defun transmission-password-hash password salt
Returns a string containing the result of hashing @var{password}
together with @var{salt}, in the format recognized by Transmission
clients for their @code{rpc-password} configuration setting.
@@ -27605,13 +27584,13 @@ File-Sharing Services
@var{salt} must be an eight-character string. The
@code{transmission-random-salt} procedure can be used to generate a
suitable salt value at random.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} transmission-random-salt
+@defun transmission-random-salt
Returns a string containing a random, eight-character salt value of the
type generated and used by Transmission clients, suitable for passing to
the @code{transmission-password-hash} procedure.
-@end deffn
+@end defun
These procedures are accessible from within a Guile REPL started with
the @command{guix repl} command (@pxref{Invoking guix repl}). This is
@@ -30508,13 +30487,11 @@ Web Services
@end deftp
-@deffn {Scheme Procedure} nginx-php-location @
- [#:nginx-package nginx] @
- [socket (string-append "/var/run/php" @
- (version-major (package-version php)) @
- "-fpm.sock")]
+@defun nginx-php-location [#:nginx-package nginx] @
+ [socket (string-append "/var/run/php" @
+ (version-major (package-version php)) "-fpm.sock")]
A helper function to quickly add php to an @code{nginx-server-configuration}.
-@end deffn
+@end defun
A simple services setup for nginx with php can look like this:
@lisp
@@ -30537,7 +30514,7 @@ Web Services
in @code{Nginx}. It is used to generate cat avatar from a seed, for instance
the hash of a user's email address.
-@deffn {Scheme Procedure} cat-avatar-generator-service @
+@defun cat-avatar-generator-service @
[#:cache-dir "/var/cache/cat-avatar-generator"] @
[#:package cat-avatar-generator] @
[#:configuration (nginx-server-configuration)]
@@ -30545,7 +30522,7 @@ Web Services
extends the nginx configuration to add a server block that serves @code{package},
a version of cat-avatar-generator. During execution, cat-avatar-generator will
be able to use @code{cache-dir} as its cache directory.
-@end deffn
+@end defun
A simple setup for cat-avatar-generator can look like this:
@lisp
@@ -34548,20 +34525,20 @@ Virtualization Services
@end table
@end deftp
-@deffn {Scheme Procedure} lookup-qemu-platforms @var{platforms}@dots{}
+@defun lookup-qemu-platforms platforms@dots{}
Return the list of QEMU platform objects corresponding to
@var{platforms}@dots{}. @var{platforms} must be a list of strings
corresponding to platform names, such as @code{"arm"}, @code{"sparc"},
@code{"mips64el"}, and so on.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} qemu-platform? @var{obj}
+@defun qemu-platform? obj
Return true if @var{obj} is a platform object.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} qemu-platform-name @var{platform}
+@defun qemu-platform-name platform
Return the name of @var{platform}---a string such as @code{"arm"}.
-@end deffn
+@end defun
@subsubheading QEMU Guest Agent
@@ -35057,27 +35034,27 @@ Virtualization Services
@end table
@end deftp
-@deffn {Scheme Procedure} debootstrap-variant @var{name} @var{configuration}
+@defun debootstrap-variant name configuration
This is a helper procedure that creates a @code{ganeti-os-variant} record. It
takes two parameters: a name and a @code{debootstrap-configuration} object.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} debootstrap-os @var{variants}@dots{}
+@defun debootstrap-os variants@dots{}
This is a helper procedure that creates a @code{ganeti-os} record. It takes
a list of variants created with @code{debootstrap-variant}.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} guix-variant @var{name} @var{configuration}
+@defun guix-variant name configuration
This is a helper procedure that creates a @code{ganeti-os-variant} record for
use with the Guix OS provider. It takes a name and a G-expression that returns
a ``file-like'' (@pxref{G-Expressions, file-like objects}) object containing a
Guix System configuration.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} guix-os @var{variants}@dots{}
+@defun guix-os variants@dots{}
This is a helper procedure that creates a @code{ganeti-os} record. It
takes a list of variants produced by @code{guix-variant}.
-@end deffn
+@end defun
@defvar %default-debootstrap-variants
This is a convenience variable to make the debootstrap provider work
@@ -35575,7 +35552,7 @@ Version Control Services
@code{git-http-configuration} and then add that location to a web
server.
-@deffn {Scheme Procedure} git-http-nginx-location-configuration @
+@defun git-http-nginx-location-configuration @
[config=(git-http-configuration)]
Compute an @code{nginx-location-configuration} that corresponds to the
given Git http configuration. An example nginx service definition to
@@ -35604,7 +35581,7 @@ Version Control Services
service will redirect all HTTP traffic on @code{git.my-host.org} to
HTTPS@. You will also need to add an @code{fcgiwrap} proxy to your
system services. @xref{Web Services}.
-@end deffn
+@end defun
@subsubheading Cgit Service
@@ -38221,7 +38198,7 @@ Miscellaneous Services
@end lisp
@end defvar
-@deffn {Scheme Procedure} fail2ban-jail-service @var{svc-type} @var{jail}
+@defun fail2ban-jail-service svc-type jail
Extend @var{svc-type}, a @code{<service-type>} object with @var{jail}, a
@code{fail2ban-jail-configuration} object.
@@ -38241,7 +38218,7 @@ Miscellaneous Services
(enabled? #t)))
(openssh-configuration ...))))
@end lisp
-@end deffn
+@end defun
Below is the reference for the different @code{jail-service-type}
configuration records.
@@ -38848,7 +38825,7 @@ Initial RAM Disk
@cindex initrd
@cindex initial RAM disk
-@deffn {Scheme Procedure} raw-initrd @var{file-systems} @
+@defun raw-initrd file-systems @
[#:linux-modules '()] [#:pre-mount #t] [#:mapped-devices '()] @
[#:keyboard-layout #f] [#:helper-packages '()] @
[#:qemu-networking? #f] [#:volatile-root? #f]
@@ -38877,9 +38854,9 @@ Initial RAM Disk
When @var{volatile-root?} is true, the root file system is writable but any changes
to it are lost.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} base-initrd @var{file-systems} @
+@defun base-initrd file-systems @
[#:mapped-devices '()] [#:keyboard-layout #f] @
[#:qemu-networking? #f] [#:volatile-root? #f] @
[#:linux-modules '()]
@@ -38901,7 +38878,7 @@ Initial RAM Disk
for @var{file-systems} and for the given options. Additional kernel
modules can be listed in @var{linux-modules}. They will be added to the initrd, and
loaded at boot time in the order in which they appear.
-@end deffn
+@end defun
Needless to say, the initrds we produce and use embed a
statically-linked Guile, and the initialization program is a Guile
@@ -38909,13 +38886,13 @@ Initial RAM Disk
@code{expression->initrd} procedure builds such an initrd, given the
program to run in that initrd.
-@deffn {Scheme Procedure} expression->initrd @var{exp} @
+@defun expression->initrd exp @
[#:guile %guile-static-stripped] [#:name "guile-initrd"]
Return as a file-like object a Linux initrd (a gzipped cpio archive)
containing @var{guile} and that evaluates @var{exp}, a G-expression,
upon booting. All the derivations referenced by @var{exp} are
automatically copied to the initrd.
-@end deffn
+@end defun
@node Bootloader Configuration
@section Bootloader Configuration
@@ -39261,14 +39238,14 @@ Bootloader Configuration
@end table
@end deftp
-@deffn {Scheme Procedure} grub-theme
+@defun grub-theme
Return the default GRUB theme used by the operating system if no
@code{theme} field is specified in @code{bootloader-configuration}
record.
It comes with a fancy background image displaying the GNU and Guix
logos.
-@end deffn
+@end defun
For example, to override the default resolution, you may use something
like
@@ -40520,7 +40497,7 @@ Service Reference
services and service types. This interface is provided by the
@code{(gnu services)} module.
-@deffn {Scheme Procedure} service @var{type} [@var{value}]
+@defun service type [value]
Return a new service of @var{type}, a @code{<service-type>} object (see
below). @var{value} can be any object; it represents the parameters of
this particular service instance.
@@ -40545,20 +40522,20 @@ Service Reference
In both cases the result is an instance of @code{openssh-service-type}
with the default configuration.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} service? @var{obj}
+@defun service? obj
Return true if @var{obj} is a service.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} service-kind @var{service}
+@defun service-kind service
Return the type of @var{service}---i.e., a @code{<service-type>} object.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} service-value @var{service}
+@defun service-value service
Return the value associated with @var{service}. It represents its
parameters.
-@end deffn
+@end defun
Here is an example of how a service is created and manipulated:
@@ -40679,24 +40656,23 @@ Service Reference
@xref{Service Types and Services}, for examples.
@end deftp
-@deffn {Scheme Procedure} service-extension @var{target-type} @
- @var{compute}
+@defun service-extension target-type compute
Return a new extension for services of type @var{target-type}.
@var{compute} must be a one-argument procedure: @code{fold-services}
calls it, passing it the value associated with the service that provides
the extension; it must return a valid value for the target service.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} service-extension? @var{obj}
+@defun service-extension? obj
Return true if @var{obj} is a service extension.
-@end deffn
+@end defun
Occasionally, you might want to simply extend an existing service. This
involves creating a new service type and specifying the extension of
interest, which can be verbose; the @code{simple-service} procedure
provides a shorthand for this.
-@deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value}
+@defun simple-service name target value
Return a service that extends @var{target} with @var{value}. This works
by creating a singleton service type @var{name}, of which the returned
service is an instance.
@@ -40708,7 +40684,7 @@ Service Reference
(simple-service 'my-mcron-job mcron-service-type
#~(job '(next-hour (3)) "guix gc -F 2G"))
@end lisp
-@end deffn
+@end defun
At the core of the service abstraction lies the @code{fold-services}
procedure, which is responsible for ``compiling'' a list of services
@@ -40718,11 +40694,10 @@ Service Reference
service extensions down the service graph, updating each node parameters
on the way, until it reaches the root node.
-@deffn {Scheme Procedure} fold-services @var{services} @
- [#:target-type @var{system-service-type}]
+@defun fold-services services [#:target-type system-service-type]
Fold @var{services} by propagating their extensions down to the root of
type @var{target-type}; return the root service adjusted accordingly.
-@end deffn
+@end defun
Lastly, the @code{(gnu services)} module also defines several essential
service types, some of which are listed below.
@@ -41005,7 +40980,7 @@ Shepherd Services
@end deftp
@cindex configuration file, of Shepherd services
-@deffn {Scheme Procedure} shepherd-configuration-action
+@defun shepherd-configuration-action
Return a @code{configuration} action to display @var{file}, which should
be the name of the service's configuration file.
@@ -41035,7 +41010,7 @@ Shepherd Services
@end example
This can come in as a handy debugging tool!
-@end deffn
+@end defun
@defvar shepherd-root-service-type
The service type for the Shepherd ``root service''---i.e., PID@tie{}1.
@@ -41266,30 +41241,28 @@ Complex Configurations
@end lisp
@end deffn
-@deffn (Scheme Procedure) maybe-value-set? @var{value}
+@defun maybe-value-set? value
Predicate to check whether a user explicitly specified the value of a
maybe field.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} serialize-configuration @var{configuration} @
-@var{fields}
+@defun serialize-configuration configuration fields
Return a G-expression that contains the values corresponding to the
@var{fields} of @var{configuration}, a record that has been generated by
@code{define-configuration}. The G-expression can then be serialized to
disk by using something like @code{mixed-text-file}.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} empty-serializer @var{field-name} @var{value}
+@defun empty-serializer field-name value
A serializer that just returns an empty string. The
@code{serialize-package} procedure is an alias for this.
-@end deffn
+@end defun
Once you have defined a configuration record, you will most likely also
want to document it so that other people know to use it. To help with
that, there are two procedures, both of which are documented below.
-@deffn {Scheme Procedure} generate-documentation @var{documentation} @
-@var{documentation-name}
+@defun generate-documentation documentation documentation-name
Generate a Texinfo fragment from the docstrings in @var{documentation},
a list of @code{(@var{label} @var{fields} @var{sub-documentation} ...)}.
@var{label} should be a symbol and should be the name of the
@@ -41319,16 +41292,15 @@ Complex Configurations
@var{documentation-name} should be a symbol and should be the name of
the configuration record.
-@end deffn
+@end defun
-@deffn {Scheme Procedure} configuration->documentation
-@var{configuration-symbol}
+@defun configuration->documentation configuration-symbol
Take @var{configuration-symbol}, the symbol corresponding to the name
used when defining a configuration record with
@code{define-configuration}, and print the Texinfo documentation of its
fields. This is useful if there aren’t any nested configuration records
since it only prints the documentation for the top-level fields.
-@end deffn
+@end defun
As of right now, there is no automated way to generate documentation for
configuration records and put them in the manual. Instead, every
--
2.39.1
^ permalink raw reply related [flat|nested] 6+ messages in thread* [bug#62042] [PATCH 4/4] doc: Use @defmac and @defspec for macros.
2023-03-08 1:19 [bug#62042] [PATCH 0/4] Harmonize @-commands used in doc/guix.texi Bruno Victal
` (2 preceding siblings ...)
2023-03-08 1:22 ` [bug#62042] [PATCH 3/4] doc: Use @defun for procedures Bruno Victal
@ 2023-03-08 1:22 ` Bruno Victal
2023-03-13 14:06 ` bug#62042: [PATCH 0/4] Harmonize @-commands used in doc/guix.texi Ludovic Courtès
4 siblings, 0 replies; 6+ messages in thread
From: Bruno Victal @ 2023-03-08 1:22 UTC (permalink / raw)
To: 62042; +Cc: Bruno Victal
* doc/guix.texi (package Reference, Defining Package Variants)
(Build Utilities, The Store Monad, G-Expressions, operating-system Reference)
(Service Reference, Complex Configurations): Use @defmac and @defspec for macros.
---
doc/guix.texi | 97 +++++++++++++++++++++++++--------------------------
1 file changed, 47 insertions(+), 50 deletions(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index ed9994a41b..358be58205 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7781,7 +7781,7 @@ package Reference
@end table
@end deftp
-@deffn {Scheme Syntax} this-package
+@defmac this-package
When used in the @emph{lexical scope} of a package field definition, this
identifier resolves to the package being defined.
@@ -7801,7 +7801,7 @@ package Reference
@end lisp
It is an error to refer to @code{this-package} outside a package definition.
-@end deffn
+@end defmac
The following helper procedures are provided to help deal with package
inputs.
@@ -8160,7 +8160,7 @@ Defining Package Variants
macro is a helper that can prove useful anytime you want to remove, add,
or replace package inputs.
-@deffn {Scheme Syntax} modify-inputs @var{inputs} @var{clauses}
+@defmac modify-inputs inputs clauses
Modify the given package inputs, as returned by @code{package-inputs} & co.,
according to the given clauses. Each clause must have one of the
following forms:
@@ -8195,7 +8195,7 @@ Defining Package Variants
The last type of clause is @code{append}, to add inputs at the back of
the list.
-@end deffn
+@end defmac
In some cases, you may find it useful to write functions
(``procedures'', in Scheme parlance) that return a package based on some
@@ -10161,7 +10161,7 @@ Build Utilities
@command{sed}. They complement Guile's extensive, but low-level, file
system interface (@pxref{POSIX,,, guile, GNU Guile Reference Manual}).
-@deffn {Scheme Syntax} with-directory-excursion @var{directory} @var{body}@dots{}
+@defmac with-directory-excursion directory body @dots{}
Run @var{body} with @var{directory} as the process's current directory.
Essentially, this macro changes the current directory to @var{directory}
@@ -10170,7 +10170,7 @@ Build Utilities
directory when the dynamic extent of @var{body} is left, be it @i{via}
normal procedure return or @i{via} a non-local exit such as an
exception.
-@end deffn
+@end defmac
@defun mkdir-p dir
Create directory @var{dir} and all its ancestors.
@@ -10202,8 +10202,8 @@ Build Utilities
is true. Report but ignore errors.
@end defun
-@deffn {Scheme Syntax} substitute* @var{file} @
- ((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{}
+@defmac substitute* file @
+ ((regexp match-var@dots{}) body@dots{}) @dots{}
Substitute @var{regexp} in @var{file} by the string returned by
@var{body}. @var{body} is evaluated with each @var{match-var} bound to
the corresponding positional regexp sub-expression. For example:
@@ -10229,7 +10229,7 @@ Build Utilities
Be careful about using @code{$} to match the end of a line; by itself it
won't match the terminating newline of a line.
-@end deffn
+@end defmac
@subsection File Search
@@ -10390,7 +10390,7 @@ Build Utilities
those with tools written with build phases in mind.
@cindex build phases, modifying
-@deffn {Scheme Syntax} modify-phases @var{phases} @var{clause}@dots{}
+@defmac modify-phases phases clause@dots{}
Modify @var{phases} sequentially as per each @var{clause}, which may
have one of the following forms:
@@ -10403,7 +10403,7 @@ Build Utilities
Where every @var{phase-name} above is an expression evaluating to a
symbol, and @var{new-phase} an expression evaluating to a procedure.
-@end deffn
+@end defmac
The example below is taken from the definition of the @code{grep}
package. It adds a phase to run after the @code{install} phase, called
@@ -11190,16 +11190,16 @@ The Store Monad
The main syntactic forms to deal with monads in general are provided by
the @code{(guix monads)} module and are described below.
-@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
+@defmac with-monad monad body @dots{}
Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
in @var{monad}.
-@end deffn
+@end defmac
-@deffn {Scheme Syntax} return @var{val}
+@defmac return val
Return a monadic value that encapsulates @var{val}.
-@end deffn
+@end defmac
-@deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ...
+@defmac >>= mval mproc @dots{}
@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
procedures @var{mproc}@dots{}@footnote{This operation is commonly
referred to as ``bind'', but that name denotes an unrelated procedure in
@@ -11218,12 +11218,10 @@ The Store Monad
@result{} 4
@result{} some-state
@end lisp
-@end deffn
+@end defmac
-@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
- @var{body} ...
-@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
- @var{body} ...
+@defmac mlet monad ((var mval) @dots{}) body @dots{}
+@defmacx mlet* monad ((var mval) @dots{}) body @dots{}
Bind the variables @var{var} to the monadic values @var{mval} in
@var{body}, which is a sequence of expressions. As with the bind
operator, this can be thought of as ``unpacking'' the raw, non-monadic
@@ -11237,9 +11235,9 @@ The Store Monad
@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
-@end deffn
+@end defmac
-@deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
+@defmac mbegin monad mexp @dots{}
Bind @var{mexp} and the following monadic expressions in sequence,
returning the result of the last expression. Every expression in the
sequence must be a monadic expression.
@@ -11247,21 +11245,21 @@ The Store Monad
This is akin to @code{mlet}, except that the return values of the
monadic expressions are ignored. In that sense, it is analogous to
@code{begin}, but applied to monadic expressions.
-@end deffn
+@end defmac
-@deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
+@defmac mwhen condition mexp0 mexp* @dots{}
When @var{condition} is true, evaluate the sequence of monadic
expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
@var{condition} is false, return @code{*unspecified*} in the current
monad. Every expression in the sequence must be a monadic expression.
-@end deffn
+@end defmac
-@deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ...
+@defmac munless condition mexp0 mexp* @dots{}
When @var{condition} is false, evaluate the sequence of monadic
expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
@var{condition} is true, return @code{*unspecified*} in the current
monad. Every expression in the sequence must be a monadic expression.
-@end deffn
+@end defmac
@cindex state monad
The @code{(guix monads)} module provides the @dfn{state monad}, which
@@ -11582,8 +11580,8 @@ G-Expressions
The syntactic form to construct gexps is summarized below.
-@deffn {Scheme Syntax} #~@var{exp}
-@deffnx {Scheme Syntax} (gexp @var{exp})
+@defmac #~@var{exp}
+@defmacx (gexp @var{exp})
Return a G-expression containing @var{exp}. @var{exp} may contain one
or more of the following forms:
@@ -11637,9 +11635,9 @@ G-Expressions
G-expressions created by @code{gexp} or @code{#~} are run-time objects
of the @code{gexp?} type (see below).
-@end deffn
+@end defmac
-@deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{}
+@defmac with-imported-modules modules body@dots{}
Mark the gexps defined in @var{body}@dots{} as requiring @var{modules}
in their execution environment.
@@ -11661,9 +11659,9 @@ G-Expressions
This form has @emph{lexical} scope: it has an effect on the gexps
directly defined in @var{body}@dots{}, but not on those defined, say, in
procedures called from @var{body}@dots{}.
-@end deffn
+@end defmac
-@deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{}
+@defmac with-extensions extensions body@dots{}
Mark the gexps defined in @var{body}@dots{} as requiring
@var{extensions} in their build and execution environment.
@var{extensions} is typically a list of package objects such as those
@@ -11673,7 +11671,7 @@ G-Expressions
load path while compiling imported modules in @var{body}@dots{}; they
are also added to the load path of the gexp returned by
@var{body}@dots{}.
-@end deffn
+@end defmac
@defun gexp? obj
Return @code{#t} if @var{obj} is a G-expression.
@@ -11957,8 +11955,8 @@ G-Expressions
@dots{})} expression to construct the file name @emph{at run time}.
@end defun
-@deffn {Scheme Syntax} let-system @var{system} @var{body}@dots{}
-@deffnx {Scheme Syntax} let-system (@var{system} @var{target}) @var{body}@dots{}
+@defmac let-system system body@dots{}
+@defmacx let-system (system target) body@dots{}
Bind @var{system} to the currently targeted system---e.g.,
@code{"x86_64-linux"}---within @var{body}.
@@ -11981,9 +11979,9 @@ G-Expressions
(error "dunno!"))))
"-net" "user" #$image)
@end lisp
-@end deffn
+@end defmac
-@deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp}
+@defmac with-parameters ((parameter value) @dots{}) exp
This macro is similar to the @code{parameterize} form for
dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU
Guile Reference Manual}). The key difference is that it takes effect
@@ -12000,7 +11998,7 @@ G-Expressions
The example above returns an object that corresponds to the i686 build
of Coreutils, regardless of the current value of @code{%current-system}.
-@end deffn
+@end defmac
Of course, in addition to gexps embedded in ``host'' code, there are
@@ -16651,7 +16649,7 @@ operating-system Reference
@end table
-@deffn {Scheme Syntax} this-operating-system
+@defmac this-operating-system
When used in the @emph{lexical scope} of an operating system field definition,
this identifier resolves to the operating system being defined.
@@ -16669,7 +16667,7 @@ operating-system Reference
It is an error to refer to @code{this-operating-system} outside an operating
system definition.
-@end deffn
+@end defmac
@end deftp
@@ -40564,8 +40562,8 @@ Service Reference
@code{modify-services} simply provides a more concise form for this
common pattern.
-@deffn {Scheme Syntax} modify-services @var{services} @
- (@var{type} @var{variable} => @var{body}) @dots{}
+@defspec modify-services services @
+ (type variable => body) @dots{}
Modify the services listed in @var{services} according to the given
clauses. Each clause has the form:
@@ -40598,7 +40596,7 @@ Service Reference
@xref{Using the Configuration System}, for example usage.
-@end deffn
+@end defspec
Next comes the programming interface for service types. This is
something you want to know when writing new service definitions, but not
@@ -41074,8 +41072,7 @@ Complex Configurations
G-expression (@pxref{G-Expressions}), which should, once serialized to
the disk, return a string. More details are listed below.
-@deffn {Scheme Syntax} define-configuration @var{name} @var{clause1} @
-@var{clause2} ...
+@defmac define-configuration name clause1 clause2 @dots{}
Create a record type named @code{@var{name}} that contains the
fields found in the clauses.
@@ -41185,9 +41182,9 @@ Complex Configurations
(string "test")
"Some documentation."))
@end lisp
-@end deffn
+@end defmac
-@deffn {Scheme Syntax} define-maybe @var{type}
+@defmac define-maybe 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 left unset, or
@@ -41239,7 +41236,7 @@ Complex Configurations
maybe-symbol
"Docstring."))
@end lisp
-@end deffn
+@end defmac
@defun maybe-value-set? value
Predicate to check whether a user explicitly specified the value of a
--
2.39.1
^ permalink raw reply related [flat|nested] 6+ messages in thread