From 2a716b7a7a4302414b4a4dfaa86c7cf18a181731 Mon Sep 17 00:00:00 2001
From: Max Kellermann <max@duempel.org>
Date: Fri, 10 Oct 2014 23:20:50 +0200
Subject: doc: document the mount/neighbor commands

---
 NEWS             |   3 +-
 doc/protocol.xml | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/user.xml     |  83 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 192 insertions(+), 1 deletion(-)

diff --git a/NEWS b/NEWS
index 75f995222..e5cc341d0 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,7 @@
 ver 0.19 (not yet released)
 * protocol
-  - new commands "addtagid", "cleartagid", "listfiles", "rangeid"
+  - new commands "addtagid", "cleartagid", "listfiles", "listmounts",
+    "listneighbors", "mount", "rangeid", "unmount"
   - "lsinfo" and "readcomments" allowed for remote files
   - "listneighbors" lists file servers on the local network
   - "playlistadd" supports file:///
diff --git a/doc/protocol.xml b/doc/protocol.xml
index 5e2043d48..858ca0990 100644
--- a/doc/protocol.xml
+++ b/doc/protocol.xml
@@ -1892,6 +1892,113 @@ OK
       </variablelist>
     </section>
 
+    <section id="mount">
+      <title>Mounts and neighbors</title>
+
+      <para>
+        A "storage" provides access to files in a directory tree.  The
+        most basic storage plugin is the "local" storage plugin which
+        accesses the local file system, and there are plugins to
+        access NFS and SMB servers.
+      </para>
+
+      <para>
+        Multiple storages can be "mounted" together, similar to the
+        <application>mount</application> command on many operating
+        systems, but without cooperation from the kernel.  No
+        superuser privileges are necessary, beause this mapping exists
+        only inside the <application>MPD</application> process
+      </para>
+
+      <variablelist>
+
+        <varlistentry id="command_mount">
+          <term>
+            <cmdsynopsis>
+              <command>mount</command>
+              <arg choice="req"><replaceable>PATH</replaceable></arg>
+              <arg choice="req"><replaceable>URI</replaceable></arg>
+            </cmdsynopsis>
+          </term>
+
+          <listitem>
+            <para>
+              Mount the specified remote storage URI at the given
+              path.  Example:
+            </para>
+
+            <programlisting>mount foo nfs://192.168.1.4/export/mp3</programlisting>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry id="command_umount">
+          <term>
+            <cmdsynopsis>
+              <command>unmount</command>
+              <arg choice="req"><replaceable>PATH</replaceable></arg>
+            </cmdsynopsis>
+          </term>
+
+          <listitem>
+            <para>
+              Unmounts the specified path.  Example:
+            </para>
+
+            <programlisting>unmount foo</programlisting>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry id="command_listmounts">
+          <term>
+            <cmdsynopsis>
+              <command>listmounts</command>
+            </cmdsynopsis>
+          </term>
+
+          <listitem>
+            <para>
+              Queries a list of all mounts.  By default, this contains
+              just the configured <varname>music_directory</varname>.
+              Example:
+            </para>
+
+            <programlisting>listmounts
+mount: 
+storage: /home/foo/music
+mount: foo
+storage: nfs://192.168.1.4/export/mp3
+OK
+</programlisting>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry id="command_listneighbors">
+          <term>
+            <cmdsynopsis>
+              <command>listneighbors</command>
+            </cmdsynopsis>
+          </term>
+
+          <listitem>
+            <para>
+              Queries a list of "neighbors" (e.g. accessible file
+              servers on the local net).  Items on that list may be
+              used with the <link
+              linkend="command_mount"><command>mount</command></link>
+              command.  Example:
+            </para>
+
+            <programlisting>listneighbors
+neighbor: smb://FOO
+name: FOO (Samba 4.1.11-Debian)
+OK
+</programlisting>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+    </section>
+
     <section id="stickers">
       <title>Stickers</title>
 
diff --git a/doc/user.xml b/doc/user.xml
index 82b5c9866..bc43a4167 100644
--- a/doc/user.xml
+++ b/doc/user.xml
@@ -253,6 +253,57 @@ systemctl start mpd.socket</programlisting>
       </para>
     </section>
 
+    <section id="config_neighbor_plugins">
+      <title>Configuring neighbor plugins</title>
+
+      <para>
+        All neighbor plugins are disabled by default to avoid unwanted
+        overhead.  To enable (and configure) a plugin, add a
+        <varname>neighbor</varname> block to
+        <filename>mpd.conf</filename>:
+      </para>
+
+      <programlisting>neighbors {
+    plugin "smbclient"
+}
+      </programlisting>
+
+      <para>
+        The following table lists the <varname>neighbor</varname>
+        options valid for all plugins:
+      </para>
+
+      <informaltable>
+        <tgroup cols="2">
+          <thead>
+            <row>
+              <entry>
+                Name
+              </entry>
+              <entry>
+                Description
+              </entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry>
+                <varname>plugin</varname>
+              </entry>
+              <entry>
+                The name of the plugin.
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+
+      <para>
+        More information can be found in the <link
+        linkend="neighbor_plugins">neighbor plugin reference</link>.
+      </para>
+    </section>
+
     <section id="config_input_plugins">
       <title>Configuring input plugins</title>
 
@@ -1407,6 +1458,18 @@ buffer_size: 16384</programlisting>
                 </entry>
               </row>
 
+              <row>
+                <entry>
+                  <varname>cache_directory</varname>
+                </entry>
+                <entry>
+                  The path of the cache directory for additional
+                  storages mounted at runtime.  This setting is
+                  necessary for the <command>mount</command> protocol
+                  command.
+                </entry>
+              </row>
+
               <row>
                 <entry>
                   <varname>compress</varname>
@@ -1535,6 +1598,26 @@ buffer_size: 16384</programlisting>
       </section>
     </section>
 
+    <section id="neighbor_plugins">
+      <title>Neighbor plugins</title>
+
+      <section id="smbclient_neighbor">
+        <title><varname>smbclient</varname></title>
+
+        <para>
+          Provides a list of SMB/CIFS servers on the local network.
+        </para>
+      </section>
+
+      <section id="upnp_neighbor">
+        <title><varname>upnp</varname></title>
+
+        <para>
+          Provides a list of UPnP servers on the local network.
+        </para>
+      </section>
+    </section>
+
     <section id="input_plugins">
       <title>Input plugins</title>
 
-- 
cgit v1.2.3