Chapter 6. Writing a help page

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.

You may recall putting this inside your plugin XML (if you have not put this in, do so now):

<document>
	[...]
	<help file="filename.rkh" />
	[...]
</document>
	

Where, obviously, you would replace filename with a more appropriate name. Now it is time to create this .rkh file. Here is a self-descriptive example:

<!DOCTYPE rkhelp>
<document>
	<summary>
In this section, you will 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 is 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" short_title="Generic">
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. The "short_title"
attribute provides a short title to use in the navigation bar. This is optional, by default
the main "title" will be used both as a heading to the section, and as the link name in the
navigation bar.

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 https://rkward.kde.org .
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, e.g.:
<link href="rkward://component/import_spss"/> or
<link href="rkward://component/rkward/import_spss"/> are equivalent).
The component_id is the same that you specified in the .pluginmap.

<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_element">
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
XML definition of the plugin, 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 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>

	<technical>
The technical section (optional, always last) may contain some technical details of the plugin
implementation, which are of interest only to RKWard developers. This is particularly relevant
for plugins that are designed to be embedded in many other plugins, and could detail, which
options are available to customize the embedded plugin, and which code sections contain which
R code.
	</technical>
</document>