doc/user: add brief "troubleshooting" chapter

1 files changed, 265 insertions, 0 deletions

diff --git a/doc/user.xml b/doc/user.xml
index fe67b9332..a27b6be88 100644
--- a/doc/user.xml
+++ b/doc/user.xml
@@ -1462,6 +1462,271 @@ buffer_size: 16384</programlisting>
     </section>
   </chapter>
 
+  <chapter id="troubleshooting">
+    <title>Troubleshooting</title>
+
+    <section id="troubleshooting_start">
+      <title>Where to start</title>
+
+      <para>
+        Make sure you have the latest <application>MPD</application>
+        version (via <command>mpd --version</command>, not
+        <command>mpc version</command>).  All the time, bugs are found
+        and fixed, and your problem might be a bug that is fixed
+        already.  Do not ask for help unless you have the latest
+        <application>MPD</application> version.  The most common
+        excuse is when your distribution ships an old
+        <application>MPD</application> version - in that case, please
+        ask your distribution for help, and not the
+        <application>MPD</application> project.
+      </para>
+
+      <para>
+        Check the log file.  Configure '<varname>log_level</varname>
+        "<parameter>verbose</parameter>"' or pass
+        <parameter>--verbose</parameter> to <filename>mpd</filename>.
+      </para>
+
+      <para>
+        Sometimes, it is helpful to run <application>MPD</application>
+        in a terminal and follow what happens.  This is how to do it:
+      </para>
+
+      <programlisting>mpd --stdout --no-daemon --verbose</programlisting>
+    </section>
+
+    <section id="support">
+      <title>Support</title>
+
+      <section id="help">
+        <title>Getting Help</title>
+
+        <para>
+          The <application>MPD</application> project runs <ulink
+          url="https://forum.musicpd.org/">a forum</ulink> and an IRC
+          channel (<varname>#mpd</varname> on Freenode) for requesting
+          help.  Visit <ulink url="https://www.musicpd.org/help/">the
+          <application>MPD</application> help page</ulink> for details
+          on how to get help.
+        </para>
+      </section>
+
+      <section id="faq">
+        <title>Common Problems</title>
+
+        <qandaset defaultlabel='qanda'>
+          <qandadiv>
+            <title>Database</title>
+
+            <qandaentry>
+              <question>
+                <para>
+                  I can't see my music in the
+                  <application>MPD</application> database!
+                </para>
+              </question>
+              <answer>
+                <itemizedlist>
+                  <listitem>
+                    <para>
+                      Check your <varname>music_directory</varname>
+                      setting.
+                    </para>
+                  </listitem>
+                </itemizedlist>
+                <itemizedlist>
+                  <listitem>
+                    <para>
+                      Does the <application>MPD</application> user
+                      have read permission on all music files, and
+                      read+execute permission on all music directories
+                      (and all of their parent directories)?
+                    </para>
+                  </listitem>
+                </itemizedlist>
+                <itemizedlist>
+                  <listitem>
+                    <para>
+                      Did you update the database?  (<command>mpc
+                      update</command>)
+                    </para>
+                  </listitem>
+                </itemizedlist>
+                <itemizedlist>
+                  <listitem>
+                    <para>
+                      Did you enable all relevant decoder plugins at
+                      compile time?  <command>mpd --version</command>
+                      will tell you.
+                    </para>
+                  </listitem>
+                </itemizedlist>
+              </answer>
+            </qandaentry>
+
+            <qandaentry>
+              <question>
+                <para>
+                  <application>MPD</application> doesn't read ID3
+                  tags!
+                </para>
+              </question>
+              <answer>
+                <para>
+                  You probably compiled <application>MPD</application>
+                  without <filename>libid3tag</filename>.
+                  <command>mpd --version</command> will tell you.
+                </para>
+              </answer>
+            </qandaentry>
+          </qandadiv>
+
+          <qandadiv>
+            <title>Playback</title>
+
+            <qandaentry>
+              <question>
+                <para>I can't hear music on my client!</para>
+              </question>
+              <answer>
+                <para>
+                  That problem usually follows a misunderstanding of the
+                  nature of <application>MPD</application>.
+                  <application>MPD</application> is a remote-controlled
+                  music player, not a music distribution system.
+                  Usually, the speakers are connected to the box where
+                  <application>MPD</application> runs, and the
+                  <application>MPD</application> client only sends
+                  control commands, but the client does not actually
+                  play your music.
+                </para>
+
+                <para>
+                  <application>MPD</application> has output plugins
+                  which allow hearing music on a remote host (such as
+                  <link
+                      linkend="httpd_output"><varname>httpd</varname></link>),
+                  but that is not <application>MPD</application>'s
+                  primary design goal.
+                </para>
+              </answer>
+            </qandaentry>
+
+            <qandaentry>
+              <question>
+                <para>"Device or resource busy"</para>
+              </question>
+              <answer>
+                <para>
+                  This ALSA error means that another program uses your
+                  sound hardware exclusively.  You can stop that
+                  program to allow <application>MPD</application> to
+                  use it.
+                </para>
+                <para>
+                  Sometimes, this other program is
+                  <application>PulseAudio</application>, which can
+                  multiplex sound from several applications, to allow
+                  them to share your sound chip.  In this case, it
+                  might be a good idea for <link
+                  linkend="pulse_output"><application>MPD</application>
+                  to use <application>PulseAudio</application></link>
+                  as well, instead of using ALSA directly.
+                </para>
+              </answer>
+            </qandaentry>
+          </qandadiv>
+        </qandaset>
+      </section>
+    </section>
+
+    <section id="bugs">
+      <title>Reporting Bugs</title>
+
+      <para>
+        If you believe you found a bug in
+        <application>MPD</application>, report it on <ulink
+        url="https://bugs.musicpd.org/my_view_page.php">the bug
+        tracker</ulink>.
+      </para>
+
+      <para>
+        Your bug report should contain:
+      </para>
+
+      <itemizedlist>
+        <listitem>
+          <para>
+            the output of <command>mpd --version</command>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            your <link linkend="config_file">configuration file</link>
+            (<filename>mpd.conf</filename>)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            relevant portions of the log file (--verbose)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            be clear about what you expect MPD to do, and what is
+            actually happening
+          </para>
+        </listitem>
+      </itemizedlist>
+
+      <section id="crash">
+        <title><application>MPD</application> crashes</title>
+
+        <para>
+          All <application>MPD</application> crashes are bugs which
+          must be fixed by a developer, and you should write a bug
+          report.  (Many crash bugs are caused by codec libraries
+          used by <application>MPD</application>, and then that
+          library must be fixed; but in any case, the
+          <application>MPD</application> bug tracker is a good place
+          to report it first if you don't know.)
+        </para>
+
+        <para>
+          A crash bug report needs to contain a "backtrace".
+        </para>
+
+        <para>
+          First of all, your <application>MPD</application> executable
+          must not be "stripped" (i.e. debug information deleted).
+          The executables shipped with Linux distributions are usually
+          stripped, but some have so-called "debug" packages (package
+          <filename>mpd-dbg</filename> or
+          <filename>mpd-dbgsym</filename> on Debian,
+          <filename>mpd-debug</filename> on other distributions).
+          Make sure this package is installed.
+        </para>
+
+        <para>
+          You can extract the backtrace from a core dump, or by
+          running <application>MPD</application> in a debugger, e.g.:
+        </para>
+
+        <programlisting>gdb --args mpd --stdout --no-daemon --verbose
+run</programlisting>
+
+        <para>
+          As soon as you have reproduced the crash, type
+          "<command>bt</command>" on the <filename>gdb</filename>
+          command prompt.  Copy the output to your bug report.
+        </para>
+      </section>
+    </section>
+  </chapter>
+
   <chapter id="plugin_reference">
     <title>Plugin reference</title>