Re-tagging 0.13.0 release to fix a couple of bugs with the tarball.

git-svn-id: https://svn.musicpd.org/mpd/tags/release-0.13.0@6325 09075e82-0dd4-0310-85a5-a0d7c8717e4f

5 files changed, 995 insertions, 0 deletions

diff --git a/trunk/doc/COMMANDS b/trunk/doc/COMMANDS
new file mode 100644
index 000000000..652e31511
--- /dev/null
+++ b/trunk/doc/COMMANDS
@@ -0,0 +1,275 @@
+                         Music Player Daemon - Commands
+
+                                    WARNING
+	This document has not been updated to reflect recent changes in
+	the MPD protocol.  It does not contain all supported commands,
+	and some commands may now take additional arguments.  However,
+	clients conforming to this specification should still be
+	compatible with the latest release of MPD.  For more up to date
+	documentation, please see the protocol reference on the wiki at
+	<http://mpd.wikia.com/wiki/Protocol_Reference>.
+
+This document is intended for client developers, not end users.
+
+Format:
+-------
+
+If arguments contain spaces, they should be surrounded by double quotation 
+marks, ".  
+
+command <type arg1> <type arg2> ...
+	explanation: w/ arg1 and arg2
+
+All data between the client and server is encoded in UTF-8. (Note,
+that in UTF-8 all standard ansi characters, 0-127, are the same as a standard
+ansi encoding. Also, no ansi character appears in any multi-byte
+characters.  So, you can use standard C functions like strlen, and strcpy
+just fine with UTF-8 encoded strings. For example: "OK\n" encoded in UTF-8 is
+simply "OK\n".  For more information on UTF=8: 
+http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8 )
+
+Command Completion:
+-------------------
+
+A command returns "OK\n" on completion or "ACK some error\n" on failure.
+These denote the end of command execution.
+
+NOTE:
+-----
+
+For manipulating playlists and playing, there are two sets of commands.  One
+set uses the song id of a song in the playlist, while another set uses the
+playlist position of the song.  The commands using song id's should be used
+instead of the commands that manipulate and control playback based on playlist
+position.  Using song id's is a safer method when multiple clients are 
+interacting with MPD.
+
+Commands:
+---------
+
+add <string path>
+	add the file _path_ to the playlist (directories add recursively)
+	_path_ can also be a single file
+	increments playlist version by for each song added
+
+clear	
+	clears the current playlist
+	increments playlist version by 1
+
+clearerror	
+	clear the current error message in status
+	(this is also accomplished by any command that starts playback)
+
+close
+	close the connection with the MPD
+
+crossfade <int seconds>
+	sets crossfading between songs
+
+currentsong
+	displays the song info of current song (same song that is identified
+	in status)
+
+delete <int song>
+	delete _song_ from playlist
+	increments playlist version by 1
+
+deleteid <int songid>
+	delete song with _songid_ from playlist
+	increments playlist version by 1
+
+find <string type> <string what>
+	finds songs in the db that are exactly _what_
+	_type_ should be "album", "artist", or "title"
+	_what_ is what to find
+
+kill
+	kill MPD
+
+list <string type> <string arg1>
+	list all tags of _type_ 
+	_type_ should be "album" or "artist"
+	_arg1_ is an optional parameter when type is album, this specifies
+		to list albums by a artist, where artist is specified with
+		arg1
+
+listall <string path>
+	lists all songs and directories in _path_ (recursively)
+	_path_ is optional and maybe a directory or path
+
+listallinfo <string path>
+	same as listall command, except it also returns metadata info
+	in the same format as lsinfo
+
+load <string name>
+	loads the playlist _name_.m3u from the playlist directory
+	increments playlist version by the number of songs added
+
+lsinfo <string directory>
+	list contents of _directory_, from the db.  _directory_ is optional
+
+move <int from> <int to>
+	move song at _from_ to _to_ in the playlist
+	increments playlist version by 1
+
+moveid <int songid> <int to>
+	move song with _songid_ to  _to_ in the playlist
+	increments playlist version by 1
+
+next
+	plays next song in playlist
+
+pause	<bool pause>
+	toggle pause/resume playing
+	_pause_ is required and should be 0 or 1
+	NOTE: use of pause command w/o the _pause_ argument is deprecated
+
+password <string password>
+	this is used for authentication with the server.
+	_password_ is simply the plaintext password
+
+ping
+	does nothing but return "OK"
+
+play <int song>
+	begin playing playlist at song number _song_, _song_ is optional
+
+playid <int songid>
+	begin playing playlist at song with _songid_, _songid_ is optional
+
+playlist
+	displays the current playlist
+	NOTE: do not use this, instead use 'playlistinfo'
+
+playlistinfo <int song>
+	displays list of songs in the playlist
+	_song_ is optional and specifies a single song to display info for
+
+playlistid <int songid>
+	displays list of songs in the playlist
+	_songid_ is optional and specifies a single song to display info for
+
+plchanges <playlist version>
+	displays changed songs currently in the playlist since 
+	_playlist version_
+	NOTE: to detect songs that were deleted at the end of the playlist,
+	use playlistlength returned by status command.
+
+plchangesposid <playlist version>
+	displays changed songs currently in the playlist since 
+	_playlist version_
+	This function only returns the position and the id of the changed song, not the complete metadata. This is more bandwidth efficient.
+	NOTE: to detect songs that were deleted at the end of the playlist,
+	use playlistlength returned by status command.
+
+previous
+	plays previous song in playlist
+
+random <int state>
+	set random state to _state_, _state_ should be 0 or 1
+
+repeat <int state>
+	set repeat state to _state_, _state_ should be 0 or 1
+
+rm <string name>
+	removes the playlist <name>.m3u from the playlist directory
+
+save <string name>
+	saves the current playlist to _name_.m3u in the playlist directory
+
+search <string type> <string what>
+	searches for any song that contain _what_
+	_type_ can be "title","artist","album", or "filename"
+	search is not case sensitive
+
+seek <int song> <int time>
+	seeks to the position _time_ (in seconds) of entry _song_ in the 
+	playlist
+
+seekid <int songid> <int time>
+	seeks to the position _time_ (in seconds) of song with _songid_
+
+setvol <int vol>
+	set volume to _vol_
+	_vol_ the range of volume is 0-100
+
+shuffle
+	shuffles the current playlist
+	increments playlist version by 1
+
+stats
+	display stats
+	artists: number of artists
+	albums: number of albums
+	songs: number of songs
+	uptime: daemon uptime in seconds
+	db_playtime: sum of all song times in db
+	db_update: last db update in UNIX time
+	playtime: time length of music played
+
+status
+	reports current status of player, and volume level.
+	volume: (0-100).
+	repeat: (0 or 1)
+	playlist: (31-bit unsigned integer, the playlist version number)
+	playlistlength: (integer, the length of the playlist)
+	state: ("play", "stop", or "pause")
+	song: (current song stopped on or playing, playlist song number)
+	songid: (current song stopped on or playing, playlist songid)
+	time: <int elapsed>:<time total> (of current playing/paused song)
+	bitrate: <int bitrate> (instantaneous bitrate in kbps)
+	xfade: <int seconds> (crossfade in seconds)
+	audio: <int sampleRate>:<int bits>:<int channels>
+	updatings_db: <int job id>
+	error: if there is an error, returns message here
+
+stop
+	stop playing
+
+swap <int song1> <int song2>
+	swap positions of _song1_ and _song2_
+	increments playlist version by 1
+
+swapid <int songid1> <int songid2>
+	swap positions of of songs with song id's of _songid1_ and _songid2_
+	increments playlist version by 1
+
+update <string path>
+	searches mp3 directory for new music and removes old music from the db
+	_path_ is an optional argument that maybe a particular directory or 
+		song/file to update.
+	returned:
+		updating_db: <int job id>
+	where job id, is the job id requested for your update, and is displayed
+	in status, while the requested update is happening
+	increments playlist version by 1
+	NOTE: To update a number of paths/songs at once, use command_list,
+	it will be much more faster/efficient.  Also, if you use a 
+	command_list for updating, only one update_db job id will be returned
+	per sequence of updates.
+
+volume <int change>
+	change volume by amount _change_
+	NOTE: volume command is deprecated, use setvol instead
+
+COMMAND LIST
+------------
+
+To facilitate faster adding of files, etc, you can pass a list of commands all
+at once using a command list.  The command list beings with:
+
+command_list_begin
+
+or:
+
+command_list_ok_begin
+
+And ends with:
+
+command_list_end
+
+It does not execute any commands until the list has ended.  The return
+value is whatever the return for a list of commands is.  On success
+for all commands, OK is returned.  If a command fails, no more commands
+are executed and the appropriate ACK error is returned. If "command_list_ok_begin is used", "list_OK\n" is returned for each successful command executed
+in the command list.
diff --git a/trunk/doc/Makefile.am b/trunk/doc/Makefile.am
new file mode 100644
index 000000000..4fe260180
--- /dev/null
+++ b/trunk/doc/Makefile.am
@@ -0,0 +1,4 @@
+man_MANS = mpd.1 mpd.conf.5
+docdir = $(prefix)/share/doc/$(PACKAGE)
+doc_DATA = COMMANDS mpdconf.example
+EXTRA_DIST = $(man_MANS) $(doc_DATA)
diff --git a/trunk/doc/mpd.1 b/trunk/doc/mpd.1
new file mode 100644
index 000000000..c1ddf1762
--- /dev/null
+++ b/trunk/doc/mpd.1
@@ -0,0 +1,61 @@
+.TH "Music Player Daemon" 1
+.SH NAME
+MPD \- A daemon for playing music
+.SH SYNOPSIS
+.B mpd
+.RI [ options ]
+.RI [ CONF_FILE ]
+.SH 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 \fB~/.mpdconf\fP then \fB/etc/mpd.conf\fP or
+uses CONF_FILE.
+
+Read more about MPD at <\fBhttp://www.musicpd.org/\fP>.
+.SH OPTIONS
+.TP
+.BI --help
+Output a brief help message.
+.TP
+.BI --kill
+Kill the currently running mpd session.  The pid_file parameter must be
+specified in the config file for this to work.
+.TP
+.BI --create-db
+Force (re)creation of database and exit.
+.TP
+.BI --no-create-db
+Do not create database, even if it doesn't exist.
+.TP
+.BI --no-daemon
+Don't detach from console.
+.TP
+.BI --stdout
+Print messages to stdout and stderr.
+.TP
+.BI --verbose
+Verbose logging.
+.TP
+.BI --version
+Print version information.
+.SH FILES
+.TP
+.BI ~/.mpdconf
+User configuration file.
+.TP
+.BI /etc/mpd.conf
+Global configuration file.
+.SH SEE ALSO
+mpd.conf(5), mpc(1)
+.SH BUGS
+If you find a bug, please report it at
+.br
+<\fBhttp://www.musicpd.org/mantis/bug_report_page.php\fP>.
+.SH AUTHORS
+Warren Dukes <warren.dukes@gmail.com>
+
+Special thanks to all the people that provided feedback and patches.
diff --git a/trunk/doc/mpd.conf.5 b/trunk/doc/mpd.conf.5
new file mode 100644
index 000000000..efe95167d
--- /dev/null
+++ b/trunk/doc/mpd.conf.5
@@ -0,0 +1,387 @@
+.TH mpd.conf 5
+.SH NAME
+mpd.conf \- Music Player Daemon configuration file
+.SH DESCRIPTION
+\fBmpd.conf\fP is the configuration file for mpd(1).  If not specified on the
+command line, MPD first searches for it at \fB~/.mpdconf\fP and then in
+\fB/etc/mpd.conf\fP.
+
+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:
+
+parameter "value"
+
+The exception to this rule is the audio_output parameter, which is of the form:
+
+audio_output {
+.br
+        parameter1 "value"
+        parameter2 "value"
+.br
+}
+
+Parameters that take a file or directory as an argument should use absolute
+paths.
+
+See \fBdocs/mpdconf.example\fP in the source tarball for an example
+configuration file.
+.SH REQUIRED PARAMETERS
+.TP
+.B music_directory <directory>
+This specifies the directory where music is located.
+.TP
+.B playlist_directory <directory>
+This specifies the directory where saved playlists are stored.
+.TP
+.B db_file <file>
+This specifies where the db file will be stored.
+.TP
+.B log_file <file>
+This specifies where the log file should be located.
+.TP
+.B error_file <file>
+This specifies where the error file should be located.
+.SH OPTIONAL PARAMETERS
+.TP
+.B pid_file <file>
+This specifies the file to save mpd's process ID in.
+.TP
+.B 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
+restore the state of mpd (including the playlist).
+.TP
+.B user <username>
+This specifies the user that mpd will run as, if set.
+.TP
+.B bind_to_address <ip address or hostname or any>
+This specifies which address mpd binds to and listens on.  Multiple
+bind_to_address parameters may be specified.  The default is "any", which binds
+to all available addresses.
+.TP
+.B port <port>
+This specifies the port that mpd listens on.  The default is 6600.
+.TP
+.B log_level <default, secure, or verbose>
+This specifies how verbose logs are.  "default" is minimal logging, "secure"
+reports from what address a connection is opened, and when it is closed, and
+"verbose" records excessive amounts of information for debugging purposes.  The
+default is "default".
+.TP
+.B zeroconf_name <name>
+If Zerconf is compiled into MPD, this is the service name to publish.  This
+should be unique to your local network, but name collisions will be properly
+dealt with.
+.TP
+.B password <password@permissions>
+This specifies a password for access to mpd.  The format is
+"password@permissions" where permissions is a comma delimited list composed
+of "read", "add", "control", and/or "admin".  "read" allows for reading of the
+database, displaying the current playlist, and current status of mpd.  "add"
+allows for adding songs and loading playlists.  "control" allows for all other
+player and playlist manipulations.  "admin" allows the db to be updated and for
+the client to kill mpd.  An example value is "somePassword@read,add".  Multiple
+password parameters may be specified.
+.TP
+.B default_permissions <permissions>
+This specifies the permissions of a client that has not been authenticated
+using a password.  The format of permissions is specified in the description of
+the "password" config parameter.  If no passwords are specified, the default is
+"read,add,control,admin", otherwise it is "" (no permissions).
+.TP
+.B audio_output
+See \fBDESCRIPTION\fP and the various \fBAUDIO OUTPUT PARAMETERS\fP sections
+for the format of this parameter.  Multiple audio_output sections may be
+specified.  If no audio_output section is specified, then MPD will scan for a
+usable audio output.
+.TP
+.B audio_output_format <sample_rate:bits:channels>
+This specifies the sample rate, bits per sample, and number of channels of
+audio that is sent to each audio output.  Note that audio outputs may specify
+their own audio format which will be used for actual output to the audio
+device.  An example is "44100:16:2" for 44100Hz, 16 bits, and 2 channels.  The
+default is to use the audio format of the input file.
+.TP
+.B samplerate_converter <integer or prefix>
+This specifies the libsamplerate converter to use.  The supplied value should
+either be an integer or a prefix of the name of a converter.  The default is
+"Fastest Sinc Interpolator".
+
+At the time of this writing, the following converters are available:
+.RS
+.TP
+Best Sinc Interpolator (0)
+
+Band limited sinc interpolation, best quality, 97dB SNR, 96% BW.
+.TP
+Medium Sinc Interpolator (1)
+
+Band limited sinc interpolation, medium quality, 97dB SNR, 90% BW.
+.TP
+Fastest Sinc Interpolator (2)
+
+Band limited sinc interpolation, fastest, 97dB SNR, 80% BW.
+.TP
+ZOH Interpolator (3)
+
+Zero order hold interpolator, very fast, very poor quality with audible
+distortions.
+.TP
+Linear Interpolator (4)
+
+Linear interpolator, very fast, poor quality.
+.RE
+.IP
+For an up-to-date list of available converters, please see the libsamplerate
+documentation (available online at <\fBhttp://www.mega-nerd.com/SRC/\fP>).
+.TP
+.B mixer_type <oss, alsa or software>
+This specifies which mixer to use.  The default depends on what audio output
+support mpd was built with.
+.TP
+.B mixer_device <mixer dev>
+This specifies which mixer to use.  The default for oss is "/dev/mixer"; the
+default for alsa is "default".
+.TP
+.B mixer_control <mixer ctrl>
+This specifies which mixer control to use (sometimes referred to as the
+"device").  Examples of mixer controls are PCM, Line1, Master, etc.  An example
+for OSS is "Pcm", and an example for alsa is "PCM".
+.TP
+.B replaygain <album or track>
+If specified, mpd will adjust the volume of songs played using ReplayGain tags
+(see <\fBhttp://www.replaygain.org/\fP>).  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.  Currently only FLAC, Ogg Vorbis,
+Musepack, and MP3 (through ID3v2 ReplayGain tags, not APEv2) are supported.
+.TP
+.B replaygain_preamp <-15 to 15>
+This is the gain (in dB) applied to songs with ReplayGain tags.
+.TP
+.B volume_normalization <yes or no>
+If yes, mpd will normalize the volume of songs as they play.  The default is no.
+.TP
+.B audio_buffer_size <size in KiB>
+This specifies the size of the audio buffer in kibibytes.  The default is 2048,
+large enough for nearly 12 seconds of CD-quality audio.
+.TP
+.B buffer_before_play <0-100%>
+This specifies how much of the audio buffer should be filled before playing a
+song.  Try increasing this if you hear skipping when manually changing songs.
+The default is 10%, a little over 1 second of CD-quality audio with the default
+buffer size.
+.TP
+.B http_buffer_size <size in KiB>
+This specifies the size of the buffer used for playing HTTP streams.  The
+default is 128.
+.TP
+.B http_prebuffer_size <size in KiB>
+This specifies how much of an HTTP stream should be buffered before beginning
+playback.  The default is 32.
+.TP
+.B http_proxy_host <hostname>
+Use to specify the proxy host used for HTTP connections.
+.TP
+.B http_proxy_port <port>
+The port that the HTTP proxy host uses.
+.TP
+.B http_proxy_user <username>
+If the HTTP proxy server requires authentication, this specifies the username.
+.TP
+.B http_proxy_password <password>
+If the HTTP proxy server requires authentication, this specifies the password.
+.TP
+.B connection_timeout <seconds>
+If a client does not send any new data in this time period, the connection is
+closed.  The default is 60.
+.TP
+.B max_connections <number>
+This specifies the maximum number of clients that can be connected to mpd.  The
+default is 5.
+.TP
+.B max_playlist_length <number>
+This specifies the maximum number of songs that can be in the playlist.  The
+default is 4096.
+.TP
+.B max_command_list_size <size in KiB>
+This specifies the maximum size a command list can be.  The default is 2048.
+.TP
+.B max_output_buffer_size <size in KiB>
+This specifies the maximum size of the output buffer to a client.  The default
+is 8192.
+.TP
+.B filesystem_charset <charset>
+This specifies the character set used for the filesystem.  A list of supported
+character sets can be obtained by running "iconv -l".  The default is
+determined from the locale when the db was originally created.
+.TP
+.B id3v1_encoding <charset>
+This specifies the character set which ID3v1 tags are encoded in.  A list of
+supported character sets can be obtained by running "iconv -l".  The default is
+to let libid3tag convert them (from ISO-8859-1, as the standard specifies) and
+do no additional conversion.
+.TP
+.B gapless_mp3_playback <yes or no>
+This specifies whether to support gapless playback of MP3s which have the
+necessary headers.  Useful if your MP3s have headers with incorrect
+information.  If you have such MP3s, it is highly recommended that you fix them
+using vbrfix (available from <http://www.willwap.co.uk/Programs/vbrfix.php>)
+instead of disabling gapless MP3 playback.  The default is to support gapless
+MP3 playback.
+.TP
+.B save_absolute_paths_in_playlists <yes or no>
+This specifies whether relative or absolute paths for song filenames are used
+when saving playlists.  The default is "no".
+.TP
+.B metadata_to_use <tags>
+This specifies the tag types that will be scanned for and made available to
+clients.  Note that you must recreate (not update) your database for changes to
+this parameter to take effect.  Possible values are artist, album, title,
+track, name, genre, date, composer, performer, comment, and disc.  Multiple
+tags may be specified as a comma separated list.  An example value is
+"artist,album,title,track".  The special value "none" may be used alone to
+disable all metadata.  The default is to use all known tag types except for
+comments.
+.SH REQUIRED AUDIO OUTPUT PARAMETERS
+.TP
+.B type <type>
+This specifies the audio output type.  See the list of supported outputs in mpd
+--version for possible values.
+.TP
+.B name <name>
+This specifies a unique name for the audio output.
+.SH OPTIONAL AUDIO OUTPUT PARAMETERS
+.TP
+.B format <sample_rate:bits:channels>
+This specifies the sample rate, bits per sample, and number of channels of
+audio that is sent to the audio output device.  See documentation for the
+\fBaudio_output_format\fP parameter for more details.  The default is to use
+whatever audio format is passed to the audio output.
+.SH OPTIONAL ALSA OUTPUT PARAMETERS
+.TP
+.B device <dev>
+This specifies the device to use for audio output.  The default is "default".
+.TP
+.B use_mmap <yes or no>
+Setting this allows you to use memory-mapped I/O.  Certain hardware setups may
+benefit from this, but most do not.  Most users do not need to set this.  The
+default is to not use memory-mapped I/O.
+.TP
+.B buffer_time <time in microseconds>
+This sets the length of the hardware sample buffer in microseconds.  Increasing
+it may help to reduce or eliminate skipping on certain setups.  Most users do
+not need to change this.  The default is 500000 microseconds (0.5 seconds).
+.TP
+.B period_time <time in microseconds>
+This sets the time between hardware sample transfers in microseconds.
+Increasing this can reduce CPU usage while lowering it can reduce underrun
+errors on bandwidth-limited devices.  Some users have reported good results
+with this set to 50000, but not all devices support values this high.  Most
+users do not need to change this.  The default is 256000000 / sample_rate(kHz),
+or 5804 microseconds for CD-quality audio.
+.SH OPTIONAL OSS OUTPUT PARAMETERS
+.TP
+.B device <dev>
+This specifies the device to use for audio output.  The default is "/dev/dsp".
+.SH OPTIONAL PULSE OUTPUT PARAMETERS
+.TP
+.B server <server list>
+A space separated list of servers to try to connect to.  See
+<\fBhttp://www.pulseaudio.org/wiki/ServerStrings\fP> for more details.  The
+default is to let PulseAudio choose a server.
+.TP
+.B sink <sink>
+The sink to output to.  The default is to let PulseAudio choose a sink.
+.SH REQUIRED JACK OUTPUT PARAMETERS
+.TP
+.B name <name>
+The client name to use when connecting to JACK.  The output ports <name>:left
+and <name>:right will also be created for the left and right channels,
+respectively.
+.SH OPTIONAL JACK OUTPUT PARAMETERS
+.TP
+.B ports <left_port,right_port>
+This specifies the left and right ports to connect to for the left and right
+channels, respectively.  The default is to let JACK choose a pair of ports.
+.TP
+.B ringbuffer_size <size in bytes>
+This specifies the size of the ringbuffer in bytes.  The default is 32768.
+.SH OPTIONAL AO OUTPUT PARAMETERS
+.TP
+.B driver <driver>
+This specifies the libao driver to use for audio output.  Possible values
+depend on what libao drivers are available.  See
+<\fBhttp://www.xiph.org/ao/doc/drivers.html\fP> for information on some
+commonly used drivers.  Typical values for Linux include "oss" and "alsa09".
+The default is "default", which causes libao to select an appropriate plugin.
+.TP
+.B options <opts>
+This specifies the options to use for the selected libao driver.  For oss, the
+only option available is "dsp".  For alsa09, the available options are: "dev",
+"buf_size", and "periods".  See <\fBhttp://www.xiph.org/ao/doc/drivers.html\fP>
+for available options for some commonly used drivers.  Options are assigned
+using "=", and ";" is used to separate options.  An example for oss:
+"dsp=/dev/dsp".  An example for alsa09: "dev=hw:0,0;buf_size=4096".  The
+default is "".
+.TP
+.B write_size <size in bytes>
+This specifies how many bytes to write to the audio device at once.  This
+parameter is to work around a bug in older versions of libao on sound cards
+with very small buffers.  The default is 1024.
+.SH REQUIRED SHOUT OUTPUT PARAMETERS
+.TP
+.B name <name>
+This specifies not only the unique audio output name, but also the stream
+title.
+.TP
+.B host <hostname>
+This specifies the hostname of the icecast server to connect to.
+.TP
+.B port <port>
+This specifies the port of the icecast server to connect to.
+.TP
+.B mount <mountpoint>
+This specifies the icecast mountpoint to use.
+.TP
+.B password <password>
+This specifies the password to use when logging in to the icecast server.
+.TP
+.B quality <quality>
+This specifies the ogg encoding quality to use.  The value must be between 0
+and 10.  Fractional values, such as 2.5, are permitted.  Either the quality or
+the bitrate parameter must be specified, but not both.
+.TP
+.B bitrate <kbps>
+This specifies the bitrate to use for encoding.  Either the quality or the
+bitrate parameter must be specified, but not both.
+.TP
+.B format <sample_rate:bits:channels>
+This specifies the sample rate, bits per sample, and number of channels to use
+for encoding.
+.SH OPTIONAL SHOUT OUTPUT PARAMETERS
+.TP
+.B user <username>
+This specifies the username to use when logging in to the icecast server.  The
+default is "source".
+.TP
+.B public <yes or no>
+This specifies whether to request that the stream be listed in all public
+stream directories that the icecast server knows about.  The default is no.
+.TP
+.B description <description>
+This specifies a description of the stream.
+.TP
+.B genre <genre>
+This specifies the genre(s) of the stream.
+.SH FILES
+.TP
+.BI ~/.mpdconf
+User configuration file.
+.TP
+.BI /etc/mpd.conf
+Global configuration file.
+.SH SEE ALSO
+mpd(1), mpc(1)
diff --git a/trunk/doc/mpdconf.example b/trunk/doc/mpdconf.example
new file mode 100644
index 000000000..8cd367541
--- /dev/null
+++ b/trunk/doc/mpdconf.example
@@ -0,0 +1,268 @@
+# An example configuration file for MPD
+# See the mpd.conf man page for a more detailed description of each parameter.
+
+######################## REQUIRED PATHS ########################
+music_directory                 "~/music"
+playlist_directory              "~/.mpd/playlists"
+db_file                         "~/.mpd/mpd.db"
+log_file                        "~/.mpd/mpd.log"
+error_file                      "~/.mpd/mpd.error"
+################################################################
+
+
+######################## OPTIONAL PATHS ########################
+#
+# If you wish to use mpd --kill to stop MPD, then you must
+# specify a file here in which to store MPD's process ID.
+#
+#pid_file                        "~/.mpd/mpd.pid"
+#
+# If specified, MPD will save its current state (playlist,
+# current song, playing/paused, etc.) at exit.  This will be
+# used to restore the session the next time it is run.
+#
+#state_file                      "~/.mpd/mpdstate"
+#
+################################################################
+
+
+######################## DAEMON OPTIONS ########################
+#
+# If started as root, MPD will drop root privileges and run as
+# this user instead.  Otherwise, MPD will run as the user it was
+# started by.  If left unspecified, MPD will not drop root
+# privileges at all (not recommended).
+#
+#user                            "nobody"
+#
+# The address and port to listen on.
+#
+#bind_to_address                 "any"
+#port                            "6600"
+#
+# Controls the amount of information that is logged.  Can be
+# "default", "secure", or "verbose".
+#
+#log_level                       "default"
+#
+# If Zeroconf is configured, the service name to publish.  This
+# should be unique on your local network, but name collisions
+# will be taken care of for you.
+#
+#zeroconf_name                   "Music Player"
+#
+################################################################
+
+
+########################## PERMISSIONS #########################
+#
+# MPD can require that users specify a password before using it.
+# You may specify one ore more here, along with what users who
+# log in with that password are allowed to do.
+#
+#password                        "password@read,add,control,admin"
+#
+# Specifies what permissions a user who has not logged in with a
+# password has.  By default, all users have full access to MPD
+# if no password is specified above, or no access if one or
+# more passwords are specified.
+#
+#default_permissions             "read,add,control,admin"
+#
+################################################################
+
+
+########################## AUDIO OUTPUT ########################
+#
+# MPD supports many audio output types, as well as playing
+# through multiple audio outputs at the same time.  You can
+# specify one or more here.  If you don't specify any, MPD will
+# automatically scan for a usable audio output.
+#
+# See <http://mpd.wikia.com/wiki/Configuration#Audio_Outputs>
+# for examples of other audio outputs.
+#
+# An example of an ALSA output:
+#
+#audio_output {
+#        type                    "alsa"
+#        name                    "My ALSA Device"
+#        device                  "hw:0,0"     # optional
+#        format                  "44100:16:2" # optional
+#}
+#
+# An example of an OSS output:
+#
+#audio_output {
+#        type                    "oss"
+#        name                    "My OSS Device"
+#        device                  "/dev/dsp"   # optional
+#        format                  "44100:16:2" # optional
+#}
+#
+# An example of a shout output (for streaming to Icecast):
+#
+#audio_output {
+#        type                    "shout"
+#        name                    "My Shout Stream"
+#        host                    "localhost"
+#        port                    "8000"
+#        mount                   "/mpd.ogg"
+#        password                "hackme"
+#        quality                 "5.0"
+#        bitrate                 "128"
+#        format                  "44100:16:1"
+#        user                    "source"                # optional
+#        description             "My Stream Description" # optional
+#        genre                   "jazz"                  # optional
+#        public                  "no"                    # optional
+#}
+#
+# Force all decoded audio to be converted to this format before
+# being passed to the audio outputs.
+#
+#audio_output_format             "44100:16:2"
+#
+# If MPD has been compiled with libsamplerate support, this
+# specifies the sample rate converter to use.  Possible
+# values can be found in the mpd.conf man page or the
+# libsamplerate documentation.
+#
+#samplerate_converter            "Fastest Sinc Interpolator"
+#
+################################################################
+
+
+############################# MIXER ############################
+#
+# MPD needs to know what mixer settings to change when you
+# adjust the volume.  If you don't specify one here, MPD will
+# pick one based on which ones it was compiled with support for.
+#
+# An example for controlling an ALSA mixer:
+#
+#mixer_type                      "alsa"
+#mixer_device                    "default"
+#mixer_control                   "PCM"
+#
+# An example for controlling an OSS mixer:
+#
+#mixer_type                      "oss"
+#mixer_device                    "/dev/mixer"
+#mixer_control                   "PCM"
+#
+# If you want MPD to adjust the volume of audio sent to the
+# audio outputs, you can tell it to use the software mixer:
+#
+#mixer_type                      "software"
+#
+################################################################
+
+
+######################### NORMALIZATION ########################
+#
+# Specifies the type of ReplayGain to use.  Can be "album" or
+# "track".  ReplayGain will not be used if not specified.  See
+# <http://www.replaygain.org> for more details.
+#
+#replaygain                      "album"
+#
+# Sets the pre-amp used for files that have ReplayGain tags.
+#
+#replaygain_preamp               "0"
+#
+# Enable on the fly volume normalization.  This will cause the
+# volume of all songs played to be adjusted so that they sound
+# as though they are of equal loudness.
+#
+#volume_normalization            "no"
+#
+################################################################
+
+
+########################### BUFFERING ##########################
+#
+# The size of the buffer containing decoded audio.  You probably
+# shouldn't change this.
+#
+#audio_buffer_size               "2048"
+#
+# How much of the buffer to fill before beginning to play.
+# Increase this if you hear skipping when changing songs.
+#
+#buffer_before_play              "10%"
+#
+# Similar options for the HTTP stream buffer.  If you hear
+# skipping while playing HTTP streams, you may wish to increase
+# these.
+#
+#http_buffer_size                "128"
+#http_prebuffer_size             "25%"
+#
+################################################################
+
+
+########################### HTTP PROXY #########################
+#
+# Specifies the HTTP proxy to use for playing HTTP streams.
+#
+#http_proxy_host                 "proxy.isp.com"
+#http_proxy_port                 "8080"
+#http_proxy_user                 "user"
+#http_proxy_password             "password"
+#
+################################################################
+
+
+############################# LIMITS ###########################
+#
+# These are various limits to prevent MPD from using too many
+# resources.  You should only change them if they start
+# restricting your usage of MPD.
+#
+#connection_timeout              "60"
+#max_connections                 "5"
+#max_playlist_length             "16384"
+#max_command_list_size           "2048"
+#max_output_buffer_size          "8192"
+#
+################################################################
+
+
+###################### CHARACTER ENCODINGS #####################
+#
+# If file or directory names do not display correctly, then you
+# may need to change this.  In most cases it should be either
+# "ISO-8859-1" or "UTF-8".  You must recreate your database
+# after changing this (use mpd --create-db).
+#
+#filesystem_charset              "ISO-8859-1"
+#
+# The encoding that ID3v1 tags should be converted from.
+#
+#id3v1_encoding                  "ISO-8859-1"
+#
+################################################################
+
+
+######################### OTHER OPTIONS ########################
+#
+# Try disabling this if you have MP3s which appear to end
+# abruptly.  If this solves the problem, it is highly
+# recommended that you fix your MP3s with vbrfix (available from
+# <http://www.willwap.co.uk/Programs/vbrfix.php>), at which
+# point you can re-enable support for gapless MP3 playback.
+#
+#gapless_mp3_playback             "yes"
+#
+# Enable this if you wish to use your MPD created playlists in
+# other music players.
+#
+#save_absolute_paths_in_playlists "no"
+#
+# A list of tag types that MPD will scan for and make available
+# to clients.
+#
+#metadata_to_use                  "artist,album,title,track,name,genre,date,composer,performer,disc"
+#
+################################################################