[rkward-cvs] [rkward] /: Document new menu ordering mechanism

Wed Dec 3 14:20:54 UTC 2014

Git commit 232574857df9c48216e99b51f80c958b5a5ea84a by Thomas Friedrichsmeier.
Committed on 03/12/2014 at 14:08.
Pushed by tfry into branch 'master'.

Document new menu ordering mechanism

M  +0    -1    ChangeLog
M  +46   -10   doc/rkwardplugins/index.docbook

http://commits.kde.org/rkward/232574857df9c48216e99b51f80c958b5a5ea84a

diff --git a/ChangeLog b/ChangeLog
index 9eaa4a6..ceb6ba3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -3,7 +3,6 @@
 - Fixed: Freezes when using RKWard-functionality (such as the RK()-device) from tcl/tk (e.g. Rcmdr)
 - Allow opening RKWard's plugin files (with correct highlighting), and other text files
 - More robust control over placement of plugins within a menu
-  - TODO: document, discuss
 - Fix several issues of excessive printing of digits in plugins' output
 - Restructure layout of CSV-import dialog
 - Allow to open (any number of) R script files and rkward://-urls from the command line
diff --git a/doc/rkwardplugins/index.docbook b/doc/rkwardplugins/index.docbook
index 9d59ca0..4984ef5 100644
--- a/doc/rkwardplugins/index.docbook
+++ b/doc/rkwardplugins/index.docbook
@@ -189,14 +189,14 @@ This is a guide to writing plugins for &rkward;.
 	</para>
 	<programlisting>
 	<hierarchy>
-		<menu id="analysis" label="Analysis" index="4">
+		<menu id="analysis" label="Analysis">
 	</programlisting>
 	<para>
-		Right below the <command><hierarchy></command> tag, you start describing, in which <command><menu></command> your plugins should go. With the above line, you basically say, that your plugin should be in the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu (not necessarily directly there, but in a submenu). The <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu is standard in &rkward;, so it does not actually have to be created from scratch. However, if it did not exist yet, using the <parameter>label</parameter> attribute you'd give it its name. The <parameter>index</parameter> attribute says, that the menu (if newly created) should be placed at the fourth position in the menubar.
+		Right below the <command><hierarchy></command> tag, you start describing, in which <command><menu></command> your plugins should go. With the above line, you basically say, that your plugin should be in the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu (not necessarily directly there, but in a submenu). The <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu is standard in &rkward;, so it does not actually have to be created from scratch. However, if it did not exist yet, using the <parameter>label</parameter> attribute you'd give it its name.
 		Finally, the <parameter>id</parameter> once again identifies this <command><menu></command>. This is needed, so several &pluginmap; files can place their plugins in the same menus. They do this by looking for a <command><menu></command> with the given <parameter>id</parameter>. If the ID does not yet exist, a new menu will be created. Otherwise the entries will be added to the existing menu.
 	</para>
 	<programlisting>
-			<menu id="means" label="Means" index="1">
+			<menu id="means" label="Means">
 	</programlisting>
 	<para>
 		Basically the same thing here: Now we define a submenu to the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu. It is to be called <menuchoice><guimenuitem>Means</guimenuitem></menuchoice>.
@@ -205,7 +205,7 @@ This is a guide to writing plugins for &rkward;.
 				<menu id="ttests" label="t-Tests">
 	</programlisting>
 	<para>
-		And a final level in the menu hierarchy: A submenu of the submenu <menuchoice><guimenuitem>Means</guimenuitem></menuchoice>. Note, that if you omit the <parameter>index</parameter> parameter, the new entry will be placed below any already existing ones.
+		And a final level in the menu hierarchy: A submenu of the submenu <menuchoice><guimenuitem>Means</guimenuitem></menuchoice>.
 	</para>
 	<programlisting>
 					<entry component="t_test_two_vars" />
@@ -226,16 +226,16 @@ This is a guide to writing plugins for &rkward;.
 	<programlisting>
 				[...]
 			</menu>
-			<entry component="corr_matrix" index="4"/>
-			<entry component="descriptive" index="3"/>
-			<entry component="simple_anova" index="5"/>
+			<entry component="corr_matrix"/>
+			<entry component="descriptive"/>
+			<entry component="simple_anova"/>
 		</menu>
 	</programlisting>
 	<para>
-		These are the final entries visible in the screenshots below. Note, that you don't need to define the entries in the order they should have in the menu. Use the <parameter>index</parameter> attribute instead.
+		These are the final entries visible in the screenshots below.
 	</para>
 	<programlisting>
-		<menu id="plots" label="Plots" index="5">
+		<menu id="plots" label="Plots">
 			[...]
 		</menu>
 	</programlisting>
@@ -243,7 +243,7 @@ This is a guide to writing plugins for &rkward;.
 		Of course you can also place your plugins in menus other than <menuchoice><guimenu>Analysis</guimenu></menuchoice>.
 	</para>
 	<programlisting>
-		<menu id="file" label="File" index="0">
+		<menu id="file" label="File">
 			[...]
 		</menu>
 	</programlisting>
@@ -271,6 +271,42 @@ This is a guide to writing plugins for &rkward;.
 	<para>
 		Confused? The easiest way to get started is probably taking some of the existing &pluginmap; files shipped with the distribution, and modifying them to your needs. Also, if you need help, don't hesitate to write to the development mailing list.
 	</para>
+	<sect1 id="pluginmap_grouping"><title>Controlling the order of menu entries</title>
+		<para>By default, all items (entries / submenus) inside a menu will be sorted alphabetically, automatically. In <emphasis>some</emphasis> cases you may want more control. In this case you can group elements as follows:</para>
+		<itemizedlist>
+			<listitem>
+				<para>You can define groups inside any menu like this. All elements belonging to the same group will be grouped together:</para>
+				<programlisting>
+		<group id="somegroup"/>
+				</programlisting>
+			</listitem><listitem>
+			<para>If you want the group to be visually separated from other entries, use:</para>
+				<programlisting>
+		<group id="somegroup" separated="true"/>
+				</programlisting>
+			</listitem><listitem>
+				<para>Entries, menus, and groups can be appended to a specified group, using:</para>
+				<programlisting>
+		<entry component="..." group="somegroup"/>
+				</programlisting>
+			</listitem><listitem>
+				<para>In fact, it is also possible to define groups (without separator lines) implicitly:</para>
+				<programlisting>
+		<entry component="first" group="a"/>
+		<entry component="third"/>
+		<entry component="second" group="a"/>
+				</programlisting>
+			</listitem><listitem>
+				<para>Group names are specific to each menu. Group "a" in menu "Data" does not conflict with group "a" in menu "Analysis", for example.</para>
+			</listitem><listitem>
+				<para>The most common use case is defining groups at the top, or at the bottom of a menu. For this, there are pre-defined groups "top" and "bottom" in each menu.</para>
+			</listitem><listitem>
+				<para>Entries within each group are sorted, alphabetically. Groups appear in the order of declaration (unless appended to another group, of course).</para>
+			</listitem><listitem>
+				<para>Menus and entries without group specification logically form a group (""), too.</para>
+			</listitem>
+		</itemizedlist>
+	</sect1>
 </chapter>
 
 <chapter id="mainxml">



