- description of new options -next and -prev

- divided the command reference into 4 subsections
- added a complete menu example for wizzards

docs/lcdproc-dev/language.docbook

@@ -43,15 +43,32 @@
   </sect1>
 
   <sect1 id="language-commands">
-    <title>The various command</title>
+    <title>Command reference</title>
     <para>
-      The commands and their parameters are listed below, along with the
+      In this section all commands and their parameters are listed,
-      responses you can expect. If you need a space or a special char in a
+      along with the responses you can expect. If you need a space or
-      string, you should quote the string with double quotes. If you need
+      a special char in a string, you should quote the string with
-      to use a double quote, escape it with a backslash.
+      double quotes. If you need to use a double quote, escape it with
+      a backslash. The listing is divided into subsections for
+      <orderedlist>
+	<listitem>
+	  <para><link linkend="language-basic">Basic stuff</link></para>
+	</listitem>
+	<listitem>
+	  <para><link linkend="language-screens">Screens and widgets</link></para>
+	</listitem>
+	<listitem>
+	  <para><link linkend="language-menus">Menu stuff</link></para>
+	</listitem>
+	<listitem>
+	  <para><link linkend="language-misc">Miscellaneous</link></para>
+	</listitem>
+      </orderedlist>
     </para>
 
-    <variablelist><title>The LCDproc commands</title>
+    <sect2 id="language-basic">
+      <title>Basic stuff</title>
+      <variablelist>
 	<varlistentry>
 	  <term>hello</term>
 	  <listitem>
@@ -149,7 +166,13 @@
 	    </para>
 	  </listitem>
 	</varlistentry>
+      </variablelist>
+    </sect2>
 
+    <sect2 id="language-screens">
+      <title>Screens and widgets</title>
+
+      <variablelist>
 	<varlistentry>
 	  <term>screen_add &lt;new_screen_id&gt;</term>
 	  <listitem>
@@ -382,7 +405,61 @@
 	    </para>
 	  </listitem>
 	</varlistentry>
+      </variablelist>
+    </sect2>
 
+    <sect2 id="language-menus">
+      <title>Menu stuff</title>
+
+      <para>
+	In this section all commands for creation, modification of
+	menus and for interaction with them are described. Although
+	keys may be used for other tasks they are listed here too.
+      </para>
+      <para>
+	TODO: example for normal (static) menu structure.
+      </para>
+      <para>
+	Menus may be even be used for wizzards (the user is
+	automatically guided through a number of configuration
+	options) by virtue of the options -next and -prev. Here a
+	complete example:
+	<programlisting>
+	  client_set name Parenttest
+	  # to be entered on escape from test_menu (but overwritten
+	  # for test_{checkbox,ring})
+	  menu_add_item "" ask menu "Leave menus?" -is_hidden true
+	    menu_add_item "ask" ask_yes action "Yes" -next _quit_
+	    menu_add_item "ask" ask_no action "No" -next _close_
+
+	  menu_add_item "" test menu "Test"
+	    menu_add_item "test" test_action action "Action"
+	    menu_add_item "test" test_checkbox checkbox "Checkbox"
+	    menu_add_item "test" test_ring ring "Ring" -strings "one\ttwo\tthree"
+	    menu_add_item "test" test_slider slider "Slider" -mintext "&lt;" -maxtext "&gt;" -value "50"
+	    menu_add_item "test" test_numeric numeric "Numeric" -value "42"
+	    menu_add_item "test" test_alpha alpha "Alpha" -value "abc"
+	    menu_add_item "test" test_ip ip "IP" -v6 false -value "192.168.1.1"
+	    menu_add_item "test" test_menu menu "Menu"
+	    menu_add_item "test_menu" test_menu_action action "Submenu's action"
+
+	  # no successor for menus. Since test_checkbox and test_ring have their
+	  # own predecessors defined the "ask" rule will not work for them
+	  menu_set_item "" test -prev "ask"
+
+	  menu_set_item "test" test_action -next "test_checkbox"
+	  menu_set_item "test" test_checkbox -next "test_ring" -prev "test_action"
+	  menu_set_item "test" test_ring -next "test_slider" -prev "test_checkbox"
+	  menu_set_item "test" test_slider -next "test_numeric" -prev "test_ring"
+	  menu_set_item "test" test_numeric -next "test_alpha" -prev "test_slider"
+	  menu_set_item "test" test_alpha -next "test_ip" -prev "test_numeric"
+	  menu_set_item "test" test_ip -next "test_menu" -prev "test_alpha"
+	  menu_set_item "test" test_menu_action -next "_close_"
+
+	  menu_set_main ""
+	</programlisting>
+      </para>
+      <variablelist>
 	<varlistentry>
 	  <term>client_add_key [-excl|-shared] {&lt;key&gt;}+</term>
 	  <listitem>
@@ -421,6 +498,12 @@
 	      an item. This main menu has an empty id ("") and the name
 	      is identical to the name of the client. The options are
 	      described under menu_set_item below.
+	    </para>
+	    <para>
+	      <emphasis role="bold">Note:</emphasis> Menu commands
+	      (menu_goto) and options (-prev, -next) assume that
+	      menu ids are <emphasis>unique</emphasis> (at least
+	      within a clients menu hierarchy).
 	      <variablelist><title>menu item types</title>
 		<varlistentry>
 		  <term>action</term>
@@ -431,31 +514,46 @@
 		<varlistentry>
 		  <term>checkbox</term>
 		  <listitem><para>
-		  Consists of a text and a status indicator. The status can be on (Y), off (N) or gray (o). 
+		      Consists of a text and a status indicator. The
+		      status can be on (Y), off (N) or gray (o).
 		    </para></listitem>
 		</varlistentry>
 		<varlistentry>
 		  <term>ring</term>
 		  <listitem><para>
