Merge branch 'master' into gnome-team

1 files changed, 71 insertions, 32 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 585baf358f..58cc3d7aad 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -34241,36 +34241,57 @@ The Music Player Daemon (MPD) is a service that can play music while
 being controlled from the local machine or over the network by a variety
 of clients.
 
-The following example shows how one might run @code{mpd} as user
-@code{"bob"} on port @code{6666}.  It uses pulseaudio for output.
+The following example shows the simplest configuration to locally
+expose, via PulseAudio, a music collection kept at @file{/srv/music},
+with @command{mpd} running as the default @samp{mpd} user.  This user
+will spawn its own PulseAudio daemon, which may compete for the sound
+card access with that of your own user.  In this configuration, you may
+have to stop the playback of your user audio applications to hear MPD's
+output and vice-versa.
 
 @lisp
 (service mpd-service-type
          (mpd-configuration
-          (user "bob")
-          (port "6666")))
+          (music-directory "/srv/music")))
 @end lisp
 
+@quotation Important
+The music directory must be readable to the MPD user, by default,
+@samp{mpd}.  Permission problems will be reported via @samp{Permission
+denied} errors in the MPD logs, which appear in @file{/var/log/messages}
+by default.
+@end quotation
+
+Most MPD clients will trigger a database update upon connecting, but you
+can also use the @code{update} action do to so:
+
+@example
+herd update mpd
+@end example
+
+All the MPD configuration fields are documented below, and a more
+complex example follows.
+
 @defvar mpd-service-type
 The service type for @command{mpd}
 @end defvar
 
+@c %start of fragment
 @deftp {Data Type} mpd-configuration
-Data type representing the configuration of @command{mpd}.
+Available @code{mpd-configuration} fields are:
 
 @table @asis
 @item @code{package} (default: @code{mpd}) (type: file-like)
 The MPD package.
 
-@item @code{user} (default: @code{%mpd-user}) (type: user-account)
+@item @code{user} (type: user-account)
 The user to run mpd as.
 
-The default @code{%mpd-user} is a system user with the name ``mpd'',
-who is a part of the group @var{group} (see below).
-@item @code{group} (default: @code{%mpd-group}) (type: user-group)
+@item @code{group} (type: user-group)
 The group to run mpd as.
 
 The default @code{%mpd-group} is a system group with name ``mpd''.
