From 51da7ca095a9ed287221c71933a829d9673a59f6 Mon Sep 17 00:00:00 2001
From: Ludovic Courtès <ludo@gnu.org>
Date: Fri, 11 Jul 2014 22:57:02 +0200
Subject: services: Use more Texinfo markup in docstrings.

* gnu/services/base.scm (host-name-service): Use Texinfo markup.
  (mingetty-service): Comment on #:allow-empty-passwords?.  Improve
  markup.
  (syslog-service, guix-service): Use Texinfo markup.
* gnu/services/networking.scm (static-networking-service): Likewise.
* gnu/services/xorg.scm (slim-service): Likewise.
---
 gnu/services/base.scm       | 20 ++++++++++++--------
 gnu/services/networking.scm |  5 +++--
 gnu/services/xorg.scm       |  9 +++++----
 3 files changed, 20 insertions(+), 14 deletions(-)

(limited to 'gnu/services')

diff --git a/gnu/services/base.scm b/gnu/services/base.scm
index c430586dbf..fb2e2928a6 100644
--- a/gnu/services/base.scm
+++ b/gnu/services/base.scm
@@ -189,7 +189,7 @@ stopped before 'kill' is called."
              (respawn? #f)))))
 
 (define (host-name-service name)
-  "Return a service that sets the host name to NAME."
+  "Return a service that sets the host name to @var{name}."
   (with-monad %store-monad
     (return (service
              (documentation "Initialize the machine's host name.")
@@ -204,6 +204,10 @@ stopped before 'kill' is called."
                            auto-login
                            login-program
                            login-pause?
+
+                           ;; Allow empty passwords by default so that
+                           ;; first-time users can log in when the 'root'
+                           ;; account has just been created.
                            (allow-empty-passwords? #t))
   "Return a service to run mingetty on @var{tty}.
 
@@ -218,7 +222,7 @@ of the log-in program (the default is the @code{login} program from the Shadow
 tool suite.)
 
 @var{motd} is a monadic value containing a text file to use as
-the \"message of the day\"."
+the ``message of the day''."
   (mlet %store-monad ((motd motd)
                       (login-program (cond ((gexp? login-program)
                                             (return login-program))
@@ -277,7 +281,7 @@ the \"message of the day\"."
              (respawn? #f)))))
 
 (define (syslog-service)
-  "Return a service that runs 'syslogd' with reasonable default settings."
+  "Return a service that runs @code{syslogd} with reasonable default settings."
 
   ;; Snippet adapted from the GNU inetutils manual.
   (define contents "
@@ -364,12 +368,12 @@ failed to register hydra.gnu.org public key: ~a~%" status))))))))
 
 (define* (guix-service #:key (guix guix) (builder-group "guixbuild")
                        (build-accounts 10) authorize-hydra-key?)
-  "Return a service that runs the build daemon from GUIX, and has
-BUILD-ACCOUNTS user accounts available under BUILD-USER-GID.
+  "Return a service that runs the build daemon from @var{guix}, and has
+@var{build-accounts} user accounts available under @var{builder-group}.
 
-When AUTHORIZE-HYDRA-KEY? is true, the hydra.gnu.org public key provided by
-GUIX is authorized upon activation, meaning that substitutes from
-hydra.gnu.org are used by default."
+When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key
+provided by @var{guix} is authorized upon activation, meaning that substitutes
+from @code{hydra.gnu.org} are used by default."
   (define activate
     ;; Assume that the store has BUILDER-GROUP as its group.  We could
     ;; otherwise call 'chown' here, but the problem is that on a COW unionfs,
diff --git a/gnu/services/networking.scm b/gnu/services/networking.scm
index 8bb05850e3..ccc322648b 100644
--- a/gnu/services/networking.scm
+++ b/gnu/services/networking.scm
@@ -36,8 +36,9 @@
                                     (name-servers '())
                                     (inetutils inetutils)
                                     (net-tools net-tools))
-  "Return a service that starts INTERFACE with address IP.  If GATEWAY is
-true, it must be a string specifying the default network gateway."
+  "Return a service that starts @var{interface} with address @var{ip}.  If
+@var{gateway} is true, it must be a string specifying the default network
+gateway."
 
   ;; TODO: Eventually we should do this using Guile's networking procedures,
   ;; like 'configure-qemu-networking' does, but the patch that does this is
diff --git a/gnu/services/xorg.scm b/gnu/services/xorg.scm
index c82f4a6aae..7ca0d3f7db 100644
--- a/gnu/services/xorg.scm
+++ b/gnu/services/xorg.scm
@@ -112,11 +112,12 @@ EndSection
                        (xauth xauth) (dmd dmd) (bash bash)
                        startx)
   "Return a service that spawns the SLiM graphical login manager, which in
-turn start the X display server with STARTX, a command as returned by
-'xorg-start-command'.
+turn starts the X display server with @var{startx}, a command as returned by
+@code{xorg-start-command}.
 
-When ALLOW-EMPTY-PASSWORDS? is true, allow logins with an empty password.
-When AUTO-LOGIN? is true, log in automatically as DEFAULT-USER."
+When @var{allow-empty-passwords?} is true, allow logins with an empty
+password.  When @var{auto-login?} is true, log in automatically as
+@var{default-user}."
   (define (slim.cfg)
     (mlet %store-monad ((startx  (or startx (xorg-start-command)))
                         (xinitrc (xinitrc)))
-- 
cgit v1.2.3