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

Tue Jan 9 14:35:04 UTC 2007

Revision: 1115
          http://svn.sourceforge.net/rkward/?rev=1115&view=rev
Author:   tfry
Date:     2007-01-09 06:35:03 -0800 (Tue, 09 Jan 2007)

Log Message:
-----------
Add section on writing help 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-01-09 13:20:52 UTC (rev 1114)
+++ trunk/rkward/doc/en/writing_plugins_introduction.docbook	2007-01-09 14:35:03 UTC (rev 1115)
@@ -90,6 +90,9 @@
 </itemizedlist>
 </para>
 <para>
+Finally, there is a chapter on <link linkend="pluginhelp">adding a help page</link> to your plugin.
+</para>
+<para>
 Also, none of the chapters shows all options, but rather only the basic concepts. A complete <link linkend="reference">reference</link> of options is provided separately.
 </para>
 </chapter>
@@ -255,12 +258,18 @@
 </para>
 <programlisting>
 <document>
-	<code file="code.php"/>
+	<code file="t_test.php"/>
 </programlisting>
 <para>
-All plugins generate some code. Currently the only way to do so is using PHP, as detailed in <link linkend="phptemplate">the next chapter</link>. This defines, where to look for the PHP-code. The filname is relative to the directory the plugin-xml is in.
+All plugins generate some code. Currently the only way to do so is using PHP, as detailed in <link linkend="phptemplate">the next chapter</link>. This defines, where to look for the PHP-code. The filename is relative to the directory the plugin-xml is in.
 </para>
 <programlisting>
+	<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.
+</para>
+<programlisting>
 	<dialog label="Independent Samples T-Test">
 </programlisting>
 <para>
@@ -801,6 +810,104 @@
 </section>
 </chapter>
 
+<chapter id="pluginhelp">
+<title>Writing a help page</title>
+<para>
+When your plugin basically works, the time has come to provide a help page. While typically you will not want to explain all the underlying concepts in depth, you may want to add some more explanation for some of the options, and link to related plugins and R functions.
+</para>
+<para>
+You may recall putting this inside your plugin-xml (if you haven't put this in, do so now):
+</para>
+<programlisting>
+<document>
+	[...]
+	<help file="filename.rkh" />
+	[...]
+</document>
+</programlisting>
+<para>
+Where, obviously, you'd replace "filename" with a more appropriate name. Now it's time to create this .rkh file. Here is a self-descriptive example:
+</para>
+<programlisting>
+<!DOCTYPE rkhelp>
+<document>
+	<summary>
+In this section, you'll put some short, very basic information about what the plugin does.
+This section will always show up on the very top of the help page.
+	</summary>
+
+	<usage>
+The usage section may contain a little more practical information. It does not explain all
+the settings in detail (that's done in the "settings" section), however.
+
+To start a new paragraph, insert an empty line, as shown above.
+This line, in contrast, will be in the same paragraph.
+
+In all sections you can insert some simple HTML code, such as <b>bold</b> or
+<i>italic</i> text. Please keep formatting to the minimum needed, however.
+
+The usage section is always the second section shown in a help page.
+	</usage>
+
+	<section id="sectionid" title="Generic section">
+If you need to, you can add additional sections between the usage and settings sections.
+However, usually, you will not need this while documenting plugins. The "id"-attribute
+provides an anchor point to jump to this section from the navigation menu.
+
+In any section you may want to insert links to further information. You do this by adding
+
+<link href="URL">link name</link>
+
+Where URL could be an external link such as http://rkward.sourceforge.net .
+Several special URLs are supported in the help pages:
+
+<link href="rkward://page/path/page_id"/>
+
+This links to a top level rkward help page (not for a plugin).
+
+<link href="rkward://component/[namespace/]component_id"/>
+
+This links to the help page of another plugin. The [namespace/] part may be omitted
+(in this case, rkward is assumed as the standard namespace). The component_id is the
+same that you specified in the <link linkend="pluginmap">.pluginmap</link>.
+
+<link href="rkward://rhelp/rfunction"/>
+
+Links to the R help page on "rfunction".
+
+Note that the link names will be generated automatically for these types of links.
+	</section>
+
+	<settings>
+		<caption id="id_of_tab_or_frame"/>
+		<setting id="id_of_elementa">
+Description of the GUI element identified by the given id
+		</setting>
+		<setting id="id_of_elementb" title="description">
+Usually the title of the GUI element will be extracted from the
+<link linkend="mainxml">XML definition of the plugin</link>, automatically. However,
+for some GUI elements, this description may not be enough to identify them, reliably.
+In this case, you can add an explicit title using the "title" attribute.
+		</setting>
+		<setting id="id_of_elementc">
+Description of the GUI element identified by "id_of_elementc"
+		</setting>
+		[...]
+	</settings>
+
+	<related>
+The related section (always last) typically just contains some links, such as:
+
+<ul>
+	<li><link href="rkward://rhelp/mean"/></li>
+	<li><link href="rkward://rhelp/median"/></li>
+	<li><link href="rkward://component/related_component"/></li>
+</ul>
+	</related>
+</document>
+</programlisting>
+</chapter>
+
 <appendix id="reference">
 <title>Reference</title>
 
@@ -903,6 +1010,26 @@
 <term><document></term>
 <listitem>Needs to be present in each description.xml-file as the root-node. No special function. No attributes</listitem>
 </varlistentry>
+<varlistentry>
+<term><code></term>
+<listitem>Defines where to look for the PHP template to the plugin. Use only once per file, as a direct child of the document-tag. Attributes:
+	<variablelist>
+	<varlistentry>
+	<term><file></term>
+	<listitem>Filename of the PHP template, relative to the directory the plugin-xml is in</listitem>
+	</varlistentry>
+	</variablelist></listitem>
+</varlistentry>
+<varlistentry>
+<term><help></term>
+<listitem>Defines where to look for the help file for the plugin. Use only once per file, as a direct child of the document-tag. Attributes:
+	<variablelist>
+	<varlistentry>
+	<term><file></term>
+	<listitem>Filename of the help file, relative to the directory the plugin-xml is in</listitem>
+	</varlistentry>
+	</variablelist></listitem>
+</varlistentry>
 </variablelist>
 </section>
 


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


