--- linuxsampler/trunk/Documentation/lscp.xml	2005/05/23 17:41:34	571
+++ linuxsampler/trunk/Documentation/lscp.xml	2005/05/24 03:18:30	573
@@ -13,7 +13,7 @@
 <?rfc iprnotified="no" ?>
 <?rfc strict="yes" ?>
 
-<rfc category="std" ipr="full2026" docName="lscp.txt">
+<rfc category="std" ipr="full2026" docName="LSCP 1.0">
     <front>
         <title>LinuxSampler Control Protocol</title>
         <author initials='C.S.' surname="Schoenebeck" fullname='C.
@@ -130,7 +130,7 @@
             group of backward compatible versions. That means a frontend is
             compatible to the connected sampler if and only if the LSCP versions
             to which each of the two parties complies to, match both of the
-            following rule:
+            following rules:
             </t>
             <t>Compatibility:</t>
             <t>
@@ -463,7 +463,7 @@
             </section>
         </section>
 
-        <section title="Description for control commands">
+        <section title="Description for control commands" anchor="control_commands">
             <t>This chapter will describe the available control commands
             that can be sent on the TCP connection in detail. Some certain
             commands (e.g. <xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref>
@@ -3264,7 +3264,7 @@
                     <t>
                         <list>
                             <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
-                               Each answer line begins with the settings category name
+                               Each answer line begins with the information category name
                                followed by a colon and then a space character &lt;SP&gt; and finally
                                the info character string to that information category. At the
                                moment the following categories are defined:
@@ -3298,9 +3298,373 @@
         </section>
 
         <section title="Command Syntax" anchor="command_syntax">
-            <t>TODO: will soon automatically included from src/network/lscp.y,
-            meanwhile have a look at that file to get the exact definition of
-            the command syntax.</t>
+            <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>
+            is defined below using Backus-Naur Form (BNF as described in <xref target="RFC2234"/>)
+            where applicable.
+            </t>
+            <!--
+                This section is automatically generated by scripts/update_grammar.pl
+                from src/network/lscp.y (yacc input file). Do not modify this section
+                manually !
+            -->
+            <!-- GRAMMAR_BNF_BEGIN - do NOT delete or modify this line !!! -->
+
+<t>input =
+	<list>
+		<t>line LF
+		</t>
+		<t>/ line CR LF
+		</t>
+	</list>
+</t>
+<t>line =
+	<list>
+		<t>/* epsilon (empty line ignored) */
+		</t>
+		<t>/ comment
+		</t>
+		<t>/ command
+		</t>
+		<t>/ error
+		</t>
+	</list>
+</t>
+<t>comment =
+	<list>
+		<t>'#'
+		</t>
+		<t>/ comment '#'
+		</t>
+		<t>/ comment SP
+		</t>
+		<t>/ comment number
+		</t>
+		<t>/ comment string
+		</t>
+	</list>
+</t>
+<t>command =
+	<list>
+		<t>ADD SP CHANNEL
+		</t>
+		<t>/ GET SP get_instruction
+		</t>
+		<t>/ CREATE SP create_instruction
+		</t>
+		<t>/ DESTROY SP destroy_instruction
+		</t>
+		<t>/ LIST SP list_instruction
+		</t>
+		<t>/ LOAD SP load_instruction
+		</t>
+		<t>/ REMOVE SP CHANNEL SP sampler_channel
+		</t>
+		<t>/ SET SP set_instruction
+		</t>
+		<t>/ SUBSCRIBE SP subscribe_event
+		</t>
+		<t>/ UNSUBSCRIBE SP unsubscribe_event
+		</t>
+		<t>/ SELECT SP text
+		</t>
+		<t>/ RESET SP CHANNEL SP sampler_channel
+		</t>
+		<t>/ RESET
+		</t>
+		<t>/ QUIT
+		</t>
+	</list>
+</t>
+<t>subscribe_event =
+	<list>
+		<t>CHANNEL_COUNT
+		</t>
+		<t>/ VOICE_COUNT
+		</t>
+		<t>/ STREAM_COUNT
+		</t>
+		<t>/ BUFFER_FILL
+		</t>
+		<t>/ CHANNEL_INFO
+		</t>
+		<t>/ MISCELLANEOUS
+		</t>
+	</list>
+</t>
+<t>unsubscribe_event =
+	<list>
+		<t>CHANNEL_COUNT
+		</t>
+		<t>/ VOICE_COUNT
+		</t>
+		<t>/ STREAM_COUNT
+		</t>
+		<t>/ BUFFER_FILL
+		</t>
+		<t>/ CHANNEL_INFO
+		</t>
+		<t>/ MISCELLANEOUS
+		</t>
+	</list>
+</t>
+<t>get_instruction =
+	<list>
+		<t>AVAILABLE_ENGINES
+		</t>
+		<t>/ AVAILABLE_MIDI_INPUT_DRIVERS
+		</t>
+		<t>/ MIDI_INPUT_DRIVER SP INFO SP string
+		</t>
+		<t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
+		</t>
+		<t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
+		</t>
+		<t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
+		</t>
+		<t>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
+		</t>
+		<t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
+		</t>
+		<t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
+		</t>
+		<t>/ AUDIO_OUTPUT_DEVICES
+		</t>
+		<t>/ MIDI_INPUT_DEVICES
+		</t>
+		<t>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
+		</t>
+		<t>/ MIDI_INPUT_DEVICE SP INFO SP number
+		</t>
+		<t>/ MIDI_INPUT_PORT SP INFO SP number SP number
+		</t>
+		<t>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
+		</t>
+		<t>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
+		</t>
+		<t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
+		</t>
+		<t>/ CHANNELS
+		</t>
+		<t>/ CHANNEL SP INFO SP sampler_channel
+		</t>
+		<t>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
+		</t>
+		<t>/ CHANNEL SP STREAM_COUNT SP sampler_channel
+		</t>
+		<t>/ CHANNEL SP VOICE_COUNT SP sampler_channel
+		</t>
+		<t>/ ENGINE SP INFO SP engine_name
+		</t>
+		<t>/ SERVER SP INFO
+		</t>
+	</list>
+</t>
+<t>set_instruction =
+	<list>
+		<t>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
+		</t>
+		<t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
+		</t>
+		<t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
+		</t>
+		<t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
+		</t>
+		<t>/ CHANNEL SP set_chan_instruction
+		</t>
+		<t>/ ECHO SP boolean
+		</t>
+	</list>
+</t>
+<t>create_instruction =
+	<list>
+		<t>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
+		</t>
+		<t>/ AUDIO_OUTPUT_DEVICE SP string
+		</t>
+		<t>/ MIDI_INPUT_DEVICE SP string SP key_val_list
+		</t>
+		<t>/ MIDI_INPUT_DEVICE SP string
+		</t>
+	</list>
+</t>
+<t>destroy_instruction =
+	<list>
+		<t>AUDIO_OUTPUT_DEVICE SP number
+		</t>
+		<t>/ MIDI_INPUT_DEVICE SP number
+		</t>
+	</list>
+</t>
+<t>load_instruction =
+	<list>
+		<t>INSTRUMENT SP load_instr_args
+		</t>
+		<t>/ ENGINE SP load_engine_args
+		</t>
+	</list>
+</t>
+<t>set_chan_instruction =
+	<list>
+		<t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
+		</t>
+		<t>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
+		</t>
+		<t>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
+		</t>
+		<t>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
+		</t>
+		<t>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
+		</t>
+		<t>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
+		</t>
+		<t>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
+		</t>
+		<t>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
+		</t>
+		<t>/ VOLUME SP sampler_channel SP volume_value
+		</t>
+	</list>
+</t>
+<t>key_val_list =
+	<list>
+		<t>string '=' param_val_list
+		</t>
+		<t>/ key_val_list SP string '=' param_val_list
+		</t>
+	</list>
+</t>
+<t>buffer_size_type =
+	<list>
+		<t>BYTES
+		</t>
+		<t>/ PERCENTAGE
+		</t>
+	</list>
+</t>
+<t>list_instruction =
+	<list>
+		<t>AUDIO_OUTPUT_DEVICES
+		</t>
+		<t>/ MIDI_INPUT_DEVICES
+		</t>
+		<t>/ CHANNELS
+		</t>
+		<t>/ AVAILABLE_ENGINES
+		</t>
+		<t>/ AVAILABLE_MIDI_INPUT_DRIVERS
+		</t>
+		<t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
+		</t>
+	</list>
+</t>
+<t>load_instr_args =
+	<list>
+		<t>filename SP instrument_index SP sampler_channel
+		</t>
+		<t>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
+		</t>
+	</list>
+</t>
+<t>load_engine_args =
+	<list>
+		<t>engine_name SP sampler_channel
+		</t>
+	</list>
+</t>
+<t>device_index =
+	<list>
+		<t>number
+		</t>
+	</list>
+</t>
+<t>audio_channel_index =
+	<list>
+		<t>number
+		</t>
+	</list>
+</t>
+<t>audio_output_type_name =
+	<list>
+		<t>string
+		</t>
+	</list>
+</t>
+<t>midi_input_port_index =
+	<list>
+		<t>number
+		</t>
+	</list>
+</t>
+<t>midi_input_channel_index =
+	<list>
+		<t>number
+		</t>
+		<t>/ ALL
+		</t>
+	</list>
+</t>
+<t>midi_input_type_name =
+	<list>
+		<t>string
+		</t>
+	</list>
+</t>
+<t>volume_value =
+	<list>
+		<t>dotnum
+		</t>
+		<t>/ number
+		</t>
+	</list>
+</t>
+<t>sampler_channel =
+	<list>
+		<t>number
+		</t>
+	</list>
+</t>
+<t>instrument_index =
+	<list>
+		<t>number
+		</t>
+	</list>
+</t>
+<t>engine_name =
+	<list>
+		<t>string
+		</t>
+	</list>
+</t>
+<t>filename =
+	<list>
+		<t>stringval
+		</t>
+	</list>
+</t>
+<t>param_val_list =
+	<list>
+		<t>param_val
+		</t>
+		<t>/ param_val_list','param_val
+		</t>
+	</list>
+</t>
+<t>param_val =
+	<list>
+		<t>string
+		</t>
+		<t>/ '\'' string '\''
+		</t>
+		<t>/ '\"' string '\"'
+		</t>
+		<t>/ number
+		</t>
+		<t>/ dotnum
+		</t>
+	</list>
+</t>
+
+            <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
         </section>
 
         <section title="Events" anchor="events">
@@ -3459,7 +3823,6 @@
                     <date year="1997"></date>
                 </front>
                 <seriesInfo name="RFC" value="2119" />
-                <seriesInfo name="STD" value="1" />
             </reference>
             <reference anchor="RFC793">
                 <front>
@@ -3470,7 +3833,19 @@
                     <date year="1981"></date>
                 </front>
                 <seriesInfo name="RFC" value="793" />
-                <seriesInfo name="STD" value="1" />
+            </reference>
+            <reference anchor="RFC2234">
+                <front>
+                    <title>Augmented BNF for Syntax Specifications</title>
+                    <author initials="D.H." surname="Crocker" fullname="David H. Crocker">
+                        <organization>Internet Mail Consortium</organization>
+                    </author>
+                    <author initials="P." surname="Overell" fullname="Paul Overell">
+                        <organization>Demon Internet Ltd</organization>
+                    </author>
+                    <date year="1997"></date>
+                </front>
+                <seriesInfo name="RFC" value="2234" />
             </reference>
          </references>
     </back>