doc: improve manpage markup

2 files changed, 44 insertions, 28 deletions

diff --git a/doc/mpd.1.rst b/doc/mpd.1.rst
index 6a48ad89e..7dbbb1344 100644
--- a/doc/mpd.1.rst
+++ b/doc/mpd.1.rst
@@ -12,48 +12,58 @@ DESCRIPTION
 
 MPD is a daemon for playing music. Music is played through the configured audio output(s) (which are generally local, but can be remote). The daemon stores info about all available music, and this info can be easily searched and retrieved. Player control, info retrieval, and playlist management can all be managed remotely.
 
-MPD searches for a config file in ``$XDG_CONFIG_HOME/mpd/mpd.conf`` then ``~/.mpdconf`` then ``/etc/mpd.conf`` or uses CONF_FILE.
+MPD searches for a config file in ``$XDG_CONFIG_HOME/mpd/mpd.conf``
+then ``~/.mpdconf`` then ``/etc/mpd.conf`` or uses ``CONF_FILE``.
 
-Read more about MPD at ``<http://www.musicpd.org/>``.
+Read more about MPD at http://www.musicpd.org/
 
 OPTIONS
 -------
 
---help
+.. program:: mpd
+
+.. option:: --help
+
   Output a brief help message.
 
---kill
+.. option:: --kill
+
   Kill the currently running mpd session. The pid_file parameter must be specified in the config file for this to work.
 
---no-config
+.. option:: --no-config
+
   Don't read from the configuration file.
 
---no-daemon
+.. option:: --no-daemon
+
   Don't detach from console.
 
---stderr
+.. option:: --stderr
+
   Print messages to stderr.
 
---verbose
+.. option:: --verbose
+
   Verbose logging.
 
---version
+.. option:: --version
+
   Print version information.
 
 FILES
 -----
 
-~/.mpdconf
+:file:`~/.mpdconf`
   User configuration file.
 
-/etc/mpd.conf
+:file:`/etc/mpd.conf`
   Global configuration file.
 
 SEE ALSO
 --------
 
-mpd.conf(5), mpc(1)
+:manpage:`mpd.conf(5)`, :manpage:`mpc(1)`
 
 BUGS
 ----
-If you find a bug, please report it at ``<https://github.com/MusicPlayerDaemon/MPD/issues/>``.
+If you find a bug, please report it at https://github.com/MusicPlayerDaemon/MPD/issues/
diff --git a/doc/mpd.conf.5.rst b/doc/mpd.conf.5.rst
index 37464fc18..03ab90d4e 100644
--- a/doc/mpd.conf.5.rst
+++ b/doc/mpd.conf.5.rst
@@ -6,16 +6,21 @@ mpd.conf
 DESCRIPTION
 ------------
 
-``mpd.conf`` is the configuration file for mpd(1). If not specified on the command line, MPD first searches for it at ``$XDG_CONFIG_HOME/mpd/mpd.conf`` then at ``~/.mpdconf`` then at ``~/.mpd/mpd.conf`` and then in ``/etc/mpd.conf``.
+:file:`mpd.conf` is the configuration file for :manpage:`mpd(1)`. If
+not specified on the command line, MPD first searches for it at
+:file:`$XDG_CONFIG_HOME/mpd/mpd.conf` then at :file:`~/.mpdconf` then
+at :file:`~/.mpd/mpd.conf` and then in :file:`/etc/mpd.conf`.
 
-Lines beginning with a "#" character are comments. All other non-empty lines
-specify parameters and their values. These lines contain the parameter name and
-parameter value (surrounded by double quotes) separated by whitespace (either
-tabs or spaces). For example:
+Lines beginning with a :samp:`#` character are comments. All other
+non-empty lines specify parameters and their values. These lines
+contain the parameter name and parameter value (surrounded by double
+quotes) separated by whitespace (either tabs or spaces).  For
+example::
 
-parameter "value"
+   parameter "value"
 
-The exception to this rule is the audio_output parameter, which is of theform::
+The exception to this rule is the audio_output parameter, which is of
+the form::
 
    audio_output {
    	parameter1 "value"
@@ -25,11 +30,12 @@ The exception to this rule is the audio_output parameter, which is of theform::
 
 Parameters that take a file or directory as an argument should use absolute paths.
 
-See ``docs/mpdconf.example`` in the source tarball for an example configuration file.
+See :file:`docs/mpdconf.example` in the source tarball for an example
+configuration file.
 
 This manual is not complete, it lists only the most important options.
 Please read the MPD user manual for a complete configuration guide:
-``<http://www.musicpd.org/doc/user/>``
+http://www.musicpd.org/doc/user/
 
 
 REQUIRED PARAMETERS
@@ -62,7 +68,7 @@ playlist_directory <directory>
 state_file <file>
    This specifies if a state file is used and where it is located. The state of
    mpd will be saved to this file when mpd is terminated by a TERM signal or by
-   the "kill" command. When mpd is restarted, it will read the state file and
+   the :program:`kill` command. When mpd is restarted, it will read the state file and
    restore the state of mpd (including the playlist).
 
 restore_paused <yes or no>
@@ -117,7 +123,7 @@ audio_output
 
 replaygain <off or album or track or auto>
   If specified, mpd will adjust the volume of songs played using ReplayGain
-  tags (see ``<http://www.replaygain.org/>``). Setting this to "album" will
+  tags (see http://www.replaygain.org/). Setting this to "album" will
   adjust volume using the album's ReplayGain tags, while setting it to "track"
   will adjust it using the track ReplayGain tags. "auto" uses the track
   ReplayGain tags if random play is activated otherwise the album ReplayGain
@@ -154,7 +160,7 @@ REQUIRED AUDIO OUTPUT PARAMETERS
 
 type <type>
   This specifies the audio output type. See the list of supported outputs in
-  mpd --version for possible values.
+  ``mpd --version`` for possible values.
 
 name <name>
   This specifies a unique name for the audio output.
@@ -184,13 +190,13 @@ mixer_type <hardware, software or none>
 FILES
 -----
 
-~/.mpdconf
+:file:`~/.mpdconf`
   User configuration file.
 
-/etc/mpd.conf
+:file:`/etc/mpd.conf`
   Global configuration file.
 
 SEE ALSO
 --------
 
-  mpd(1), mpc(1)
+:manpage:`mpd(1)`, :manpage:`mpc(1)`