[rkward-cvs] SF.net SVN: rkward: [1896] trunk/rkward/doc/en/writing_plugins_introduction .docbook

Wed May 9 22:23:28 UTC 2007

Revision: 1896
          http://svn.sourceforge.net/rkward/?rev=1896&view=rev
Author:   tfry
Date:     2007-05-09 15:23:28 -0700 (Wed, 09 May 2007)

Log Message:
-----------
Typos, and start reference for .rkh pages

Modified Paths:
--------------
    trunk/rkward/doc/en/writing_plugins_introduction.docbook

Modified: trunk/rkward/doc/en/writing_plugins_introduction.docbook
===================================================================

--- trunk/rkward/doc/en/writing_plugins_introduction.docbook	2007-05-09 21:47:30 UTC (rev 1895)
+++ trunk/rkward/doc/en/writing_plugins_introduction.docbook	2007-05-09 22:23:28 UTC (rev 1896)
@@ -128,7 +128,7 @@
 <document base_prefix="" namespace="rkward">
 </programlisting>
 <para>
-The "base_prefix"-attribute can be used, if all your plugins reside in a common directory. Basically, then, you can omit that directory from the filenames specified below. As you will see below, all plugins get a unique identifier. The "namespace" is a way to organized those ids, and make it less likely to create a duplicate identifier accidentally. Internally, basically the namespace and then a "::" gets prepended to all the identifiers you specify below.
+The "base_prefix"-attribute can be used, if all your plugins reside in a common directory. Basically, then, you can omit that directory from the filenames specified below. As you will see below, all plugins get a unique identifier. The "namespace" is a way to organize those ids, and make it less likely to create a duplicate identifier accidentally. Internally, basically the namespace and then a "::" gets prepended to all the identifiers you specify below. If unsure, leave these at "" and "rkward".
 </para>
 <programlisting>
 	<components>
@@ -161,7 +161,7 @@
 		<menu id="analysis" label="Analysis" index="4">
 </programlisting>
 <para>
-Right below the <hierarchy>-tag, you start describing, in which menu, your plugins should go. With the above line, you basically say, that your plugin should be in the "Analysis" menu (not necessarily directly there, but in a submenu). The "Analysis" menu is standard in &kapp;, so it does not acutally have to be created from scratch. However, if it did not exist yet, using the "label"-attribute you'd give it its name. The "index" attribute says, that the menu (if newly created) should be placed at the fourth position in the menubar.
+Right below the <hierarchy>-tag, you start describing, in which menu, your plugins should go. With the above line, you basically say, that your plugin should be in the "Analysis" menu (not necessarily directly there, but in a submenu). The "Analysis" menu is standard in &kapp;, so it does not actually have to be created from scratch. However, if it did not exist yet, using the "label"-attribute you'd give it its name. The "index" attribute says, that the menu (if newly created) should be placed at the fourth position in the menubar.
 Finally, the "id" once again identifies this menu. This is needed, so several .pluginmap-files can place their plugins in the same menus. They do this by looking for a menu with the given "id". 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>
@@ -238,7 +238,7 @@
 	</mediaobject>
 </screenshot>
 <para>
-Confused? The easiest way to get started is probably taking some of the existing .plugin_map 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.
+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>
 </chapter>
 
@@ -267,7 +267,7 @@
 	<help file="t_test.rkh"/>
 </programlisting>
 <para>
-It is usually a good idea, to also provide a help page for your plugin. The filename of that help page is given, here, relative to the directory, the plugin-xml is in. Writing help pages is documented <link linkend="pluginhelp">here</link>. If you do not provide a help file, omit this line.
+It is usually a good idea to also provide a help page for your plugin. The filename of that help page is given, here, relative to the directory, the plugin-xml is in. Writing help pages is documented <link linkend="pluginhelp">here</link>. If you do not provide a help file, omit this line.
 </para>
 <programlisting>
 	<dialog label="Independent Samples T-Test">
@@ -407,7 +407,7 @@
 	Much of the same thing here. We add some texts, and in between that <copy> further sections from the dialog interface.
 	</para>
 	<para>
-	You may of course make the wizard-interface look very different to the plain dialog, and not use the <copy> tag at all. Be sure, however, to assign corresponding elements the same "id" in both interfaces. This is not only used to transfer settings from the dialog-interface to the wizard-interface and back, when the user switches interfaces (which does not yet happen in the current version of RKWard), but also simplifies writing your code-template (see below). 
+	You may of course make the wizard-interface look very different to the plain dialog, and not use the <copy> tag at all. Be sure, however, to assign corresponding elements the same "id" in both interfaces. This is not only used to transfer settings from the dialog-interface to the wizard-interface and back, when the user switches interfaces (which does not yet happen in the current version of RKWard), but also simplifies writing your code-template (see below).
 	</para>
 </section>
 
