doc/protocol: add some missing specifications

doc/protocol.xml

@@ -8,12 +8,38 @@
     <title>General protocol syntax</title>
 
     <section>
-      <title>Requests</title>
+      <title>Protocol overview</title>
+
+      <para>
+        The MPD command protocol exchanges line-based text records
+        between client and server over TCP.  Once the client is
+        connected to the server, they conduct a conversation until the
+        client closes the connection. The conversation flow is always
+        initiated by the client.
+      </para>
+
+      <para>
+        The client transmits a command sequence, terminated by the
+        newline character <constant>\n</constant>.  The server will
+        respond with one or more lines, the last of which will be a
+        completion code.
+      </para>
 
       <para>
-        If arguments contain spaces, they should be surrounded by double quotation
-        marks.
+        When the client connects to the server, the server will answer
+        with the following line:
+
+        <synopsis>OK MPD version</synopsis>
+
+        where <varname>version</varname> is a version identifier such as
+        0.12.2.  This version identifier is the version of the protocol
+        spoken, not the real version of the daemon.  (There is no way to
+        retrieve this real version identifier from the connection.)
       </para>
+    </section>
+
+    <section>
+      <title>Requests</title>
 
       <cmdsynopsis>
         <command>COMMAND</command>
@@ -21,6 +47,16 @@
       </cmdsynopsis>
 
       <para>
+        If arguments contain spaces, they should be surrounded by double
+        quotation marks.
+      </para>
+
+      <para>
+        Argument strings are separated from the command and any other
+        arguments by linear white-space (' ' or '\t').
+      </para>
+
+      <para>
         All data between the client and the server is encoded in
         UTF-8. (Note: In UTF-8 all standard ansi characters, 0-127 are
         the same as a standard ansi encoding.  Also, no ansi character
@@ -38,13 +74,97 @@
       <title>Responses</title>
 
       <para>
-        A command returns <returnvalue>OK</returnvalue> on completion
-        or <returnvalue>ACK some error</returnvalue> on failure.
-        These denote the end of command execution.
+        A command returns <returnvalue>OK</returnvalue> on completion or
+        <returnvalue>ACK some error</returnvalue> on failure.  These
+        denote the end of command execution.
       </para>
+
+      <section>
+        <title>Failure responses</title>
+
+        <para>
+          The nature of the error can be gleaned from the information
+          that follows the <returnvalue>ACK</returnvalue>.
+          <returnvalue>ACK</returnvalue> lines are of the form:
+
+          <synopsis>ACK [error@command_listNum] {current_command} message_text\n</synopsis>
+
+          These responses are generated by a call to
+          <function>commandError</function>. They contain four separate
+          terms. Let's look at each of them:
+
+          <itemizedlist>
+            <listitem>
+              <para>
+                <returnvalue>error</returnvalue>: numeric value of one
+                of the <constant>ACK_ERROR</constant> constants defined
+                in <filename>ack.h</filename>.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <returnvalue>command_listNum</returnvalue>:
+                offset of the command that caused the error in a <link
+                  linkend="command_lists">Command List</link>.
+                An error will always cause a command list to terminate
+                at the command that causes the error.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <returnvalue>current_command</returnvalue>:
+                name of the command, in a <link
+                  linkend="command_lists">Command List</link>,
+                that was executing when the error occurred.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <returnvalue>message_text</returnvalue>:
+                some (hopefully) informative text that describes the
+                nature of the error.
+              </para>
+            </listitem>
+          </itemizedlist>
+        </para>
+
+        <example>
+          <title>foo</title>
+          <para>
+            An example might help. Consider the following sequence
+            sent from the client to the server.
+
+            <synopsis>
+              command_list_begin
+              volume 86
+              play 10240
+              status
+              command_list_end
+            </synopsis>
+          </para>
+
+          <para>
+            The server responds with:
+
+            <returnvalue>
+              ACK [50@1] {play} song doesn't exist: "10240"
+            </returnvalue>
+          </para>
+
+          <para>
+            This tells us that the play command, which was the
+            second in the list (the first or only command is
+            numbered 0), failed with error 50.  The number 50
+            translates to <constant>ACK_ERROR_NO_EXIST</constant>--the
+            song doesn't exist.  This is reiterated by the message text
+            which also tells us which song doesn't exist.
+          </para>
+
+        </example>
+      </section>
     </section>
 
-    <section>
+    <section id="command_lists">
       <title>Command lists</title>
 
       <para>