diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/build.scm | 26 | ||||
-rw-r--r-- | doc/contributing.texi | 22 | ||||
-rw-r--r-- | doc/guix-cookbook.texi | 4 | ||||
-rw-r--r-- | doc/guix.texi | 225 | ||||
-rw-r--r-- | doc/htmlxref.cnf | 9 | ||||
-rw-r--r-- | doc/local.mk | 18 |
6 files changed, 227 insertions, 77 deletions
diff --git a/doc/build.scm b/doc/build.scm index 9d79215b98..cf3e5d2830 100644 --- a/doc/build.scm +++ b/doc/build.scm @@ -62,11 +62,19 @@ (or (getenv "GUIX_MANUAL") "guix")) +(define %manual-languages + ;; Available translations for the 'guix-manual' text domain. + '("de" "en" "es" "fr" "ru" "zh_CN")) + +(define %cookbook-languages + ;; Available translations for the 'guix-cookbook' text domain. + '("de" "en" "fr" "sk")) + (define %languages - ;; The cookbook is not translated in the same languages as the manual + ;; Available translations for the document being built. (if (string=? %manual "guix-cookbook") - '("de" "en" "fr" "sk") - '("de" "en" "es" "fr" "ru" "zh_CN"))) + %cookbook-languages + %manual-languages)) (define (texinfo-manual-images source) "Return a directory containing all the images used by the user manual, taken @@ -301,8 +309,9 @@ actual file name." (define (html-files directory) ;; Return the list of HTML files under DIRECTORY. (map (cut string-append directory "/" <>) - (scandir #$manual (lambda (file) - (string-suffix? ".html" file))))) + (or (scandir #$manual (lambda (file) + (string-suffix? ".html" file))) + '()))) (define anchors (sort (concatenate @@ -969,7 +978,8 @@ PDF for language '~a'!~%~%" (computed-file (string-append manual "-pdf-manual") build #:local-build? #f)) -(define (guix-manual-text-domain source languages) +(define* (guix-manual-text-domain source + #:optional (languages %manual-languages)) "Return the PO files for LANGUAGES of the 'guix-manual' text domain taken from SOURCE." (define po-directory @@ -1042,9 +1052,7 @@ must be the Guix top-level source directory, from which PO files are taken." (define exp `(begin (bindtextdomain "guix-manual" - #+(guix-manual-text-domain - source - languages)) + #+(guix-manual-text-domain source)) (bindtextdomain "iso_639-3" ;language names #+(file-append iso-codes "/share/locale")) diff --git a/doc/contributing.texi b/doc/contributing.texi index 207efc4ee6..862dcbf12a 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1911,6 +1911,28 @@ Currently, some parts of Guix cannot be translated on Weblate, help wanted! translated. @end itemize +@subsubheading Conditions for Inclusion + +There are no conditions for adding new translations of the @code{guix} and +@code{guix-packages} components, other than they need at least one translated +string. New languages will be added to Guix as soon as possible. The +files may be removed if they fall out of sync and have no more translated +strings. + +Given that the web site is dedicated to new users, we want its translation +to be as complete as possible before we include it in the language menu. +For a new language to be included, it needs to reach at least 80% completion. +When a language is included, it may be removed in the future if it stays +out of sync and falls below 60% completion. + +The manual and cookbook are automatically added in the default compilation +target. Everytime we synchronize translations, developers need to +recompile all the translated manuals and cookbooks. This is useless for what +is essentially the English manual or cookbook. Therefore, we will only +include a new language when it reaches 10% completion in the component. +When a language is included, it may be removed in the future if it stays +out of sync and falls below 5% completion. + @subsubheading Translation Infrastructure Weblate is backed by a git repository from which it discovers new strings to diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index d89ce66017..b4dc9f864c 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -296,7 +296,7 @@ online}, together with @uref{https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-001-structure-and-interpretation-of-computer-programs-spring-2005/video-lectures/, videos of the lectures by the authors}. The book is available in Texinfo format as the @code{sicp} Guix package. Go ahead, run @code{guix install -sicp} and start reading with @code{info sicp} (@pxref{,,, sicp, Structure and Interpretation of Computer Programs}). +sicp} and start reading with @code{info sicp} (@pxref{Top,,, sicp, Structure and Interpretation of Computer Programs}). An @uref{https://sarabander.github.io/sicp/, unofficial ebook is also available}. @@ -903,7 +903,7 @@ Installed in the store and in the profile, as well as being present at build time. @end table -@xref{Package Reference,,, guix, GNU Guix Reference Manual} for more details. +@xref{package Reference,,, guix, GNU Guix Reference Manual} for more details. The distinction between the various inputs is important: if a dependency can be handled as an @emph{input} instead of a @emph{propagated input}, it should be done so, or diff --git a/doc/guix.texi b/doc/guix.texi index 44b0f9f1ea..5399584cb0 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -100,6 +100,8 @@ Copyright @copyright{} 2021 Josselin Poiret@* Copyright @copyright{} 2021 Andrew Tropin@* Copyright @copyright{} 2021 Sarah Morgensen@* Copyright @copyright{} 2021 Josselin Poiret@* +Copyright @copyright{} 2022 Remco van 't Veer@* +Copyright @copyright{} 2022 Aleksandr Vityazev@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -1552,7 +1554,11 @@ is normally run as @code{root} like this: # guix-daemon --build-users-group=guixbuild @end example -@noindent +@cindex socket activation, for @command{guix-daemon} +This daemon can also be started following the systemd ``socket +activation'' protocol (@pxref{Service De- and Constructors, +@code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}). + For details on how to set it up, @pxref{Setting Up the Daemon}. @cindex chroot @@ -5847,6 +5853,55 @@ This is similar to the same-named option in @command{guix package} (@pxref{profile-manifest, @option{--manifest}}) and uses the same manifest files. +See @option{--export-manifest} below on how to obtain a first manifest. + +@cindex manifest, exporting +@anchor{shell-export-manifest} +@item --export-manifest +Write to standard output a manifest suitable for @option{--manifest} +corresponding to given command-line options. + +This is a way to ``convert'' command-line arguments into a manifest. +For example, imagine you are tired of typing long lines and would like +to get a manifest equivalent to this command line: + +@example +guix shell -D guile git emacs emacs-geiser emacs-geiser-guile +@end example + +Just add @option{--export-manifest} to the command line above: + +@example +guix shell --export-manifest \ + -D guile git emacs emacs-geiser emacs-geiser-guile +@end example + +@noindent +... and you get a manifest along these lines: + +@lisp +(concatenate-manifests + (list (specifications->manifest + (list "git" + "emacs" + "emacs-geiser" + "emacs-geiser-guile")) + (package->development-manifest + (specification->package "guile")))) +@end lisp + +You can store it into a file, say @file{manifest.scm}, and from there +pass it to @command{guix shell} or indeed pretty much any @command{guix} +command: + +@example +guix shell -m manifest.scm +@end example + +Voilà, you've converted a long command line into a manifest! That +conversion process honors package transformation options (@pxref{Package +Transformation Options}) so it should be lossless. + @item --profile=@var{profile} @itemx -p @var{profile} Create an environment containing the packages installed in @var{profile}. @@ -6234,6 +6289,10 @@ This is similar to the same-named option in @command{guix package} (@pxref{profile-manifest, @option{--manifest}}) and uses the same manifest files. +@xref{shell-export-manifest, @command{guix shell --export-manifest}}, +for information on how to ``convert'' command-line options into a +manifest. + @item --ad-hoc Include all specified packages in the resulting environment, as if an @i{ad hoc} package were defined with them as inputs. This option is @@ -6692,6 +6751,10 @@ for use on machines that do not have Guix installed. Note that you can specify @emph{either} a manifest file @emph{or} a list of packages, but not both. +@xref{shell-export-manifest, @command{guix shell --export-manifest}}, +for information on how to ``convert'' command-line options into a +manifest. + @item --system=@var{system} @itemx -s @var{system} Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of @@ -7303,7 +7366,8 @@ for details. A one-line description of the package. @item @code{description} -A more elaborate description of the package. +A more elaborate description of the package, as a string in Texinfo +syntax. @item @code{license} @cindex license, of packages @@ -13982,6 +14046,11 @@ spawn an HTTP server on port 8080: guix publish @end example +@cindex socket activation, for @command{guix publish} +@command{guix publish} can also be started following the systemd +``socket activation'' protocol (@pxref{Service De- and Constructors, +@code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}). + Once a publishing server has been authorized, the daemon may download substitutes from it. @xref{Getting Substitutes from Other Servers}. @@ -17640,6 +17709,44 @@ The list of syslog-controlled files to be rotated. By default it is: "/var/log/maillog")}. @end defvr +Some log files just need to be deleted periodically once they are old, +without any other criterion and without any archival step. This is the +case of build logs stored by @command{guix-daemon} under +@file{/var/log/guix/drvs} (@pxref{Invoking guix-daemon}). The +@code{log-cleanup} service addresses this use case. For example, +@code{%base-services} (@pxref{Base Services}) includes the following: + +@lisp +;; Periodically delete old build logs. +(service log-cleanup-service-type + (log-cleanup-configuration + (directory "/var/log/guix/drvs"))) +@end lisp + +That ensures build logs do not accumulate endlessly. + +@defvr {Scheme Variable} log-cleanup-service-type +This is the type of the service to delete old logs. Its value must be a +@code{log-cleanup-configuration} record as described below. +@end defvr + +@deftp {Data Type} log-cleanup-configuration +Data type representing the log cleanup configuration + +@table @asis +@item @code{directory} +Name of the directory containing log files. + +@item @code{expiry} (default: @code{(* 6 30 24 3600)}) +Age in seconds after which a file is subject to deletion (six months by +default). + +@item @code{schedule} (default: @code{"30 12 01,08,15,22 * *"}) +String or gexp denoting the corresponding mcron job schedule +(@pxref{Scheduled Job Execution}). +@end table +@end deftp + @node Networking Setup @subsection Networking Setup @@ -18865,6 +18972,12 @@ Name of the file where @command{sshd} writes its PID. @item @code{port-number} (default: @code{22}) TCP port on which @command{sshd} listens for incoming connections. +@item @code{max-connections} (default: @code{200}) +Hard limit on the maximum number of simultaneous client connections, +enforced by the inetd-style Shepherd service (@pxref{Service De- and +Constructors, @code{make-inetd-constructor},, shepherd, The GNU Shepherd +Manual}). + @item @code{permit-root-login} (default: @code{#f}) This field determines whether and when to allow logins as root. If @code{#f}, root logins are disallowed; if @code{#t}, they are allowed. @@ -19384,19 +19497,12 @@ signing and encryption keys are defined in @file{/etc/yggdrasil-private.conf} @example # sample content for /etc/yggdrasil-private.conf @{ - # Your public encryption key. Your peers may ask you for this to put - # into their AllowedEncryptionPublicKeys configuration. - EncryptionPublicKey: 378dc5... - - # Your private encryption key. DO NOT share this with anyone! - EncryptionPrivateKey: 0777... - - # Your public signing key. You should not ordinarily need to share - # this with anyone. - SigningPublicKey: e1664... + # Your public key. Your peers may ask you for this to put + # into their AllowedPublicKeys configuration. + PublicKey: 64277... - # Your private signing key. DO NOT share this with anyone! - SigningPrivateKey: 0589d... + # Your private key. DO NOT share this with anyone! + PrivateKey: 5c750... @} @end example @end defvr @@ -24975,21 +25081,21 @@ account fingerprint for a registered username. @end deftp -@subsubheading Murmur (VoIP server) +@subsubheading Mumble server -@cindex Murmur (VoIP server) +@cindex Mumble +@cindex Murmur @cindex VoIP server -This section describes how to set up and run a Murmur server. Murmur is -the server of the @uref{https://mumble.info, Mumble} voice-over-IP -(VoIP) suite. +This section describes how to set up and run a +@uref{https://mumble.info, Mumble} server (formerly known as Murmur). -@deftp {Data Type} murmur-configuration -The service type for the Murmur server. An example configuration can +@deftp {Data Type} mumble-server-configuration +The service type for the Mumble server. An example configuration can look like this: @lisp -(service murmur-service-type - (murmur-configuration +(service mumble-server-service-type + (mumble-server-configuration (welcome-text "Welcome to this Mumble server running on Guix!") (cert-required? #t) ;disallow text password logins @@ -24997,7 +25103,8 @@ look like this: (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem"))) @end lisp -After reconfiguring your system, you can manually set the murmur @code{SuperUser} +After reconfiguring your system, you can manually set the mumble-server +@code{SuperUser} password with the command that is printed during the activation phase. It is recommended to register a normal Mumble user account @@ -25009,17 +25116,17 @@ the @code{SuperUser} password that you set previously, and grant your newly registered mumble user administrator or moderator rights and create some channels. -Available @code{murmur-configuration} fields are: +Available @code{mumble-server-configuration} fields are: @table @asis @item @code{package} (default: @code{mumble}) -Package that contains @code{bin/murmurd}. +Package that contains @code{bin/mumble-server}. -@item @code{user} (default: @code{"murmur"}) -User who will run the Murmur server. +@item @code{user} (default: @code{"mumble-server"}) +User who will run the Mumble-Server server. -@item @code{group} (default: @code{"murmur"}) -Group of the user who will run the murmur server. +@item @code{group} (default: @code{"mumble-server"}) +Group of the user who will run the mumble-server server. @item @code{port} (default: @code{64738}) Port on which the server will listen. @@ -25036,11 +25143,11 @@ Maximum of users that can be connected to the server at once. @item @code{max-user-bandwidth} (default: @code{#f}) Maximum voice traffic a user can send per second. -@item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"}) +@item @code{database-file} (default: @code{"/var/lib/mumble-server/db.sqlite"}) File name of the sqlite database. The service's user will become the owner of the directory. -@item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"}) +@item @code{log-file} (default: @code{"/var/log/mumble-server/mumble-server.log"}) File name of the log file. The service's user will become the owner of the directory. @@ -25079,8 +25186,9 @@ If it is set to @code{#t} clients that use weak password authentication will not be accepted. Users must have completed the certificate wizard to join. @item @code{remember-channel?} (default: @code{#f}) -Should murmur remember the last channel each user was in when they disconnected -and put them into the remembered channel when they rejoin. +Should mumble-server remember the last channel each user was in when +they disconnected and put them into the remembered channel when they +rejoin. @item @code{allow-html?} (default: @code{#f}) Should html be allowed in text messages, user comments, and channel descriptions. @@ -25096,10 +25204,10 @@ Disabling this setting will prevent public listing of the server. Should the server advertise itself in the local network through the bonjour protocol. @item @code{send-version?} (default: @code{#f}) -Should the murmur server version be exposed in ping requests. +Should the mumble-server server version be exposed in ping requests. @item @code{log-days} (default: @code{31}) -Murmur also stores logs in the database, which are accessible via RPC. +Mumble also stores logs in the database, which are accessible via RPC. The default is 31 days of months, but you can set this setting to 0 to keep logs forever, or -1 to disable logging to the database. @@ -25132,17 +25240,19 @@ This option is specified using @uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT, OpenSSL cipher list notation}. -It is recommended that you try your cipher string using 'openssl ciphers <string>' -before setting it here, to get a feel for which cipher suites you will get. -After setting this option, it is recommend that you inspect your Murmur log -to ensure that Murmur is using the cipher suites that you expected it to. +It is recommended that you try your cipher string using +'openssl ciphers <string>' before setting it here, to get a feel for +which cipher suites you will get. +After setting this option, it is recommend that you inspect your Mumble +server log to ensure that Mumble is using the cipher suites that you +expected it to. Note: Changing this option may impact the backwards compatibility of your -Murmur server, and can remove the ability for older Mumble clients to be able -to connect to it. +Mumble-Server server, and can remove the ability for older Mumble clients to be able to connect to it. @item @code{public-registration} (default: @code{#f}) -Must be a @code{<murmur-public-registration-configuration>} record or @code{#f}. +Must be a @code{<mumble-server-public-registration-configuration>} +record or @code{#f}. You can optionally register your server in the public server list that the @code{mumble} client shows on startup. @@ -25156,8 +25266,8 @@ Optional alternative override for this configuration. @end table @end deftp -@deftp {Data Type} murmur-public-registration-configuration -Configuration for public registration of a murmur service. +@deftp {Data Type} mumble-server-public-registration-configuration +Configuration for public registration of a mumble-server service. @table @asis @item @code{name} @@ -25177,7 +25287,12 @@ If it is set your server will be linked by this host name instead. @end table @end deftp - +@quotation Deprecation notice +Due to historical reasons, all of the above @code{mumble-server-} +procedures are also exported with the @code{murmur-} prefix. +It is recommended that you switch to using @code{mumble-server-} +going forward. +@end quotation @node File-Sharing Services @subsection File-Sharing Services @@ -28945,6 +29060,14 @@ The file to read the IP address of the upstream nameservers from. @item @code{no-resolv?} (default: @code{#f}) When true, don't read @var{resolv-file}. +@item @code{forward-private-reverse-lookup?} (default: @code{#t}) +When false, all reverse lookups for private IP ranges are answered with +"no such domain" rather than being forwarded upstream. + +@item @code{query-servers-in-order?} (default: @code{#f}) +When true, dnsmasq queries the servers in the same order as they appear +in @var{servers}. + @item @code{servers} (default: @code{'()}) Specify IP address of upstream servers directly. @@ -28974,6 +29097,10 @@ disables caching. @item @code{negative-cache?} (default: @code{#t}) When false, disable negative caching. +@item @code{cpe-id} (default: @code{#f}) +If set, add a CPE (Customer-Premises Equipment) identifier to DNS +queries which are forwarded upstream. + @item @code{tftp-enable?} (default: @code{#f}) Whether to enable the built-in TFTP server. @@ -34303,6 +34430,10 @@ time-to-live (TTL) of @emph{negative} lookups---missing store items, for which the HTTP 404 code is returned. By default, no negative TTL is advertised. +@item @code{log-level} (default: @code{'DEBUG}) +Log level to use, specify a log level like @code{'INFO} to stop logging +individual requests. + @end table @end deftp @@ -38215,7 +38346,7 @@ variables. ("ENV_VAR2" . "value2")) @end lisp -The easiest way to extend a service type, without defining new service +The easiest way to extend a service type, without defining a new service type is to use the @code{simple-service} helper from @code{(gnu services)}. diff --git a/doc/htmlxref.cnf b/doc/htmlxref.cnf index c00a9a53b8..7c780c7a4a 100644 --- a/doc/htmlxref.cnf +++ b/doc/htmlxref.cnf @@ -1,9 +1,9 @@ # htmlxref.cnf - reference file for free Texinfo manuals on the web. # Modified by Ludovic Courtès <ludo@gnu.org> for the GNU Guix manual. -htmlxrefversion=2021-09-24.23; # UTC +htmlxrefversion=2022-04-08.17; # UTC -# Copyright 2010-2020 Free Software Foundation, Inc. +# Copyright 2010-2020, 2022 Free Software Foundation, Inc. # # Copying and distribution of this file, with or without modification, # are permitted in any medium without royalty provided the copyright @@ -414,7 +414,8 @@ guile-gtk node ${GS}/guile-gtk/docs/guile-gtk/ guile-rpc mono ${GS}/guile-rpc/manual/guile-rpc.html guile-rpc node ${GS}/guile-rpc/manual/html_node/ -GUIX = ${GS}/guix/manual +GUIX_ROOT = https://guix.gnu.org +GUIX = ${GUIX_ROOT}/guix/manual guix.de mono ${GUIX}/de/guix.de.html guix.de node ${GUIX}/de/html_node/ guix.es mono ${GUIX}/es/guix.es.html @@ -428,7 +429,7 @@ GUIX = ${GS}/guix/manual guix mono ${GUIX}/en/guix.html guix node ${GUIX}/en/html_node/ -GUIX_COOKBOOK = ${GS}/guix/cookbook +GUIX_COOKBOOK = ${GUIX_ROOT}/cookbook guix-cookbook.de mono ${GUIX_COOKBOOK}/de/guix-cookbook.html guix-cookbook.de node ${GUIX_COOKBOOK}/de/html_node/ guix-cookbook.fr mono ${GUIX_COOKBOOK}/fr/guix-cookbook.html diff --git a/doc/local.mk b/doc/local.mk index c9a8391993..445be17027 100644 --- a/doc/local.mk +++ b/doc/local.mk @@ -22,8 +22,8 @@ # along with GNU Guix. If not, see <http://www.gnu.org/licenses/>. # If adding a language, update the following variables, and info_TEXINFOS. -MANUAL_LANGUAGES = de es fa fi fr it ko pt_BR ru sk zh_CN -COOKBOOK_LANGUAGES = de es fa fi fr ko pt_BR ru sk uk zh_Hans +MANUAL_LANGUAGES = de es fr pt_BR ru zh_CN +COOKBOOK_LANGUAGES = de fr ko sk # Arg1: A list of languages codes. # Arg2: The file name stem. @@ -34,27 +34,15 @@ lang_to_texinfo = $(foreach lang,$(1),%D%/$(2).$(lang).texi) info_TEXINFOS = %D%/guix.texi \ %D%/guix.de.texi \ %D%/guix.es.texi \ - %D%/guix.fa.texi \ - %D%/guix.fi.texi \ %D%/guix.fr.texi \ - %D%/guix.it.texi \ - %D%/guix.ko.texi \ %D%/guix.pt_BR.texi \ %D%/guix.ru.texi \ - %D%/guix.sk.texi \ %D%/guix.zh_CN.texi \ %D%/guix-cookbook.texi \ %D%/guix-cookbook.de.texi \ - %D%/guix-cookbook.es.texi \ - %D%/guix-cookbook.fa.texi \ - %D%/guix-cookbook.fi.texi \ %D%/guix-cookbook.fr.texi \ %D%/guix-cookbook.ko.texi \ - %D%/guix-cookbook.pt_BR.texi \ - %D%/guix-cookbook.ru.texi \ - %D%/guix-cookbook.sk.texi \ - %D%/guix-cookbook.uk.texi \ - %D%/guix-cookbook.zh_Hans.texi + %D%/guix-cookbook.sk.texi %C%_guix_TEXINFOS = \ %D%/contributing.texi \ |