@@ -420,7 +420,7 @@
 	<section id="radio_vs_checkbox_vs_dropdown">
 		<title><radio> vs. <checkbox> vs. <dropdown></title>
 		<para>
-		The three elements <radio>, <checkbox>, <dropdown>, all serve a similar function: To select one out of a several options. Obviously, a checkbox only allows to chose between two options: checked or not checked, so you can't use it, if there are more than two options to chose from. But when to use which of the elements? Some rules of thumb:
+		The three elements <radio>, <checkbox>, <dropdown>, all serve a similar function: To select one out of several options. Obviously, a checkbox only allows to chose between two options: checked or not checked, so you can't use it, if there are more than two options to chose from. But when to use which of the elements? Some rules of thumb:
 		</para>
 		<para>
 		If you find yourself creating a <radio> or <dropdown> with only two options, ask yourself, whether the question is essentially a yes / no type of question. E.g. a choice between "adjust results" and "do not adjust results", or between "remove missing values" and "keep missing values". In this case a <checkbox> is the best choice: It uses little space, will have the least words of labels, and is easiest to read for the user. There are very few situations where you should chose a <radio> over a <checkbox>, when there are only two options. An example of that might be: "Method of calculation: 'pearson'/'spearman'". Here, more methods might be thinkable, and they don't really form a pair of opposites.
@@ -2295,6 +2295,100 @@
 </varlistentry>
 </variablelist>
 </section>
+
+<section id="helpfileelements"><title>Elements for use in .rkh (help) files</title>
+<variablelist>
+<varlistentry>
+<term><document></term>
+<listitem>Needs to be present in each .rkh file as the root-node (exactly once). No attributes.</listitem>
+</varlistentry>
+<varlistentry>
+<term><title></term>
+<listitem>Title of the help page. This is <emphasis>not</emphasis> interpreted for help pages for a plugin (this takes the title from the plugin itself), only for stand-alone pages. No attributes. The text contained within the <title> tag will become the caption of the help page. May only be defined once, as a direct child of the <document> node.</listitem>
+</varlistentry>
+<varlistentry>
+<term><summary></term>
+<listitem>A short summary of the help page (or what this plugin is used for). This will always be shown at the top of the help page. No attributes. The text contained within the <summary> tag will be displayed. Recommended but not required. May only be defined once, as a direct child of the <document> node.</listitem>
+</varlistentry>
+<varlistentry>
+<term><usage></term>
+<listitem>A slightly more elaborate summary of the usage. This will always be shown directly after the <summary>. No attributes. The text contained within the <usage> tag will be displayed. Recommended for plugin help pages, but not required. May only be defined once, as a direct child of the <document> node.</listitem>
+</varlistentry>
+<varlistentry>
+<term><section></term>
+<listitem>
+	<variablelist>
+	<varlistentry>
+	<term>id</term>
+	<listitem></listitem>
+	</varlistentry>
+	<varlistentry>
+	<term>title</term>
+	<listitem></listitem>
+	</varlistentry>
+	<varlistentry>
+	<term>short_title</term>
+	<listitem></listitem>
+	</varlistentry>
+	</variablelist></listitem>
+</varlistentry>
+<varlistentry>
+<term><settings></term>
+<listitem></listitem>
+</varlistentry>
+<varlistentry>
+<term><setting></term>
+<listitem>
+	<variablelist>
+	<varlistentry>
+	<term>id</term>
+	<listitem></listitem>
+	</varlistentry>
+	<varlistentry>
+	<term>title</term>
+	<listitem></listitem>
+	</varlistentry>
+	</variablelist></listitem>
+</varlistentry>
+<varlistentry>
+<term><caption></term>
+<listitem>
+	<variablelist>
+	<varlistentry>
+	<term>id</term>
+	<listitem></listitem>
+	</varlistentry>
+	<varlistentry>
+	<term>title</term>
+	<listitem></listitem>
+	</varlistentry>
+	</variablelist></listitem>
+</varlistentry>
+<varlistentry>
+<term><related></term>
+<listitem></listitem>
+</varlistentry>
+<varlistentry>
+<term><technical></term>
+<listitem></listitem>
+</varlistentry>
+<varlistentry>
+<term><link></term>
+<listitem>
+	<variablelist>
+	<varlistentry>
+	<term>href</term>
+	<listitem></listitem>
+	</varlistentry>
+	</variablelist></listitem>
+</varlistentry>
+<varlistentry>
+<term><various html tags></term>
+<listitem></listitem>
+</varlistentry>
+</variablelist>
+</section>
+
 </appendix>
 
 <appendix id="troubleshooting">


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.


