[rkward] doc: doc: various small style improvements
Pino Toscano
null at kde.org
Sat Sep 29 17:34:05 BST 2018
Git commit bf4716fdd1fe5a0ee3724a363de7fa545b431d79 by Pino Toscano.
Committed on 29/09/2018 at 16:33.
Pushed by pino into branch 'master'.
doc: various small style improvements
- settle on a single &R; entity, replacing &r;
- get rid of &kapp; in favour of &rkward;
- use entities more: &rkward;, &GUI;, &XML;, &HTML;, &ie;, ⪚,
&javascript;, &URL;, etc
- remove contractions ("don't" -> "do not", etc)
- switch URLs within kde.org to https
- remove extra exclamation marks
- remove few trailing whitespaces
- few more minor fixes
M +9 -24 doc/rkward/index.docbook
M +7 -7 doc/rkward/man-rkward.1.docbook
M +251 -252 doc/rkwardplugins/index.docbook
https://commits.kde.org/rkward/bf4716fdd1fe5a0ee3724a363de7fa545b431d79
diff --git a/doc/rkward/index.docbook b/doc/rkward/index.docbook
index cd7a2849..c7e43f18 100644
--- a/doc/rkward/index.docbook
+++ b/doc/rkward/index.docbook
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
<!ENTITY rkward '<application>RKWard</application>'>
- <!ENTITY kapp "&rkward;"><!-- replace rkward here -->
+ <!ENTITY R '<application>R</application>'>
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE"><!-- change language only here -->
@@ -37,7 +37,6 @@ thanks ;-).
<book lang="&language;">
-
<bookinfo>
<title>The RKWard Handbook</title>
@@ -78,7 +77,7 @@ Do NOT change these in the translation. -->
<abstract>
<para>
-&rkward; is a GUI frontend to the powerful R language for statistical computing.
+&rkward; is a GUI frontend to the powerful &R; language for statistical computing.
</para>
</abstract>
@@ -95,34 +94,33 @@ Please at least include KDE, the KDE package it is in, the name
</bookinfo>
-
<chapter id="introduction">
<title>Introduction</title>
<para>
-&kapp; is meant to be(come) an easy to use graphical frontend to the powerful R language for statistical computing. Since R is a full featured programming language, &kapp; will never be able to offer a complete GUI for everything in R. However, &kapp; strives to make common task simple, to provide an easy entry point for newcomers, while at the same time, transparent access to the full power of the underlying R language is provided for advanced users.
+&rkward; is meant to be(come) an easy to use graphical frontend to the powerful &R; language for statistical computing. Since &R; is a full featured programming language, &rkward; will never be able to offer a complete GUI for everything in &R;. However, &rkward; strives to make common task simple, to provide an easy entry point for newcomers, while at the same time, transparent access to the full power of the underlying &R; language is provided for advanced users.
</para>
</chapter>
<chapter id="using-kapp">
-<title>Using &kapp;</title>
+<title>Using &rkward;</title>
<para>
-Most documentation is available from inside RKWard itself by selecting Help->Help on RKWard from the Menu, NOT in this document!
+Most documentation is available from inside &rkward; itself by selecting <menuchoice><guimenu>Help</guimenu><guimenuitem>Help</guimenuitem></menuchoice> in &rkward; from the menu, <emphasis>not</emphasis> in this document.
</para>
<para>
-A useful guide to getting started with &kapp; is <ulink url="http://rkward.kde.org/User_Documentation">User Documentation Section in the &kapp; wiki</ulink>.
+A useful guide to getting started with &rkward; is <ulink url="https://rkward.kde.org/User_Documentation">User Documentation Section in the &rkward; wiki</ulink>.
</para>
<para>
-Please go there for an introduction to &kapp;, and contact us, if you can help with creating user documentation.
+Please go there for an introduction to &rkward;, and contact us, if you can help with creating user documentation.
</para>
</chapter>
<chapter id="developers">
-<title>Developer's Guide to &kapp;</title>
+<title>Developer's Guide to &rkward;</title>
<para>
-&kapp; can be extended without the need to recompile using plugins. Extensive documentation on this should be included with &kapp; in docbook format, and is available in HTML format <ulink url="http://api.kde.org/doc/rkwardplugins">here</ulink>. (TODO: figure out, how to include this in the docs).
+&rkward; can be extended without the need to recompile using plugins. Extensive documentation on this should be included with &rkward; in DocBook format, and is available in &HTML; format <ulink url="https://api.kde.org/doc/rkwardplugins">here</ulink>. (TODO: figure out, how to include this in the documentation).
</para>
<!-- Use refentries to describe APIs. Refentries are fairly complicated and you
@@ -172,16 +170,3 @@ sgml-indent-step:0
sgml-indent-data:nil
End:
-->
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/doc/rkward/man-rkward.1.docbook b/doc/rkward/man-rkward.1.docbook
index 28cbb125..0cda2d32 100644
--- a/doc/rkward/man-rkward.1.docbook
+++ b/doc/rkward/man-rkward.1.docbook
@@ -49,8 +49,8 @@
<refsect1>
<title>Description</title>
-<para>&rkward; is the a &kde;-based GUI and IDE for the &R; scripting language for statistical computing.</para>
-<para>For more information, please refer to <ulink url="http://rkward.kde.org/">the &rkward; website</ulink>, and the documentation provided inside &rkward;.</para>
+<para>&rkward; is the a &kde;-based &GUI; and <acronym>IDE</acronym> for the &R; scripting language for statistical computing.</para>
+<para>For more information, please refer to <ulink url="https://rkward.kde.org/">the &rkward; website</ulink>, and the documentation provided inside &rkward;.</para>
</refsect1>
<refsect1>
@@ -79,19 +79,19 @@
</varlistentry>
<varlistentry>
<term><option>--r-executable</option> <replaceable>command</replaceable></term>
-<listitem><para>In the case of several R installations, specify the installation to use, e.g. /usr/bin/R. Note that the rkward R library must have been installed to this installation of R, or startup will fail.</para></listitem>
+<listitem><para>In the case of several R installations, specify the installation to use, ⪚ <filename>/usr/bin/R</filename>. Note that the &rkward; R library must have been installed to this installation of R, or startup will fail.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reuse</option></term>
-<listitem><para>If an instance of RKWard is already running, bring that to the front, and open <replaceable>files_to_open</replaceable>. Note that all other command line options will be ignored in case an instance is reused.</para></listitem>
+<listitem><para>If an instance of &rkward; is already running, bring that to the front, and open <replaceable>files_to_open</replaceable>. Note that all other command line options will be ignored in case an instance is reused.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--nowarn-external</option></term>
-<listitem><para>Usually, when invoking RKWard plugins from the command line (i.e. when <replaceable>files_to_open</replaceable> contains urls of the form <replaceable>rkward://runplugin/...</replaceable>), RKWard will show a warning that such urls <emphasis>could</emphasis> be used to trigger malicious actions on your system. This warning applies specifically to links found on untrusted websites, or other untrusted external sources. If you want to script RKWard locally, you can avoid this warning by adding --nowarn-external to the command line.</para></listitem>
+<listitem><para>Usually, when invoking &rkward; plugins from the command line (&ie; when <replaceable>files_to_open</replaceable> contains &URL;s of the form <replaceable>rkward://runplugin/...</replaceable>), &rkward; will show a warning that such &URL;s <emphasis>could</emphasis> be used to trigger malicious actions on your system. This warning applies specifically to links found on untrusted websites, or other untrusted external sources. If you want to script &rkward; locally, you can avoid this warning by adding --nowarn-external to the command line.</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>files_to_open</replaceable></term>
-<listitem><para>You can specify any number of file names or urls for RKWard to open. Usually this will be either workspace files, workplace files, R script files, or rkward://-urls (e.g. for starting with a plugin dialog). Specifying more than one workspace file will lead to the workspaces being merged together, and is not recommended.</para></listitem>
+<listitem><para>You can specify any number of file names or &URL;s for &rkward; to open. Usually this will be either workspace files, workplace files, R script files, or rkward:// &URL;s (⪚ for starting with a plugin dialog). Specifying more than one workspace file will lead to the workspaces being merged together, and is not recommended.</para></listitem>
</varlistentry>
</variablelist>
@@ -118,7 +118,7 @@ rkward --backend-debugger 'valgrind --log-file=valgrind.log'
<refsect1>
<title>Authors</title>
-<para>&rkward; was written by Thomas Friedrichsmeier and the &rkward; team. See <ulink url="http://rkward.kde.org/">the &rkward; website</ulink>.</para>
+<para>&rkward; was written by Thomas Friedrichsmeier and the &rkward; team. See <ulink url="https://rkward.kde.org/">the &rkward; website</ulink>.</para>
</refsect1>
</refentry>
diff --git a/doc/rkwardplugins/index.docbook b/doc/rkwardplugins/index.docbook
index 516bfe45..1ce26996 100644
--- a/doc/rkwardplugins/index.docbook
+++ b/doc/rkwardplugins/index.docbook
@@ -1,9 +1,8 @@
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
<!ENTITY rkward '<application>RKWard</application>'>
- <!ENTITY r '<application>R</application>'>
+ <!ENTITY R '<application>R</application>'>
<!ENTITY pluginmap '<literal role="extension">.pluginmap</literal>'>
- <!ENTITY kapp "&rkward;"><!-- replace rkward here -->
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE"><!-- change language only here -->
@@ -88,7 +87,7 @@ This is a guide to writing plugins for &rkward;.
</note>
<para>
This document describes how to write your own plugins. Note, that at the time of this writing, some of the concepts are not yet set in stone. Therefore, this document should be regarded as an introduction to the current approach, and as a basis for discussion. All sorts of comments are welcome.
- The documentation has grown quite large over time. Don't let that scare you. We recommend reading through the four basic steps (as
+ The documentation has grown quite large over time. Do not let that scare you. We recommend reading through the four basic steps (as
outlined, below), to get a basic idea of how things work. After that you may want to skim the table of contents to see which advanced
topics could be of relevance to you.
</para>
@@ -103,8 +102,8 @@ This is a guide to writing plugins for &rkward;.
</para>
<itemizedlist>
<listitem><para><link linkend="pluginmap">Placing a new Action in the menu hierarchy</link></para></listitem>
- <listitem><para><link linkend="mainxml">Describing the looks and behavior of the plugin GUI</link></para></listitem>
- <listitem><para><link linkend="jstemplate">Defining, how R-code is to be generated from the settings, the user makes in the GUI</link></para></listitem>
+ <listitem><para><link linkend="mainxml">Describing the looks and behavior of the plugin &GUI;</link></para></listitem>
+ <listitem><para><link linkend="jstemplate">Defining, how R-code is to be generated from the settings, the user makes in the &GUI;</link></para></listitem>
<listitem><para><link linkend="pluginhelp">Adding a help page to your plugin</link></para></listitem>
</itemizedlist>
<para>
@@ -113,7 +112,7 @@ This is a guide to writing plugins for &rkward;.
<para>
Some advanced concepts may be used in those four steps, but are dealt with in separate chapters, to keep things simple:
<itemizedlist>
- <listitem><para><link linkend="logic">GUI logic</link></para></listitem>
+ <listitem><para><link linkend="logic">&GUI; logic</link></para></listitem>
<listitem><para><link linkend="embedding">Embedding Plugins into Plugins</link></para></listitem>
<listitem><para><link linkend="plugin_series">Useful concepts for creating many series of similar plugins</link></para></listitem>
</itemizedlist>
@@ -126,13 +125,13 @@ This is a guide to writing plugins for &rkward;.
<chapter id="whatareplugins">
<title>Preliminaries: What are plugins in &rkward;? How do they work?</title>
<para>
- Of course the first question you might have is: What portions of &rkward; functionality is realized using plugins? Or: What can plugins do?
+ Of course the first question you might have is: what portions of &rkward; functionality is realized using plugins? Or: what can plugins do?
</para>
<para>
- One way to answer this is: Deselect all &pluginmap; files under <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &rkward;</guimenuitem><guimenuitem>Plugins</guimenuitem></menuchoice>, and see what's missing. A slightly more helpful answer: Most actual statistics functions accessible via the GUI are realized using plugins. Also, you can create fairly flexible GUIs for all kinds of operations using plugins.
+ One way to answer this is: deselect all &pluginmap; files under <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &rkward;</guimenuitem><guimenuitem>Plugins</guimenuitem></menuchoice>, and see what is missing. A slightly more helpful answer: most actual statistics functions accessible via the &GUI; are realized using plugins. Also, you can create fairly flexible &GUI;s for all kinds of operations using plugins.
</para>
<para>
- The basic paradigm behind &rkward; plugins is the one we'll walk you through in this document: An XML file describes what the GUI looks like. An additional JavaScript file is used to generate &r; syntax from the GUI settings. That is, plugins do not really have to perform any statistical calculations. Rather plugins generate the &r; syntax needed to run those calculations. The &r; syntax is then sent to the &r; backend for evaluation, and typically a result is shown in the output window.
+ The basic paradigm behind &rkward; plugins is the one we will walk you through in this document: an &XML; file describes what the &GUI; looks like. An additional &javascript; file is used to generate &R; syntax from the &GUI; settings. That is, plugins do not really have to perform any statistical calculations. Rather plugins generate the &R; syntax needed to run those calculations. The &R; syntax is then sent to the &R; backend for evaluation, and typically a result is shown in the output window.
</para>
<para>
Read on in the next chapters to see how this is done.
@@ -142,11 +141,11 @@ This is a guide to writing plugins for &rkward;.
<chapter id="pluginmap">
<title>Creating menu entries</title>
<para>
- When you create a new plugin, you need to tell &rkward; about it. So the first thing to do, is to write a &pluginmap; file (or modify an existing one). The format of &pluginmap; is XML. I'll walk you through an example (also of course, be sure you have &rkward; configured to load your &pluginmap; -- <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &rkward;</guimenuitem><guimenuitem>Plugins</guimenuitem></menuchoice>):
+ When you create a new plugin, you need to tell &rkward; about it. So the first thing to do, is to write a &pluginmap; file (or modify an existing one). The format of &pluginmap; is &XML;. I will walk you through an example (also of course, be sure you have &rkward; configured to load your &pluginmap; -- <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &rkward;</guimenuitem><guimenuitem>Plugins</guimenuitem></menuchoice>):
</para>
<tip>
<para>
- After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &r; functions to create most of &rkward;'s XML tags for you.
+ After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &R; functions to create most of &rkward;'s &XML; tags for you.
</para>
</tip>
<programlisting>
@@ -161,7 +160,7 @@ This is a guide to writing plugins for &rkward;.
<para>
The <parameter>base_prefix</parameter> 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. It safe to leave this at <replaceable>""</replaceable>.
</para><para>
- As you will see below, all plugins get a unique identifier, <parameter>id</parameter>. The <parameter>namespace</parameter> 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 <quote>::</quote> gets prepended to all the identifiers you specify in this &pluginmap;. In general, if you intend to <link linkend="sect_external_plugins">distribute your plugins in an &r; package</link>, it is a good idea to use the package name as <parameter>namespace</parameter> parameter. Plugins shipped with the official &rkward; distribution have <replaceable>namespace="rkward"</replaceable>.
+ As you will see below, all plugins get a unique identifier, <parameter>id</parameter>. The <parameter>namespace</parameter> 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 <quote>::</quote> gets prepended to all the identifiers you specify in this &pluginmap;. In general, if you intend to <link linkend="sect_external_plugins">distribute your plugins in an &R; package</link>, it is a good idea to use the package name as <parameter>namespace</parameter> parameter. Plugins shipped with the official &rkward; distribution have <replaceable>namespace="rkward"</replaceable>.
</para>
<para>
The <parameter>id</parameter> attribute is optional, but specifying an id for your &pluginmap; makes it possible for other people to make their &pluginmap;s load your &pluginmap;, automatically (see <link linkend="chapter_dependencies">the section on dependencies</link>).
@@ -170,13 +169,13 @@ This is a guide to writing plugins for &rkward;.
<components>
</programlisting>
<para>
- Components? Aren't we talking about plugins? Yes, but in the future, plugins will be no more than a special class of components. What we do here, then, is to register all components/plugins with &rkward;. Let's look at an example entry:
+ Components? Are not we talking about plugins? Yes, but in the future, plugins will be no more than a special class of components. What we do here, then, is to register all components/plugins with &rkward;. Let's look at an example entry:
</para>
<programlisting>
<component type="standard" id="t_test_two_vars" file="t_test_two_vars.xml" label="Two Variable t-Test" />
</programlisting>
<para>
- First the <parameter>type</parameter> attribute: Leave this to <replaceable>"standard"</replaceable> for now. Further types are not yet implemented. The <parameter>id</parameter> we've already hinted at. Each component has to be given a unique (in its namespace) identifier. Pick one that is easily recognizable. Avoid spaces and any special characters. Those are not banned, so far, but might have special meanings. With the <parameter>file</parameter> attribute, you specify where the <link linkend="mainxml">description of the actual plugin itself</link> is located. This is relative to the directory the &pluginmap; file is in, and the <parameter>base_prefix</parameter> above. Finally, give the component a label. This label will be shown wherever the plugin is placed in the menu (or in the future perhaps in other places as well).
+ First the <parameter>type</parameter> attribute: Leave this to <replaceable>"standard"</replaceable> for now. Further types are not yet implemented. The <parameter>id</parameter> we have already hinted at. Each component has to be given a unique (in its namespace) identifier. Pick one that is easily recognizable. Avoid spaces and any special characters. Those are not banned, so far, but might have special meanings. With the <parameter>file</parameter> attribute, you specify where the <link linkend="mainxml">description of the actual plugin itself</link> is located. This is relative to the directory the &pluginmap; file is in, and the <parameter>base_prefix</parameter> above. Finally, give the component a label. This label will be shown wherever the plugin is placed in the menu (or in the future perhaps in other places as well).
</para>
<para>
Typically a &pluginmap; file will contain several components, so here are a few more:
@@ -190,14 +189,14 @@ This is a guide to writing plugins for &rkward;.
</components>
</programlisting>
<para>
- Ok, this was the first step. &rkward; now knows those plugins exist. But how to invoke them? They need to be placed in a menu hierarchy:
+ OK, this was the first step. &rkward; now knows those plugins exist. But how to invoke them? They need to be placed in a menu hierarchy:
</para>
<programlisting>
<hierarchy>
<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.
+ 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 would 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>
@@ -226,7 +225,7 @@ This is a guide to writing plugins for &rkward;.
<menu id="frequency" label="Frequency" index="2"/>
</programlisting>
<para>
- In case you have lost track: This is another submenu to the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu. See the screenshot below. We'll skip some of what's not visible, marked with [...].
+ In case you have lost track: This is another submenu to the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu. See the screenshot below. We will skip some of what is not visible, marked with [...].
</para>
<programlisting>
[...]
@@ -260,7 +259,7 @@ This is a guide to writing plugins for &rkward;.
</document>
</programlisting>
<para>
- That's how to do it. And this screenshot shows the result:
+ That is how to do it. And this screenshot shows the result:
</para>
<screenshot>
<screeninfo>Menu hierarchy created by the code shown above</screeninfo>
@@ -274,7 +273,7 @@ This is a guide to writing plugins for &rkward;.
</mediaobject>
</screenshot>
<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.
+ 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, do not 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>
@@ -315,18 +314,18 @@ This is a guide to writing plugins for &rkward;.
</chapter>
<chapter id="mainxml">
-<title>Defining the GUI</title>
+<title>Defining the &GUI;</title>
<sect1 id="sect_defining_the_GUI"><title>Defining a dialog</title>
<para>
- In the <link linkend="pluginmap">previous chapter</link> you've seen how to register a plugin with &rkward;. The most important ingredient was specifying the path to an XML file with a description of what the plugin actually looks like. In this chapter you'll learn how to create this XML file.
+ In the <link linkend="pluginmap">previous chapter</link> you have seen how to register a plugin with &rkward;. The most important ingredient was specifying the path to an &XML; file with a description of what the plugin actually looks like. In this chapter you will learn how to create this &XML; file.
</para>
<tip>
<para>
- After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &r; functions to create most of &rkward;'s XML tags for you.
+ After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &R; functions to create most of &rkward;'s &XML; tags for you.
</para>
</tip>
<para>
- Once again we'll walk you through an example. The example is a (slightly simplified) version of the two variable t-Test.
+ Once again we will walk you through an example. The example is a (slightly simplified) version of the two variable t-Test.
</para>
<programlisting>
<!DOCTYPE rkplugin>
@@ -339,13 +338,13 @@ This is a guide to writing plugins for &rkward;.
<code file="t_test_two_vars.js"/>
</programlisting>
<para>
- All plugins generate some code. Currently the only way to do so is using JS, as detailed in <link linkend="jstemplate">the next chapter</link>. This defines, where to look for the JS code. The filename is relative to the directory the plugin XML is in.
+ All plugins generate some code. Currently the only way to do so is using JS, as detailed in <link linkend="jstemplate">the next chapter</link>. This defines, where to look for the JS code. The filename is relative to the directory the plugin &XML; is in.
</para>
<programlisting>
<help file="t_test_two_vars.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="Two Variable t-Test">
@@ -358,13 +357,13 @@ This is a guide to writing plugins for &rkward;.
<tab label="Basic settings">
</programlisting>
<para>
- GUI elements can be organized using a tabbook. Here we define a tabbook as the first element in the dialog. Use <command><tabbook></command>[...]<command></tabbook></command> to define the tabbook and then for each page in the tabbook use <command><tab></command>[...]<command></tab></command>. The <parameter>label</parameter> attribute in the <command><tab></command> element allows you to specify a caption for that page of the tabbook.
+ &GUI; elements can be organized using a tabbook. Here we define a tabbook as the first element in the dialog. Use <command><tabbook></command>[...]<command></tabbook></command> to define the tabbook and then for each page in the tabbook use <command><tab></command>[...]<command></tab></command>. The <parameter>label</parameter> attribute in the <command><tab></command> element allows you to specify a caption for that page of the tabbook.
</para>
<programlisting>
<row id="main_settings_row">
</programlisting>
<para>
- The <command><row></command> and <command><column></command> tags specify the layout of the GUI elements. Here you say, that you'd like to place some elements side-by-side (left to right). The <parameter>id</parameter> attribute is not strictly necessary, but we'll use it later on, when adding a wizard interface to our plugin. The first element to place in the row, is:
+ The <command><row></command> and <command><column></command> tags specify the layout of the &GUI; elements. Here you say, that you would like to place some elements side-by-side (left to right). The <parameter>id</parameter> attribute is not strictly necessary, but we will use it later on, when adding a wizard interface to our plugin. The first element to place in the row, is:
</para>
<programlisting>
<varselector id="vars"/>
@@ -410,7 +409,7 @@ This is a guide to writing plugins for &rkward;.
</tab>
</programlisting>
<para>
- Each tag has to be closed. We've put all the elements we wanted (the two <command><varslots></command> and the <command><radio></command>) in the <command><column></command>. We put all elements we wanted (the <command><varselector></command> and the <command><column></command> with those elements) in the <command><row></command>. And we've put all the elements we wanted into the first page in the <command><tabbook></command>. We're not yet done defining the <command><tabbook></command> (more pages to come), and of course there's more to come in the <command><dialog></command>, too. But this screenshot is basically what we've done so far:
+ Each tag has to be closed. We have put all the elements we wanted (the two <command><varslots></command> and the <command><radio></command>) in the <command><column></command>. We put all elements we wanted (the <command><varselector></command> and the <command><column></command> with those elements) in the <command><row></command>. And we have put all the elements we wanted into the first page in the <command><tabbook></command>. We are not yet done defining the <command><tabbook></command> (more pages to come), and of course there is more to come in the <command><dialog></command>, too. But this screenshot is basically what we have done so far:
</para>
<screenshot>
<screeninfo>t-Test plugin</screeninfo>
@@ -431,13 +430,13 @@ This is a guide to writing plugins for &rkward;.
<checkbox id="varequal" label="assume equal variances" value=", var.equal=TRUE"/>
</programlisting>
<para>
- By default elements will be placed top-to-bottom like in a <command><column></command>. Since that is what we want here, we don't have to explicitly state a <command><row></command> or <command><column></command> layout. The first element we define is a checkbox. Just like the <command><radio></command><command><option></command>s, the checkbox has a <parameter>label</parameter> and a <parameter>value</parameter>. The <parameter>value</parameter> is what gets returned, if the check box is checked. Of course the checkbox also needs an <parameter>id</parameter>.
+ By default elements will be placed top-to-bottom like in a <command><column></command>. Since that is what we want here, we do not have to explicitly state a <command><row></command> or <command><column></command> layout. The first element we define is a checkbox. Just like the <command><radio></command><command><option></command>s, the checkbox has a <parameter>label</parameter> and a <parameter>value</parameter>. The <parameter>value</parameter> is what gets returned, if the check box is checked. Of course the checkbox also needs an <parameter>id</parameter>.
</para>
<programlisting>
<frame label="Confidence Interval" id="frame_conf_int">
</programlisting>
<para>
- Here's yet another layout element: In order to signal that the two elements below belong together, we draw a <command><frame></command> (box). That frame may have a <parameter>label</parameter> (caption). Since the frame is just a passive layout element, it does not need an <parameter>id</parameter>, we still define one here, as we'll refer to it later, when defining an additional wizard interface.
+ Here is yet another layout element: In order to signal that the two elements below belong together, we draw a <command><frame></command> (box). That frame may have a <parameter>label</parameter> (caption). Since the frame is just a passive layout element, it does not need an <parameter>id</parameter>, we still define one here, as we will refer to it later, when defining an additional wizard interface.
</para>
<programlisting>
<checkbox id="confint" label="print confidence interval" value="1" checked="true"/>
@@ -456,20 +455,20 @@ This is a guide to writing plugins for &rkward;.
</dialog>
</programlisting>
<para>
- That's all for the second page of the <command><tabbook></command>, all pages in the <command><tabbook></command> and all elements in the <command><dialog></command>. We're finished defining what the dialog looks like.
+ That is all for the second page of the <command><tabbook></command>, all pages in the <command><tabbook></command> and all elements in the <command><dialog></command>. We are finished defining what the dialog looks like.
</para>
<programlisting>
</document>
</programlisting>
<para>
- Finally we close the <command><document></command> tag, and that's it. The GUI is defined. You can save the file now. But how does &r; syntax get generated from the GUI-settings? We'll deal with that in the <link linkend="jstemplate">next chapter</link>. First, however, we'll look into adding a wizard interface, and some general considerations.
+ Finally we close the <command><document></command> tag, and that is it. The &GUI; is defined. You can save the file now. But how does &R; syntax get generated from the &GUI; settings? We will deal with that in the <link linkend="jstemplate">next chapter</link>. First, however, we will look into adding a wizard interface, and some general considerations.
</para>
</sect1>
<sect1 id="wizard_interface">
<title>Adding a wizard interface</title>
<para>
- Actually we don't have to define an additional <command><wizard></command> interface, but here's how that would be done. To add a wizard interface, you'll add a <command><wizard></command> tag at the same level as the <command><dialog></command> tag:
+ Actually we do not have to define an additional <command><wizard></command> interface, but here is how that would be done. To add a wizard interface, you will add a <command><wizard></command> tag at the same level as the <command><dialog></command> tag:
</para>
<programlisting>
<wizard label="Two Variable t-Test">
@@ -481,18 +480,18 @@ This is a guide to writing plugins for &rkward;.
</page>
</programlisting>
<para>
- Some of this is pretty self explanatory: We add a <command><wizard></command> tag with a <parameter>label</parameter> for the wizard. Since a wizard can hold several pages that are shown one after another, we next define the first <command><page></command>, and put an explanatory <command><text></command> note in there. Then we use a <command><copy></command> tag. What this does, is really it saves us having to define yet again, what we already wrote for the <command><dialog></command>: The copy tag looks for another tag with the same <parameter>id</parameter> earlier in the XML. This happens to be defined in the <command><dialog></command> section, and is a <command><row></command> in which there are the <command><varselector></command>, <command><varslots></command> and the <quote>hypothesis</quote> <command><radio></command> control. All of this is copied 1:1 and inserted right at the <command><copy></command> element.
+ Some of this is pretty self explanatory: We add a <command><wizard></command> tag with a <parameter>label</parameter> for the wizard. Since a wizard can hold several pages that are shown one after another, we next define the first <command><page></command>, and put an explanatory <command><text></command> note in there. Then we use a <command><copy></command> tag. What this does, is really it saves us having to define yet again, what we already wrote for the <command><dialog></command>: The copy tag looks for another tag with the same <parameter>id</parameter> earlier in the &XML;. This happens to be defined in the <command><dialog></command> section, and is a <command><row></command> in which there are the <command><varselector></command>, <command><varslots></command> and the <quote>hypothesis</quote> <command><radio></command> control. All of this is copied 1:1 and inserted right at the <command><copy></command> element.
</para>
<para>
Now to the second page:
</para>
<programlisting>
<page id="secondpage">
- <text>Below are some advanced options. It's generally safe not to assume the
+ <text>Below are some advanced options. It is generally safe not to assume the
variables have equal variances. An appropriate correction will be applied then.
Choosing "assume equal variances" may increase test-strength, however.</text>
<copy id="varequal"/>
- <text>Sometimes it's helpful to get an estimate of the confidence interval of
+ <text>Sometimes it is helpful to get an estimate of the confidence interval of
the difference in means. Below you can specify whether one should be shown, and
which confidence-level should be applied (95% corresponds to a 5% level of
significance).</text>
@@ -509,9 +508,9 @@ This is a guide to writing plugins for &rkward;.
</sect1>
<sect1 id="mainxmltips">
- <title>Some considerations on GUI design</title>
+ <title>Some considerations on &GUI; design</title>
<para>
- This section contains some general considerations on which GUI elements to use where. If this is your first attempt of creating a plugin, feel free to skip over this section, as it isn't relevant to getting a basic GUI working. Come back here, later, to see, whether you can refine your plugin's GUI in some way or another.
+ This section contains some general considerations on which &GUI; elements to use where. If this is your first attempt of creating a plugin, feel free to skip over this section, as it is not relevant to getting a basic &GUI; working. Come back here, later, to see, whether you can refine your plugin's &GUI; in some way or another.
</para>
<sect2 id="radio_vs_checkbox_vs_dropdown">
@@ -520,7 +519,7 @@ This is a guide to writing plugins for &rkward;.
The three elements <command><radio></command>, <command><checkbox></command>, <command><dropdown></command>, all serve a similar function: To select one out of several options. Obviously, a check box only allows to choose between two options: checked or not checked, so you cannot use it, if there are more than two options to choose from. But when to use which of the elements? Some rules of thumb:
</para>
<para>
- If you find yourself creating a <command><radio></command> or <command><dropdown></command> with only two options, ask yourself, whether the question is essentially a yes / no type of question. E.g. a choice between <quote>adjust results</quote> and <quote>do not adjust results</quote>, or between <quote>remove missing values</quote> and <quote>keep missing values</quote>. In this case a <command><checkbox></command> 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 choose a <command><radio></command> over a <command><checkbox></command>, when there are only two options. An example of that might be: <quote>Method of calculation: 'pearson'/'spearman'</quote>. Here, more methods might be thinkable, and they don't really form a pair of opposites.
+ If you find yourself creating a <command><radio></command> or <command><dropdown></command> with only two options, ask yourself, whether the question is essentially a yes / no type of question. E.g. a choice between <quote>adjust results</quote> and <quote>do not adjust results</quote>, or between <quote>remove missing values</quote> and <quote>keep missing values</quote>. In this case a <command><checkbox></command> 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 choose a <command><radio></command> over a <command><checkbox></command>, when there are only two options. An example of that might be: <quote>Method of calculation: 'pearson'/'spearman'</quote>. Here, more methods might be thinkable, and they do not really form a pair of opposites.
</para>
<para>
Choosing between a <command><radio></command> and a <command><dropdown></command> is mostly a question of space. The <command><dropdown></command> has the advantage of using little space, even if there are a lot of options to choose from. On the other hand, a <command><radio></command> has the advantage of making all possible choices visible to the user at once, without clicking on the dropdown arrow. Generally, if there are six or more options to choose from, a <command><dropdown></command> is preferable. If there are five or less options, a <command><radio></command> is the better choice.
@@ -530,19 +529,19 @@ This is a guide to writing plugins for &rkward;.
</chapter>
<chapter id="jstemplate">
-<title>Generating &r; code from GUI settings</title>
-<sect1 id="sect_generating_R_code"><title>Using JavaScript in &rkward; plugins</title>
+<title>Generating &R; code from &GUI; settings</title>
+<sect1 id="sect_generating_R_code"><title>Using &javascript; in &rkward; plugins</title>
<para>
- Now we have a GUI defined, but we still need to generate some &r; code from that. For that, we need another text file, <filename>code.js</filename>, located in the same directory as the <link linkend="mainxml"><filename>description.xml</filename></link>. You may or may not be familiar with JavaScript (or, to be technically precise: ECMA-script). Documentation on JS can be found in abundance, both in printed form, and on the Internet (⪚: <ulink url="https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide">https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide</ulink>). But for most purposes you will not need to know much about JS at all, as we'll only use some very basic features.
+ Now we have a &GUI; defined, but we still need to generate some &R; code from that. For that, we need another text file, <filename>code.js</filename>, located in the same directory as the <link linkend="mainxml"><filename>description.xml</filename></link>. You may or may not be familiar with &javascript; (or, to be technically precise: ECMA-script). Documentation on JS can be found in abundance, both in printed form, and on the Internet (⪚: <ulink url="https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide">https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide</ulink>). But for most purposes you will not need to know much about JS at all, as we will only use some very basic features.
</para>
<tip>
<para>
- After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &r; functions to create JavaScript code commonly used in &rkward;. It can also autodetect variables used in a plugin XML file and create basic JavaScript code from that for you to start with.
+ After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &R; functions to create &javascript; code commonly used in &rkward;. It can also autodetect variables used in a plugin &XML; file and create basic &javascript; code from that for you to start with.
</para>
</tip>
<note>
<para>
- Plugin .js files are assumed to be UTF-8 encoded. Be sure to check you editor's encoding, if using any non-ascii characters.
+ Plugin <literal role="extension">.js</literal> files are assumed to be UTF-8 encoded. Be sure to check you editor's encoding, if using any non-ascii characters.
</para>
</note>
<para>
@@ -567,13 +566,13 @@ function calculate () {
}
</programlisting>
<para>
- This function generates the actual &r; syntax to be run from the GUI settings. Let's look at this in detail: The code to be used is generated using <function>echo()</function> statement. Looking at the <function>echo()</function> statement step by step, the first part of it is
+ This function generates the actual &R; syntax to be run from the &GUI; settings. Let's look at this in detail: The code to be used is generated using <function>echo()</function> statement. Looking at the <function>echo()</function> statement step by step, the first part of it is
</para>
<screen>
res <- t.test (
</screen>
<para>
- as plain text. Next we need to fill in the value, the user selected as the first variable. We fetch this using <function>getString ("x")</function>, and append it to the string to be <quote>echoed</quote>. This prints out the value of the GUI-element with <parameter>id=</parameter><replaceable>"x"</replaceable>: our first <command><checkbox></command>. Next, we append a ', ', and do the same to fetch the value of the element <replaceable>"y"</replaceable> - the second <command><checkbox></command>. For the hypothesis (the <command><radio></command> group), and the equal variances <command><checkbox></command>, the procedure is very similar.
+ as plain text. Next we need to fill in the value, the user selected as the first variable. We fetch this using <function>getString ("x")</function>, and append it to the string to be <quote>echoed</quote>. This prints out the value of the &GUI;-element with <parameter>id=</parameter><replaceable>"x"</replaceable>: our first <command><checkbox></command>. Next, we append a ', ', and do the same to fetch the value of the element <replaceable>"y"</replaceable> - the second <command><checkbox></command>. For the hypothesis (the <command><radio></command> group), and the equal variances <command><checkbox></command>, the procedure is very similar.
</para>
<para>
Note that instead of concatenating the output snippets with <quote>+</quote>, you can also use several <function>echo()</function> statements. Everything is printed on a single line. To produce a line break in the generated code, insert a <replaceable>"\n"</replaceable> in the echoed string. In theory, you can even produce many lines with a single echo-statement, but please keep it to one line (or less) of generated code per <function>echo()</function>.
@@ -584,7 +583,7 @@ res <- t.test (
</para>
</note>
<para>
- It gets a little more tricky for the confidence level. For reasons of aesthetics, we don't want to explicitly specify the confidence level to use, if it corresponds to the default value. Hence, instead of printing the value unconditionally, we first fetch into a variable. Then we check, whether that variable differs from <replaceable>"0.95"</replaceable> and if so print out an additional argument. Finally, we echo a closing bracket and a line break: <replaceable>")\n"</replaceable>. That's all for the calculate function.
+ It gets a little more tricky for the confidence level. For reasons of aesthetics, we do not want to explicitly specify the confidence level to use, if it corresponds to the default value. Hence, instead of printing the value unconditionally, we first fetch into a variable. Then we check, whether that variable differs from <replaceable>"0.95"</replaceable> and if so print out an additional argument. Finally, we echo a closing bracket and a line break: <replaceable>")\n"</replaceable>. That is all for the calculate function.
</para>
</sect2>
<sect2 id="sect_JS_printout"><title>printout()</title>
@@ -595,7 +594,7 @@ function printout () {
}
</programlisting>
<para>
- And this was all there is to the printout function in most cases. <function>rk.header()</function> prints a standard headline for the results. Note that in the .js files, you have to
+ And this was all there is to the printout function in most cases. <function>rk.header()</function> prints a standard headline for the results. Note that in the <literal role="extension">.js</literal> files, you have to
mark up all translatable strings by hand, using <command>i18n()</command>, or some alternative commands. More on this in the <link linkend="i18n_js">chapter on internationalization</link>.
You can also add some more information to this, if you like, ⪚:
</para>
@@ -610,10 +609,10 @@ echo ('rk.print (res)\n');
}
</programlisting>
<para>
- <function>rk.print()</function> utilizes the R2HTML package to provide HTML formatted output. Another helpful function is <function>rk.results()</function>, which can also output different kinds of result tables. If in doubt, however, just use <function>rk.print()</function>, and be done with. The JS class <function>Header</function> is a JS level helper to generate a call to <function>rk.header()</function> (just take a look at the generated &r; code). In some cases you may want to call <function>echo ('rk.header (...)')</function> directly to print a header for your output.
+ <function>rk.print()</function> utilizes the R2HTML package to provide &HTML; formatted output. Another helpful function is <function>rk.results()</function>, which can also output different kinds of result tables. If in doubt, however, just use <function>rk.print()</function>, and be done with. The JS class <function>Header</function> is a JS level helper to generate a call to <function>rk.header()</function> (just take a look at the generated &R; code). In some cases you may want to call <function>echo ('rk.header (...)')</function> directly to print a header for your output.
</para>
<para>
- Note that internally, the output is just a plain HTML document at this point of time. Therefore you might be tempted to add custom HTML using <function>rk.cat.output()</function>. While this will work, please don't do this. The output format may change (⪚ to ODF) in the future, so it's best not to introduce HTML specific code. Rather keep things simple with <function>rk.header()</function>, <function>rk.print()</function>, <function>rk.results()</function>, and -- if needed -- <function>rk.print.literal()</function>. If those don't seem to satisfy your formatting needs, contact us on the mailing list for help.
+ Note that internally, the output is just a plain &HTML; document at this point of time. Therefore you might be tempted to add custom &HTML; using <function>rk.cat.output()</function>. While this will work, please do not do this. The output format may change (⪚ to ODF) in the future, so it is best not to introduce &HTML; specific code. Rather keep things simple with <function>rk.header()</function>, <function>rk.print()</function>, <function>rk.results()</function>, and -- if needed -- <function>rk.print.literal()</function>. If those do not seem to satisfy your formatting needs, contact us on the mailing list for help.
</para>
<para>
Congratulations! You created your first plugin. Read on in the next chapters for more advanced concepts.
@@ -624,13 +623,13 @@ echo ('rk.print (res)\n');
<sect1 id="jsconventions">
<title>Conventions, policies, and background</title>
<para>
- There are many ways to write &r; code for a certain task, and there are even more ways to generate this &r; code from JS. How exactly you do it, is left up to you. Still there are a number of considerations that you should follow, and background information you should understand.
+ There are many ways to write &R; code for a certain task, and there are even more ways to generate this &R; code from JS. How exactly you do it, is left up to you. Still there are a number of considerations that you should follow, and background information you should understand.
</para>
<sect2 id="policylocal">
<title>Understanding the <function>local()</function> environment</title>
<para>
- More often than not you will have to create one or more temporary &r; objects in the code generated by your plugin. Normally, you do not want those to be placed in the user's workspace, potentially even overwriting user variables. Hence, all plugin generated code is run in a <function>local()</function> environment (see &r; help page on function <function>local()</function>). This means, all variables you create are temporary and will not be saved permanently.
+ More often than not you will have to create one or more temporary &R; objects in the code generated by your plugin. Normally, you do not want those to be placed in the user's workspace, potentially even overwriting user variables. Hence, all plugin generated code is run in a <function>local()</function> environment (see &R; help page on function <function>local()</function>). This means, all variables you create are temporary and will not be saved permanently.
</para>
<para>
If the user explicitly asks for a variable to be saved, you will need to assign to that object using <function>.GlobalEnv$objectname <- value</function>. In general, do not use the <function><<-</function> operator. It will not necessarily assign in .GlobalEnv.
@@ -643,10 +642,10 @@ echo ('rk.print (res)\n');
<sect2 id="policyformatting">
<title>Code formatting</title>
<para>
- The most important thing is for your generated &r; code to work, but it should be also easy to read. Therefore, please also keep an eye on formatting. Some considerations:
+ The most important thing is for your generated &R; code to work, but it should be also easy to read. Therefore, please also keep an eye on formatting. Some considerations:
</para>
<para>
- Normal top-level &r; statements should be left aligned.
+ Normal top-level &R; statements should be left aligned.
</para>
<para>
Statements in a lower block should be indented with one tab (see example below).
@@ -699,7 +698,7 @@ function calculate () {
Here are a few assorted tricks which may make writing plugins less tedious:
</para>
<para>
- If you need the value of a GUI setting at several places in you plugin's code, consider assigning it to a variable in JS, and using that instead of fetching it again and again with <function>getString()/getBoolean()/getList()</function>. This is faster, more readable, and less typing all at the same time:
+ If you need the value of a &GUI; setting at several places in you plugin's code, consider assigning it to a variable in JS, and using that instead of fetching it again and again with <function>getString()/getBoolean()/getList()</function>. This is faster, more readable, and less typing all at the same time:
</para>
<programlisting>
function calculate () {
@@ -732,15 +731,15 @@ function calculate () {
<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.
+ 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>
<tip>
<para>
- After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &r; functions to create most of &rkward;'s XML tags for you. It's also capable of creating basic help file skeletons from existing plugin XML files for you to start with.
+ After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &R; functions to create most of &rkward;'s &XML; tags for you. It is also capable of creating basic help file skeletons from existing plugin &XML; files for you to start with.
</para>
</tip>
<para>
- You may recall putting this inside your plugin XML (if you haven't put this in, do so now):
+ You may recall putting this inside your plugin &XML; (if you have not put this in, do so now):
</para>
<programlisting>
<document>
@@ -750,19 +749,19 @@ function calculate () {
</document>
</programlisting>
<para>
- Where, obviously, you'd replace <filename>filename</filename> with a more appropriate name. Now it's time to create this <literal role="extension">.rkh</literal> file. Here is a self-descriptive example:
+ Where, obviously, you would replace <filename>filename</filename> with a more appropriate name. Now it is time to create this <literal role="extension">.rkh</literal> 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.
+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's done in the "settings" section), however.
+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.
@@ -785,7 +784,7 @@ In any section you may want to insert links to further information. You do this
<link href="URL">link name</link>
-Where URL could be an external link such as http://rkward.kde.org .
+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"/>
@@ -802,7 +801,7 @@ The component_id is the same that you specified in the <link linkend="pluginmap"
<link href="rkward://rhelp/rfunction"/>
-Links to the &r; help page on "rfunction".
+Links to the &R; help page on "rfunction".
Note that the link names will be generated automatically for these types of links.
</section>
@@ -814,7 +813,7 @@ 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,
+<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>
@@ -847,10 +846,10 @@ R code.
<chapter id="logic">
-<title>Logic interactions between GUI elements</title>
-<sect1 id="sect_GUI_logic"><title>GUI logic</title>
+<title>Logic interactions between &GUI; elements</title>
+<sect1 id="sect_GUI_logic"><title>&GUI; logic</title>
<para>
- All the basic concepts of creating a plugin for &rkward; have been described in the previous chapters. Those basic concepts should be sufficient for many -- if not most -- cases. However, sometimes you want more control over how your plugin's GUI behaves.
+ All the basic concepts of creating a plugin for &rkward; have been described in the previous chapters. Those basic concepts should be sufficient for many -- if not most -- cases. However, sometimes you want more control over how your plugin's &GUI; behaves.
</para>
<para>
For instance, suppose you want to extend the t-test example used in this documentation to allow both: comparing a variable against another variable (as shown), and comparing a variable against a constant value. Now, one way of doing this would be to add a radio-control that switches between the two modes, and adding a spinbox to enter the constant value to compare against. Consider this simplified example:
@@ -877,7 +876,7 @@ R code.
</document>
</programlisting>
<para>
- So far so good, but there are a number of problems with this GUI. First, both the varslot and the spinbox are always shown, whereas only one of the two is really used. Worse, the varslot always requires a valid selection, even if you compare against a constant. Obviously, if we create a multi-purpose GUI like this, we want more flexibility. Enter: the <command><logic></command> section (inserted at the same level as <command><code></command>, <command><dialog></command>, or <command><wizard></command>).
+ So far so good, but there are a number of problems with this &GUI;. First, both the varslot and the spinbox are always shown, whereas only one of the two is really used. Worse, the varslot always requires a valid selection, even if you compare against a constant. Obviously, if we create a multi-purpose &GUI; like this, we want more flexibility. Enter: the <command><logic></command> section (inserted at the same level as <command><code></command>, <command><dialog></command>, or <command><wizard></command>).
</para>
<programlisting>
[...]
@@ -897,7 +896,7 @@ R code.
The first line inside the logic section is a <command><convert></command> tag. Basically, this provides a new boolean (on or off, true or false) property, which can be used later on. This property (<replaceable>"varmode"</replaceable>) is true, whenever the upper radio button is selected and false whenever the lower radio button is selected. How is this done?
</para>
<para>
- First, under <parameter>sources</parameter>, the source properties to work on are listed (in this case only one each; you could list several as <parameter>sources=</parameter><replaceable>"mode.string;somethingelse"</replaceable>, then <replaceable>"varmode"</replaceable> would only be true, if both <replaceable>"mode.string"</replaceable> and <replaceable>"somethingelse"</replaceable> are equal to the string <replaceable>"variable"</replaceable>). Note that in this case we don't just write <replaceable>"mode"</replaceable> (as we would in <function>getString("mode")</function>), but <replaceable>"mode.string"</replaceable>. This is actually the internal way a radio control works: It has a property <quote>string</quote>, which holds its string value. <function>getString("mode")</function> is just a shorthand, and equivalent to <function>getString("mode.string")</function>. See the reference for all properties of the different GUI elements.
+ First, under <parameter>sources</parameter>, the source properties to work on are listed (in this case only one each; you could list several as <parameter>sources=</parameter><replaceable>"mode.string;somethingelse"</replaceable>, then <replaceable>"varmode"</replaceable> would only be true, if both <replaceable>"mode.string"</replaceable> and <replaceable>"somethingelse"</replaceable> are equal to the string <replaceable>"variable"</replaceable>). Note that in this case we do not just write <replaceable>"mode"</replaceable> (as we would in <function>getString("mode")</function>), but <replaceable>"mode.string"</replaceable>. This is actually the internal way a radio control works: It has a property <quote>string</quote>, which holds its string value. <function>getString("mode")</function> is just a shorthand, and equivalent to <function>getString("mode.string")</function>. See the reference for all properties of the different &GUI; elements.
</para>
<para>
Second, we set the mode of conversion to <parameter>mode=</parameter><replaceable>"equals"</replaceable>. This means, we want to check, whether the source(s) is (are) equal to a certain value. Finally standard is the value to compare against, so with <parameter>standard=</parameter><replaceable>"variable"</replaceable>, we check whether the property <replaceable>"mode.string"</replaceable> is equal to the string <replaceable>"variable"</replaceable> (the value of the upper radio option). If it is equal, then the property varmode is true, else it is false.
@@ -908,19 +907,19 @@ R code.
<para>
For the spinbox, we want the exact reverse. Fortunately, we do not need another <command><convert></command> for this: Boolean
properties can be negated very easily by appending the modifier <replaceable>"not"</replaceable>, so we <command><connect></command> <replaceable>"varmode.not"</replaceable> to the spinbox's visibility property. In effect, either
- the varslot is shown and required, <emphasis>or</emphasis> the spinbox is shown and required - depending on which option is selected in the radio control. The GUI is changing itself according to the radio option. Try the example, if you like.
+ the varslot is shown and required, <emphasis>or</emphasis> the spinbox is shown and required - depending on which option is selected in the radio control. The &GUI; is changing itself according to the radio option. Try the example, if you like.
</para>
<para>
- For a complete list of properties, refer to the <link linkend="reference">reference</link>. One more property, however, is special in that all GUI elements have it: <quote>enabled</quote>. This is slightly less drastic than <quote>visible</quote>. It does not show/hide the GUI element, but only enables/disables it. Disabled elements are typically shown grayed out, and do not react to user input.
+ For a complete list of properties, refer to the <link linkend="reference">reference</link>. One more property, however, is special in that all &GUI; elements have it: <quote>enabled</quote>. This is slightly less drastic than <quote>visible</quote>. It does not show/hide the &GUI; element, but only enables/disables it. Disabled elements are typically shown grayed out, and do not react to user input.
</para>
<note>
<para>Besides <command><convert></command> and <command><connect></command>, there are several further elements for use in the <command><logic></command> section. E.g. conditional constructs can also be implemented using the <command><switch></command>-element. Refer to the <link linkend="logicelements">reference on logic elements</link> for details.</para>
</note>
</sect1>
<sect1 id="logic_scripted">
-<title>Scripted GUI logic</title>
+<title>Scripted &GUI; logic</title>
<para>
- While connecting properties as described above is often enough, sometimes it is more flexible or more convenient to use JS to script the GUI logic. In this way, the above example could be re-written as:
+ While connecting properties as described above is often enough, sometimes it is more flexible or more convenient to use JS to script the &GUI; logic. In this way, the above example could be re-written as:
</para>
<programlisting>
[...]
@@ -948,10 +947,10 @@ R code.
The first line of code tells &rkward; to call the function <function>modeChanged()</function> whenever the value of the <parameter>id=</parameter><replaceable>"mode"</replaceable> radio box changes. Inside this function, we define a helper-variable <replaceable>"varmode"</replaceable> which is true when the mode is <replaceable>"variable"</replaceable>, false as it is <replaceable>"constant"</replaceable>. Then we use <function>gui.setValue()</function> to set the <quote>enabled</quote> properties of <replaceable>"y"</replaceable> and <replaceable>"constant"</replaceable>, in just the same way as we did using <command><connect></command> statements, before.
</para>
<para>
- The scripted approach to GUI logic becomes particularly useful when you want to change the available option according to the type of object that the user has selected. See <link linkend="guilogic_functions">the reference</link> for available functions.
+ The scripted approach to &GUI; logic becomes particularly useful when you want to change the available option according to the type of object that the user has selected. See <link linkend="guilogic_functions">the reference</link> for available functions.
</para>
<para>
- Note that the scripted approach to GUI logic can be mixed with <command><connect></command> and <command><convert></command>-statements if you like. Also note that the <command><script></command> tag allows to specify a script file name in addition to or as an alternative to inlining the script code. Typically, inlining the script code as shown above is most convenient, however.
+ Note that the scripted approach to &GUI; logic can be mixed with <command><connect></command> and <command><convert></command>-statements if you like. Also note that the <command><script></command> tag allows to specify a script file name in addition to or as an alternative to inlining the script code. Typically, inlining the script code as shown above is most convenient, however.
</para>
</sect1>
</chapter>
@@ -960,16 +959,16 @@ R code.
<title>Embedding Plugins into Plugins</title>
<sect1 id="sect_embedding"><title>Use cases for embedding</title>
<para>
- When writing plugins, you will often find that you're creating a number of plugins that only differ in some respects, but have a lot more in common. For instance, for plotting, there are a number of generic &r; options that can be used with mostly all types of plots. Should you create a GUI and JS-template for those over and over again?
+ When writing plugins, you will often find that you are creating a number of plugins that only differ in some respects, but have a lot more in common. For instance, for plotting, there are a number of generic &R; options that can be used with mostly all types of plots. Should you create a &GUI; and JS-template for those over and over again?
</para>
<para>
- Obviously that would be quite a hassle. Fortunately, you don't have to do that. Rather you create the common functionality once, and later you can embed it into several plugins. In fact it is possible to embed any plugin into any other plugin, even if the original author of the embedded plugin never thought, somebody would want to embed their plugin into another one.
+ Obviously that would be quite a hassle. Fortunately, you do not have to do that. Rather you create the common functionality once, and later you can embed it into several plugins. In fact it is possible to embed any plugin into any other plugin, even if the original author of the embedded plugin never thought, somebody would want to embed their plugin into another one.
</para>
</sect1>
<sect1 id="embedding_dialog">
<title>Embedding inside a dialog</title>
<para>
- Ok, enough said. How does it work? Simple: Just use the <command><embed></command> tag. Here's a stripped down example:
+ OK, enough said. How does it work? Simple: Just use the <command><embed></command> tag. Here is a stripped down example:
</para>
<programlisting>
<dialog>
@@ -987,7 +986,7 @@ R code.
</dialog>
</programlisting>
<para>
- What happens here, is that the entire GUI or the plot options plugin (except of course for the standard elements like <guibutton>Submit</guibutton> button, &etc;) is embedded right into your plugin (try it!).
+ What happens here, is that the entire &GUI; or the plot options plugin (except of course for the standard elements like <guibutton>Submit</guibutton> button, &etc;) is embedded right into your plugin (try it!).
</para>
<para>
As you can see the syntax of the <command><embed></command>-tag is fairly simple. It takes an <parameter>id</parameter> as most elements. The parameter component specifies which plugin to embed, as defined in the &pluginmap; file (<replaceable>"rkward::plot_options"</replaceable> is the result of concatenating the namespace <quote>rkward</quote>, a separator <quote>::</quote>, and the name of the component <quote>plot_options</quote>).
@@ -1006,13 +1005,13 @@ function printout () {
}
</programlisting>
<para>
- So essentially, we're fetching the code generated by the embedded plugin just like we're fetching any other GUI setting. Here the string <replaceable>"plotoptions.code.printout"</replaceable> can be deparsed to: <quote>The printout section of the generated code of the element with the <parameter>id</parameter> plotoptions</quote> (plotoptions is the ID we gave for the <command><embed></command> tag above). And yes, if you want advanced control, you can even fetch the values of individual GUI elements inside the embedded plugin (but not the other way around, as the embedded plugin does not know anything about its surroundings).
+ So essentially, we are fetching the code generated by the embedded plugin just like we are fetching any other &GUI; setting. Here the string <replaceable>"plotoptions.code.printout"</replaceable> can be deparsed to: <quote>The printout section of the generated code of the element with the <parameter>id</parameter> plotoptions</quote> (plotoptions is the ID we gave for the <command><embed></command> tag above). And yes, if you want advanced control, you can even fetch the values of individual &GUI; elements inside the embedded plugin (but not the other way around, as the embedded plugin does not know anything about its surroundings).
</para>
</sect1>
<sect1 id="embedding_wizard">
<title>Embedding inside a wizard</title>
<para>
- If your plugin provides a wizard GUI, embedding works basically in the same way. You'll generally use:
+ If your plugin provides a wizard &GUI;, embedding works basically in the same way. You will generally use:
</para>
<programlisting>
<wizard [...]>
@@ -1034,7 +1033,7 @@ function printout () {
<sect1 id="embedding_as_button">
<title>Less embedded embedding: Further Options button</title>
<para>
- While embedding is cool, you should be careful not to overdo it. Too many functions inside a GUI just make it hard to find the relevant options. Of course, sometimes you may want to embed a great deal of options (like all the options to <function>plot()</function>), but as those are really optional, you don't want them prominently in your GUI.
+ While embedding is cool, you should be careful not to overdo it. Too many functions inside a &GUI; just make it hard to find the relevant options. Of course, sometimes you may want to embed a great deal of options (like all the options to <function>plot()</function>), but as those are really optional, you do not want them prominently in your &GUI;.
</para>
<para>
An alternative is to embed those options <quote>as a button</quote>:
@@ -1052,7 +1051,7 @@ function printout () {
</dialog>
</programlisting>
<para>
- In this case, a single push button will be added to your plugin, labeled <guibutton>Specify plotting options</guibutton>. When you press that button, a separate dialog will come up, with all the options of the embedded plugin. Even while this embedded GUI is not visible most of the time, you can fetch its settings just as described <link linkend="embedding_code">above</link>.
+ In this case, a single push button will be added to your plugin, labeled <guibutton>Specify plotting options</guibutton>. When you press that button, a separate dialog will come up, with all the options of the embedded plugin. Even while this embedded &GUI; is not visible most of the time, you can fetch its settings just as described <link linkend="embedding_code">above</link>.
</para>
<para>
<caution>
@@ -1065,7 +1064,7 @@ function printout () {
<sect1 id="embedding_incomplete">
<title>Embedding/defining incomplete plugins</title>
<para>
- Some plugins -- and as a matter of fact, the plot_options used as an example above, is one of them -- are not complete by themselves. They simply do not have the GUI elements to select some important values. They are meant to be used only embedded into other plugins.
+ Some plugins -- and as a matter of fact, the plot_options used as an example above, is one of them -- are not complete by themselves. They simply do not have the &GUI; elements to select some important values. They are meant to be used only embedded into other plugins.
</para>
<para>
In how far is the plot_options plugin incomplete? Well, for some option settings, it needs to know the name of the objects/expressions for the x and y axes (actually it will do fine if it only has either, but it needs at least one to function properly). However, it does not have a mechanism of selecting those objects, or entering them any other way. So how does it know about them?
@@ -1096,7 +1095,7 @@ function printout () {
</logic>
</programlisting>
<para>
- This is nothing new in principle, we've covered <command><connect></command> statements in the <link linkend="logic">chapter of GUI logic</link>. You simply connect the values in two varlots (called <replaceable>"xvarslot"</replaceable> and <replaceable>"yvarslot"</replaceable> in this example) to the receiving <quote>external</quote> properties of the embedded plugin. That's it. Everything else is taken care of automatically.
+ This is nothing new in principle, we have covered <command><connect></command> statements in the <link linkend="logic">chapter of &GUI; logic</link>. You simply connect the values in two varlots (called <replaceable>"xvarslot"</replaceable> and <replaceable>"yvarslot"</replaceable> in this example) to the receiving <quote>external</quote> properties of the embedded plugin. That is it. Everything else is taken care of automatically.
</para>
</sect1>
</chapter>
@@ -1105,10 +1104,10 @@ function printout () {
<title>Dealing with many similar plugins</title>
<sect1 id="sect_similar_plugins"><title>Overview on different approaches</title>
<para>
- Sometimes, you may wish to develop plugins for a series of similar functions. As an example, consider the distribution plots. These generate fairly similar code, and of course it's desirable to make the graphical interfaces look similar to each other. Finally large sections of the help files can be identical. Only a few parameters are different for each plugin.
+ Sometimes, you may wish to develop plugins for a series of similar functions. As an example, consider the distribution plots. These generate fairly similar code, and of course it is desirable to make the graphical interfaces look similar to each other. Finally large sections of the help files can be identical. Only a few parameters are different for each plugin.
</para>
<para>
- The naive approach to this is to develop one plugin, then basically copy and paste the entire contents of the <literal role="extension">.js</literal>, <literal role="extension">.xml</literal>, and <literal role="extension">.rkh</literal> files, then changing the few portions that are different. However, what if sometime later you find a spelling mistake that has been copied and pasted to all plugins? What if you want to add support for a new feature? You'd have to visit all plugins again, and change each single one. A tiresome and tedious process.
+ The naive approach to this is to develop one plugin, then basically copy and paste the entire contents of the <literal role="extension">.js</literal>, <literal role="extension">.xml</literal>, and <literal role="extension">.rkh</literal> files, then changing the few portions that are different. However, what if sometime later you find a spelling mistake that has been copied and pasted to all plugins? What if you want to add support for a new feature? You would have to visit all plugins again, and change each single one. A tiresome and tedious process.
</para>
<para>
A second approach would be to use <link linkend="embedding">embedding</link>. However, in some cases this does not lend itself well to the problem at hand, mostly because the <quote>chunks</quote> you can embed are sometimes too large to be useful, and it places some constraints on the layout. For these cases, the concepts <link linkend="include_js">including <literal role="extension">.js</literal> files</link>, <link linkend="include_xml">including <literal role="extension">.xml</literal> files</link> and <link linkend="snippets">snippets</link> can be very useful (but see the <link linkend="include_snippets_vs_embedding">thoughts on when it is preferable to use embedding</link>).
@@ -1147,7 +1146,7 @@ function calculate () {
}
</programlisting>
<para>
- Note that sometimes it's even more useful to reverse this, and define the <quote>skeleton</quote> of <function>preprocess()</function>, <function>calculate()</function>, and <function>printout()</function> functions is a common file, and make these call back for those part which are different across plugins. E.g.:
+ Note that sometimes it is even more useful to reverse this, and define the <quote>skeleton</quote> of <function>preprocess()</function>, <function>calculate()</function>, and <function>printout()</function> functions is a common file, and make these call back for those part which are different across plugins. E.g.:
</para>
<programlisting>
// this is a file called "common_functions.js"
@@ -1186,7 +1185,7 @@ function getSpecifics () {
<sect1 id="include_xml">
<title>Including <literal role="extension">.xml</literal> files</title>
<para>
- Basically the same feature of including files is also available for use in the <literal role="extension">.xml</literal>, &pluginmap; and <literal role="extension">.rkh</literal> files. At any place in these files you can place an <command><include></command> tag as shown below. The effect is that the entire contents of that XML file (to be precise: everything within the <command><document></command> tag of that file) is included verbatim at this point in the file. Note that you can only include another XML file.
+ Basically the same feature of including files is also available for use in the <literal role="extension">.xml</literal>, &pluginmap; and <literal role="extension">.rkh</literal> files. At any place in these files you can place an <command><include></command> tag as shown below. The effect is that the entire contents of that &XML; file (to be precise: everything within the <command><document></command> tag of that file) is included verbatim at this point in the file. Note that you can only include another &XML; file.
</para>
<programlisting>
<document>
@@ -1226,10 +1225,10 @@ function getSpecifics () {
</document>
</programlisting>
<para>
- Hence, you define the snippet at one place at the top of the XML file, and then you <command><insert></command> it at any place(s) you wish.
+ Hence, you define the snippet at one place at the top of the &XML; file, and then you <command><insert></command> it at any place(s) you wish.
</para>
<para>
- While this example is not too useful in itself, think about combining this with an <command><include></command>d <literal role="extension">.xml</literal> file. Note that you can also place snippets for the <literal role="extension">.rkh</literal> file in the same file. You'd simply <command><include></command> the file there as well, and <command><insert></command> the relevant snippet:
+ While this example is not too useful in itself, think about combining this with an <command><include></command>d <literal role="extension">.xml</literal> file. Note that you can also place snippets for the <literal role="extension">.rkh</literal> file in the same file. You would simply <command><include></command> the file there as well, and <command><insert></command> the relevant snippet:
</para>
<programlisting>
<!-- This is a file called "common_snippets.xml" -->
@@ -1305,10 +1304,10 @@ function getSpecifics () {
<sect1 id="include_snippets_vs_embedding">
<title><include> and <snippets> vs. <embed></title>
<para>
- At first glance, <command><include></command> and <command><snippets></command> provides functionality rather similar to <link linkend="embedding">embedding</link>: It allows to reuse some portions of code across plugins. So what's the difference between these approaches, and when should you use which?
+ At first glance, <command><include></command> and <command><snippets></command> provides functionality rather similar to <link linkend="embedding">embedding</link>: It allows to reuse some portions of code across plugins. So what is the difference between these approaches, and when should you use which?
</para>
<para>
- The key difference between these concepts is that embeddable plugins are a more tight bundle. They combine a complete GUI, code to generate &r; code from this, and a help page. In contrast, include and insert allow much more fine grained control, but at the price of less modularity.
+ The key difference between these concepts is that embeddable plugins are a more tight bundle. They combine a complete &GUI;, code to generate &R; code from this, and a help page. In contrast, include and insert allow much more fine grained control, but at the price of less modularity.
</para>
<para>
That is, a plugin embedding another plugin will typically not need to know much about the internal details of the embedded plugin. A prime example is the plot_options plugin. Plugins wishing to embed this do not necessarily need to know about all the options provided, or how they are provided. This is a good thing, as otherwise a change in the plot_options plugin might make it necessary to adjust all plugins embedding this (a lot). In contrast, include and insert really exposes all the internal details, and plugins using this will -- for example -- need to know the exact ids and perhaps even the type of the elements used.
@@ -1335,22 +1334,22 @@ This chapter contains information on some topics that are useful only to certain
<para>
In order to draw a plot to the output window, use <function>rk.graph.on()</function> directly before creating the plot, and
<function>rk.graph.off()</function>, directly afterwards. This is similar to ⪚ calling <function>postscript()</function> and
- <function>dev.off()</function> in a regular &r; session.
+ <function>dev.off()</function> in a regular &R; session.
</para>
<para>
- Importantly, however, you must <emphasis>always</emphasis> call <function>rk.graph.off()</function> after calling <function>rk.graph.on()</function>. Otherwise the output file will be left in a broken state. To ensure <function>rk.graph.off()</function> really gets called, you should wrap <emphasis>all</emphasis> &r; commands between the two calls in
- <function>try()</function> statement. Never heard of that? Don't worry, it's easy. All you need to do is follow the pattern shown in
+ Importantly, however, you must <emphasis>always</emphasis> call <function>rk.graph.off()</function> after calling <function>rk.graph.on()</function>. Otherwise the output file will be left in a broken state. To ensure <function>rk.graph.off()</function> really gets called, you should wrap <emphasis>all</emphasis> &R; commands between the two calls in
+ <function>try()</function> statement. Never heard of that? Do not worry, it is easy. All you need to do is follow the pattern shown in
<link linkend="plot_plugin_example">example</link>, below.
</para>
</sect2>
<sect2 id="preview_plots">
<title>Adding preview functionality</title>
- <note><para>This section discusses adding preview functionality to plugins producing plots. There are separate sections on <link linkend="preview_output">previews of (HTML) output</link>, <link linkend="preview_data">previews of (imported) data</link>, and <link linkend="preview_custom">custom previews</link>. However, it is recommended that you read this section first, as the approach is similar in each case.</para></note>
+ <note><para>This section discusses adding preview functionality to plugins producing plots. There are separate sections on <link linkend="preview_output">previews of (&HTML;) output</link>, <link linkend="preview_data">previews of (imported) data</link>, and <link linkend="preview_custom">custom previews</link>. However, it is recommended that you read this section first, as the approach is similar in each case.</para></note>
<para>
- A very useful feature for all plugins generating a plot/graph is to provide an automatically updating preview. To do so, you will need two things: Adding a <command><preview></command> check box to your <link linkend="mainxml">GUI definition</link>, and adjusting the <link linkend="jstemplate">generated code</link> for the preview.
+ A very useful feature for all plugins generating a plot/graph is to provide an automatically updating preview. To do so, you will need two things: Adding a <command><preview></command> check box to your <link linkend="mainxml">&GUI; definition</link>, and adjusting the <link linkend="jstemplate">generated code</link> for the preview.
</para>
<para>
- Adding a <command><preview></command> check box is simple. Just place the following somewhere in your GUI. It will take care of all the behind-the-scenes magic of creating a preview device, updating the preview whenever the setting have changed, &etc; Example:
+ Adding a <command><preview></command> check box is simple. Just place the following somewhere in your &GUI;. It will take care of all the behind-the-scenes magic of creating a preview device, updating the preview whenever the setting have changed, &etc; Example:
</para>
<note><para>Starting with version 0.6.5 of &rkward; <command><preview></command> preview elements are special-cased in plugin dialogs (not wizards): They will be placed in the button-column, irrespective of where exactly they are defined in the UI. It is still a good idea to define them at a sensible place in the layout, for backwards compatibility.
</para></note>
@@ -1366,7 +1365,7 @@ This chapter contains information on some topics that are useful only to certain
</document>
</programlisting>
<para>
- And that's it for the GUI definition.
+ And that is it for the &GUI; definition.
</para>
<para>
Adjusting the JS template is a little more work. You will have to create a new function called <function>preview()</function> in addition to the <function>preprocess()</function>, <function>calculate()</function>, &etc; functions. This function should generate the code needed to produce the plot, and only that. Esp. no printing of headers, <function>rk.graphics.on()</function>, or similar calls. See the <link linkend="plot_plugin_example">example</link>, below for the typical pattern that you will use.
@@ -1407,7 +1406,7 @@ This chapter contains information on some topics that are useful only to certain
<sect2 id="plot_plugin_example">
<title>A canonical example</title>
<para>
- Here's an example .JS file that you should use as a template, whenever you create a plotting plugin:
+ Here is an example .JS file that you should use as a template, whenever you create a plotting plugin:
</para>
<programlisting>
function preprocess () {
@@ -1528,7 +1527,7 @@ This chapter contains information on some topics that are useful only to certain
}
</programlisting>
<para>
- Again, the <command>preview()</command> function generates almost the same &r; code as the <command>calculate()</command> function, so we create a helper function <command>doCalcuate()</command> to factor out the common parts. The most important thing to note is that you will have to assign the imported data to a object called
+ Again, the <command>preview()</command> function generates almost the same &R; code as the <command>calculate()</command> function, so we create a helper function <command>doCalcuate()</command> to factor out the common parts. The most important thing to note is that you will have to assign the imported data to a object called
<parameter>preview_data</parameter> (inside the current - local - environment). <emphasis>Everything else will happen automatically</emphasis> (roughly speaking, &rkward; will call <command>rk.edit(preview_data)</command>, wrapped inside a call to <command>.rk.with.window.hints()</command>).
</para>
<note><para>
@@ -1540,10 +1539,10 @@ This chapter contains information on some topics that are useful only to certain
<sect2 id="preview_custom">
<title>Custom previews</title>
<para>
- The <command><preview></command> element can be used to create previews for any type of "document" window that can be attached to &rkward;'s workplace. In addition to <link linkend="preview_plots">plots</link> and <link linkend="preview_data">data windows</link>, this includes HTML files, &r; scripts, and object summary windows. For the latter ones, you will have to use <command><preview mode="custom"></command>.
+ The <command><preview></command> element can be used to create previews for any type of "document" window that can be attached to &rkward;'s workplace. In addition to <link linkend="preview_plots">plots</link> and <link linkend="preview_data">data windows</link>, this includes HTML files, &R; scripts, and object summary windows. For the latter ones, you will have to use <command><preview mode="custom"></command>.
</para>
<para>
- If you have read the sections describing plot preview and data previews, you should have a general idea on the procedure, but "custom" previews require slightly more manual work behind the scenes. The most important &r; function to look at is <command>rk.assign.preview.data()</command>, here. The following short listing shows what your generated (preview) &r; code could look like for a plugin creating a text file output:
+ If you have read the sections describing plot preview and data previews, you should have a general idea on the procedure, but "custom" previews require slightly more manual work behind the scenes. The most important &R; function to look at is <command>rk.assign.preview.data()</command>, here. The following short listing shows what your generated (preview) &R; code could look like for a plugin creating a text file output:
</para>
<programlisting>
## To be generated in the preview() code section of a plugin
@@ -1569,10 +1568,10 @@ This chapter contains information on some topics that are useful only to certain
<sect1 id="contextualized_plugins">
<title>Context-dependent plugins</title>
<para>
- So far we have assumed, all plugins are always meaningful, and all placed in the main menu. However, some plugins are meaningful only (or additionally) in a certain context. For instance a plugin to export the contents of an &r; X11 graphics device is obviously most useful, when placed in the menu of an X11 device, not in the main menubar. Also, such a plugin should know about the device number that it should operate on, without having to ask the user about this.
+ So far we have assumed, all plugins are always meaningful, and all placed in the main menu. However, some plugins are meaningful only (or additionally) in a certain context. For instance a plugin to export the contents of an &R; X11 graphics device is obviously most useful, when placed in the menu of an X11 device, not in the main menubar. Also, such a plugin should know about the device number that it should operate on, without having to ask the user about this.
</para>
<para>
- We call such plugins context-dependent. Correspondingly, in the <link linkend="pluginmap">&pluginmap; file</link>, they are not (or not only) placed in the main <command><hierarchy></command> but rather into a <command><context></command> element. So far only two different contexts are supported (more will come later): x11 and file import. We'll deal with those in turn. Even if you are only interested in the import context, please also read the section on the x11 context, as this is slightly more elaborate.
+ We call such plugins context-dependent. Correspondingly, in the <link linkend="pluginmap">&pluginmap; file</link>, they are not (or not only) placed in the main <command><hierarchy></command> but rather into a <command><context></command> element. So far only two different contexts are supported (more will come later): x11 and file import. We will deal with those in turn. Even if you are only interested in the import context, please also read the section on the x11 context, as this is slightly more elaborate.
</para>
<sect2 id="context_x11">
@@ -1610,7 +1609,7 @@ This chapter contains information on some topics that are useful only to certain
</document>
</programlisting>
<para>
- In the <link linkend="logic">logic section of the plugin xml</link>, you can now declare two <command><external></command> properties: <parameter>devnum</parameter> and <parameter>context</parameter>. <parameter>context</parameter> (if declared) will be set to <replaceable>"x11"</replaceable> when the plugin is invoked in this context. <parameter>devnum</parameter> will be set to the number of the graphics device to operate on. And that's all.
+ In the <link linkend="logic">logic section of the plugin xml</link>, you can now declare two <command><external></command> properties: <parameter>devnum</parameter> and <parameter>context</parameter>. <parameter>context</parameter> (if declared) will be set to <replaceable>"x11"</replaceable> when the plugin is invoked in this context. <parameter>devnum</parameter> will be set to the number of the graphics device to operate on. And that is all.
</para>
</sect2>
@@ -1654,17 +1653,17 @@ This chapter contains information on some topics that are useful only to certain
</sect1>
<sect1 id="querying_r_for_info">
-<title>Querying &r; for information</title>
- <para>In some cases, you may want to fetch further information from &r;, to be presented in your plugin's UI. For instance, you may want to offer a selection of the levels of a factor that the user
+<title>Querying &R; for information</title>
+ <para>In some cases, you may want to fetch further information from &R;, to be presented in your plugin's UI. For instance, you may want to offer a selection of the levels of a factor that the user
has selected for analysis. Since version 0.6.2 of &rkward; it is possible to do so. Before we start, it is important that you are aware of some caveats:</para>
- <para>R Code run from inside the plugin's UI logic is evaluated in R's event loop, meaning they can be run <emphasis>while</emphasis> other computations are running. This is to make sure your plugin's UI will be usable, even while &r; is busy doing other things. However, this makes it really important, that your code does not have side effects. In particular:</para>
+ <para>R Code run from inside the plugin's UI logic is evaluated in R's event loop, meaning they can be run <emphasis>while</emphasis> other computations are running. This is to make sure your plugin's UI will be usable, even while &R; is busy doing other things. However, this makes it really important, that your code does not have side effects. In particular:</para>
<itemizedlist>
<listitem><para>Do <emphasis>not</emphasis> make any assignments in .GlobalEnv or any other non-local environment.</para></listitem>
<listitem><para>Do <emphasis>not</emphasis> print anything to the output file.</para></listitem>
<listitem><para>Do <emphasis>not</emphasis> plot anything on-screen.</para></listitem>
<listitem><para>In general, do <emphasis>not</emphasis> do anything that has side-effects. Your code may <emphasis>read in information</emphasis>, not "<emphasis>do</emphasis>" anything.</para></listitem>
</itemizedlist>
- <para>With this in mind, here's the general pattern. You will use this inside a <link linkend="logic_scripted">scripted UI logic</link> section:</para>
+ <para>With this in mind, here is the general pattern. You will use this inside a <link linkend="logic_scripted">scripted UI logic</link> section:</para>
<programlisting>
<script><![CDATA[
last_command_id = -1;
@@ -1694,7 +1693,7 @@ This chapter contains information on some topics that are useful only to certain
a bit more complex. For one thing you want to make sure, that your <command><valueselector></command> remains disabled, while it does not contain up-to-date information. Another
thing is that you could potentially have queued more than one command, before you get the first results. This is why every command is given an "id", and we store that in <parameter>last_command_id</parameter> for later reference.</para>
<para>When the command is done, the specified callback is called (<parameter>commandFinished</parameter>, in this case) with two parameters: The result itself, and the id of the corresponding
- command. The result will be of a type resembling the representation in &r;, &ie; a numeric Array, if the result is numeric, &etc; It can even be an &r; <command>list()</command>, but in this case
+ command. The result will be of a type resembling the representation in &R;, &ie; a numeric Array, if the result is numeric, &etc; It can even be an &R; <command>list()</command>, but in this case
it will be represented as a JS <command>Array()</command> without names.</para>
<para>Note that even this example is somewhat simplified. In reality you should take additional precautions, ⪚ to avoid putting an extreme amount of levels into the selector. The good news
is that probably you do not have to do all this yourself. The above example is taken from the <command>rkward::level_select</command> plugin, for instance, which you can simply <link linkend="embedding">embed</link> in your own
@@ -1704,11 +1703,11 @@ This chapter contains information on some topics that are useful only to certain
<sect1 id="current_object">
<title>Referencing the current object or current file</title>
<para>
- For many plugins it is desirable to work on the <quote>current</quote> object. For instance a <quote>sort</quote> plugin could pre-select the data.frame that is currently being edited for sorting. The name of the current object is available to plugins as a pre-defined property called <parameter>current_object</parameter>. You can connect to this property in the usual way. If no object is current, the property equates to an empty string. Similarly, the url of the current script file
+ For many plugins it is desirable to work on the <quote>current</quote> object. For instance a <quote>sort</quote> plugin could pre-select the data.frame that is currently being edited for sorting. The name of the current object is available to plugins as a pre-defined property called <parameter>current_object</parameter>. You can connect to this property in the usual way. If no object is current, the property equates to an empty string. Similarly, the &URL; of the current script file
is accessible as a pre-defined property called <parameter>current_filename</parameter>. That property is empty if no script file is currently being edited, or the script file has not been saved, yet.
</para>
<para>
- Currently the <parameter>current_object</parameter> can only be of class <function>data.frame</function>, but please do not rely on this, since this will be extended to other types of data in the future. If you are interested in <function>data.frame</function> objects, only, connect to the <parameter>current_dataframe</parameter> property, instead. Alternatively, you can enforce type requirements by using appropriate constraints on your <command><varslot></command>s, or by using <link linkend="logic_scripted">GUI logic scripting</link>.
+ Currently the <parameter>current_object</parameter> can only be of class <function>data.frame</function>, but please do not rely on this, since this will be extended to other types of data in the future. If you are interested in <function>data.frame</function> objects, only, connect to the <parameter>current_dataframe</parameter> property, instead. Alternatively, you can enforce type requirements by using appropriate constraints on your <command><varslot></command>s, or by using <link linkend="logic_scripted">&GUI; logic scripting</link>.
</para>
</sect1>
@@ -1796,7 +1795,7 @@ This chapter contains information on some topics that are useful only to certain
<command><varslot></command> inside the <command><content></command> area, allowing the user to select one item
at a time. However, it will mean much less clicks for the user, if you use a <command><varslot multi="true"></command>
<emphasis>outside</emphasis> the <command><optionset></command>, instead. Then you will connect this selection of objects
- to a so-called "driven" optionset. Here's how:
+ to a so-called "driven" optionset. Here is how:
</para>
<programlisting>
<dialog [...]>
@@ -1822,7 +1821,7 @@ This chapter contains information on some topics that are useful only to certain
</dialog>
</programlisting>
<para>
- We'll start looking at the example at the bottom. You'll note that two <command><optioncolumn></command> specifications have
+ We will start looking at the example at the bottom. You will note that two <command><optioncolumn></command> specifications have
<parameter>external="true"</parameter>. This tells &rkward; that these are controlled from outside the <command><optionset></command>. Here, the sole purpose of the "varnames"-optioncolumn is to provide easy-to-read labels in the
optionset display (it is connected to the "shortname" modifier of the property holding the selected
objects). The purpose of the "vars"-optioncolumn is to serve as the "key" column, as specified by
@@ -1844,16 +1843,16 @@ This chapter contains information on some topics that are useful only to certain
<title>Alternatives: When not to use optionsets</title>
<para>
Optionsets are a powerful tool, but they can sometimes do more harm than good, as they add considerable complexity, both
- from the perspective of a plugin developer, and from the perspective of a user. Thus, think twice, when using them. Here's
+ from the perspective of a plugin developer, and from the perspective of a user. Thus, think twice, when using them. Here is
some advice:
</para>
<itemizedlist>
<listitem><para>For some simple cases, the <command><matrix></command> element may provide a useful lightweight alternative.</para></listitem>
- <listitem><para>Don't make your plugin do too much. We gave the example of using an optionset for a plugin to
+ <listitem><para>Do not make your plugin do too much. We gave the example of using an optionset for a plugin to
draw several lines within one plot. But in general it is not a good idea to create a plugin that will produce individual
plots for each item in an optionset. Rather make the plugin produce one plot, and the user can call it multiple times.
</para></listitem>
- <listitem><para>If you don't expect more than two or three items in a set, consider repeating the options, manually,
+ <listitem><para>If you do not expect more than two or three items in a set, consider repeating the options, manually,
instead.</para></listitem>
</itemizedlist>
</sect2>
@@ -1887,14 +1886,14 @@ x </components ...>
<note><para>Actually &rkward; 0.6.1 is the first version to interpret dependencies - and to report dependency errors - at all. Thus, contrary to what the example may suggest, specifying any earlier versions in the dependencies will not have any direct effect (but may still be a good idea for documentation purposes).</para></note>
<para><emphasis>Sometimes</emphasis> it will even be possible to handle version incompatibility issues <emphasis>inside</emphasis> a single &pluginmap; file, using the <command><dependency_check></command> element, described in the following section.</para>
</sect1>
-<sect1 id="sect_dependencies_r_version"><title>&r; version compatibility</title>
+<sect1 id="sect_dependencies_r_version"><title>&R; version compatibility</title>
<para>Similar to <parameter>rkward_min_version</parameter> and <parameter>rkward_max_version</parameter>, the <command><dependencies></command> element allows specification of the attributes <parameter>R_min_version</parameter> and <parameter>R_max_version</parameter>. However, there are the following differences:</para>
<itemizedlist>
- <listitem><para>Plugins which fail to meet the &r; version requirement are <emphasis>not</emphasis> currently skipped when reading a &pluginmap; file. The user can still call the plugin, and will not see any immediate warning (in future versions, a warning message will probably be shown)</para></listitem>
- <listitem><para>In consequence it is also <emphasis>not</emphasis> possible to define alternative versions of a plugin depending on the running version of &r;.</para></listitem>
- <listitem><para>However, it is often easy to achieve backwards compatibility as shown below. If you are aware of &r; compatibility issues, please consider using this method, instead of defining a dependency on a particular version of &r;.</para></listitem>
+ <listitem><para>Plugins which fail to meet the &R; version requirement are <emphasis>not</emphasis> currently skipped when reading a &pluginmap; file. The user can still call the plugin, and will not see any immediate warning (in future versions, a warning message will probably be shown)</para></listitem>
+ <listitem><para>In consequence it is also <emphasis>not</emphasis> possible to define alternative versions of a plugin depending on the running version of &R;.</para></listitem>
+ <listitem><para>However, it is often easy to achieve backwards compatibility as shown below. If you are aware of &R; compatibility issues, please consider using this method, instead of defining a dependency on a particular version of &R;.</para></listitem>
</itemizedlist>
- <para>In many cases, it is easily possible to provide reduced functionality, if a certain feature is not available in the running version of &r;. Consider the following short example of a plugin .xml file:</para>
+ <para>In many cases, it is easily possible to provide reduced functionality, if a certain feature is not available in the running version of &R;. Consider the following short example of a plugin <literal role="extension">.xml</literal> file:</para>
<programlisting>
<dialog [...]>
<logic>
@@ -1910,10 +1909,10 @@ x </components ...>
[...]
</dialog>
</programlisting>
- <para>In this example the compression option "xz" will simply be disabled when the &r; runtime version is older than 2.10.0 (which did not support xz compression). The <command><dependency_check></command> element supports the same attributes as the <command><dependencies></command> element in &pluginmap; files. It creates a boolean property, which is true, if the specified dependencies are met, false otherwise.</para>
+ <para>In this example the compression option "xz" will simply be disabled when the &R; runtime version is older than 2.10.0 (which did not support xz compression). The <command><dependency_check></command> element supports the same attributes as the <command><dependencies></command> element in &pluginmap; files. It creates a boolean property, which is true, if the specified dependencies are met, false otherwise.</para>
</sect1>
-<sect1 id="sect_dependencies_r_packages"><title>Dependencies on &r; packages</title>
-<para>Dependencies on specific &r; packages can be defined, but as of &rkward; 0.6.1, these dependencies are neither checked, nor installed / loaded, automatically. They are shown in the plugin help files, however. Here is an example definition:</para>
+<sect1 id="sect_dependencies_r_packages"><title>Dependencies on &R; packages</title>
+<para>Dependencies on specific &R; packages can be defined, but as of &rkward; 0.6.1, these dependencies are neither checked, nor installed / loaded, automatically. They are shown in the plugin help files, however. Here is an example definition:</para>
<programlisting>
<dependencies>
<package
@@ -1924,7 +1923,7 @@ x </components ...>
</dependencies>
</programlisting>
<note><para>Always make sure to add appropriate <function>require()</function> calls, if you plugin needs certain packages to be loaded.</para></note>
-<note><para>If you <link linkend="external_plugins">distribute your &pluginmap; as an &r; package</link>, and all plugins depend on a particular package, then you should define that dependency on the &r; package level. Defining dependencies to &r; packages on the level of the &rkward; &pluginmap; is most useful, if only some of your plugins need the dependency, the dependency is not available from CRAN, or your &pluginmap; is not distributed as an &r; package.</para></note>
+<note><para>If you <link linkend="external_plugins">distribute your &pluginmap; as an &R; package</link>, and all plugins depend on a particular package, then you should define that dependency on the &R; package level. Defining dependencies to &R; packages on the level of the &rkward; &pluginmap; is most useful, if only some of your plugins need the dependency, the dependency is not available from CRAN, or your &pluginmap; is not distributed as an &R; package.</para></note>
</sect1>
<sect1 id="sect_dependencies_other_pluginmaps"><title>Dependencies on other &rkward; &pluginmap;s</title>
<para>If your plugins depend on plugins defined in another &pluginmap; (that is <emphasis>not</emphasis> part of your package) you can define this dependency like this:</para>
@@ -1936,11 +1935,11 @@ x </components ...>
/>
</dependencies>
</programlisting>
-<para>Currently will neither load, nor install, nor even warn about missing &pluginmap;s, but at least information on dependencies (and where to obtain them) will be shown on the plugin's help page. You do not have to (and you should not) declare dependencies on &pluginmap;s that are shipped with the official &rkward; distribution, or on &pluginmap;s that are inside your own package. Further, if a required &pluginmap; is <link linkend="external_plugins">distributed as an &r; package</link>, declare a dependency of the package (as shown in the previous section), rather than on the map.</para>
+<para>Currently will neither load, nor install, nor even warn about missing &pluginmap;s, but at least information on dependencies (and where to obtain them) will be shown on the plugin's help page. You do not have to (and you should not) declare dependencies on &pluginmap;s that are shipped with the official &rkward; distribution, or on &pluginmap;s that are inside your own package. Further, if a required &pluginmap; is <link linkend="external_plugins">distributed as an &R; package</link>, declare a dependency of the package (as shown in the previous section), rather than on the map.</para>
<para>To make sure that required &pluginmap;s are actually loaded, use the <command><require></command>-tag (refer to the <link linkend="pluginmapelements">reference</link> for details).</para>
</sect1>
<sect1 id="sect_dependencies_example"><title>An example</title>
- <para>To clarify how dependency definitions can be mixed, here's a combined example:</para>
+ <para>To clarify how dependency definitions can be mixed, here is a combined example:</para>
<programlisting>
<document ...>
<dependencies rkward_min_version="0.5.0c">
@@ -1995,7 +1994,7 @@ x </components ...>
</sect1>
<sect1 id="i18n_xml"><title>i18n in &rkward;'s xml files</title>
<para>
- For &rkward;'s xml files, i18n will mostly just work. If you are writing your own <command>.pluginmap</command> (⪚ for an <link linkend="external_plugins">external plugin</link>),
+ For &rkward;'s &XML; files, i18n will mostly just work. If you are writing your own <command>.pluginmap</command> (⪚ for an <link linkend="external_plugins">external plugin</link>),
you will have to specify a <replaceable>po_id</replaceable> next to the pluginmap's <replaceable>id</replaceable>. This defines the "message catalog" to use. In general this should
be set identical to the <replaceable>id</replaceable> of your <command>.pluginmap</command>, but if you provide several <command>.pluginmap</command>s and want to control, how
message catalogs are divided up, this allows you to do so. The <replaceable>po_id</replaceable> is inherited by any <command>.pluginmap</command> you include, unless that declares
@@ -2033,7 +2032,7 @@ user (selection from a list of values shown next to this element) -->
</para>
<para>
Finally, in rare cases, you may want to exclude certain strings from translation. This may make sense, for example, if you offer a choice between
- several &r; function names in a <command><radio></command>-control. You do not want these to be translated, then (but depending on the context,
+ several &R; function names in a <command><radio></command>-control. You do not want these to be translated, then (but depending on the context,
you should consider giving a descriptive label, instead):
</para>
<programlisting>
@@ -2050,7 +2049,7 @@ user (selection from a list of values shown next to this element) -->
</sect1>
<sect1 id="i18n_js"><title>i18n in &rkward;'s js files and sections</title>
<para>
- In contrast to the .xml files, making the js files of a plugin translatable requires more custom work. The key difference, here, is that there is no decent automatic way to tell,
+ In contrast to the <literal role="extension">.xml</literal> files, making the <literal role="extension">.js</literal> files of a plugin translatable requires more custom work. The key difference, here, is that there is no decent automatic way to tell,
whether a string is meant to be displayed as a human readable string, or a piece of code. So you need to mark this up, yourself. We have already shown examples of this, all along. Here
is a more complete description of the i18n-functions available in js code, and some hints for more complex cases:
</para>
@@ -2109,7 +2108,7 @@ user (selection from a list of values shown next to this element) -->
Should you require a translatable string to be quoted, a second time, send it through <command>quote()</command>, <emphasis>twice</emphasis>.
</para>
<para>
- That said, it is generally not a good idea to make bits like function names or variable names translatable. For one thing, &r;, the programming language, is inherently in English,
+ That said, it is generally not a good idea to make bits like function names or variable names translatable. For one thing, &R;, the programming language, is inherently in English,
and there is no internationalization of the language itself. Code comments are a different beast, but you should use the <command>comment()</command>-function for those. Secondly,
making syntactically relevant parts of the generated code translatable means that translations could actually break your plugin.
E.g. if an unsuspecting translator translates a string meant as a variable name in two distinct words with a space in between.
@@ -2124,7 +2123,7 @@ user (selection from a list of values shown next to this element) -->
<itemizedlist>
<listitem><para>Provide the plugin in two versions for &rkward; >= 0.6.3 and &rkward; < 0.6.3, as described in the chapter on
<link linkend="sect_dependencies_rkward_version">handling dependencies</link></para></listitem>
- <listitem><para>Simply don't translate the strings in the .js-file, yet. Obviously this is an easy, but rather inelegant solution.</para></listitem>
+ <listitem><para>Simply do not translate the strings in the .js-file, yet. Obviously this is an easy, but rather inelegant solution.</para></listitem>
<listitem><para>Include some support code in your .js-file(s) like shown below:</para></listitem>
</itemizedlist>
<programlisting>
@@ -2150,7 +2149,7 @@ user (selection from a list of values shown next to this element) -->
<sect1 id="i18n_workflow"><title>Translation maintainance</title>
<para>
Now that you have made your plugin translatable, how do you actually get it translated? In general you only need to worry about this, when developing an <link linkend="external_plugins">
- external plugin</link>. For plugins in &rkward;'s main repository, all the magic is done for you. Here's the basic workflow. Note that you need the "gettext" tools, installed:
+ external plugin</link>. For plugins in &rkward;'s main repository, all the magic is done for you. Here is the basic workflow. Note that you need the "gettext" tools, installed:
</para>
<itemizedlist>
<listitem><para>Mark up all strings, providing context and comments as needed</para></listitem>
@@ -2179,14 +2178,14 @@ user (selection from a list of values shown next to this element) -->
</para>
<itemizedlist>
<listitem><para>&rkward; plugins were not translatable until version 0.6.3, and were mostly not written with i18n in mind, before then. Thus you are going to encounter rather
- more ambiguous strings, and other i18n problems than in other mature projects. Please don't just silently work around these, but let us (or the plugin maintainers)
+ more ambiguous strings, and other i18n problems than in other mature projects. Please do not just silently work around these, but let us (or the plugin maintainers)
know, so we can fix these issues.</para></listitem>
<listitem><para>Many &rkward; plugins refer to highly specialized terms, from data handling and statistics, but also from other fields of science. In many cases, a good translation
- will require at least basic knowledge of these fields. In some cases, there <emphasis>is</emphasis> no good translation for a technical term, and the best option may
- be to leave the term untranslated, or to include the English term in parentheses. Don't focus too much on the 100% mark of translated strings, focus on providing
+ will require at least basic knowledge of these fields. In some cases, there <emphasis>is</emphasis> no good translation for a technical term, and the best option may
+ be to leave the term untranslated, or to include the English term in parentheses. Do not focus too much on the 100% mark of translated strings, focus on providing
a good translation, even if that means skipping some strings (or even skipping some message catalogs as a whole). Other users may be able to fill in any gaps in technical
terms.</para></listitem>
- <listitem><para>At the time of this writing, &rkward;'s project hosting is about to change, and this also affect the translation workflow. Do read comments accompanying
+ <listitem><para>At the time of this writing, &rkward;'s project hosting is about to change, and this also affect the translation workflow. Do read comments accompanying
the .pot-files, on how translations should be handled. If in doubt, it is never wrong to send your work the rkward-devel mailing list, or to ask for up-to-date instructions,
there.</para></listitem>
</itemizedlist>
@@ -2195,8 +2194,8 @@ user (selection from a list of values shown next to this element) -->
<chapter id="chapter_about_information">
<title>Author, license and version information</title>
-<para>So you have written a set of plugins, and you are getting ready to <link linkend="external_plugins">share your work</link>. To make sure users will know what your work is all about, under what terms they can use and distribute it, and whom they should contact about issues or ideas, you should add some information <emphasis>about</emphasis> your plugins. This can be done using the <command><about></command> element. It can be used in either the &pluginmap; or in individual plugin .xml files (in both cases as a direct child of the document tag). When specified in the &pluginmap; it will apply to all plugins. If <command><about></command> is specified in both places, the <command><about></command> information in the plugin .xml file will override that in the &pluginmap; file. You can also add an <command><about></command> element to .rkh-pages, which are not connected to a plugin, if there is a need for that.</para>
-<para>Here's an example &pluginmap; file with only a few explanations, below. In cases of doubt, more information may be available from the reference.</para>
+<para>So you have written a set of plugins, and you are getting ready to <link linkend="external_plugins">share your work</link>. To make sure users will know what your work is all about, under what terms they can use and distribute it, and whom they should contact about issues or ideas, you should add some information <emphasis>about</emphasis> your plugins. This can be done using the <command><about></command> element. It can be used in either the &pluginmap; or in individual plugin <literal role="extension">.xml</literal> files (in both cases as a direct child of the document tag). When specified in the &pluginmap; it will apply to all plugins. If <command><about></command> is specified in both places, the <command><about></command> information in the plugin <literal role="extension">.xml</literal> file will override that in the &pluginmap; file. You can also add an <command><about></command> element to .rkh-pages, which are not connected to a plugin, if there is a need for that.</para>
+<para>Here is an example &pluginmap; file with only a few explanations, below. In cases of doubt, more information may be available from the reference.</para>
<programlisting>
<document
namespace="rkward"
@@ -2238,15 +2237,15 @@ user (selection from a list of values shown next to this element) -->
<para>Most of this should explain itself, so we’ll not discuss each and every tag element. But let’s look at some details that probably need some commentary for easier understanding. </para>
<para>The <parameter>category</parameter> element in <command><about></command> can be defined rather freely, but should be meaningful, as it’s thought to be used to order plugins into groups. All other attributes in this opening tag are mandatory and must be filled with reasonable content. </para>
<para>At least one <command><author></command> with a valid email address and the role <quote>aut</quote> (<quote>author</quote>) must also be given. In case your plugin causes problems or someone would like to share its gratitude with you, it should be easy to contact someone who’s involved. For further information on other valid roles, like <quote>ctb</quote> for code contributors or <quote>cre</quote> for package maintenance, please refer to the <ulink url="http://stat.ethz.ch/R-manual/R-patched/library/utils/html/person.html">R documentation on <function>person()</function></ulink>. </para>
-<note><para>Remember that you can use <command><include></command> and / or <command><insert></command> to repeat information across several .xml files (⪚ information on an author who was involved with several plugins). <link linkend="sect_similar_plugins">More information</link>.</para></note>
-<tip><para>You don't have to write this XML code by hand. If you use the function <function>rk.plugin.skeleton()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> and provide all necessary information via the <parameter>about</parameter> option, it will automatically create a &pluginmap; file with a working <about> section for you.</para></tip>
+<note><para>Remember that you can use <command><include></command> and / or <command><insert></command> to repeat information across several <literal role="extension">.xml</literal> files (⪚ information on an author who was involved with several plugins). <link linkend="sect_similar_plugins">More information</link>.</para></note>
+<tip><para>You do not have to write this &XML; code by hand. If you use the function <function>rk.plugin.skeleton()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> and provide all necessary information via the <parameter>about</parameter> option, it will automatically create a &pluginmap; file with a working <about> section for you.</para></tip>
</chapter>
<chapter id="external_plugins">
<title>Share your work with others</title>
<sect1 id="sect_external_plugins"><title>External plugins</title>
<para>
- As of version 0.5.5, &rkward; provides a comfortable way to install additional third party plugins which do not belong to the core package itself. We call these <quote>external plugins</quote>. They come in form of an &r; package and can be managed directly via the usual package management features of &r; and/or &rkward;.
+ As of version 0.5.5, &rkward; provides a comfortable way to install additional third party plugins which do not belong to the core package itself. We call these <quote>external plugins</quote>. They come in form of an &R; package and can be managed directly via the usual package management features of &R; and/or &rkward;.
</para>
<para>
This section of the documentation describes how external plugins are to be packaged, so that &rkward; can use them. The plugin creation itself is of course identical to the previous sections. That is, you should probably first write a working plugin, and then check back here to learn how to distribute it.
@@ -2263,7 +2262,7 @@ user (selection from a list of values shown next to this element) -->
<sect1 id="why_external_plugins">
<title>Why external plugins?</title>
<para>
- The number of packages to extend the functionality of &r; is immense already, and climbing. On one hand, we want to encourage you to write plugins for even the most specialised tasks you need solved. On the other hand, the average user should not get lost in huge menu trees full of unknown statistical terms. Therefore it seemed reasonable to keep the plugin handling in &rkward; quite modular as well. The &rkward; team maintains its own public package repository at <ulink url="http://files.kde.org/rkward/R">http://files.kde.org/rkward/R</ulink>, designated to host your external plugins.
+ The number of packages to extend the functionality of &R; is immense already, and climbing. On one hand, we want to encourage you to write plugins for even the most specialised tasks you need solved. On the other hand, the average user should not get lost in huge menu trees full of unknown statistical terms. Therefore it seemed reasonable to keep the plugin handling in &rkward; quite modular as well. The &rkward; team maintains its own public package repository at <ulink url="https://files.kde.org/rkward/R/">https://files.kde.org/rkward/R/</ulink>, designated to host your external plugins.
</para>
<para>
As a rule of thumb, plugins that seem to serve a widely used purpose (⪚ t-Tests) should become part of the core package, while those who serve a rather limited group of people with special interests should be provided as an optional package. For you as a plugin author it’s best practice to just start with an external plugin.
@@ -2314,7 +2313,7 @@ user (selection from a list of values shown next to this element) -->
</note>
<tip>
<para>
- You don't have to create this file hierarchy by hand. If you use the function <function>rk.plugin.skeleton()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link>, it will automatically create all necessary files and directories for you, except the <filename>po</filename> directory which is created and managed by the <link linkend="i18n_workflow">translation script</link>.
+ You do not have to create this file hierarchy by hand. If you use the function <function>rk.plugin.skeleton()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link>, it will automatically create all necessary files and directories for you, except the <filename>po</filename> directory which is created and managed by the <link linkend="i18n_workflow">translation script</link>.
</para>
</tip>
<sect3 id="basic_plugin_components">
@@ -2323,7 +2322,7 @@ user (selection from a list of values shown next to this element) -->
It is mandatory to include at least three files: a <link linkend="pluginmap">&pluginmap;</link>, a plugin <link linkend="mainxml">.xml</link> description and a plugin <link linkend="jstemplate">.js</link> file. That is, even the "plugins" directory is optional. It might just help to give your files some order, especially if you include more that one plugin/dialog in the archive, which is of course no problem. You can have as many directories for the actual plugin files as you see fit, they just have to resemble the <link linkend="pluginmap">&pluginmap;</link>, respectively. It is also possible to even include several &pluginmap; files, if it fits your needs, but you should include them all in <quote>plugin_name.pluginmap</quote> then.
</para>
<para>
- Each &r; package must have a valid <filename>DESCRIPTION</filename> file, which is also crucial for &rkward; recognizing it as a plugin provider. Most of the information it carries is also needed in the plugin <link linkend="chapter_about_information">Meta-information</link> and possibly <link linkend="chapter_dependencies">dependencies</link>, but in a different format (the &r; documentation explains <ulink url="http://cran.r-project.org/doc/manuals/R-exts.html#The-DESCRIPTION-file">the <filename>DESCRIPTION</filename> file in detail</ulink>).
+ Each &R; package must have a valid <filename>DESCRIPTION</filename> file, which is also crucial for &rkward; recognizing it as a plugin provider. Most of the information it carries is also needed in the plugin <link linkend="chapter_about_information">Meta-information</link> and possibly <link linkend="chapter_dependencies">dependencies</link>, but in a different format (the &R; documentation explains <ulink url="http://cran.r-project.org/doc/manuals/R-exts.html#The-DESCRIPTION-file">the <filename>DESCRIPTION</filename> file in detail</ulink>).
</para>
<para>
In addition to the general contents of a <filename>DESCRIPTION</filename> file, make sure to also include the line <quote>Enhances: rkward</quote>. This will cause &rkward; to automatically scan the package for plugins if it is installed. An example <filename>DESCRIPTION</filename> file looks like this:
@@ -2348,7 +2347,7 @@ user (selection from a list of values shown next to this element) -->
</programlisting>
<tip>
<para>
- You don't have to write this file by hand. If you use the function <function>rk.plugin.skeleton()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> and provide all necessary information via the <quote>about</quote> option, it will automatically create a working <filename>DESCRIPTION</filename> file for you.
+ You do not have to write this file by hand. If you use the function <function>rk.plugin.skeleton()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> and provide all necessary information via the <quote>about</quote> option, it will automatically create a working <filename>DESCRIPTION</filename> file for you.
</para>
</tip>
</sect3>
@@ -2361,7 +2360,7 @@ user (selection from a list of values shown next to this element) -->
<sect3 id="automated_plugin_testing">
<title>Automated plugin testing (optional)</title>
<para>
- Another optional directory is "tests", which is meant to provide files needed for <ulink url="http://sourceforge.net/apps/mediawiki/rkward/index.php?title=Automated_Plugin_Testing">automated plugin testing</ulink>. These tests are helpful to quickly check if your plugins still work with new versions of &r; or &rkward;. If you want to include tests, you should really restrain yourself to the naming scheme and hierarchy shown here. That is, tests should reside in a directory called <filename>tests</filename>, which includes a file <filename>testsuite.R</filename> and a folder with tests standards named after the appropriate test suite. You can, however, provide more than one test suite; in that case, if you don’t want to append them all in the one <filename>testsuite.R</filename> file, you can split them in ⪚ one file for each test suite and create one <filename>testsuite.R</filename> with <function>source()</function> calls for each suite file. In either case, create separate subdirectories with test
+ Another optional directory is "tests", which is meant to provide files needed for <ulink url="http://sourceforge.net/apps/mediawiki/rkward/index.php?title=Automated_Plugin_Testing">automated plugin testing</ulink>. These tests are helpful to quickly check if your plugins still work with new versions of &R; or &rkward;. If you want to include tests, you should really restrain yourself to the naming scheme and hierarchy shown here. That is, tests should reside in a directory called <filename>tests</filename>, which includes a file <filename>testsuite.R</filename> and a folder with tests standards named after the appropriate test suite. You can, however, provide more than one test suite; in that case, if you don’t want to append them all in the one <filename>testsuite.R</filename> file, you can split them in ⪚ one file for each test suite and create one <filename>testsuite.R</filename> with <function>source()</function> calls for each suite file. In either case, create separate subdirectories with test
standards for each defined suite.
</para>
<para>
@@ -2373,7 +2372,7 @@ standards for each defined suite.
<sect1 id="building_the_plugin_package">
<title>Building the plugin package</title>
- <para>As explained earlier, external &rkward; plugins are in effect &r; packages, and therefore the packaging process is identical. In contrast to "real" &r; packages, a pure plugin package doesn't carry any further &r; code (although you can of course add &rkward; plugins to usual &r; packages as well, using the same methods explained here). This should make it even easier to create a functioning package, as long as you have a valid <filename>DESCRIPTION</filename> file and adhere to the file hierarchy explained in <link linkend="structure_of_a_plugin_package">previous sections</link>.</para>
+ <para>As explained earlier, external &rkward; plugins are in effect &R; packages, and therefore the packaging process is identical. In contrast to "real" &R; packages, a pure plugin package does not carry any further &R; code (although you can of course add &rkward; plugins to usual &R; packages as well, using the same methods explained here). This should make it even easier to create a functioning package, as long as you have a valid <filename>DESCRIPTION</filename> file and adhere to the file hierarchy explained in <link linkend="structure_of_a_plugin_package">previous sections</link>.</para>
<para>The easiest way to actually build and test your plugin is to use the <application>R</application> command on the command line, for example:</para>
<para><userinput>
<command>R</command> <option>CMD build</option> <parameter><filename>SquaretheCircle</filename></parameter>
@@ -2381,52 +2380,52 @@ standards for each defined suite.
<para><userinput>
<command>R</command> <option>CMD INSTALL</option> <parameter><filename>SquaretheCircle_0.1-3.tar.gz</filename></parameter>
</userinput></para>
- <tip><para>You don't have to build the package like this on the command line. If you use the function <function>rk.build.package()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link>, it will build and/or check your plugin package for you.</para></tip>
+ <tip><para>You do not have to build the package like this on the command line. If you use the function <function>rk.build.package()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link>, it will build and/or check your plugin package for you.</para></tip>
</sect1>
</chapter>
<chapter id="rkwarddev">
<title>Plugin development with the <application>rkwarddev</application> package</title>
<sect1 id="rkdev_overview"><title>Overview</title>
- <para>Writing external plugins involves writing files in three languages (XML, JavaScript and R) and the creation of a standardized hierarchy of directories. To make this a lot easier for willing plugin developers, we're providing the <application>rkwarddev</application> package. It provides a number of simple &r; functions to create the XML code for all dialog elements like tabbooks, checkboxes, dropdownlists or filebrowsers, as well as functions to create JavaScript code and &rkward; help files to start with. The function <function>rk.plugin.skeleton()</function> creates the expected directory tree and all necessary files where they are supposed to be.</para>
- <para>This package is not installed by default, but has to be installed manually from <ulink url="http://files.kde.org/rkward/R/">&rkward;'s own repository</ulink>. You can either do that by using the GUI interface (<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure packages</guimenuitem></menuchoice>), or from any running &r; session:</para>
+ <para>Writing external plugins involves writing files in three languages (&XML;, &javascript; and R) and the creation of a standardized hierarchy of directories. To make this a lot easier for willing plugin developers, we are providing the <application>rkwarddev</application> package. It provides a number of simple &R; functions to create the &XML; code for all dialog elements like tabbooks, checkboxes, dropdownlists or filebrowsers, as well as functions to create &javascript; code and &rkward; help files to start with. The function <function>rk.plugin.skeleton()</function> creates the expected directory tree and all necessary files where they are supposed to be.</para>
+ <para>This package is not installed by default, but has to be installed manually from <ulink url="https://files.kde.org/rkward/R/">&rkward;'s own repository</ulink>. You can either do that by using the &GUI; interface (<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure packages</guimenuitem></menuchoice>), or from any running &R; session:</para>
<programlisting>
- install.packages("rkwarddev", repos="http://files.kde.org/rkward/R")
+ install.packages("rkwarddev", repos="https://files.kde.org/rkward/R")
library(rkwarddev)
</programlisting>
- <para><application>rkwarddev</application> depends on another small package called <quote>XiMpLe</quote>, which is a very simple XML parser and generator and also present in the same repository.</para>
- <para>The full <ulink url="http://http://files.kde.org/rkward/R/pckg/rkwarddev/rkwarddev.pdf">documentation in PDF format</ulink> can also be found there. A more detailed introduction to working with the package can be found in the <ulink url="http://files.kde.org/rkward/R/pckg/rkwarddev/rkwarddev_vignette.pdf">rkwarddev vignette</ulink>.</para>
+ <para><application>rkwarddev</application> depends on another small package called <quote>XiMpLe</quote>, which is a very simple &XML; parser and generator and also present in the same repository.</para>
+ <para>The full <ulink url="https://files.kde.org/rkward/R/pckg/rkwarddev/rkwarddev.pdf">documentation in PDF format</ulink> can also be found there. A more detailed introduction to working with the package can be found in the <ulink url="https://files.kde.org/rkward/R/pckg/rkwarddev/rkwarddev_vignette.pdf">rkwarddev vignette</ulink>.</para>
</sect1>
<sect1 id="rkdev_example"><title>Practical example</title>
- <para>To get you an idea how <quote>scripting a plugin</quote> looks like, compared to the direct approach you have seen in the previous chapters, we'll create the full t-test plugin once again -- this time only with the &r; functions of the <application>rkwarddev</application> package.</para>
+ <para>To get you an idea how <quote>scripting a plugin</quote> looks like, compared to the direct approach you have seen in the previous chapters, we will create the full t-test plugin once again -- this time only with the &R; functions of the <application>rkwarddev</application> package.</para>
- <tip><para>The package will add a new GUI dialog to &rkward; under <menuchoice><guimenu>File</guimenu><guimenuitem>Export</guimenuitem><guimenuitem>Create &rkward; plugin script</guimenuitem></menuchoice>. Like the name suggests, you can create plugin skeletons for further editing with it. This dialog itself was in turn generated by an <application>rkwarddev</application> script which you can find in the <quote>demo</quote> directory of the installed package and package sources, as an additional example. You can also run it by calling <function>demo("skeleton_dialog")</function></para></tip>
+ <tip><para>The package will add a new &GUI; dialog to &rkward; under <menuchoice><guimenu>File</guimenu><guimenuitem>Export</guimenuitem><guimenuitem>Create &rkward; plugin script</guimenuitem></menuchoice>. Like the name suggests, you can create plugin skeletons for further editing with it. This dialog itself was in turn generated by an <application>rkwarddev</application> script which you can find in the <quote>demo</quote> directory of the installed package and package sources, as an additional example. You can also run it by calling <function>demo("skeleton_dialog")</function></para></tip>
- <sect2 id="rkdev_gui"><title>GUI description</title>
- <para>You will immediately notice that the workflow is considerably different: Contrary to writing the XML code directly, you do not begin with the <command><document></command> definition, but directly with the plugin elements you'd like to have in the dialog. You can assign each interface element -- be it check boxes, dropdown menus, variable slots or anything else -- to individual &r; objects, and then combine these objects to the actual GUI. The package has functions for <link linkend="interfaceelements">each XML tag</link> that can be used to define the plugin GUI, and most of them even have the same name, only with the prefix <function>rk.XML.*</function>. For example, defining a <command><varselector></command> and two <command><varslot></command> elements for the <replaceable>"x"</replaceable> and <replaceable>"y"</replaceable> variable of the t-test example can be done by:</para>
+ <sect2 id="rkdev_gui"><title>&GUI; description</title>
+ <para>You will immediately notice that the workflow is considerably different: Contrary to writing the XML code directly, you do not begin with the <command><document></command> definition, but directly with the plugin elements you would like to have in the dialog. You can assign each interface element -- be it check boxes, dropdown menus, variable slots or anything else -- to individual &R; objects, and then combine these objects to the actual &GUI;. The package has functions for <link linkend="interfaceelements">each XML tag</link> that can be used to define the plugin &GUI;, and most of them even have the same name, only with the prefix <function>rk.XML.*</function>. For example, defining a <command><varselector></command> and two <command><varslot></command> elements for the <replaceable>"x"</replaceable> and <replaceable>"y"</replaceable> variable of the t-test example can be done by:</para>
<programlisting>
variables <- rk.XML.varselector(id.name="vars")
var.x <- rk.XML.varslot("compare", source=variables, types="number", required=TRUE, id.name="x")
var.y <- rk.XML.varslot("against", source=variables, types="number", required=TRUE, id.name="y")
</programlisting>
- <para>The most interesting detail is probably <parameter>source=</parameter><replaceable>variables</replaceable>: A prominent feature of the package is that all functions can generate automatic IDs, so you don't have to bother with either thinking of <parameter>id</parameter> values or remembering them to refer to a specific plugin element. You can simply give the &r; objects as reference, as all functions who need an ID from some other element can also read it from these objects. <function>rk.XML.varselector()</function> is a little special, as it usually has no specific content to make an ID from (it can, but only if you specify a label), so we have to set an ID name. But <function>rk.XML.varslot()</function> wouldn't need the <parameter>id.name</parameter> arguments here, so this would suffice:</para>
+ <para>The most interesting detail is probably <parameter>source=</parameter><replaceable>variables</replaceable>: A prominent feature of the package is that all functions can generate automatic IDs, so you do not have to bother with either thinking of <parameter>id</parameter> values or remembering them to refer to a specific plugin element. You can simply give the &R; objects as reference, as all functions who need an ID from some other element can also read it from these objects. <function>rk.XML.varselector()</function> is a little special, as it usually has no specific content to make an ID from (it can, but only if you specify a label), so we have to set an ID name. But <function>rk.XML.varslot()</function> would not need the <parameter>id.name</parameter> arguments here, so this would suffice:</para>
<programlisting>
variables <- rk.XML.varselector(id.name="vars")
var.x <- rk.XML.varslot("compare", source=variables, types="number", required=TRUE)
var.y <- rk.XML.varslot("against", source=variables, types="number", required=TRUE)
</programlisting>
- <para>In order to recreate the example code to the point, you'd have to set all ID values manually. But since the package shall make our lives easier, from now on we will no longer care about that.</para>
+ <para>In order to recreate the example code to the point, you would have to set all ID values manually. But since the package shall make our lives easier, from now on we will no longer care about that.</para>
<tip>
<para>
- <application>rkwarddev</application> is capable of a lot of automation to help you build your plugins. However, it might be preferable to not use it to its full extend. If your goal is to produce code that is not only working but can also be easily read and compared to your generator script by a human being, you should consider to always set useful IDs with <parameter>id.name</parameter>. Naming your &r; objects identical to these IDs will also help in getting script code that is easy to understand.
+ <application>rkwarddev</application> is capable of a lot of automation to help you build your plugins. However, it might be preferable to not use it to its full extend. If your goal is to produce code that is not only working but can also be easily read and compared to your generator script by a human being, you should consider to always set useful IDs with <parameter>id.name</parameter>. Naming your &R; objects identical to these IDs will also help in getting script code that is easy to understand.
</para>
</tip>
- <para>If you want to see how the XML code of the defined element looks like if you exported it to a file, you can just call the object by its name. So, if you now called <quote>var.x</quote> in your &r; session, you should see something like this:</para>
+ <para>If you want to see how the XML code of the defined element looks like if you exported it to a file, you can just call the object by its name. So, if you now called <quote>var.x</quote> in your &R; session, you should see something like this:</para>
<programlisting>
<varslot id="vrsl_compare" label="compare" source="vars" types="number" required="true" />
</programlisting>
- <para>Some tags are only useful in the context of others. Therefore, for instance, you won't find a function for the <command><option></command> tag. Instead, both radio buttons and dropdown lists are defined including their options as a named list, where the names represent the labels to be shown in the dialog, and their value is a named vector which can have two entries, <parameter>val</parameter> for the value of an option and the boolean <parameter>chk</parameter> to specify if this option is checked by default.</para>
+ <para>Some tags are only useful in the context of others. Therefore, for instance, you will not find a function for the <command><option></command> tag. Instead, both radio buttons and dropdown lists are defined including their options as a named list, where the names represent the labels to be shown in the dialog, and their value is a named vector which can have two entries, <parameter>val</parameter> for the value of an option and the boolean <parameter>chk</parameter> to specify if this option is checked by default.</para>
<programlisting>
test.hypothesis <- rk.XML.radio("using test hypothesis",
options=list(
@@ -2444,7 +2443,7 @@ test.hypothesis <- rk.XML.radio("using test hypothesis",
<option label="Second is greater" value="less" />
</radio>
</programlisting>
- <para>All that's missing from the elements of the <quote>Basic settings</quote> tab is the check box for paired samples, and the structuring of all of these elements in rows and columns:</para>
+ <para>All that is missing from the elements of the <quote>Basic settings</quote> tab is the check box for paired samples, and the structuring of all of these elements in rows and columns:</para>
<programlisting>
check.paired <- rk.XML.cbox("Paired sample", value="1", un.value="0")
basic.settings <- rk.XML.row(variables, rk.XML.col(var.x, var.y, test.hypothesis, check.paired))
@@ -2465,7 +2464,7 @@ basic.settings <- rk.XML.row(variables, rk.XML.col(var.x, var.y, test.hypothe
</column>
</row>
</programlisting>
- <para>In a similar manner, the next lines will create &r; objects for the elements of the <quote>Options</quote> tab, introducing functions for spinboxes, frames and stretch:</para>
+ <para>In a similar manner, the next lines will create &R; objects for the elements of the <quote>Options</quote> tab, introducing functions for spinboxes, frames and stretch:</para>
<programlisting>
check.eqvar <- rk.XML.cbox("assume equal variances", value="1", un.value="0")
conf.level <- rk.XML.spinbox("confidence level", min=0, max=1, initial=0.95)
@@ -2489,26 +2488,26 @@ full.wizard <- rk.XML.wizard(
if your theory does not tell you, which variable is greater."),
rk.XML.copy(basic.settings)),
rk.XML.page(
- rk.XML.text("Below are some advanced options. It's generally safe not to assume the
+ rk.XML.text("Below are some advanced options. It is generally safe not to assume the
variables have equal variances. An appropriate correction will be applied then.
Choosing \"assume equal variances\" may increase test-strength, however."),
rk.XML.copy(check.eqvar),
- rk.XML.text("Sometimes it's helpful to get an estimate of the confidence interval of
+ rk.XML.text("Sometimes it is helpful to get an estimate of the confidence interval of
the difference in means. Below you can specify whether one should be shown, and
which confidence-level should be applied (95% corresponds to a 5% level of
significance)."),
rk.XML.copy(conf.frame)))
</programlisting>
- <para>That's it for the GUI. The global document will be combined in the end by <function>rk.plugin.skeleton()</function>.</para>
+ <para>That is it for the &GUI;. The global document will be combined in the end by <function>rk.plugin.skeleton()</function>.</para>
</sect2>
- <sect2 id="rkdev_jscode"><title>JavaScript code</title>
+ <sect2 id="rkdev_jscode"><title>&javascript; code</title>
<para>Until now, using the <application>rkwarddev</application> package might not seem to have helped so much. This is going to change right now.</para>
- <para>First of all, just like we didn't have to care about IDs for elements when defining the GUI layout, we don't have to care about JavaScript variable names in the next step. If you want more control, you can write plain JavaScript code and have it pasted to the generated file. But it's probably much more efficient to do it the <application>rkwarddev</application> way.</para>
- <para>Most notably you don't have to define any variable yourself, as <function>rk.plugin.skeleton()</function> can scan your XML code and automatically define all variables you will probably need -- for instance, you wouldn't bother to include a check box if you don't use its value or state afterwards. So we can start writing the actual &r; code generating JS immediately.</para>
- <tip><para>The function <function>rk.JS.scan()</function> can also scan existing XML files for variables.</para></tip>
- <para>The package has some functions for JS code constructs that are commonly used in &rkward; plugins, like the <function>echo()</function> function or <function>if() {...} else {...}</function> conditions. There are some differences between JS and &r;, ⪚, for <function>paste()</function> in &r; you use the comma to concatenate character strings, whereas for <function>echo()</function> in JS you use <quote>+</quote>, and lines must end with a semicolon. By using the &r; functions, you can almost forget about these differences and keep writing &r; code.</para>
- <para>These functions can take different classes of input objects: Either plain text, &r; objects with XML code like above, or in turn results of some other JS functions of the package. In the end, you will always call <function>rk.paste.JS()</function>, which behaves similar to <function>paste()</function>, but depending on the input objects it will replace them with their XML ID, JavaScript variable name or even complete JavaScript code blocks.</para>
+ <para>First of all, just like we did not have to care about IDs for elements when defining the &GUI; layout, we do not have to care about &javascript; variable names in the next step. If you want more control, you can write plain &javascript; code and have it pasted to the generated file. But it is probably much more efficient to do it the <application>rkwarddev</application> way.</para>
+ <para>Most notably you do not have to define any variable yourself, as <function>rk.plugin.skeleton()</function> can scan your &XML; code and automatically define all variables you will probably need -- for instance, you would not bother to include a check box if you do not use its value or state afterwards. So we can start writing the actual &R; code generating JS immediately.</para>
+ <tip><para>The function <function>rk.JS.scan()</function> can also scan existing &XML; files for variables.</para></tip>
+ <para>The package has some functions for JS code constructs that are commonly used in &rkward; plugins, like the <function>echo()</function> function or <function>if() {...} else {...}</function> conditions. There are some differences between JS and &R;, ⪚, for <function>paste()</function> in &R; you use the comma to concatenate character strings, whereas for <function>echo()</function> in JS you use <quote>+</quote>, and lines must end with a semicolon. By using the &R; functions, you can almost forget about these differences and keep writing &R; code.</para>
+ <para>These functions can take different classes of input objects: Either plain text, &R; objects with &XML; code like above, or in turn results of some other JS functions of the package. In the end, you will always call <function>rk.paste.JS()</function>, which behaves similar to <function>paste()</function>, but depending on the input objects it will replace them with their &XML; ID, &javascript; variable name or even complete &javascript; code blocks.</para>
<para>For the t-test example, we need two JS objects: One to calculate the results, and one to print them in the <function>printout()</function> function:</para>
<programlisting>
JS.calc <- rk.paste.JS(
@@ -2531,8 +2530,8 @@ JS.calc <- rk.paste.JS(
JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
</programlisting>
- <para>As you can see, <application>rkwarddev</application> also provides an &r; implementation of the <function>echo()</function> function. It returns exactly one character string with a valid JS version of itself. You might also notice that all of the &r; objects here are the ones we created earlier. They will automatically be replaced with their variable names, so this should be quite intuitive. Whenever you need just this replacement, the function <function>id()</function> can be used, which also will return exactly one character string from all the objects it was given (you could say it behaves like <function>paste()</function> with a very specific object substitution).</para>
- <para>The <function>js()</function> function is a wrapper that allows you to use &r;'s <command>if(){...} else {...}</command> conditions like you are used to. They will be translated directly into JS code. It also preserves some operators like <command><</command>, <command>>=</command> or <command>||</command>, so you can logically compare your &r; objects without the need for quoting most of the time. Let's have a look at the resulting <quote>JS.calc</quote> object, which now contains a character string with this content:</para>
+ <para>As you can see, <application>rkwarddev</application> also provides an &R; implementation of the <function>echo()</function> function. It returns exactly one character string with a valid JS version of itself. You might also notice that all of the &R; objects here are the ones we created earlier. They will automatically be replaced with their variable names, so this should be quite intuitive. Whenever you need just this replacement, the function <function>id()</function> can be used, which also will return exactly one character string from all the objects it was given (you could say it behaves like <function>paste()</function> with a very specific object substitution).</para>
+ <para>The <function>js()</function> function is a wrapper that allows you to use &R;'s <command>if(){...} else {...}</command> conditions like you are used to. They will be translated directly into JS code. It also preserves some operators like <command><</command>, <command>>=</command> or <command>||</command>, so you can logically compare your &R; objects without the need for quoting most of the time. Let's have a look at the resulting <quote>JS.calc</quote> object, which now contains a character string with this content:</para>
<programlisting>
echo("res <- t.test (x=" + vrslCompare + ", y=" + vrslAgainst + ", hypothesis=\"" + radUsngtsth + "\"");
if(chcPardsmpl) {
@@ -2548,13 +2547,13 @@ JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
</programlisting>
<note>
<para>
- Alternatively for <function>if()</function> conditions nested in <function>js()</function>, you can use the <function>ite()</function> function, which behaves similar to &r;'s <function>ifelse()</function>. However, conditional statements constructed using <function>ite()</function> are usually harder to read and should be replaced by <function>js()</function> whenever possible.
+ Alternatively for <function>if()</function> conditions nested in <function>js()</function>, you can use the <function>ite()</function> function, which behaves similar to &R;'s <function>ifelse()</function>. However, conditional statements constructed using <function>ite()</function> are usually harder to read and should be replaced by <function>js()</function> whenever possible.
</para>
</note>
</sect2>
<sect2 id="rkdev_pluginmap"><title>Plugin map</title>
- <para>This section is very short: We don't need to write a &pluginmap; at all, as it can be generated automatically by <function>rk.plugin.skeleton()</function>. The menu hierarchy can be specified via the <parameter>pluginmap</parameter> option:</para>
+ <para>This section is very short: We do not need to write a &pluginmap; at all, as it can be generated automatically by <function>rk.plugin.skeleton()</function>. The menu hierarchy can be specified via the <parameter>pluginmap</parameter> option:</para>
<programlisting>
[...]
pluginmap=list(
@@ -2565,12 +2564,12 @@ JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
</sect2>
<sect2 id="rkdev_rkh"><title>Help page</title>
- <para>This section is very short as well: <function>rk.plugin.skeleton()</function> cannot write a whole help page from the information it has. But it can scan the XML document also for elements which probably deserve a help page entry, and automatically create a help page template for our plugin. All we have to do afterwards is to write some lines for each listed section.</para>
- <tip><para>The function <function>rk.rkh.scan()</function> can also scan existing XML files to create a help file skeleton.</para></tip>
+ <para>This section is very short as well: <function>rk.plugin.skeleton()</function> cannot write a whole help page from the information it has. But it can scan the &XML; document also for elements which probably deserve a help page entry, and automatically create a help page template for our plugin. All we have to do afterwards is to write some lines for each listed section.</para>
+ <tip><para>The function <function>rk.rkh.scan()</function> can also scan existing &XML; files to create a help file skeleton.</para></tip>
</sect2>
<sect2 id="rkdev_plugin_generator"><title>Generate the plugin files</title>
- <para>Now comes the final step, in which we'll hand over all generated objects to <function>rk.plugin.skeleton()</function>:</para>
+ <para>Now comes the final step, in which we will hand over all generated objects to <function>rk.plugin.skeleton()</function>:</para>
<programlisting>
plugin.dir <- rk.plugin.skeleton("t-Test",
xml=list(
@@ -2587,11 +2586,11 @@ plugin.dir <- rk.plugin.skeleton("t-Test",
edit=TRUE,
show=TRUE)
</programlisting>
- <para>The files will be created in a temporal directory by default. The last three options are not necessary, but very handy: <parameter>load=</parameter><replaceable>TRUE</replaceable> will automatically add the new plugin to &rkward;s configuration (since it's in a temp dir and hence will cease to exist when &rkward; is closed, it will automatically be removed again by &rkward; during its next start), <parameter>edit=</parameter><replaceable>TRUE</replaceable> will open all created files for editing in &rkward; editor tabs, and <parameter>show=</parameter><replaceable>TRUE</replaceable> will attempt to directly launch the plugin, so you can examine what it looks like without a click. You might consider adding <parameter>overwrite=</parameter><replaceable>TRUE</replaceable> if you're about to run your script repeatedly (⪚ after changes to the code), as by default no files will be overwritten.</para>
- <para>The result object <quote>plugin.dir</quote> contains the path to the directory in which the plugin was created. This can be useful in combination with the function <function>rk.build.package()</function>, to build an actual &r; package to share your plugin with others -- ⪚ by sending it to the &rkward; development team to be added to our plugin repository.</para>
+ <para>The files will be created in a temporal directory by default. The last three options are not necessary, but very handy: <parameter>load=</parameter><replaceable>TRUE</replaceable> will automatically add the new plugin to &rkward;s configuration (since it is in a temp dir and hence will cease to exist when &rkward; is closed, it will automatically be removed again by &rkward; during its next start), <parameter>edit=</parameter><replaceable>TRUE</replaceable> will open all created files for editing in &rkward; editor tabs, and <parameter>show=</parameter><replaceable>TRUE</replaceable> will attempt to directly launch the plugin, so you can examine what it looks like without a click. You might consider adding <parameter>overwrite=</parameter><replaceable>TRUE</replaceable> if you are about to run your script repeatedly (⪚ after changes to the code), as by default no files will be overwritten.</para>
+ <para>The result object <quote>plugin.dir</quote> contains the path to the directory in which the plugin was created. This can be useful in combination with the function <function>rk.build.package()</function>, to build an actual &R; package to share your plugin with others -- ⪚ by sending it to the &rkward; development team to be added to our plugin repository.</para>
</sect2>
<sect2 id="rkdev_ttest_script"><title>The full script</title>
- <para>To recapitulate all of the above, here's the full script to create the working t-test example. Adding to the already explained code, it also loads the package if needed, and it uses the <function>local()</function> environment, so all the created objects will not end up in your current workspace (except for <quote>plugin.dir</quote>):</para>
+ <para>To recapitulate all of the above, here is the full script to create the working t-test example. Adding to the already explained code, it also loads the package if needed, and it uses the <function>local()</function> environment, so all the created objects will not end up in your current workspace (except for <quote>plugin.dir</quote>):</para>
<programlisting>
require(rkwarddev)
@@ -2627,11 +2626,11 @@ local({
if your theory does not tell you, which variable is greater."),
rk.XML.copy(basic.settings)),
rk.XML.page(
- rk.XML.text("Below are some advanced options. It's generally safe not to assume the
+ rk.XML.text("Below are some advanced options. It is generally safe not to assume the
variables have equal variances. An appropriate correction will be applied then.
Choosing \"assume equal variances\" may increase test-strength, however."),
rk.XML.copy(check.eqvar),
- rk.XML.text("Sometimes it's helpful to get an estimate of the confidence interval of
+ rk.XML.text("Sometimes it is helpful to get an estimate of the confidence interval of
the difference in means. Below you can specify whether one should be shown, and
which confidence-level should be applied (95% corresponds to a 5% level of
significance)."),
@@ -2677,7 +2676,7 @@ local({
</sect1>
<sect1 id="rkwarddev_rkh"><title>Adding help pages</title>
<para>
- If you want to write a help page for your plugin, the most straight forward way to do so is to add the particular instructions directly to the definitions of the XML elements they belong to:
+ If you want to write a help page for your plugin, the most straight forward way to do so is to add the particular instructions directly to the definitions of the &XML; elements they belong to:
</para>
<programlisting>
variables <- rk.XML.varselector(
@@ -2687,7 +2686,7 @@ variables <- rk.XML.varselector(
)
</programlisting>
<para>
- The text given to the <parameter>help</parameter> parameter can then be fetched by <function>rk.rkh.scan()</function> and written to the help page of this plugin component. For this to work technically, however, <function>rk.rkh.scan()</function> must know which &r; objects belong to one plugin component. This is why you must also provide the <parameter>component</parameter> parameter and make sure it is identical for all objects belonging together.
+ The text given to the <parameter>help</parameter> parameter can then be fetched by <function>rk.rkh.scan()</function> and written to the help page of this plugin component. For this to work technically, however, <function>rk.rkh.scan()</function> must know which &R; objects belong to one plugin component. This is why you must also provide the <parameter>component</parameter> parameter and make sure it is identical for all objects belonging together.
</para>
<para>
Since you will usually combine many objects into one dialog and might also like to be able to re-use objects like the <command><varslot></command> in multiple components of your plugins, it is possible to globally define a component with the <function>rk.set.comp()</function>. If set, it is assumed that all the following objects used in your script belong to that particular component, until <function>rk.set.comp()</function> is being called again with a different component name. You can then omit the <parameter>component</parameter> parameter:
@@ -2725,7 +2724,7 @@ cboxNoi18n <- rk.XML.cbox(label="Power", id.name="power", i18n=FALSE)
<checkbox id="power" noi18n_label="Power" value="true" />
</programlisting>
<para>
- There's also support for translatable JS code. In fact, the package tries add <function>i18n()</function> calls by default in places where this is usually helpful. The <function>rk.JS.header()</function> function is a good example:
+ There is also support for translatable JS code. In fact, the package tries add <function>i18n()</function> calls by default in places where this is usually helpful. The <function>rk.JS.header()</function> function is a good example:
</para>
<programlisting>
jsHeader <- rk.JS.header("Test results")
@@ -2743,7 +2742,7 @@ new Header(i18n("Test results")).print();
<sect1 id="propertytypes"><title>Types of properties/Modifiers</title>
<para>
- At some places in this introduction we've talked about <quote>properties</quote> of GUI elements or otherwise. In fact there are several different types of properties. Usually you do not need to worry about this, as you can use common sense to connect any property to any other property. However, internally, there are different types of properties. What this matters for, is when fetching some special values in the JS-template. In getString ("id")/getBoolean ("id")/getList ("id") statements you can also specify some so called <quote>modifiers</quote> like this: <function>getString ("id.modifier")</function>. This modifier will affect, in which way the value is printed. Read on for the list of properties, and the modifiers they each make available:
+ At some places in this introduction we have talked about <quote>properties</quote> of &GUI; elements or otherwise. In fact there are several different types of properties. Usually you do not need to worry about this, as you can use common sense to connect any property to any other property. However, internally, there are different types of properties. What this matters for, is when fetching some special values in the JS-template. In getString ("id")/getBoolean ("id")/getList ("id") statements you can also specify some so called <quote>modifiers</quote> like this: <function>getString ("id.modifier")</function>. This modifier will affect, in which way the value is printed. Read on for the list of properties, and the modifiers they each make available:
</para>
<variablelist>
<varlistentry>
@@ -2756,7 +2755,7 @@ new Header(i18n("Test results")).print();
</varlistentry>
<varlistentry>
<term>quoted</term>
- <listitem><para>The string in quoted form (suitable for passing to &r; as character).</para></listitem>
+ <listitem><para>The string in quoted form (suitable for passing to &R; as character).</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
@@ -2810,7 +2809,7 @@ new Header(i18n("Test results")).print();
</varlistentry>
<varlistentry>
<term>RObject properties</term>
-<listitem><para>A property designed a selection of one or more &r; objects. Used most prominently in varselectors and varslots. The following values will be returned according to the given modifier:
+<listitem><para>A property designed a selection of one or more &R; objects. Used most prominently in varselectors and varslots. The following values will be returned according to the given modifier:
<variablelist>
<varlistentry>
<term>No modifier ("")</term>
@@ -2870,7 +2869,7 @@ new Header(i18n("Test results")).print();
</sect1>
<sect1 id="globalxmlelements">
- <title>General purpose elements to be used in any XML file (<literal role="extension">.xml</literal>, <literal role="extension">.rkh</literal>, &pluginmap;)</title>
+ <title>General purpose elements to be used in any &XML; file (<literal role="extension">.xml</literal>, <literal role="extension">.rkh</literal>, &pluginmap;)</title>
<variablelist>
<varlistentry>
<term><snippets></term>
@@ -2898,7 +2897,7 @@ new Header(i18n("Test results")).print();
</varlistentry>
<varlistentry>
<term><include></term>
- <listitem><para>Include the contents of another XML file (everything inside the <document> element of that file). Allowed anywhere. Attributes:
+ <listitem><para>Include the contents of another &XML; file (everything inside the <document> element of that file). Allowed anywhere. Attributes:
<variablelist>
<varlistentry>
<term><file></term>
@@ -2909,7 +2908,7 @@ new Header(i18n("Test results")).print();
</variablelist>
</sect1>
-<sect1 id="xmlelements"><title>Elements to be used in the XML description of the plugin</title>
+<sect1 id="xmlelements"><title>Elements to be used in the &XML; description of the plugin</title>
<para>Properties held by the elements are listed in a <link linkend="elementproperties">separate section</link>.</para>
<sect2 id="generalelements"><title>General elements</title>
@@ -2920,7 +2919,7 @@ new Header(i18n("Test results")).print();
</varlistentry>
<varlistentry>
<term><about></term>
-<listitem><para>Information about this plugin (author, licence, &etc;). This element is allowed in both an individual plugin's .xml file, and in &pluginmap; files. Refer to the <link linkend="pluginmapelements">&pluginmap; file reference</link> for reference details, <link linkend="chapter_about_information">the chapter on 'about' information</link> for an introduction.</para></listitem>
+<listitem><para>Information about this plugin (author, licence, &etc;). This element is allowed in both an individual plugin's <literal role="extension">.xml</literal> file, and in &pluginmap; files. Refer to the <link linkend="pluginmapelements">&pluginmap; file reference</link> for reference details, <link linkend="chapter_about_information">the chapter on 'about' information</link> for an introduction.</para></listitem>
</varlistentry>
<varlistentry>
<term><code></term>
@@ -2944,15 +2943,15 @@ new Header(i18n("Test results")).print();
</varlistentry>
<varlistentry>
<term><copy></term>
-<listitem><para>Can be used as a child (direct or indirect) of the main layout elements, &ie; <dialog> and <wizard>. This is used to copy an entire block a xml elements 1:1. Attributes:
+<listitem><para>Can be used as a child (direct or indirect) of the main layout elements, &ie; <dialog> and <wizard>. This is used to copy an entire block a &XML; elements 1:1. Attributes:
<variablelist>
<varlistentry>
<term><parameter>id</parameter></term>
- <listitem><para>The ID to look for. The <copy> tag will look for a previous XML element that has been given the same ID, and copy it including all descendant elements.</para></listitem>
+ <listitem><para>The ID to look for. The <copy> tag will look for a previous &XML; element that has been given the same ID, and copy it including all descendant elements.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>copy_element_tag_name</parameter></term>
- <listitem><para>In some few cases, you will want an almost literal copy, but change the tag-name of the element to copy. The most important example of this is, when you want to copy an entire <tab> from a dialog interface to the <page> of a wizard interface. In this case, you'd set copy_element_tag_name="page" to do this conversion automatically.</para></listitem>
+ <listitem><para>In some few cases, you will want an almost literal copy, but change the tag-name of the element to copy. The most important example of this is, when you want to copy an entire <tab> from a dialog interface to the <page> of a wizard interface. In this case, you would set copy_element_tag_name="page" to do this conversion automatically.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
@@ -2963,7 +2962,7 @@ new Header(i18n("Test results")).print();
<variablelist>
<varlistentry>
<term><dialog></term>
-<listitem><para>Defines a dialog-type interface. Place the GUI-definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Attributes:
+<listitem><para>Defines a dialog-type interface. Place the &GUI; definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
@@ -2977,7 +2976,7 @@ new Header(i18n("Test results")).print();
</varlistentry>
<varlistentry>
<term><wizard></term>
-<listitem><para>Defines a wizard-type interface. Place the GUI-definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Accepts only <page> or <embed>-tags as direct children. Attributes:
+<listitem><para>Defines a wizard-type interface. Place the &GUI; definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Accepts only <page> or <embed>-tags as direct children. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
@@ -2993,7 +2992,7 @@ new Header(i18n("Test results")).print();
</sect2>
<sect2 id="layoutelements"><title>Layout elements</title>
-<para>All elements in this section accept an attribute id="identifierstring". This attribute is optional for all elements. It can be used, for example, to hide/disable the entire layout element and all the elements contained therein (see <link linkend="logic">chapter GUI logic</link>). The id-string may not contain "." (dot) or ";" (semicolon), and should generally be limited to alphanumeric characters and the underscore ("_"). Only the additional attributes are listed.</para>
+<para>All elements in this section accept an attribute id="identifierstring". This attribute is optional for all elements. It can be used, for example, to hide/disable the entire layout element and all the elements contained therein (see <link linkend="logic">chapter &GUI; logic</link>). The id-string may not contain "." (dot) or ";" (semicolon), and should generally be limited to alphanumeric characters and the underscore ("_"). Only the additional attributes are listed.</para>
<variablelist>
<varlistentry>
<term><page></term>
@@ -3009,7 +3008,7 @@ new Header(i18n("Test results")).print();
</varlistentry>
<varlistentry>
<term><stretch></term>
-<listitem><para>By default, elements in the GUI take up all the space that's available. For instance, if you have two columns side by side, the left one is packed with elements, but the right one only contains a lonely <command><radio></command>, the <command><radio></command> control will expand vertically, even though it does not really need the available space, and it will look ugly. In this case you really want to add a "blank" below the <command><radio></command>. For this, use the <stretch> element. It will simply use up some space. Don't overuse this element, usually it's a good idea for GUI elements to get all the available space, only sometimes will the layout become spaced out. The <stretch> element does not take any arguments, not even an "id". Also you can place no children inside the <stretch> element (in other words, you'll only ever use it as "<stretch/>")</para></listitem>
+<listitem><para>By default, elements in the &GUI; take up all the space that is available. For instance, if you have two columns side by side, the left one is packed with elements, but the right one only contains a lonely <command><radio></command>, the <command><radio></command> control will expand vertically, even though it does not really need the available space, and it will look ugly. In this case you really want to add a "blank" below the <command><radio></command>. For this, use the <stretch> element. It will simply use up some space. Do not overuse this element, usually it is a good idea for &GUI; elements to get all the available space, only sometimes will the layout become spaced out. The <stretch> element does not take any arguments, not even an "id". Also you can place no children inside the <stretch> element (in other words, you will only ever use it as "<stretch/>")</para></listitem>
</varlistentry>
<varlistentry>
<term><frame></term>
@@ -3035,7 +3034,7 @@ new Header(i18n("Test results")).print();
</varlistentry>
<varlistentry>
<term><tab></term>
-<listitem><para>Defines a page in a tabbook. Place the GUI-definition for the tab inside this tag. May be used only as a direct child of a <tabbook> tag. A <tabbook> should have at least two defined tabs. Attributes:
+<listitem><para>Defines a page in a tabbook. Place the &GUI; definition for the tab inside this tag. May be used only as a direct child of a <tabbook> tag. A <tabbook> should have at least two defined tabs. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
@@ -3045,7 +3044,7 @@ new Header(i18n("Test results")).print();
</varlistentry>
<varlistentry>
<term><text></term>
-<listitem><para>Shows the text enclosed in this tag in the GUI. Some simple HTML-style markup is supported (notably <markup><b></markup>, <markup><i></markup>, <markup><p></markup>, and <markup><br/></markup>). Please keep formatting to a minimum, however. Inserting a completely empty line adds a hard line break. Attributes:
+<listitem><para>Shows the text enclosed in this tag in the &GUI;. Some simple &HTML; style markup is supported (notably <markup><b></markup>, <markup><i></markup>, <markup><p></markup>, and <markup><br/></markup>). Please keep formatting to a minimum, however. Inserting a completely empty line adds a hard line break. Attributes:
<variablelist>
<varlistentry>
<term><parameter>type</parameter></term>
@@ -3113,7 +3112,7 @@ new Header(i18n("Test results")).print();
</varlistentry>
<varlistentry>
<term><parameter>classes</parameter></term>
- <listitem><para>If you specify one or more &r; classnames (separated by spaces (" ")), here, the varslot will only accept objects belonging to those classes (optional, <emphasis>use with great care</emphasis>, the user should not be prevented from making valid choices, and &r; has <emphasis>a lot</emphasis> of different classes!)</para></listitem>
+ <listitem><para>If you specify one or more &R; classnames (separated by spaces (" ")), here, the varslot will only accept objects belonging to those classes (optional, <emphasis>use with great care</emphasis>, the user should not be prevented from making valid choices, and &R; has <emphasis>a lot</emphasis> of different classes)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>types</parameter></term>
@@ -3136,7 +3135,7 @@ new Header(i18n("Test results")).print();
<varlistentry>
<term><valueselector></term>
-<listitem><para>Provides a list of available strings (not &r; objects) to be selected in one or more accompanying <valueslot>s. String options can be defined using <option>-tags as direct children (see below), or set using dynamic <link linkend="elementproperties">properties</link>. Attributes:
+<listitem><para>Provides a list of available strings (not &R; objects) to be selected in one or more accompanying <valueslot>s. String options can be defined using <option>-tags as direct children (see below), or set using dynamic <link linkend="elementproperties">properties</link>. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
@@ -3202,7 +3201,7 @@ have an "id" of their own, but see below. Attributes:
</varlistentry>
<varlistentry>
<term><parameter>id</parameter></term>
- <listitem><para>Specifying the "id" parameter for the <option> elements is optional (and in fact it's recommended, not to set an "id", unless you really need one). However, specifying an "id" will allow you to enable/disable <option>s, dynamically, by connecting to the boolean property <replaceable>id_of_radio.id_of_optionX.enabled</replaceable>. Currently this works for options inside <radio> or <dropdown>
+ <listitem><para>Specifying the "id" parameter for the <option> elements is optional (and in fact it is recommended, not to set an "id", unless you really need one). However, specifying an "id" will allow you to enable/disable <option>s, dynamically, by connecting to the boolean property <replaceable>id_of_radio.id_of_optionX.enabled</replaceable>. Currently this works for options inside <radio> or <dropdown>
elements, only; <valueselector> and <select> options do not currently support ids.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
@@ -3263,7 +3262,7 @@ made checkable, thus acting like a simple check box at the same time.
<varlistentry>
<term><matrix></term>
-<listitem><para>A table for entering matrix data (or vectors) in the GUI.</para> <note><para>This input element is <emphasis>not</emphasis> optimized for entering/editing large amounts of data. While there is no strict limit on the size of a <matrix>, in general it should not exceed around ten rows / columns. If you expect larger data, allow users to select it as an &r; object (which may be a good idea as an alternative option, in almost <emphasis>every</emphasis> instance where you use a matrix element).</para></note> <para>Attributes:
+<listitem><para>A table for entering matrix data (or vectors) in the &GUI;.</para> <note><para>This input element is <emphasis>not</emphasis> optimized for entering/editing large amounts of data. While there is no strict limit on the size of a <matrix>, in general it should not exceed around ten rows / columns. If you expect larger data, allow users to select it as an &R; object (which may be a good idea as an alternative option, in almost <emphasis>every</emphasis> instance where you use a matrix element).</para></note> <para>Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
@@ -3311,7 +3310,7 @@ made checkable, thus acting like a simple check box at the same time.
</varlistentry>
<varlistentry>
<term><parameter>fixed_height</parameter></term>
- <listitem><para>Force the GUI element to stay at its initial height. Do not use in combination with matrices, where the number of rows may change in any way. Useful, esp. when creating a vector input element (columns="1"). With this option set to true, no horizontal scroll bar will be shown, even in the matrix exceeds the available width (as this would affect the height). (optional, defaults to false).</para></listitem>
+ <listitem><para>Force the &GUI; element to stay at its initial height. Do not use in combination with matrices, where the number of rows may change in any way. Useful, esp. when creating a vector input element (columns="1"). With this option set to true, no horizontal scroll bar will be shown, even in the matrix exceeds the available width (as this would affect the height). (optional, defaults to false).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>fixed_width</parameter></term>
@@ -3398,7 +3397,7 @@ made checkable, thus acting like a simple check box at the same time.
</varlistentry>
<varlistentry>
<term><parameter>allow_urls</parameter></term>
- <listitem><para>Whether (non-local) urls can be selected (optional, defaults to "false")</para></listitem>
+ <listitem><para>Whether (non-local) &URL;s can be selected (optional, defaults to "false")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>filter</parameter></term>
@@ -3406,14 +3405,14 @@ made checkable, thus acting like a simple check box at the same time.
</varlistentry>
<varlistentry>
<term><parameter>required</parameter></term>
- <listitem><para>Whether - for submitting the code - it is required that the field is not empty. Note that this does not necessarily mean, the selected filename is valid! See <link linkend="elementproperties">required-property</link> (optional, defaults to true)</para></listitem>
+ <listitem><para>Whether - for submitting the code - it is required that the field is not empty. Note that this does not necessarily mean that the selected filename is valid. See <link linkend="elementproperties">required-property</link> (optional, defaults to true)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><saveobject></term>
-<listitem><para>An element designed to select the name of an &r; object to save to (&ie; generally not already existing, in contrast to a varslot):
+<listitem><para>An element designed to select the name of an &R; object to save to (&ie; generally not already existing, in contrast to a varslot):
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
@@ -3429,7 +3428,7 @@ made checkable, thus acting like a simple check box at the same time.
</varlistentry>
<varlistentry>
<term><parameter>checkable</parameter></term>
- <listitem><para>In many use cases, saving to an &r; object is optional. In these cases, a check box can be integrated into the saveobject-element using this attribute. When set to true, the saveobject will be activated / deactivated by the check box. See the <link linkend="elementproperties">active-property</link> of saveobject (optional, defaults to false)</para></listitem>
+ <listitem><para>In many use cases, saving to an &R; object is optional. In these cases, a check box can be integrated into the saveobject-element using this attribute. When set to true, the saveobject will be activated / deactivated by the check box. See the <link linkend="elementproperties">active-property</link> of saveobject (optional, defaults to false)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>checked</parameter></term>
@@ -3498,7 +3497,7 @@ made checkable, thus acting like a simple check box at the same time.
</varlistentry>
<varlistentry>
<term><parameter>as_button</parameter></term>
- <listitem><para>If set to "true", only a pushbutton will be placed in the embedding GUI, the embedded GUI will only be shown (in a separate window) when the pushbutton is pressed (optional, default is "false")</para></listitem>
+ <listitem><para>If set to "true", only a pushbutton will be placed in the embedding &GUI;, the embedded &GUI; will only be shown (in a separate window) when the pushbutton is pressed (optional, default is "false")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>label</parameter></term>
@@ -3519,7 +3518,7 @@ made checkable, thus acting like a simple check box at the same time.
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
- <listitem><para>Type of preview. Supported types are "plot" (see <link linkend="preview_plots">chapter on graph previews</link>), "output" (see <link linkend="preview_output">chapter on (HTML) output previews</link>), "data" (see <link linkend="preview_data">data previews</link>), and "custom" (see <link linkend="preview_custom">custom previews</link>). (optional, default is "plot")</para></listitem>
+ <listitem><para>Type of preview. Supported types are "plot" (see <link linkend="preview_plots">chapter on graph previews</link>), "output" (see <link linkend="preview_output">chapter on (&HTML;) output previews</link>), "data" (see <link linkend="preview_data">data previews</link>), and "custom" (see <link linkend="preview_custom">custom previews</link>). (optional, default is "plot")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>placement</parameter></term>
@@ -3583,7 +3582,7 @@ Attributes:
</varlistentry>
<varlistentry>
<term><parameter>to</parameter></term>
- <listitem><para>The string value to set the property to (required). Note: For boolean properties such as visibility, enabledness, you'll typically set the to attribute to either to="true" or to="false".</para></listitem>
+ <listitem><para>The string value to set the property to (required). Note: For boolean properties such as visibility, enabledness, you will typically set the to attribute to either to="true" or to="false".</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
@@ -3619,7 +3618,7 @@ Attributes:
<varlistentry>
<term><parameter>require_true</parameter></term>
<listitem><para>If set to "true", the property will become required, and will only be considered valid, if its state is true/on. Hence, if the property is false, it will block the <guibutton>Submit</guibutton> button (optional, defaults to "false").
- <caution><para>If you use this, make sure the user can easily detect what's wrong, such as by showing an explanatory <text>.</para></caution></para></listitem>
+ <caution><para>If you use this, make sure the user can easily detect what is wrong, such as by showing an explanatory <text>.</para></caution></para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
@@ -3678,7 +3677,7 @@ Attributes:
<varlistentry>
<term><connect></term>
-<listitem><para>Connects two properties. The client property will be changed whenever the governor property changes (but not the other way around!). Attributes:
+<listitem><para>Connects two properties. The client property will be changed whenever the governor property changes (but not the other way around). Attributes:
<variablelist>
<varlistentry>
<term><parameter>client</parameter></term>
@@ -3697,7 +3696,7 @@ Attributes:
<varlistentry>
<term><dependency_check></term>
-<listitem><para>Creates a boolean property that is true, if the specified dependencies are met, false otherwise. The xml syntax of the element is the same as that of the <command><dependencies></command> element, described in the <link linkend="pluginmapelements">&pluginmap; reference</link>. As of &rkward; 0.6.1, only the &rkward; and &r; version specifications are taken into account, not dependencies on packages or pluginmaps.</para></listitem>
+<listitem><para>Creates a boolean property that is true, if the specified dependencies are met, false otherwise. The &XML; syntax of the element is the same as that of the <command><dependencies></command> element, described in the <link linkend="pluginmapelements">&pluginmap; reference</link>. As of &rkward; 0.6.1, only the &rkward; and &R; version specifications are taken into account, not dependencies on packages or pluginmaps.</para></listitem>
</varlistentry>
<varlistentry>
@@ -3722,15 +3721,15 @@ Attributes:
<variablelist>
<varlistentry>
<term>visible</term>
-<listitem><para>Whether the GUI element is visible or not (boolean)</para></listitem>
+<listitem><para>Whether the &GUI; element is visible or not (boolean)</para></listitem>
</varlistentry>
<varlistentry>
<term>enabled</term>
-<listitem><para>Whether the GUI element is enabled or not (boolean)</para></listitem>
+<listitem><para>Whether the &GUI; element is enabled or not (boolean)</para></listitem>
</varlistentry>
<varlistentry>
<term>required</term>
-<listitem><para>Whether the GUI element is required (to hold a valid setting) or not. Note that any element which is disabled or hidden is also implicitly non-required (boolean).</para></listitem>
+<listitem><para>Whether the &GUI; element is required (to hold a valid setting) or not. Note that any element which is disabled or hidden is also implicitly non-required (boolean).</para></listitem>
</varlistentry>
</variablelist>
<para>
@@ -3902,7 +3901,7 @@ Attributes:
</varlistentry>
<varlistentry>
<term>cbind</term>
- <listitem><para>Data in a format suitable for pasting to &r;, wrapped in a cbind statement (string; read-only).</para></listitem>
+ <listitem><para>Data in a format suitable for pasting to &R;, wrapped in a cbind statement (string; read-only).</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
@@ -3947,11 +3946,11 @@ Attributes:
</varlistentry>
<varlistentry>
<term>parent</term>
- <listitem><para>The parent object of the selected object. This is always an existing &r; object of a type that can contain other objects (⪚ a list or data.frame). When set to an empty string or an invalid object, ".GlobalEnv" is assumed (RObject)</para></listitem>
+ <listitem><para>The parent object of the selected object. This is always an existing &R; object of a type that can contain other objects (⪚ a list or data.frame). When set to an empty string or an invalid object, ".GlobalEnv" is assumed (RObject)</para></listitem>
</varlistentry>
<varlistentry>
<term>objectname</term>
- <listitem><para>The base-name of the selected object, &ie; the string entered by the user (changed to a valid &r; name, if necessary) (string)</para></listitem>
+ <listitem><para>The base-name of the selected object, &ie; the string entered by the user (changed to a valid &R; name, if necessary) (string)</para></listitem>
</varlistentry>
<varlistentry>
<term>active</term>
@@ -4033,7 +4032,7 @@ Attributes:
<term><switch></term>
<listitem><para>This element (used in the <logic> section) is special, in that is technically *is* a (string) property, instead of just holding one or more properties. It allows to switch between several target properties depending on the value of a condition property, or to re-map values of the condition property. Any modifiers that you supply are passed on to the target properties, thus, ⪚ if all target
properties are RObject properties, you can use the "shortname" modifier on the switch, too. However, if the target properties are of
-different types, using modifiers may lead to errors. For <replaceable>fixed_value</replaceable>s, any modifier is dropped, silently. Note that target properties, when accessed through a switch, are always read-only!</para></listitem>
+different types, using modifiers may lead to errors. For <replaceable>fixed_value</replaceable>s, any modifier is dropped, silently. Note that target properties, when accessed through a switch, are always read-only.</para></listitem>
</varlistentry>
</variablelist>
@@ -4147,14 +4146,14 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
</varlistentry>
<varlistentry>
<term>R_min_version, R_max_version</term>
- <listitem><para>Minimum and maximum allowed version of &r;. Version specifications may <emphasis>not</emphasis> include non-numeric suffixes, like "0.5.7z-devel1". The &r; version dependency will be shown on the plugins' help pages, but does not have any direct effect, as of &rkward; 0.6.1. <link linkend="sect_dependencies_r_version">More information</link>. Optional; if not specified, no minimum / maximum version of &r; will be required.</para></listitem>
+ <listitem><para>Minimum and maximum allowed version of &R;. Version specifications may <emphasis>not</emphasis> include non-numeric suffixes, like "0.5.7z-devel1". The &R; version dependency will be shown on the plugins' help pages, but does not have any direct effect, as of &rkward; 0.6.1. <link linkend="sect_dependencies_r_version">More information</link>. Optional; if not specified, no minimum / maximum version of &R; will be required.</para></listitem>
</varlistentry>
</variablelist>
<para>Child elements:</para>
<variablelist>
<varlistentry>
<term><package></term>
- <listitem><para>Adds a dependency on a specific &r; package. Attributes:
+ <listitem><para>Adds a dependency on a specific &R; package. Attributes:
<variablelist>
<varlistentry>
<term>name</term>
@@ -4185,7 +4184,7 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
</varlistentry>
<varlistentry>
<term>url</term>
- <listitem><para>URL where the &pluginmap; can be found. Required.</para></listitem>
+ <listitem><para>&URL; where the &pluginmap; can be found. Required.</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
@@ -4215,7 +4214,7 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
</varlistentry>
<varlistentry>
<term>url</term>
- <listitem><para>URL where more information can be found. Optional, but recommended.</para></listitem>
+ <listitem><para>&URL; where more information can be found. Optional, but recommended.</para></listitem>
</varlistentry>
<varlistentry>
<term>copyright</term>
@@ -4223,7 +4222,7 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
</varlistentry>
<varlistentry>
<term>licence</term>
- <listitem><para>License specification, ⪚ "GPL" or "BSD". Please make sure to accompany your files with a complete copy of the relevant licence! Optional, but recommended.</para></listitem>
+ <listitem><para>License specification, ⪚ "GPL" or "BSD". Please make sure to accompany your files with a complete copy of the relevant licence. Optional, but recommended.</para></listitem>
</varlistentry>
<varlistentry>
<term>category</term>
@@ -4250,7 +4249,7 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
</varlistentry>
<varlistentry>
<term>url</term>
- <listitem><para>URL with more information on the author, ⪚ homepage (optional).</para></listitem>
+ <listitem><para>&URL; with more information on the author, ⪚ homepage (optional).</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
@@ -4276,7 +4275,7 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
</varlistentry>
<varlistentry>
<term>file</term>
- <listitem><para>Required at least for components of type="standard": The filename of the XML file describing the GUI.</para></listitem>
+ <listitem><para>Required at least for components of type="standard": The filename of the &XML; file describing the &GUI;.</para></listitem>
</varlistentry>
<varlistentry>
<term>label</term>
@@ -4422,19 +4421,19 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
</varlistentry>
<varlistentry>
<term><settings></term>
-<listitem><para>Defines the section containing reference on the various GUI settings. Only meaningful and only used for plugin related help pages. Use as a direct child of the <document>. May contain only <setting> and <caption> elements as direct children. No attributes.</para></listitem>
+<listitem><para>Defines the section containing reference on the various &GUI; settings. Only meaningful and only used for plugin related help pages. Use as a direct child of the <document>. May contain only <setting> and <caption> elements as direct children. No attributes.</para></listitem>
</varlistentry>
<varlistentry>
<term><setting></term>
-<listitem><para>Explains a single setting in the GUI. Only allowed as a direct child of the <settings> element. The text contained within the element is displayed.
+<listitem><para>Explains a single setting in the &GUI;. Only allowed as a direct child of the <settings> element. The text contained within the element is displayed.
<variablelist>
<varlistentry>
<term>id</term>
- <listitem><para>The ID of the setting in the plugin .xml. Required, no default.</para></listitem>
+ <listitem><para>The ID of the setting in the plugin <literal role="extension">.xml</literal>. Required, no default.</para></listitem>
</varlistentry>
<varlistentry>
<term>title</term>
- <listitem><para>An optional title for the setting. If omitted (omission is recommended in most cases), the title will be taken from the plugin .xml.</para></listitem>
+ <listitem><para>An optional title for the setting. If omitted (omission is recommended in most cases), the title will be taken from the plugin <literal role="extension">.xml</literal>.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
@@ -4444,17 +4443,17 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
<variablelist>
<varlistentry>
<term>id</term>
- <listitem><para>The ID of the corresponding element (typically a <frame>, <page> or <tab>) in the plugin .xml.</para></listitem>
+ <listitem><para>The ID of the corresponding element (typically a <frame>, <page> or <tab>) in the plugin <literal role="extension">.xml</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<term>title</term>
- <listitem><para>An optional title for the caption. If omitted (omission is recommended in most cases), the title will be taken from the plugin .xml.</para></listitem>
+ <listitem><para>An optional title for the caption. If omitted (omission is recommended in most cases), the title will be taken from the plugin <literal role="extension">.xml</literal>.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><related></term>
-<listitem><para>Defines a section containing links to further related information. Will always be displayed after the <settings> section. No attributes. The text contained within the <related> tag will be displayed. Typically this will contain an HTML-style list. Recommended for plugin help pages, but not required. May only be defined once, as a direct child of the <document> node.</para></listitem>
+<listitem><para>Defines a section containing links to further related information. Will always be displayed after the <settings> section. No attributes. The text contained within the <related> tag will be displayed. Typically this will contain an style list. Recommended for plugin help pages, but not required. May only be defined once, as a direct child of the <document> node.</para></listitem>
</varlistentry>
<varlistentry>
<term><technical></term>
@@ -4466,7 +4465,7 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
<variablelist>
<varlistentry>
<term>href</term>
- <listitem><para>The target url. Note that several rkward specific URLs are available. See <link linkend="pluginhelp">section on writing help pages</link> for details.</para></listitem>
+ <listitem><para>The target &URL;. Note that several &rkward; specific &URL;s are available. See <link linkend="pluginhelp">section on writing help pages</link> for details.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
@@ -4481,13 +4480,13 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
-<term><various html tags></term>
-<listitem><para>Most basic html tags are allowed within the sections. Please keep manual formatting to a minimum, however.</para></listitem>
+<term><various &HTML; tags></term>
+<listitem><para>Most basic &HTML; tags are allowed within the sections. Please keep manual formatting to a minimum, however.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
-<sect1 id="guilogic_functions"><title>Functions available for GUI logic scripting</title>
+<sect1 id="guilogic_functions"><title>Functions available for &GUI; logic scripting</title>
<variablelist>
<varlistentry><term>Class "Component"</term>
<listitem><para>Class which represents a single component or component-property. The most important instance of this class is the variable "gui" which is predefined as the root property of the current component. The following methods are available for instances of class "Component":
@@ -4503,7 +4502,7 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
</variablelist></para></listitem>
</varlistentry>
<varlistentry><term>Class "RObject"</term>
-<listitem><para>Class which represents a single &r; object. An instance of this class can be obtained by using <command>makeRObject(objectname)</command>. The following methods are available for instances of class "RObject": <warning><para>If any commands are still pending in the backend, the information provided by these methods can be out-of-date by the time that the plugin code is run. Do <emphasis>not</emphasis> rely on it for critical operations (risking loss of data).</para></warning>
+<listitem><para>Class which represents a single &R; object. An instance of this class can be obtained by using <command>makeRObject(objectname)</command>. The following methods are available for instances of class "RObject": <warning><para>If any commands are still pending in the backend, the information provided by these methods can be out-of-date by the time that the plugin code is run. Do <emphasis>not</emphasis> rely on it for critical operations (risking loss of data).</para></warning>
<variablelist>
<varlistentry><term>getName()</term><listitem><para>Returns the absolute name of the object.</para></listitem></varlistentry>
<varlistentry><term>exists()</term><listitem><para>Returns whether the object exists. You should generally check this before using any of the methods listed below.</para></listitem></varlistentry>
@@ -4530,7 +4529,7 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
<listitem><para><command>include(filename)</command> can be used to include a separate JS file.</para></listitem>
</varlistentry>
<varlistentry><term>doRCommand()-function</term>
-<listitem><para><command>doRCommand(command, callback)</command> can be used to query &r; for information. Please read the section on <link linkend="querying_r_for_info">querying &r; from inside a plugin</link> for details, and caveats.</para></listitem>
+<listitem><para><command>doRCommand(command, callback)</command> can be used to query &R; for information. Please read the section on <link linkend="querying_r_for_info">querying &R; from inside a plugin</link> for details, and caveats.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
@@ -4540,13 +4539,13 @@ different types, using modifiers may lead to errors. For <replaceable>fixed_valu
<appendix id="troubleshooting">
<title>Troubleshooting during plugin development</title>
<para>
- So you've read all the documentation, did everything right, and still cannot get it to work? Don't worry, we'll work it out. First thing to do is: Activate <guilabel>&rkward; Debug Messages</guilabel> - window (available from the <guimenu>Windows</guimenu> - menu, or right click on one of the tool bars), and then start your plugin, again. As a general rule of thumb, you should not see any output in the messages window when your plugin gets invoked, or at any other time. If there is one, it's likely related to your plugin. See if it helps you.
+ So you have read all the documentation, did everything right, and still cannot get it to work? Do not worry, we will work it out. First thing to do is: Activate <guilabel>&rkward; Debug Messages</guilabel> - window (available from the <guimenu>Windows</guimenu> - menu, or right click on one of the tool bars), and then start your plugin, again. As a general rule of thumb, you should not see any output in the messages window when your plugin gets invoked, or at any other time. If there is one, it is likely related to your plugin. See if it helps you.
</para>
<para>
If everything seems fine on the console, try to increase the debug-level (from the command line, using <command>rkward --debug-level 3</command>, or by setting debug level to 3 in <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure &rkward;</guimenuitem> <guimenuitem>Debug</guimenuitem></menuchoice>). Not all messages shown at higher debug levels necessarily indicate a problem, but chance are, your problem shows up somewhere between the messages.
</para>
<para>
-If you still cannot find out what's wrong, don't despair. We know this is complicated stuff, and - after all - possibly you've also come across a bug in &rkward;, and &rkward; needs to be fixed. Just write to the development mailing list, and tell us about the problem. We'll be happy to help you.
+If you still cannot find out what is wrong, do not despair. We know this is complicated stuff, and - after all - possibly you have also come across a bug in &rkward;, and &rkward; needs to be fixed. Just write to the development mailing list, and tell us about the problem. We will be happy to help you.
</para>
<para>
Finally, even if you found out how to do it on your own, but found the documentation to be not-so-helpful or even wrong in some respects, please tell us on the mailing list as well, so we can fix/improve the documentation.
More information about the kde-doc-english
mailing list