--- a/src/upmpdcli.conf-dist
+++ b/src/upmpdcli.conf-dist
@@ -1,193 +1,273 @@
-# Configuration file for upmpdcli, the UPnP Media Renderer front-end to MPD
-
-# Note: the command line options have higher priorities than the values in
-# this file.
-
-# Host MPD runs on. Defaults to localhost. This can also be specified as -h host
+# <filetitle>Configuration parameters for upmpdcli</filetitle>
+
+# <note>Note: the command line options have higher priorities than the
+# values in this file.</note>
+
+# <grouptitle>MPD parameters</grouptitle>
+
+# <var name="mpdhost"><brief>Host MPD runs on.</brief>
+# <descr>Defaults to localhost. This can also be specified as -h
+# host</descr></var>
#mpdhost = localhost
-# Port for MPD. Can also be specified as -p port
+# <var name="mpdport"><brief>IP port used by MPD</brief>. <descr>Can
+# also be specified as -p port. Defaults to the normal MPD port,
+# 6600</descr></var>
#mpdport = 6600
-# MPD password
+# <var name="mpdpassword"><brief>MPD password.</brief><descr>Password for
+# connecting to *MPD* (only necessary if password access is enabled in the
+# *MPD* configuration file).</descr></var>
#mpdpassword =
-# Displayed "Friendly Name" for the UPnP Media Renderer
+# <grouptitle>Upmpdcli general parameters</grouptitle>
+
+# <var name="friendlyname"><brief>"Friendly Name" for the UPnP Media
+# Renderer.</brief><descr>This will be displayed by most Control Points to
+# identify the Renderer. Some OpenHome Control Points may display the
+# 'ohproductroom' value instead.</descr></var>
#friendlyname = UpMpd
-# Log file name. Defaults to stderr. This can also be specified as
-# -d logfilename
+# <var name="upnpav"><brief>Enable UPnP AV services
+# (0/1).</brief><descr>This is set by default, but it may useful to switch
+# it off with some OpenHome Control Points which are too easily confused by
+# the presence of UPnP AV services.</descr></var>
+#upnpav = 1
+
+# <var name="openhome"><brief>Enable OpenHome services
+# (0/1).</brief><descr>This defaults to 1, as OpenHome queuing is superior
+# for most usages. There should be little reason to turn it
+# off.</descr></var>
+openhome = 1
+
+# <var name="logfilename"><brief>Log file name.</brief><descr>Defaults to
+# stderr. This can also be specified as -d logfilename.</descr></var>
#logfilename =
-# Log level. 0-4. Can also be specified as -l loglevel.
+# <var name="loglevel"><brief>Log level. 0-4.</brief><descr>Can also be
+# specified as -l loglevel.</descr></var>
#loglevel = 3
-# You can set a path to an icon here. The icon will be displayed by a control
-# point. The icon will only be read once, when upmpdcli starts up.
-# iconpath = /usr/share/upmpdcli/icon.png
-
-# You can set a path to an html file here, to replace the default
+# <var name="iconpath"><brief>Path to the Renderer icon.</brief>
+# <descr>The image will be displayed by Control Points which support
+# it. The UPnP protocol has provisions for a renderer to send the URL to a
+# descriptive icon as part of the device description. Due to current (and
+# probably permanent) *upmpdcli* limitations, the image file *must* be a
+# 64x64 32 bits-per-pixel png file. Default: '$pkgdatadir/icon.png'.
+# The icon will only be read once, when upmpdcli starts
+# up.</descr></var>
+#iconpath = /usr/share/upmpdcli/icon.png
+
+# <var name="pkgdatadir"><brief>XML and other constant data storage
+# directory.</brief><descr>Default: '$prefix/share/upmpcli' (e.g.:
+# '/usr/share/upmpdcli').</descr></var>
+#pkgdatadir=/usr/share/upmpdcli
+
+# <var name="cachedir"><brief>Directory used to store cached
+# data</brief><descr>Only used for the OpenHome queue metadata for now.
+# The default value is ~/.cache/upmpdcli for normal users or
+# /var/cache/upmpdcli when upmpdcli is started as root.</descr></var>
+#cachedir = /var/cache/upmpdcli
+
+# <var name="presentationhtml"><brief>Path to the presentation HTML
+# document</brief><descr>You can change it to replace the default
# presentation page. The page will only be read once, when upmpdcli starts
-# up.
-# presentationhtml = /usr/share/upmpdcli/presentation.html
-
-# Network interface to use for UPnP.
+# up. It can't presently be used for status updates (but I guess that you
+# could put a redirect in there, to something more dynamic served by a real
+# HTTP server). Default: '$pkgdatadir/presentation.html'.</descr></var>
+#presentationhtml = /usr/share/upmpdcli/presentation.html
+
+# <var name="pidfile"><brief>Name of lock file used to store the current
+# process pid.</brief><descr>Only used if the process is launched by user
+# root. Used by the init system, and to avoid multiple instances. The only
+# reason to change the value is if you actually want to have several
+# instances running (also change cachedir in this case).</descr></var>
+#pidfile = /var/run/upmpdcli.pid
+
+# <grouptitle>UPnP network parameters</grouptitle>
+
+# <var name="upnpiface"><brief>Network interface to use for
+# UPnP.</brief><descr>libupnp/pupnp only supports communicating on a single
+# interface and will use the first found, this allows forcing the use of
+# another interface.</descr></var>
#upnpiface =
-# IP address to use for UPnP. Alternative to using an interface name
+
+# <var name="upnpip"><brief>IP address to use for UPnP,
+# alternative to using an interface name.</brief></var>
#upnpip =
-# Port number used for UPnP.
+
+# <var name="upnpport"><brief>Port number used for
+# UPnP.</brief><descr>libupnp/pupnp defaults to using the first free port
+# after 49152. Note that clients do not need to know about the value, which
+# is automatically discovered.</descr></var>
#upnpport =
-# Enable UPnP AV services. This is set by default, but it may useful to
-# disable it with some pure OpenHome Control Points.
-# upnpav = 1
-
-# Decide if we offer the OpenHome services. 0 or 1.
-# The default is 'yes' as OpenHome queuing is superior for most usages.
-openhome = 1
-
-# Save queue metadata to disk to allow persistence across restart, like
-# MPD.
+# <grouptitle>Audio control hooks</grouptitle>
+
+# <var name="onstart"><brief>Command to run when playback is about to
+# begin.</brief><descr>Specify the full path to the
+# program, e.g. /usr/bin/logger.</descr></var>
+#onstart =
+
+# <var name="onplay"><brief>Command to run when MPD state switches to "PLAY".
+# </brief><descr>Specify the full path to the program,
+# e.g. /usr/bin/logger.</descr></var>
+# onplay =
+
+# <var name="onstop"><brief>Command to run when MPD state switches to
+# "STOP".</brief><descr>Specify the full path to the program,
+# e.g. /usr/bin/logger.</descr></var>
+#onstop =
+
+# <var name="externalvolumecontrol"><brief>Use external commands to manage
+# the the sound volume (0/1).</brief><descr>This is used in the case where MPD
+# is unable to control the volume, but some other command can, for example
+# if you have an external amp on which it is possible to set and read the
+# volume through scripts. If set, the calls to MPD to set and read the volume
+# will be replaced by executions of 'onvolumechange' and
+# 'getexternalvolume'</descr></var>
+#externalvolumecontrol =
+
+# <var name="getexternalvolume"><brief>Command to run for reading the sound
+# volume.</brief><descr>The command should write a 0-100 numeric value to
+# stdout.</descr></var>
+#getexternalvolume =
+
+# <var name="onvolumechange"><brief>Command to run to set the
+# volume.</brief><descr>Used when 'externalvolumecontrol' is set.
+# Specify the full path to the program, which is called with the volume as
+# the first argument, e.g. /some/script 85.</descr></var>
+#onvolumechange =
+
+# <grouptitle>OpenHome parameters</grouptitle>
+
+# <var name="ohmanufacturername"><brief>Manufacturer name. Does not vary at
+# run-time.</brief></var>
+#ohmanufacturername = UpMPDCli heavy industries Co.
+# <var name="ohmanufacturerinfo"><brief>Manufacturer information. Does not
+# vary at run-time.</brief></var>
+#ohmanufacturerinfo = Such nice guys and gals
+# <var name="ohmanufacturerurl"><brief>URL for manufacturer web site. Does
+# not vary at run-time.</brief></var>
+#ohmanufacturerurl = http://www.lesbonscomptes.com/upmpdcli
+# <var name="ohmanufacturerimageuri"><brief>Uri for manufacturer���s logo. Does
+# not vary at run-time.</brief></var>
+#ohmanufacturerimageuri =
+# <var name="ohmodelname"><brief>Model name. Does not vary at
+# run-time.</brief></var>
+#ohmodelname = UpMPDCli UPnP-MPD gateway
+# <var name="ohmodelinfo"><brief>Model information. Does not vary at
+# run-time.</brief></var>
+#ohmodelinfo =
+# <var name="ohmodelurl"><brief>URL for model web site. Does not vary at
+# run-time.</brief></var>
+#ohmodelurl = http://www.lesbonscomptes.com/upmpdcli
+# <var name="ohmodelimageuri"><brief>Uri for model���s icon. Does not vary at
+# run-time.</brief></var>
+#ohmodelimageuri =
+# <var name="ohproductname"><brief>User-visible product name. By default
+# this is set to ModelName.</brief></var>
+#ohproductname = Upmpdcli
+# <var name="ohproductroom"><brief>The name of the room where the Product
+# is located.</brief><descr>Set to ���Main Room��� by default, displayed in
+# place of the "friendly name" by some control points. ProductRoom is used
+# to group the Product with other related Products in the same physical
+# room (e.g. a source with a pre-amp). Products which are physically linked
+# must always share the same ProductRoom name.</descr></var>
+#ohproductroom = Main Room
+# <var name="ohproductinfo"><brief>Product information. Does not vary at
+# run-time.</brief></var>
+#ohproductinfo =
+# <var name="ohproducturl"><brief>URL for product web site. This may be the
+# UPnP presentation page.</brief></var>
+#ohproducturl =
+# <var name="ohproductimageuri"><brief>Uri for product image. Does not vary
+# at run-time.</brief></var>
+#ohproductimageuri =
+
+# <var name="ohmetapersist"><brief>Save queue metadata to disk
+# (0/1).</brief><descr>This allows persistence of the metadata information
+# across restarts, the default is 1, and there is no reason to turn it
+# off.</descr></var>
ohmetapersist = 1
-# Directory used to store cached data (only the queue metadata for now).
-# Default is ~/.cache/upmpdcli for normal users or /var/cache/upmpdcli when
-# started as root
-# cachedir = /var/cache/upmpdcli
-
-# Name of lock file used to store the current process pid. Only used if the
-# process is launched by user root. Used by the init system, and to avoid
-# multiple instances. The only reason to change the value is if you
-# actually want to have several instances running (also change cachedir in
-# this case).
-# pidfile = /var/run/upmpdcli.pid
-
-# Mimimum interval (Seconds) between 2 saves of the cache. Setting this may
-# improve playlist load speed on a slow device. The default is to start a
-# new save as soon as the previous one is done (if the list changed again
-# inbetween).
-# ohmetasleep = 0
-
-# Run a command when playback is about to begin. Specify the full path to the
-# program, e.g. /usr/bin/logger. Executable scripts work, but must have a
-# #!/bin/sh (or whatever) in the headline.
-# onstart =
-
-# Run a command when playback is about to begin. Specify the full path to the
-# program, e.g. /usr/bin/logger. Executable scripts work, but must have a
-# #!/bin/sh (or whatever) in the headline.
-# onplay =
-
-# Run a command when playback is about to end. Specify the full path to the
-# program, e.g. /usr/bin/logger. Executable scripts work, but must have a
-# #!/bin/sh (or whatever) in the headline.
-# onstop =
-
-# volume control can be done via mpd using alsa mixer controls. If you have an external amp
-# and it is capable of setting and reading volume via a script you can activate
-# externalvolumecontrol. No volumes will be set via mpd anylonger. It will call
-# scripts onvolumechange for setting and getexternalvolume for reading recent volume.
-# externalvolumecontrol =
-
-# Run a command for reading volume from external device. upmpdcli will read
-# volume from stdout of the script given.
-# getexternalvolume =
-
-# Run a command when volume is changed. Specify the full path to the program,
-# e.g. /usr/bin/logger. Executable scripts work, but must have a #!/bin/sh (or
-# whatever) in the headline.
-# The command is called with the volume as the first argument, e.g.
-# <command> 85.
-# onvolumechange =
-
-### Parameters for the OpenHome Product service
-# Manufacturer name. Does not vary at run-time.
-#ohmanufacturername = UpMPDCli heavy industries Co.
-# Manufacturer information. Does not vary at run-time.
-#ohmanufacturerinfo = Such nice guys and gals
-# URL for manufacturer web site. Does not vary at run-time.
-#ohmanufacturerurl = http://www.lesbonscomptes.com/upmpdcli
-# Uri for manufacturer���s logo. Does not vary at run-time.
-#ohmanufacturerimageuri =
-# Model name. Does not vary at run-time.
-#ohmodelname = UpMPDCli UPnP-MPD gateway
-# Model information. Does not vary at run-time.
-#ohmodelinfo =
-# URL for model web site. Does not vary at run-time.
-#ohmodelurl = http://www.lesbonscomptes.com/upmpdcli
-# Uri for model���s icon. Does not vary at run-time.
-#ohmodelimageuri =
-# User-visible product name. By default this is set to ModelName.
-#ohproductname = Upmpdcli
-# The name of the room where the Product is located. Set to ���Main Room��� by
-# default.
-# ProductRoom is used to group the Product with other related Products in the
-# same physical room (e.g. a source with a pre-amp). Products which are
-# physically linked must always share the same ProductRoom name.
-#ohproductroom = Main Room
-# Product information. Does not vary at run-time.
-#ohproductinfo =
-# URL for product web site. This may be the UPnP presentation page.
-#ohproducturl =
-# Uri for product image. Does not vary at run-time.
-#ohproductimageuri =
-
-### Parameters for the Songcast modes. These are read by either/both the
-### songcast and upmpdcli.
-
-# Log file name for sc2mpd (default stderr), and level. The file must
-# *not* be the same as the one used for upmpdcli
+# <var name="ohmetasleep"><brief>Mimimum interval (Seconds) between two
+# cache saves.</brief><descr>Increasing this may improve playlist load
+# speed on a slow device. The default is to start a new save as soon as the
+# previous one is done (if the list changed again inbetween).</descr></var>
+#ohmetasleep = 0
+
+# <grouptitle>Songcast Receiver parameters</grouptitle>
+
+# Parameters for the Songcast modes. These are read by either/both the
+# songcast and upmpdcli processes
+
+# <var name="sclogfilename"><brief>Log file name for sc2mpd (default
+# stderr)</brief><descr>The value *must not* be the same as the one used
+# for upmpdcli.</descr></var>
#sclogfilename = /tmp/scmpdcli.log
+
+# <var name="scloglevel"><brief>Log verbosity for sc2mpd.</brief></var>
#scloglevel = 6
-# Play method. This can be either mpd or alsa. alsa is the only way to
-# really avoid skips (and control the synchronization in multi-room setups).
+# <var name="scplaymethod"><brief>sc2mpd play method
+# (mpd/alsa).</brief><descr>With this set as 'alsa', sc2mpd will send the
+# audio directly to the sound driver, which is the only way to really avoid
+# skips and control the synchronization in multi-room setups.</descr></var>
#scplaymethod = mpd
-# For the mpd play method only: port for connections from MPD to
-# sc2mpd. The latter only accepts connections from localhost.
+# <var name="schttpport"><brief>Port used by sc2mpd for MPD to connect
+# to.</brief><descr>Used only for scplaymethod=mpd. sc2mpd only accepts
+# connections from localhost.</descr></var>
#schttpport = 8768
-# For the alsa play method only: Alsa device to use
+# <var name="scalsadevice"><brief>Alsa device used by sc2mpd for playing
+# audio.</brief><descr>Only used for scplaymethod=alsa. Use 'aplay -L' to
+# see the possible values.</descr></var>
#scalsadevice = default
-# Resampling method. The default is SRC_SINC_FASTEST and works on a
-# Rasberry Pi.
-# Possible values: SRC_SINC_BEST_QUALITY SRC_SINC_MEDIUM_QUALITY
-# SRC_SINC_FASTEST SRC_ZERO_ORDER_HOLD SRC_LINEAR
-# See libsamplerate doc for descriptions. Anything above SRC_SINC_FASTEST
-# needs a serious CPU
-# BEST_QUALITY uses approx 25% cpu on a core i7 4770T. Obviously too much,
-# actually might not be sustainable (it's almost 100% of 1 cpu)
-# MEDIUM_QUALITY is around 10% on the same machine, FASTEST is 4-5%. Given
-# that this measured for the full process, probably a couple % for the
-# conversion in fact.
-# Raspberry Pi: FASTEST is 30% CPU on a Pi2 with USB audio. It's
-# 25-30% on a Pi 1 with i2s audio.
-# sccvttype = SRC_SINC_FASTEST.
-
-# Path to sc2mpd if it is not in /usr/bin and the location is not in the
-# PATH for the init scripts.
+# <var name="sccvttype"><brief>sc2mpd resampling method.</brief><descr>
+# Only used for scplaymethod=alsa. sc2mpd uses libsamplerate. The default
+# method is SRC_SINC_FASTEST and a Rasberry Pi 1 is fast enough to use it.
+# Possible values: SRC_SINC_BEST_QUALITY, SRC_SINC_MEDIUM_QUALITY,
+# SRC_SINC_FASTEST, SRC_ZERO_ORDER_HOLD, SRC_LINEAR. See the libsamplerate
+# documentation for descriptions. Anything above SRC_SINC_FASTEST needs a
+# serious CPU. BEST_QUALITY uses approx 25% cpu on a core i7
+# 4770T. Obviously too much, actually might not be sustainable (it's almost
+# 100% of 1 cpu). MEDIUM_QUALITY is around 10% on the same machine,
+# FASTEST is 4-5%. Given that this is measured for the full process, probably
+# a couple % for the conversion in fact.</descr></var>
+#sccvttype = SRC_SINC_FASTEST.
+
+# <var name="sc2mpd"><brief>Path to sc2mpd.</brief><descr>Only useful if it
+# is not in /usr/bin and the location is not in the $PATH for the init
+# scripts.</descr></var>
#sc2mpd = /usr/bin/sc2mpd
-## Parameters tor the Sender/Receiver mode. Only does anything if
-## scplaymethod is alsa
-
-# Path to the script which starts the auxiliary mpd and the sender process
+# <grouptitle>Songcast Sender parameters</grouptitle>
+
+# Parameters tor the Sender/Receiver mode. Only does anything if
+# scplaymethod is alsa
+
+# <var name="scsenderpath"><brief>Path to the script which starts the
+# auxiliary mpd and the sender process.</brief></var>
#scsenderpath = /usr/bin/scmakempdsender
-# Decide if we scale the songcast stream (apply software volume control to
-# it). True by default, the volume set from a control point on the upmpdcli
-# instance which started the sender affects the volume for all receivers.
+# <var name="scstreamscaled"><brief>Decide if we scale the songcast
+# stream.</brief><descr>If set, MPD software volume control will be applied
+# to the stream. True by default: using a Control Point to set the volume
+# on the upmpdcli instance which started the Sender affects the volume for
+# all Receivers.</descr></var>
#scstreamscaled = 1
-# localhost port to use by the auxiliary mpd
+# <var name="scsendermpdport"><brief>localhost port to use by the auxiliary
+# mpd.</brief></var>
#scsendermpdport = 6700
-# Scripts_dir holds scripts to set up additional external sources. See the
-# documentation.
+# <var name="scripts_dir"><brief>Location for the scripts used to set up
+# additional external sources.</brief><descr>See the Songcast Sender
+# support documentation page.</descr></var>
#scripts_dir = /usr/share/upmpdcli/src_scripts
-
# Initial / default List of radios borrowed from misc sources. Edit to taste
#