[rkward-cvs] SF.net SVN: rkward:[3936] trunk/rkward/doc/rkwardplugins/index.docbook
m-eik at users.sourceforge.net
m-eik at users.sourceforge.net
Wed Oct 12 13:02:58 UTC 2011
Revision: 3936
http://rkward.svn.sourceforge.net/rkward/?rev=3936&view=rev
Author: m-eik
Date: 2011-10-12 13:02:57 +0000 (Wed, 12 Oct 2011)
Log Message:
-----------
markup in writing plugins docs
Modified Paths:
--------------
trunk/rkward/doc/rkwardplugins/index.docbook
Modified: trunk/rkward/doc/rkwardplugins/index.docbook
===================================================================
--- trunk/rkward/doc/rkwardplugins/index.docbook 2011-10-12 10:32:34 UTC (rev 3935)
+++ trunk/rkward/doc/rkwardplugins/index.docbook 2011-10-12 13:02:57 UTC (rev 3936)
@@ -53,7 +53,7 @@
and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>
-<date>2011-09-20</date>
+<date>2011-10-12</date>
<releaseinfo>0.5.7.00</releaseinfo>
<abstract>
@@ -75,22 +75,22 @@
<title>Introduction</title>
<para>
-Documentation as of &kapp; release 0.5.7.
+Documentation as of &rkward; release 0.5.7.
</para>
<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 it 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.
</para>
<para>
-For questions and comments, please write to the &kapp; development mailing list.
+For questions and comments, please write to the &rkward; development mailing list.
</para>
<para>
-<emphasis>You do not need to read this in order to use &kapp;.</emphasis> This document is about extending &kapp;. It is targeted at advanced users, or people willing to help improve &kapp;.
+<emphasis>You do not need to read this in order to use &rkward;.</emphasis> This document is about extending &rkward;. It is targeted at advanced users, or people willing to help improve &rkward;.
</para>
<para>
Writing a standard plugin is basically a four-step process:
<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="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="pluginhelp">Adding a help page to your plugin</link></para></listitem>
</itemizedlist>
@@ -110,15 +110,15 @@
</chapter>
<chapter id="whatareplugins">
-<title>Preliminaries: What are plugins in &kapp;? How do they work?</title>
+<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 &kapp; 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 Settings->Configure &kapp;->Plugins, 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 <literal role="extension">.pluginmap</literal> 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.
</para>
<para>
-The basic paradigm behind &kapp; 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'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.
</para>
<para>
Read on in the next chapters to see how this is done.
@@ -128,9 +128,9 @@
<chapter id="pluginmap">
<title>Creating menu entries</title>
<para>
-When you create a new plugin, you need to tell &kapp; 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 &kapp; configured to load your pluginmap – Settings->Configure &kapp;->Plugins):
+When you create a new plugin, you need to tell &rkward; about it. So the first thing to do, is to write a <literal role="extension">.pluginmap</literal> file (or modify an existing one). The format of <literal role="extension">.pluginmap</literal> 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>):
</para>
-<tip><para>After reading this chapter, have a look at the <link linkend="rkwarddev"><quote>rkwarddev</quote> package</link> as well. It provides some R functions to create most of RKWard's XML tags for you.</para></tip>
+<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.</para></tip>
<programlisting>
<!DOCTYPE rkpluginmap>
</programlisting>
@@ -147,16 +147,16 @@
<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 &kapp;. Let's look at an example entry:
+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:
</para>
<programlisting>
<component type="standard" id="independent_samples_t_test" file="means/ttests/independent_samples.xml" label="Independent Samples" />
</programlisting>
<para>
- First the <parameter>type</parameter>-attribute: Leave this to <quote>standard</quote> for now. Further types are not yet implemented. The <parameter>id</parameter> I'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 whereever 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 <quote>standard</quote> for now. Further types are not yet implemented. The <parameter>id</parameter> I'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 <literal role="extension">.pluginmap</literal> file is in, and the <parameter>base_prefix</parameter> above. Finally, give the component a label. This label will be shown whereever 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:
+Typically a <literal role="extension">.pluginmap</literal> file will contain several components, so here are a few more:
</para>
<programlisting>
<component type="standard" id="unimplemented_test" file="means/unimplemented.xml" />
@@ -167,27 +167,27 @@
</components>
</programlisting>
<para>
-Ok, this was the first step. &kapp; 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" index="4">
</programlisting>
<para>
- Right below the <hierarchy>-tag, you start describing, in which menu, your plugins should go. With the above line, you basically say, that your plugin should be in the <quote>Analysis</quote> menu (not necessarily directly there, but in a submenu). The <quote>Analysis</quote> menu is standard in &kapp;, so it does not actually have to be created from scratch. However, if it did not exist yet, using the <parameter>label</parameter> attribute you'd give it its name. The <parameter>index</parameter> attribute says, that the menu (if newly created) should be placed at the fourth position in the menubar.
- Finally, the <parameter>id</parameter> once again identifies this menu. This is needed, so several .pluginmap-files can place their plugins in the same menus. They do this by looking for a menu with the given <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.
+ Right below the <hierarchy> tag, you start describing, in which menu, your plugins should go. With the above line, you basically say, that your plugin should be in the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu (not necessarily directly there, but in a submenu). The <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu is standard in &rkward;, so it does not actually have to be created from scratch. However, if it did not exist yet, using the <parameter>label</parameter> attribute you'd give it its name. The <parameter>index</parameter> attribute says, that the menu (if newly created) should be placed at the fourth position in the menubar.
+ Finally, the <parameter>id</parameter> once again identifies this menu. This is needed, so several <literal role="extension">.pluginmap</literal> files can place their plugins in the same menus. They do this by looking for a menu with the given <parameter>id</parameter>. If the id does not yet exist, a new menu will be created. Otherwise the entries will be added to the existing menu.
</para>
<programlisting>
<menu id="means" label="Means" index="1">
</programlisting>
<para>
-Basically the same thing here: Now we define a submenu to the <quote>Analysis</quote> menu. It is to be called <quote>Means</quote>.
+Basically the same thing here: Now we define a submenu to the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu. It is to be called <menuchoice><guimenuitem>Means</guimenuitem></menuchoice>.
</para>
<programlisting>
<menu id="ttests" label="T-Tests">
</programlisting>
<para>
- And a final level in the menu-hierarchy: A sub-menu of the sub-menu <quote>Means</quote>. Note, that if you omit the <parameter>index</parameter> parameter, the new entry will be placed below any already existing ones.
+ And a final level in the menu-hierarchy: A sub-menu of the sub-menu <menuchoice><guimenuitem>Means</guimenuitem></menuchoice>. Note, that if you omit the <parameter>index</parameter> parameter, the new entry will be placed below any already existing ones.
</para>
<programlisting>
<entry component="independent_samples_t_test" />
@@ -203,7 +203,7 @@
<menu id="frequency" label="Frequency" index="2"/>
</programlisting>
<para>
-In case you have lost track: This is another submenu to the <quote>Analysis</quote> 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'll skip some of what's not visible, marked with [...].
</para>
<programlisting>
[...]
@@ -222,7 +222,7 @@
</menu>
</programlisting>
<para>
-Of course you can also place your plugins in menus other than <quote>Analysis</quote>.
+Of course you can also place your plugins in menus other than <menuchoice><guimenu>Analysis</guimenu></menuchoice>.
</para>
<programlisting>
<menu id="file" label="File" index="0">
@@ -230,7 +230,7 @@
</menu>
</programlisting>
<para>
- Even in standard-menus such as <quote>File</quote>. All you need is the correct <parameter>id</parameter>.
+ Even in standard-menus such as <menuchoice><guimenu>File</guimenu></menuchoice>. All you need is the correct <parameter>id</parameter>.
</para>
<programlisting>
</hierarchy>
@@ -251,16 +251,16 @@
</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 <literal role="extension">.pluginmap</literal> files shipped with the distribution, and modifying them to your needs. Also, if you need help, don't hesitate to write to the development mailing list.
</para>
</chapter>
<chapter id="mainxml">
<title>Defining the GUI</title>
<para>
-In the <link linkend="pluginmap">previous chapter</link> you've seen how to register a plugin with &kapp;. 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'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.
</para>
-<tip><para>After reading this chapter, have a look at the <link linkend="rkwarddev"><quote>rkwarddev</quote> package</link> as well. It provides some R functions to create most of RKWard's XML tags for you.</para></tip>
+<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.</para></tip>
<para>
Once again we'll walk you through an example. The example is a (slightly simplified) version of the independent samples t-Test.
</para>
@@ -275,7 +275,7 @@
<code file="t_test.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.rkh"/>
@@ -306,7 +306,7 @@
<varselector id="vars"/>
</programlisting>
<para>
-Using this simple tag you create a list from which the user can select variables. You have to specify an id for this element, so RKWard knows how to find it. Note that you may NOT use a dot (.) in the <parameter>id</parameter> string.
+Using this simple tag you create a list from which the user can select variables. You have to specify an id for this element, so &rkward; knows how to find it. Note that you may NOT use a dot (.) in the <parameter>id</parameter> string.
</para>
<programlisting>
<column>
@@ -319,7 +319,7 @@
<varslot types="number" id="y" source="vars" required="true" label="against"/>
</programlisting>
<para>
- These elements are the counterpart to the <varselector>. They represent <quote>slots</quote> into which the user can put variables. You will note that the <parameter>source</parameter> is set to the same value as the <parameter>id</parameter> of the <varselector>. This means, the <varslot>s will each take their variables from the varselector. The <varslot>s also have to be given an <parameter>id</parameter>. They may have a label, and they may be set to <quote>required</quote>. This means that the <quote>submit</quote> button will not be enabled until the <varslot> holds a valid value. Finally the <parameter>type</parameter> attribute is not interpreted, yet, but it will be used to take care that only the correct types of variables will be allowed in the <varslot>.
+ These elements are the counterpart to the <varselector>. They represent <quote>slots</quote> into which the user can put variables. You will note that the <parameter>source</parameter> is set to the same value as the <parameter>id</parameter> of the <varselector>. This means, the <varslot>s will each take their variables from the varselector. The <varslot>s also have to be given an <parameter>id</parameter>. They may have a label, and they may be set to <quote>required</quote>. This means that the <guibutton>Submit</guibutton> button will not be enabled until the <varslot> holds a valid value. Finally the <parameter>type</parameter> attribute is not interpreted, yet, but it will be used to take care that only the correct types of variables will be allowed in the <varslot>.
</para>
<programlisting>
<radio id="hypothesis" label="using test hypothesis">
@@ -351,7 +351,7 @@
</mediaobject>
</screenshot>
<para>
- Note that we have not specified the <quote>Submit</quote>, <quote>Close</quote>, etc. buttons or the code-view. Those elements get generated automatically. But of course we still have to define the second page of the <tabbook>:
+ Note that we have not specified the <guibutton>Submit</guibutton>, <guibutton>Close</guibutton>, etc. buttons or the code-view. Those elements get generated automatically. But of course we still have to define the second page of the <tabbook>:
</para>
<programlisting>
<tab label="Options">
@@ -372,7 +372,7 @@
</frame>
</programlisting>
<para>
- Inside the <frame> we place another <checkbox> (using <markup>checked="true"</markup>, we signal that checkbox should be checked by default), and a <spinbox>. The spinbox allows the user to select a value between <quote>min</quote> and <quote>max</quote> with the default/initial value <quote>0.95</quote>. Setting the <parameter>type</parameter> to <quote>real</quote> signals that real numbers are accepted as opposed to <parameter>type=</parameter><markup>"integer"</markup> which would accept integers only.
+ Inside the <frame> we place another <checkbox> (using <parameter>checked</parameter>=<replaceable>"true"</replaceable>, we signal that checkbox should be checked by default), and a <spinbox>. The spinbox allows the user to select a value between <replaceable>"min"</replaceable> and <replaceable>"max"</replaceable> with the default/initial value <replaceable>"0.95"</replaceable>. Setting the <parameter>type</parameter> to <replaceable>"real"</replaceable> signals that real numbers are accepted as opposed to <parameter>type</parameter>=<replaceable>"integer"</replaceable> which would accept integers only.
</para>
<note><para>
It is also possible, and often preferrable, to make the <frame> itself checkable, instead of adding a <checkbox> inside. See the reference for details. This is not done, here, for illustrational purposes.
@@ -390,7 +390,7 @@
</programlisting>
<para>
Finally we close the <document>-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? I'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.
+But how does &r; syntax get generated from the GUI-settings? I'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.
</para>
<sect1 id="wizard_interface">
@@ -424,7 +424,7 @@
Much of the same thing here. We add some texts, and in between that <copy> further sections from the dialog interface.
</para>
<para>
- You may of course make the wizard interface look very different to the plain dialog, and not use the <copy> tag at all. Be sure, however, to assign corresponding elements the same <parameter>id</parameter> in both interfaces. This is not only used to transfer settings from the dialog interface to the wizard-interface and back, when the user switches interfaces (which does not yet happen in the current version of RKWard), but also simplifies writing your code-template (see below).
+ You may of course make the wizard interface look very different to the plain dialog, and not use the <copy> tag at all. Be sure, however, to assign corresponding elements the same <parameter>id</parameter> in both interfaces. This is not only used to transfer settings from the dialog interface to the wizard-interface and back, when the user switches interfaces (which does not yet happen in the current version of &rkward;), but also simplifies writing your code-template (see below).
</para>
</sect1>
@@ -452,18 +452,18 @@
<chapter id="jstemplate">
<title>Generating R code from GUI settings</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, <quote>code.js</quote>, located in the same directory as the <link linkend="mainxml">description.xml</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 (e.g.: <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 (e.g.: <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.
</para>
-<tip><para>After reading this chapter, have a look at the <link linkend="rkwarddev"><quote>rkwarddev</quote> package</link> as well. It provides some R functions to create JavaScript code commonly used in RKWard. For instance, it can autodetect variables used in a plugin XML file and create basic JavaScript code from that for you to start with.</para></tip>
+<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;. For instance, it can autodetect variables used in a plugin XML file and create basic JavaScript code from that for you to start with.</para></tip>
<para>
-For the independent samples t-test, the code.js file looks as follows (with comments in between):
+For the independent samples t-test, the <filename>code.js</filename> file looks as follows (with comments in between):
</para>
<programlisting>
function preprocess () {
}
</programlisting>
<para>
-The JS-file is organized into three separate functions: preprocess, calculate, and printout. This is because not all code is needed at all stages. Currently the preprocess-function is not really used in many places (typically you will omit it altogether).
+The JS file is organized into three separate functions: <function>preprocess()</function>, <function>calculate()</function>, and <function>printout()</function>. This is because not all code is needed at all stages. Currently the preprocess-function is not really used in many places (typically you will omit it altogether).
</para>
<programlisting>
function calculate () {
@@ -475,7 +475,7 @@
</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
+ 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 (
@@ -518,13 +518,13 @@
<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 explicitely asks for a variable to be saved, you will need to assign to that object using <quote>.GlobalEnv$objectname <- value</quote>. In general, do not use the <quote><<-</quote> operator. It will not necessarily assign in .GlobalEnv.
@@ -537,10 +537,10 @@
<sect2 id="policyformatting">
<title>Code formatting</title>
<para>
-The most important thing is for your generated R code to work. But please also keep an eye on formatting. Some considerations:
+The most important thing is for your generated &r; code to work. But 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).
@@ -615,9 +615,9 @@
<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"><quote>rkwarddev</quote> 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.</para></tip>
+ <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.</para></tip>
<para>
You may recall putting this inside your plugin-xml (if you haven't put this in, do so now):
</para>
@@ -629,7 +629,7 @@
</document>
</programlisting>
<para>
- Where, obviously, you'd replace <quote>filename</quote> with a more appropriate name. Now it's time to create this .rkh file. Here is a self-descriptive example:
+ 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:
</para>
<programlisting>
<!DOCTYPE rkhelp>
@@ -728,7 +728,7 @@
<chapter id="logic">
<title>GUI logic</title>
<para>
-All the basic concepts of creating a plugin for &kapp; 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:
@@ -775,13 +775,13 @@
</programlisting>
</para>
<para>
-The first two lines inside the logic section are <conver> tags. Those basically provide two new boolean (on or off, true or false) properties, which can be used later on. The first property (<quote>varmode</quote>) is true, whenever the upper radio-button is selected and the second whenever the lower radio-button is selected. How is this done?
+The first two lines inside the logic section are <conver> tags. Those basically provide two new boolean (on or off, true or false) properties, which can be used later on. The first property (<quote>varmode</quote>) is true, whenever the upper radio button is selected and the second 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><markup>"mode.string;somethingelse"</markup>, then <quote>varmode</quote> would only be true, if both <quote>mode.string</quote> and <quote>somethingelse</quote> are equal to the string <quote>variable</quote>). Note that in this case we don't just write <quote>mode</quote> (as we would in <function>getValue("mode")</function>, but <quote>mode.string</quote>. This is actually the internal way a radio control works: It has a property <quote>string</quote>, which holds its string value. <function>getValue("mode")</function> is just a shorthand, and equivalent to <function>getValue("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 <quote>varmode</quote> would only be true, if both <quote>mode.string</quote> and <quote>somethingelse</quote> are equal to the string <quote>variable</quote>). Note that in this case we don't just write <quote>mode</quote> (as we would in <function>getValue("mode")</function>, but <quote>mode.string</quote>. This is actually the internal way a radio control works: It has a property <quote>string</quote>, which holds its string value. <function>getValue("mode")</function> is just a shorthand, and equivalent to <function>getValue("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><markup>"equals"</markup>. This means, we want to check, whether the sources are equal to a certain value. Finally standard is the value to compare against, so with <parameter>standard=</parameter><markup>"variable"</markup>, we check whether the property <quote>mode.string</quote> is equal to the string <quote>variable</quote> (the value of the upper radio option). If it is equal, then the property varmode is true, else it is false.
+ Second, we set the mode of conversion to <parameter>mode</parameter>=<replaceable>"equals"</replaceable>. This means, we want to check, whether the sources 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 <quote>mode.string</quote> is equal to the string <quote>variable</quote> (the value of the upper radio option). If it is equal, then the property varmode is true, else it is false.
</para>
<para>
The next line is basically the same, but reversed. Here we define a property (<quote>constmode</quote>) which becomes true, if the second radio option is selected.
@@ -827,7 +827,7 @@
[...]
</programlisting>
<para>
-The first line of code tells RKWard to call the function <function>modeChanged()</function> whenever the value of the <quote>mode</quote> radio-box changes. Inside this function, we define a helper-variable <quote>varmode</quote> which is true when the mode is <quote>variable</quote>, false is it is <quote>constant</quote>. Then we use <function>gui.setValue()</function> to set the and <quote>enabled</quote>-properties of <quote>y</quote> and <quote>constant</quote>, in just the same way as we did using <connect>-statements, before.</para>
+The first line of code tells &rkward; to call the function <function>modeChanged()</function> whenever the value of the <quote>mode</quote> radio-box changes. Inside this function, we define a helper-variable <quote>varmode</quote> which is true when the mode is <quote>variable</quote>, false is it is <quote>constant</quote>. Then we use <function>gui.setValue()</function> to set the and <quote>enabled</quote>-properties of <quote>y</quote> and <quote>constant</quote>, in just the same way as we did using <connect>-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.
</para>
@@ -840,7 +840,7 @@
<chapter id="embedding">
<title>Embedding Plugins into Plugins</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'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?
</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.
@@ -866,7 +866,7 @@
</dialog>
</programlisting>
<para>
-What happens here, is that the entire GUI or the plot options plugin (except of course for the standard elements like submit-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 <embed>-tag is fairly simple. It takes an id as most elements. The parameter component specifies which plugin to embed, as defined in the <link linkend="pluginmap">.pluginmap</link> file (<quote>rkward::plot_options</quote> is the result of concatenating the namespace <quote>rkward</quote>, a separator <quote>::</quote>, and the name of the component <quote>plot_options</quote>).
@@ -911,7 +911,7 @@
</para>
</sect1>
<sect1 id="embedding_as_button">
-<title>Less embedded embedding: Further options button</title>
+<title>Less embedded embedding: Further <guibutton>Options</guibutton> 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.
</para>
@@ -931,10 +931,10 @@
</dialog>
</programlisting>
<para>
-In this case, a single push button will be added to your plugin, labelled <quote>Specify plotting options</quote>. 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, labelled <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>
-<emphasis>Caution:</emphasis> Probably the <quote>button</quote> approach should only ever be used for plugins that can never be invalid (for missing/bad settings). Otherwise the user would not be able to submit the code, but might have a hard time finding out, the reason for that is hidden behind some button.
+ <caution><remark>Probably the <quote>button</quote> approach should only ever be used for plugins that can never be invalid (for missing/bad settings). Otherwise the user would not be able to submit the code, but might have a hard time finding out, the reason for that is hidden behind some button.</remark></caution>
</para>
</sect1>
<sect1 id="embedding_incomplete">
@@ -982,10 +982,10 @@
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.
</para>
<para>
-The naive approach to this is to develop one plugin, then basically copy and paste the entire contents of the .js, .xml, and .rkh 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'd 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 .js files</link> <link linkend="include_xml">including .xml 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 preferrable to use embedding</link>).
+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 preferrable to use embedding</link>).
</para>
<para>
One word of caution, before you begin reading, though: These concepts can help making it simpler to deal with many similar plugins, and can improve maintainability and readability of those plugins. However, overdoing it can easily lead to the reverse effect. Use with some caution.
@@ -993,7 +993,7 @@
<sect1 id="include_js">
<title>Using the JS include statement</title>
<para>
-You can easily include one script file into another in &kapp; plugins. The value of this becomes immediately obvious, if some sections of your JS code are similar across plugins. You can simply define those sections in a separate .js file, and include this in all the plugin .js files. For example, as in:
+You can easily include one script file into another in &rkward; plugins. The value of this becomes immediately obvious, if some sections of your JS code are similar across plugins. You can simply define those sections in a separate <literal role="extension">.js</literal> file, and include this in all the plugin <literal role="extension">.js</literal> files. For example, as in:
</para>
<programlisting>
// this is a file called "common_functions.js"
@@ -1006,7 +1006,7 @@
}
</programlisting>
<programlisting>
-// this is one of your regular plugin .js files
+// this is one of your regular plugin <literal role="extension">.js</literal> files
// include the common functions
include ("common_functions.js");
@@ -1036,7 +1036,7 @@
}
</programlisting>
<programlisting>
-// this is one of your regular plugin .js files
+// this is one of your regular plugin <literal role="extension">.js</literal> files
// include the common functions
include ("common_functions.js");
@@ -1057,9 +1057,9 @@
</sect1>
<sect1 id="include_xml">
- <title>Including .xml files</title>
+ <title>Including <literal role="extension">.xml</literal> files</title>
<para>
-Basically the same feature of including files is also available for use in the .xml and .rkh files. At any place in these files you can place an <include> tag as shown below. The effect is that the entire contents of that XML file (to be precise: everything within the <document> 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> and <literal role="extension">.rkh</literal> files. At any place in these files you can place an <include> tag as shown below. The effect is that the entire contents of that XML file (to be precise: everything within the <document> 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>
@@ -1099,10 +1099,10 @@
</document>
</programlisting>
<para>
-Hence, you define the snippet at one place at the top of the xml file, and then you <insert> 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 <insert> it at any place(s) you wish.
</para>
<para>
-While this example is not too useful in itself, think about combining this with an <include>d .xml file. Note that you can also place snippets for the .rkh file in the same file. You'd simply <include> the file there as well, and <insert> the relevant snippet:
+While this example is not too useful in itself, think about combining this with an <include>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 <include> the file there as well, and <insert> the relevant snippet:
</para>
<programlisting>
<!-- This is a file called "common_snippets.xml" -->
@@ -1181,7 +1181,7 @@
At first glance, <include> and <snippets> 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?
</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.
@@ -1268,7 +1268,7 @@
<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 <hierarchy> but rather into a <context> 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.
@@ -1319,7 +1319,7 @@
Before reading this section, please make sure to read the section on the <link linkend="context_x11">X11 device context</link>, as that explains the basic concepts.
</para>
<para>
- The <quote>import</quote> context is used to declare import file filter plugins. You simply place those in a context with <parameter>id=</parameter><markup>"import"</markup> in the .pluginmap file. However, there is one additional twist when declaring these plugins: In order to offer a unified file selection dialog for all supported file types, you need to declare one additional bit of information on your component:
+ The <quote>import</quote> context is used to declare import file filter plugins. You simply place those in a context with <parameter>id</parameter>=<replaceable>"import"</replaceable> in the <literal role="extension">.pluginmap</literal> file. However, there is one additional twist when declaring these plugins: In order to offer a unified file selection dialog for all supported file types, you need to declare one additional bit of information on your component:
</para>
<programlisting>
<document [...]>
@@ -1362,14 +1362,14 @@
<chapter id="external_plugins">
<title>External plugins</title>
- <para>As of version 0.5.5, &kapp; 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 &kapp;. </para>
- <para>This section of the documentation describes how external plugins are to be packaged, so that &kapp; 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. </para>
+ <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;. </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. </para>
<para>Since external plugins are a relatively young feature, details of this might probably change in future releases. You’re welcome to contribute your ideas to improve the process. </para>
- <tip><para>These docs explain the details of external plugins so you can learn how they work. In addition to that, also have a look at the <link linkend="rkwarddev"><quote>rkwarddev</quote> package</link>, which was designed to automate a lot of the writing process. </para></tip>
+ <tip><para>These docs explain the details of external plugins so you can learn how they work. In addition to that, also have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link>, which was designed to automate a lot of the writing process. </para></tip>
<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 &kapp; quite modular as well. </para>
+ <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. </para>
<para>As a rule of thumb, plugins that seem to serve a widely used purpose (e.g. 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. </para>
</sect1>
@@ -1403,12 +1403,12 @@
DESCRIPTION
</programlisting>
<note><para> In this example, all occasions of <token>plugin_name</token>, <token>testsuite_name</token> and <token>sometest_name</token> are to be replaced with their correct names, accordingly.</para></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"><quote>rkwarddev</quote> package</link>, it will automatically create all necessary files and directories for you.</para></tip>
+ <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.</para></tip>
<sect3 id="basic_plugin_components">
<title>Basic plugin components</title>
- <para>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 DESCRIPTION file, which is also crucial for &kapp; recognizing it as a plugin provider. Most of the information it carries is also needed in the plugin <link linkend="meta-information">Meta-information</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 DESCRIPTION file in detail</ulink>).</para>
- <para>In addition to the general contents of a DESCRIPTIONS file, make sure to also include the line <quote>Enhances: rkward</quote>. This will cause &kapp; to automatically scan the package for plugins if it is installed. An example DESCRIPTION file looks like this:</para>
+ <para>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 <literal role="extension">.pluginmap</literal> 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="meta-information">Meta-information</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:</para>
<programlisting>
Package: SquaretheCircle
Type: Package
@@ -1427,16 +1427,16 @@
person(given="A.", family="Assistant", role=c("cre",
"ctb"), email="alterego at eternalwondermaths.example.org"))
</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"><quote>rkwarddev</quote> package</link> and provide all necessary information via the <quote>about</quote> option, it will automatically create a working DESCRIPTION file for you.</para></tip>
+ <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.</para></tip>
</sect3>
<sect3 id="additional_information">
<title>Additional information (optional)</title>
- <para>ChangeLog, README, AUTHORS, LICENSE should be self-explaining and are entirely optional. Actually, they won’t be interpreted by &kapp;, so they are rather meant to carry additional information that might be relevant e.g. for distributors. Most of their relevant content (author credits, licence terms etc.) will be included in the actual plugin files anyway, though (see the <link linkend="meta-information">section on meta-information</link>). Note that all of these files could also be placed somewhere in the "inst" directory, if you want them not only to be present in the source archive but the installed package as well. </para>
+ <para><filename>ChangeLog</filename>, <filename>README</filename>, <filename>AUTHORS</filename>, <filename>LICENSE</filename> should be self-explaining and are entirely optional. Actually, they won’t be interpreted by &rkward;, so they are rather meant to carry additional information that might be relevant e.g. for distributors. Most of their relevant content (author credits, licence terms etc.) will be included in the actual plugin files anyway, though (see the <link linkend="meta-information">section on meta-information</link>). Note that all of these files could also be placed somewhere in the "inst" directory, if you want them not only to be present in the source archive but the installed package as well. </para>
</sect3>
<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 &kapp;. 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 <quote>tests</quote>, which includes a file <quote>testsuite.R</quote> 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 <quote>testsuite.R</quote> file, you can split them in e.g. one file for each test suite and create one <quote>testsuite.R</quote> with <function>source()</function> calls for each suite file. In either case, create separate subdirectories with test standards for each defined suite. </para>
+ <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 <quote>tests</quote>, which includes a file <quote>testsuite.R</quote> 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 <quote>testsuite.R</quote> file, you can split them in e.g. one file for each test suite and create one <quote>testsuite.R</quote> with <function>source()</function> calls for each suite file. In either case, create separate subdirectories with test standards for each defined suite. </para>
<para>The benefits of upholding to this structure is that plugin tests can be run simply by calling <function>rktests.makplugintests()</function> from the "rkwardtests" package without additional arguments. Have a look at the online documentation on <ulink url="http://sourceforge.net/apps/mediawiki/rkward/index.php?title=Automated_Plugin_Testing">Automated Plugin Testing</ulink> for further details. </para>
</sect3>
</sect2>
@@ -1444,8 +1444,8 @@
<sect1 id="meta-information">
<title>Meta-information</title>
- <para>Each plugin archive should provide some basic meta-information on what it deals with, where to find more information, who maintains it, if it relies on specific R packages or other plugins, etc. </para>
- <para>This information is given at least once in your .pluginmap, and can then be included or overwritten in each plugin .xml file (which might be useful if that particular plugin file was contributed by someone else, for instance). </para>
+ <para>Each plugin archive should provide some basic meta-information on what it deals with, where to find more information, who maintains it, if it relies on specific &r; packages or other plugins, etc. </para>
+ <para>This information is given at least once in your <literal role="extension">.pluginmap</literal>, and can then be included or overwritten in each plugin <literal role="extension">.xml</literal> file (which might be useful if that particular plugin file was contributed by someone else, for instance). </para>
<para>To achieve this, the <about> tag is used. The overall structure of this tag looks something like this: </para>
<programlisting>
<about>
@@ -1463,7 +1463,7 @@
</about>
</programlisting>
<para>That is, the <about> tag contains <author> and <dependencies>, and <dependencies> contains <package> and <pluginmap>. Each of these five tags knows in turn several further attributes (see below). </para>
- <para>As you can see, you can have more than one entry on authors, needed R packages and &kapp; pluginmaps. </para>
+ <para>As you can see, you can have more than one entry on authors, needed &r; packages and &rkward; pluginmaps. </para>
<para>A full-blown example would look like this: </para>
<programlisting>
<document
@@ -1533,17 +1533,17 @@
</hierarchy>
</document>
</programlisting>
- <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"><quote>rkwarddev</quote> package</link> and provide all necessary information via the <quote>about</quote> option, it will automatically create a .pluginmap file with a working <about> section for you.</para></tip>
+ <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 <quote>about</quote> option, it will automatically create a <literal role="extension">.pluginmap</literal> file with a working <about> section for you.</para></tip>
<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 <about> 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 <author> with a valid e-mail 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>
- <para>Actually the whole <dependencies> might be left empty if your plugin is supposed to run with any &kapp; version and standard R installation. But please be reasonable here as well. The inclusion of any <package> or <pluginmap> tags is of course optional as well, depending on the needs of your plugins. All the <parameter>min_version</parameter> and <parameter>max_version</parameter> information can be omitted, as well. They are obviously useful if your plugin is known to rely on certain versions of an R package, for instance. </para>
- <para>If you need an R package that is probably not hosted on an official CRAN mirror, you can specify a repository where it can be found in the <package> tag. &kapp; will check whether this repository is already defined in its configuration, and if not, add it, but only after the user has given its explicit permission to that. </para>
+ <para>Actually the whole <dependencies> might be left empty if your plugin is supposed to run with any &rkward; version and standard &r; installation. But please be reasonable here as well. The inclusion of any <package> or <pluginmap> tags is of course optional as well, depending on the needs of your plugins. All the <parameter>min_version</parameter> and <parameter>max_version</parameter> information can be omitted, as well. They are obviously useful if your plugin is known to rely on certain versions of an &r; package, for instance. </para>
+ <para>If you need an &r; package that is probably not hosted on an official CRAN mirror, you can specify a repository where it can be found in the <package> tag. &rkward; will check whether this repository is already defined in its configuration, and if not, add it, but only after the user has given its explicit permission to that. </para>
<para>The <parameter>id</parameter>" element in the <pluginmap> tag refers to the ID given in the top level <document> tag of the pluginmap that you need. </para>
</sect1>
<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 DESCRIPTION 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 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>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>
@@ -1551,43 +1551,43 @@
<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"><quote>rkwarddev</quote> package</link>, it will build and/or check your plugin package for you.</para></tip>
+ <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>
</sect1>
</chapter>
<chapter id="rkwarddev">
- <title>Plugin development with the <quote>rkwarddev</quote> package</title>
+ <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 <quote>rkwarddev</quote> 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://rkward.sourceforge.net/R/">RKWard's own repository</ulink>. You can either do that by using the GUI interface (Settings -> Configure packages), 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'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://rkward.sourceforge.net/R/">&rkward;'s own repository</ulink>. You can either do that by using the GUI interface (Settings -> Configure packages), or from any running &r; session:</para>
<programlisting>
install.packages("rkwarddev", repos="http://rkward.sf.net/R")
library(rkwarddev)
</programlisting>
- <para><quote>rkwarddev</quote> 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><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://rkward.sourceforge.net/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://rkward.sourceforge.net/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 <quote>rkwarddev</quote> 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'll 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 in the <quote>File</quote> menu, called <quote>RKWard Plugin Skeleton</quote>. Like the name suggests, you can create plugin skeletons for further editing with it. This dialog itself was in turn generated by an <quote>rkwarddev</quote> 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; in the <menuchoice><guimenu>File</guimenu></menuchoice> menu, called <quote>&rkward; Plugin Skeleton</quote>. 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 imediately notice that the workflow is considerably different: Contrary to writing the XML code directly, you do not begin with the <document> definition, but directly with the plugin elements you'd like to have in the dialog. You can assign each interface element -- be it checkboxes, 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 <varselector> and two <varslot> elements for the <quote>x</quote> and <quote>y</quote> variable of the t-test example can be done by:</para>
+ <para>You will imediately notice that the workflow is considerably different: Contrary to writing the XML code directly, you do not begin with the <document> definition, but directly with the plugin elements you'd like to have in the dialog. You can assign each interface element -- be it checkboxes, 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 <varselector> and two <varslot> elements for the <quote>x</quote> and <quote>y</quote> 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><markup>variables</markup>: 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 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>
<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>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>
@@ -1630,7 +1630,7 @@
</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)
@@ -1661,12 +1661,12 @@
</sect2>
<sect2 id="rkdev_jscode"><title>JavaScript code</title>
- <para>Until now, using the <quote>rkwarddev</quote> 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 <quote>rkwarddev</quote> 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 checkbox if you don't use its value or state afterwards. So we can start writing the actual R code generating JS immediately.</para>
+ <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 checkbox 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, e.g., 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 allways 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>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, e.g., 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 allways 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(
@@ -1678,7 +1678,7 @@
JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
</programlisting>
- <para>As you can see, <quote>rkwarddev</quote> 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 exatly 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>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 exatly 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 name <function>ite()</function> is an abbreviation for <quote>if, then, else</quote>, and these three conditional statements are exactly what its three optional arguments are for -- although our example only uses two, so we're dealing with three <quote>if, then</quote> conditions here. Maybe it's best to just look at the above <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 + "\"");
@@ -1719,8 +1719,8 @@
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><markup>TRUE</markup> will automatically add the new plugin to &kapp;s configuration (since it's in a temp dir and hence will cease to exist when &kapp; is closed, it will automatically be removed again by &kapp; during its next start), <parameter>edit=</parameter><markup>TRUE</markup> will open all created files for editing in &kapp; editor tabs, and <parameter>show=</parameter><markup>TRUE</markup> will attempt to directly launch the plugin, so you can examine what it looks like without a klick. You might consider adding <parameter>overwrite=</parameter><markup>TRUE</markup> if you're about to run your script repeatedly (e.g. 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 -- e.g. 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'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 klick. You might consider adding <parameter>overwrite</parameter>=<replaceable>TRUE</replaceable> if you're about to run your script repeatedly (e.g. 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 -- e.g. 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 objects will not be created in your global environment (except for <quote>plugin.dir</quote>):</para>
@@ -1838,7 +1838,7 @@
</varlistentry>
<varlistentry>
<term>RObject properties</term>
-<listitem><para>A property designed a selection of one or more R objects. Used most porminently 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 porminently in varselectors and varslots. The following values will be returned according to the given modifier:
<variablelist>
<varlistentry>
<term>No modifier ("")</term>
@@ -1850,7 +1850,7 @@
</varlistentry>
<varlistentry>
<term>"label"</term>
- <listitem><para>Like above, but returns the &kapp; label(s) of the object(s) (if no label availabe, this is the same as shortname)</para></listitem>
+ <listitem><para>Like above, but returns the &rkward; label(s) of the object(s) (if no label availabe, this is the same as shortname)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
@@ -1884,7 +1884,7 @@
</sect1>
<sect1 id="globalxmlelements">
- <title>General purpose elements to be used in any XML file (.xml, .rkh, .pluginmap)</title>
+ <title>General purpose elements to be used in any XML file (<literal role="extension">.xml</literal>, <literal role="extension">.rkh</literal>, <literal role="extension">.pluginmap</literal>)</title>
<variablelist>
<varlistentry>
<term><snippets></term>
@@ -1912,7 +1912,7 @@
</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>
@@ -2105,7 +2105,7 @@
</varlistentry>
<varlistentry>
<term><classes></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 (otional, <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 (otional, <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><types></term>
@@ -2159,7 +2159,7 @@
</varlistentry>
<varlistentry>
<term><checked></term>
- <listitem><para>Whether the option should be checked/selected by default "true" or "false". Only one button in a <radio> may be set to checked="true". If no option is set to checked, the first option in the parent element will be checked/selected automatically. (optional, default to "false")</para></listitem>
+ <listitem><para>Whether the option should be checked/selected by default "true" or "false". Only one button in a <radio> may be set to <parameter>checked</parameter>=<replaceable>"true"</replaceable>. If no option is set to checked, the first option in the parent element will be checked/selected automatically. (optional, default to "false")</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
@@ -2245,7 +2245,7 @@
</varlistentry>
<varlistentry>
<term><saveobject></term>
-<listitem><para>An element designed to select the name of an R object to save to (i.e. 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 (i.e. generally not already existing, in contrast to a varslot):
<variablelist>
<varlistentry>
<term><label></term>
@@ -2261,7 +2261,7 @@
</varlistentry>
<varlistentry>
<term><checkable></term>
- <listitem><para>In many use cases, saving to an R object is optional. In these cases, a checkbox can be integrated into the saveobject-element using this attribute. When set to true, the saveobject will be activated / deactivated by the checkbox. 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 checkbox can be integrated into the saveobject-element using this attribute. When set to true, the saveobject will be activated / deactivated by the checkbox. See the <link linkend="elementproperties">active-property</link> of saveobject (optional, defaults to false)</para></listitem>
</varlistentry>
<varlistentry>
<term><checked></term>
@@ -2415,7 +2415,8 @@
</varlistentry>
<varlistentry>
<term><require_true></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 submit button (optional, defaults to "false". <emphasis>Caution:</emphasis> If you use this, make sure the user can easily detect what's wrong, such as by showing an explanatory <text>)</para></listitem>
+ <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><remark>If you use this, make sure the user can easily detect what's wrong, such as by showing an explanatory <text>)</remark></caution></para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
@@ -2594,11 +2595,11 @@
</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 (e.g. 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 (e.g. 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, i.e. 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, i.e. the string entered by the user (changed to a valid &r; name, if necessary) (string)</para></listitem>
</varlistentry>
<varlistentry>
<term>active</term>
@@ -2673,15 +2674,15 @@
</variablelist>
</sect1>
-<sect1 id="pluginmapelements"><title>Elements for use in .pluginmap files</title>
+<sect1 id="pluginmapelements"><title>Elements for use in <literal role="extension">.pluginmap</literal> files</title>
<variablelist>
<varlistentry>
<term><document></term>
-<listitem><para>Needs to be present in each .pluginmap file as the root-node (exactly once). Attributes:
+<listitem><para>Needs to be present in each <literal role="extension">.pluginmap</literal> file as the root-node (exactly once). Attributes:
<variablelist>
<varlistentry>
<term>base_prefix</term>
- <listitem><para>Filenames specified in the pluginmap file are assumed to be relative to the directory of the .pluginmap-file + the prefix you specify here. Useful, esp., if all your components are located below a single subdirectory. </para></listitem>
@@ Diff output truncated at 100000 characters. @@
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the rkward-tracker
mailing list