-		  Consists of a text and a status indicator. The status can be one of the strings specified for the item. 
+		      Consists of a text and a status indicator. The
+		      status can be one of the strings specified for the
+		      item.
 		    </para></listitem>
 		</varlistentry>
 		<varlistentry>
 		  <term>slider</term>
 		  <listitem><para>
-		  Is visible as a text. When selected, a screen comes up that shows a slider. You can set the slider using the cursor keys. When Enter is pressed, the menu returns.
+		      Is visible as a text. When selected, a screen comes
+		      up that shows a slider. You can set the slider using
+		      the cursor keys. When Enter is pressed, the menu
+		      returns.
 		    </para></listitem>
 		</varlistentry>
 		<varlistentry>
 		  <term>numeric</term>
 		  <listitem><para>
-		  Allows the user to input an integer value. Is visible as a text. When selected, a screen comes up that shows the current numeric value, that you can edit with the cursor keys and Enter. The number is ended by selecting a 'null' input digit. After that the menu returns.
+		      Allows the user to input an integer value. Is
+		      visible as a text. When selected, a screen comes up
+		      that shows the current numeric value, that you can
+		      edit with the cursor keys and Enter. The number is
+		      ended by selecting a 'null' input digit. After that
+		      the menu returns.
 		    </para></listitem>
 		</varlistentry>
 		<varlistentry>
 		  <term>alpha</term>
 		  <listitem><para>
-		  Is visible as a text. When selected, a screen comes up that shows the current string value, that you can edit with the cursor keys and Enter. The string is ended by selecting a 'null' input character. After that the menu returns.
+		      Is visible as a text. When selected, a screen comes
+		      up that shows the current string value, that you can
+		      edit with the cursor keys and Enter. The string is
+		      ended by selecting a 'null' input character. After
+		      that the menu returns.
 		    </para></listitem>
 		</varlistentry>
 		<varlistentry>
@@ -464,13 +562,16 @@
 		      Allows the user to input an ip number (v4 or
 		      v6). When selected, a screen comes up that shows an ip
 		      number that can be edited - digit by digit - via
-                left/right (switch digit) and up/down keys (increase/decrease).
+		      left/right (switch digit) and up/down keys
+		      (increase/decrease).
 		    </para></listitem>
 		</varlistentry>
 		<varlistentry>
 		  <term>menu</term>
 		  <listitem><para>
-		  This is a submenu. It is visible as a text, with an appended '>'. When selected, the submenu becomes the active menu.
+		      This is a submenu. It is visible as a text, with an
+		      appended '>'. When selected, the submenu becomes the
+		      active menu.
 		    </para></listitem>
 		</varlistentry>
 	      </variablelist>
@@ -482,7 +583,9 @@
 	  <term>menu_del_item &lt;menu_id&gt; &lt;item_id&gt;</term>
 	  <listitem>
 	    <para>
-	    Removes a menuitem &lt;item_id&gt; from menu &lt;menu_id&gt;. The menu named "" is the client's main menu.
+	      Removes a menuitem &lt;item_id&gt; from menu
+	      &lt;menu_id&gt;. The menu named "" is the client's main
+	      menu.
 	    </para>
 	  </listitem>
 	</varlistentry>
@@ -511,12 +614,18 @@
 			</varlistentry>
 			<varlistentry>
 			  <term>-next &lt;successor_id&gt; ()</term>
-                      <listitem><para>
+			  <listitem>
-			Sets the menuitem to show after closing this
+			    <para>
-                      	Item. Parentid has to be of a non-menu type that
+			      Sets the menuitem to show after hitting
-                      	has its own screen, e.g., not a
+			      the ENTER key when this Item is
-                        checkbox. Special values are
+			      active. This works for
+			      <emphasis>all</emphasis> menu item types
+			      <emphasis>except menus</emphasis>
+			      i.e. also for menu item types without an
+			      own screen e.g., checkbox, ring and
+			      action.
 			      <variablelist>
+				<title>Special values</title>
 				<varlistentry>
 				  <term>_close_</term>
 				  <listitem><para>
@@ -541,6 +650,31 @@
 			      </variablelist>
 			    </para></listitem>
 			</varlistentry>
+			<varlistentry>
+			  <term>-prev &lt;predecessor_id&gt; ()</term>
+			  <listitem>
+			    <para>
+			      Sets the menuitem to show after hitting
+			      the ESCAPE key when this Item is
+			      active. This works for
+			      <emphasis>all</emphasis> menu item types
+			      i.e. also for menu item types without an
+			      own screen e.g., checkbox, ring and
+			      action.
+			    </para>
+			    <para>
+			      <emphasis role="bold">Note:</emphasis>
+			      If you define a predecessor for e.g., a
+			      checkbox and its parent menu too, the
+			      menu's predecessor is ignored in favor
+			      of the checkboxes one.
+			    </para>
+			    <para>
+			      This option respects the same special
+			      values as the -next option.
+			    </para>
+			  </listitem>
+			</varlistentry>
 		      </variablelist>
 		    </para></listitem>
 		</varlistentry>
@@ -811,7 +945,13 @@
 	    </para>
 	  </listitem>
 	</varlistentry>
+      </variablelist>
+    </sect2>
 
+    <sect2 id="language-misc">
+      <title>Miscellaneous</title>
+
+      <variablelist>
 	<varlistentry>
 	  <term>backlight on|off|toggle|blink|flash</term>
 	  <listitem>
@@ -844,9 +984,10 @@
 	    </para>
 	  </listitem>
 	</varlistentry>
-
       </variablelist>
+    </sect2>
   </sect1>
+
   <sect1 id="language-messages">
     <title>LCDd messages</title>
     <para>