+
 @item @code{shepherd-requirement} (default: @code{'()}) (type: list-of-symbol)
 A list of symbols naming Shepherd services that this service
 will depend on.
@@ -34278,24 +34299,31 @@ will depend on.
 @item @code{environment-variables} (default: @code{'("PULSE_CLIENTCONFIG=/etc/pulse/client.conf" "PULSE_CONFIG=/etc/pulse/daemon.conf")}) (type: list-of-strings)
 A list of strings specifying environment variables.
 
-@item @code{log-file} (default: @code{"/var/log/mpd/log"}) (type: maybe-string)
-The location of the log file.  Set to @code{syslog} to use the local
-syslog daemon or @code{%unset-value} to omit this directive from the
-configuration file.
+@item @code{log-file} (type: maybe-string)
+The location of the log file.  Unless specified, logs are sent to the
+local syslog daemon.  Alternatively, a log file name can be specified,
+for example @file{/var/log/mpd.log}.
 
 @item @code{log-level} (type: maybe-string)
-Suppress any messages below this threshold.  Available values:
-@code{notice}, @code{info}, @code{verbose}, @code{warning} and
-@code{error}.
+Supress any messages below this threshold.  The available values, in
+decreasing order of verbosity, are: @code{verbose}, @code{info},
+@code{notice}, @code{warning} and @code{error}.
 
 @item @code{music-directory} (type: maybe-string)
 The directory to scan for music files.
 
+@item @code{music-dir} (type: maybe-string)
+The directory to scan for music files.
+
 @item @code{playlist-directory} (type: maybe-string)
 The directory to store playlists.
 
+@item @code{playlist-dir} (type: maybe-string)
+The directory to store playlists.
+
 @item @code{db-file} (type: maybe-string)
-The location of the music database.
+The location of the music database.  When left unspecified,
+@file{~/.cache/db} is used.
 
 @item @code{state-file} (type: maybe-string)
 The location of the file that stores current MPD's state.
@@ -34303,15 +34331,19 @@ The location of the file that stores current MPD's state.
 @item @code{sticker-file} (type: maybe-string)
 The location of the sticker database.
 
-@item @code{default-port} (default: @code{6600}) (type: maybe-integer)
+@item @code{default-port} (default: @code{6600}) (type: maybe-port)
 The default port to run mpd on.
 
 @item @code{endpoints} (type: maybe-list-of-strings)
-The addresses that mpd will bind to.  A port different from @var{default-port}
-may be specified, e.g. @code{localhost:6602} and IPv6 addresses must be
-enclosed in square brackets when a different port is used.
-To use a Unix domain socket, an absolute path or a path starting with @code{~}
-can be specified here.
+The addresses that mpd will bind to.  A port different from
+@var{default-port} may be specified, e.g.  @code{localhost:6602} and
+IPv6 addresses must be enclosed in square brackets when a different port
+is used.  To use a Unix domain socket, an absolute path or a path
+starting with @code{~} can be specified here.
+
+@item @code{address} (type: maybe-string)
+The address that mpd will bind to.  To use a Unix domain socket, an
+absolute path can be specified here.
 
 @item @code{database} (type: maybe-mpd-plugin)
 MPD database plugin configuration.
@@ -34328,6 +34360,10 @@ List of MPD input plugin configurations.
 @item @code{archive-plugins} (default: @code{'()}) (type: list-of-mpd-plugin)
 List of MPD archive plugin configurations.
 
+@item @code{auto-update?} (type: maybe-boolean)
+Whether to automatically update the music database when files are
+changed in the @var{music-directory}.
+
 @item @code{input-cache-size} (type: maybe-string)
 MPD input cache size.
 
@@ -34353,6 +34389,7 @@ appended to the configuration.
 
 @end table
 @end deftp
+@c %end of fragment
 
 @deftp {Data Type} mpd-plugin
 Data type representing a @command{mpd} plugin.
@@ -34392,8 +34429,9 @@ Partitions} for available options.
 @end table
 @end deftp
 
+@c %start of fragment
 @deftp {Data Type} mpd-output
-Data type representing a @command{mpd} audio output.
+Available @code{mpd-output} fields are:
 
 @table @asis
 @item @code{name} (default: @code{"MPD"}) (type: string)
@@ -34420,15 +34458,16 @@ is only useful for output plugins that can receive tags, for example the
 
 @item @code{always-on?} (default: @code{#f}) (type: boolean)
 If set to @code{#t}, then MPD attempts to keep this audio output always
-open.  This may be useful for streaming servers, when you don?t want to
+open.  This may be useful for streaming servers, when you don’t want to
 disconnect all listeners even when playback is accidentally stopped.
 
-@item @code{mixer-type} (default: @code{"none"}) (type: string)
+@item @code{mixer-type} (type: maybe-string)
 This field accepts a string that specifies which mixer should be used
 for this audio output: the @code{hardware} mixer, the @code{software}
 mixer, the @code{null} mixer (allows setting the volume, but with no
 effect; this can be used as a trick to implement an external mixer
-External Mixer) or no mixer (@code{none}).
+External Mixer) or no mixer (@code{none}).  When left unspecified, a
+@code{hardware} mixer is used for devices that support it.
 
 @item @code{replay-gain-handler} (type: maybe-string)
 This field accepts a string that specifies how
@@ -34443,6 +34482,7 @@ appended to the audio output configuration.
 
 @end table
 @end deftp
+@c %end of fragment
 
 The following example shows a configuration of @command{mpd} that
 configures some of its plugins and provides a HTTP audio streaming output.
@@ -34540,11 +34580,10 @@ HTTP port to listen on.
 How much detail to include in logs, possible values: @code{0} to
 @code{7}.
 
-@item @code{log-to} (default: @code{"/var/log/mympd/log"}) (type: string-or-symbol)
-Where to send logs.  By default, the service logs to
-@file{/var/log/mympd.log}.  The alternative is @code{'syslog}, which
-sends output to the running syslog service under the @samp{daemon}
-facility.
+@item @code{log-to} (type: maybe-string)
+Where to send logs.  Unless specified, the service logs to the local
+syslog service under the @samp{daemon} facility.  Alternatively, a log
+file name can be specified, for example @file{/var/log/mympd.log}.
 
 @item @code{lualibs} (default: @code{"all"}) (type: maybe-string)
 See