[websites/rkward-kde-org] /: Add rkwardplugins documentation
Thomas Friedrichsmeier
null at kde.org
Sun Apr 24 21:34:18 BST 2022
Git commit d89e8b662ad9b830c6336082742b82249194b05c by Thomas Friedrichsmeier.
Committed on 24/04/2022 at 20:33.
Pushed by tfry into branch 'master'.
Add rkwardplugins documentation
M +3 -0 _config.yml
A +165 -0 doc/common/artistic-license.html
A +- -- doc/common/block_title_bottom.png
A +- -- doc/common/block_title_mid.png
A +- -- doc/common/block_title_top.png
A +45 -0 doc/common/bsd-license.html
A +141 -0 doc/common/ccbysa4-license.html
A +512 -0 doc/common/fdl-license.html
A +15 -0 doc/common/fdl-notice.html
A +512 -0 doc/common/fdl-translated.html
A +381 -0 doc/common/gpl-license.html
A +381 -0 doc/common/gpl-translated.html
A +341 -0 doc/common/kde-default.css
A +329 -0 doc/common/kde-docs.css
A +- -- doc/common/kde_logo.png
A +- -- doc/common/kde_logo_bg.png
A +- -- doc/common/kmenu.png
A +502 -0 doc/common/lgpl-license.html
A +502 -0 doc/common/lgpl-translated.html
A +- -- doc/common/part_of_the_kde_family_horizontal_190.png
A +164 -0 doc/common/qpl-license.html
A +- -- doc/common/top-kde.jpg
A +- -- doc/common/top-left.jpg
A +- -- doc/common/top-right.jpg
A +- -- doc/common/top.jpg
A +45 -0 doc/common/x11-license.html
A +179 -0 doc/common/xml.dcl
A +6 -0 doc/rkwardplugins/building_the_plugin_package.html
A +86 -0 doc/rkwardplugins/ch10s02.html
A +39 -0 doc/rkwardplugins/chapter_about_information.html
A +15 -0 doc/rkwardplugins/chapter_dependencies.html
A +63 -0 doc/rkwardplugins/contextualized_plugins.html
A +7 -0 doc/rkwardplugins/current_object.html
A +24 -0 doc/rkwardplugins/elementproperties.html
A +6 -0 doc/rkwardplugins/embedding.html
A +23 -0 doc/rkwardplugins/embedding_as_button.html
A +12 -0 doc/rkwardplugins/embedding_code.html
A +22 -0 doc/rkwardplugins/embedding_dialog.html
A +28 -0 doc/rkwardplugins/embedding_incomplete.html
A +18 -0 doc/rkwardplugins/embedding_wizard.html
A +10 -0 doc/rkwardplugins/external_plugins.html
A +5 -0 doc/rkwardplugins/globalxmlelements.html
A +4 -0 doc/rkwardplugins/guilogic_functions.html
A +7 -0 doc/rkwardplugins/helpfileelements.html
A +14 -0 doc/rkwardplugins/i18n.html
A +34 -0 doc/rkwardplugins/i18n_js.html
A +10 -0 doc/rkwardplugins/i18n_translators.html
A +15 -0 doc/rkwardplugins/i18n_workflow.html
A +45 -0 doc/rkwardplugins/i18n_xml.html
A +56 -0 doc/rkwardplugins/include_js.html
A +10 -0 doc/rkwardplugins/include_snippets_vs_embedding.html
A +12 -0 doc/rkwardplugins/include_xml.html
A +8 -0 doc/rkwardplugins/index.html
A +22 -0 doc/rkwardplugins/introduction.html
A +46 -0 doc/rkwardplugins/jsconventions.html
A +57 -0 doc/rkwardplugins/jstemplate.html
A +28 -0 doc/rkwardplugins/jstips.html
A +3 -0 doc/rkwardplugins/license.html
A +55 -0 doc/rkwardplugins/logic.html
A +31 -0 doc/rkwardplugins/logic_scripted.html
A +95 -0 doc/rkwardplugins/mainxml.html
A +10 -0 doc/rkwardplugins/mainxmltips.html
A +117 -0 doc/rkwardplugins/optionset.html
A +10 -0 doc/rkwardplugins/plugin_series.html
A +106 -0 doc/rkwardplugins/pluginhelp.html
A +101 -0 doc/rkwardplugins/pluginmap.html
A +17 -0 doc/rkwardplugins/pluginmapelements.html
A +33 -0 doc/rkwardplugins/querying_r_for_info.html
A +10 -0 doc/rkwardplugins/reference.html
A +207 -0 doc/rkwardplugins/rkdev_example.html
A +5 -0 doc/rkwardplugins/rkwarddev.html [INFRASTRUCTURE] [INFRASTRUCTURE] [INFRASTRUCTURE]
A +24 -0 doc/rkwardplugins/rkwarddev_i18n.html
A +22 -0 doc/rkwardplugins/rkwarddev_rkh.html
A +32 -0 doc/rkwardplugins/sect_dependencies_example.html
A +9 -0 doc/rkwardplugins/sect_dependencies_other_pluginmaps.html
A +10 -0 doc/rkwardplugins/sect_dependencies_r_packages.html
A +16 -0 doc/rkwardplugins/sect_dependencies_r_version.html
A +90 -0 doc/rkwardplugins/snippets.html
A +101 -0 doc/rkwardplugins/specialized_plugins.html
A +4 -0 doc/rkwardplugins/standard_embeddable_plugins.html
A +68 -0 doc/rkwardplugins/structure_of_a_plugin_package.html
A +10 -0 doc/rkwardplugins/troubleshooting.html
A +10 -0 doc/rkwardplugins/whatareplugins.html
A +6 -0 doc/rkwardplugins/why_external_plugins.html [INFRASTRUCTURE]
A +33 -0 doc/rkwardplugins/wizard_interface.html
A +48 -0 doc/rkwardplugins/xmlelements.html
https://invent.kde.org/websites/rkward-kde-org/commit/d89e8b662ad9b830c6336082742b82249194b05c
diff --git a/_config.yml b/_config.yml
index 94c8cb8..5d39c01 100644
--- a/_config.yml
+++ b/_config.yml
@@ -78,3 +78,6 @@ exclude:
- Gemfile
- Gemfile.lock
- vendor
+
+keep_files:
+ - doc
diff --git a/doc/common/artistic-license.html b/doc/common/artistic-license.html
new file mode 100644
index 0000000..2069b4e
--- /dev/null
+++ b/doc/common/artistic-license.html
@@ -0,0 +1,165 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>The "Artistic License"</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="Artistic License">
+ <META NAME="keywords" CONTENT="Artistic, artistic, Artistic License, Artistic license, Artisticlicense, artistic license, artisticlicense, Artistic Licence, Artistic licence, Artisticlicence, artistic licence, artisticlicence, license, licence, software, softwarelicense">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+ <H1>The "Artistic License"</H1>
+
+ <H2>Preamble</H2>
+
+ <P>The intent of this document is to state the conditions under
+ which a Package may be copied, such that the Copyright Holder
+ maintains some semblance of artistic control over the
+ development of the package, while giving the users of the
+ package the right to use and distribute the Package in a
+ more-or-less customary fashion, plus the right to make
+ reasonable modifications.</P>
+
+ <H2>Definitions</H2>
+
+
+ <P>"Package" refers to the collection of files distributed by the
+ Copyright Holder, and derivatives of that collection of files
+ created through textual modification.</P>
+
+ <P>"Standard Version" refers to such a Package if it has not been
+ modified, or has been modified in accordance with the wishes of
+ the Copyright Holder as specified below.</P>
+
+ <P>"Copyright Holder" is whoever is named in the copyright or
+ copyrights for the package.</P>
+
+ <P>"You" is you, if you're thinking about copying or distributing
+ this Package.</P>
+
+ <P>"Reasonable copying fee" is whatever you can justify on the
+ basis of media cost, duplication charges, time of people
+ involved, and so on. (You will not be required to justify it to
+ the Copyright Holder, but only to the computing community at
+ large as a market that must bear the fee.)</P>
+
+ <P>"Freely Available" means that no fee is charged for the item
+ itself, though there may be fees involved in handling the
+ item. It also means that recipients of the item may redistribute
+ it under the same conditions they received it.</P>
+
+
+ <OL STYLE="list-style-type: decimal;">
+ <LI><DIV CLASS="li">You may make and give away verbatim copies of the source
+ form of the Standard Version of this Package without
+ restriction, provided that you duplicate all of the original
+ copyright notices and associated disclaimers.</DIV></LI>
+
+ <LI>You may apply bug fixes, portability fixes and other
+ modifications derived from the Public Domain or from the
+ Copyright Holder. A Package modified in such a way shall still
+ be considered the Standard Version.</LI>
+
+ <LI>You may otherwise modify your copy of this Package in any
+ way, provided that you insert a prominent notice in each
+ changed file stating how and when you changed that file, and
+ provided that you do at least ONE of the following:
+ <OL STYLE="list-style-type: lower-alpha;">
+ <LI>place your modifications in the Public Domain or
+ otherwise make them Freely Available, such as by posting
+ said modifications to Usenet or an equivalent medium, or
+ placing the modifications on a major archive site such as
+ uunet.uu.net, or by allowing the Copyright Holder to
+ include your modifications in the Standard Version of the
+ Package.</LI>
+
+ <LI>use the modified Package only within your corporation or
+ organization.</LI>
+
+ <LI>rename any non-standard executables so the names do not
+ conflict with standard executables, which must also be
+ provided, and provide a separate manual page for each
+ non-standard executable that clearly documents how it
+ differs from the Standard Version. d. make other
+ distribution arrangements with the Copyright Holder.</LI>
+ </OL>
+ </LI>
+ </OL>
+
+ <P>You may distribute the programs of this Package in object code
+ or executable form, provided that you do at least ONE of the
+ following:</P>
+
+ <OL STYLE="list-style-type: lower-alpha;">
+ <LI>distribute a Standard Version of the executables and library
+ files, together with instructions (in the manual page or
+ equivalent) on where to get the Standard Version.</LI>
+
+ <LI>accompany the distribution with the machine-readable source
+ of the Package with your modifications.</LI>
+
+ <LI>give non-standard executables non-standard names, and
+ clearly document the differences in manual pages (or
+ equivalent), together with instructions on where to get the
+ Standard Version.</LI>
+
+ <LI>make other distribution arrangements with the Copyright
+ Holder.</LI>
+ </OL>
+
+ <P>You may charge a reasonable copying fee for any distribution of
+ this Package. You may charge any fee you choose for support of
+ this Package. You may not charge a fee for this Package
+ itself. However, you may distribute this Package in aggregate
+ with other (possibly commercial) programs as part of a larger
+ (possibly commercial) software distribution provided that you do
+ not advertise this Package as a product of your own. You may
+ embed this Package's interpreter within an executable of yours
+ (by linking); this shall be construed as a mere form of
+ aggregation, provided that the complete Standard Version of the
+ interpreter is so embedded.</P>
+
+ <P>The scripts and library files supplied as input to or produced
+ as output from the programs of this Package do not automatically
+ fall under the copyright of this Package, but belong to whomever
+ generated them, and may be sold commercially, and may be
+ aggregated with this Package. If such scripts or library files
+ are aggregated with this Package via the so-called "undump" or
+ "unexec" methods of producing a binary executable image, then
+ distribution of such an image shall neither be construed as a
+ distribution of this Package nor shall it fall under the
+ restrictions of Paragraphs 3 and 4, provided that you do not
+ represent such an executable image as a Standard Version of this
+ Package.</P>
+
+ <P>C subroutines (or comparably compiled subroutines in other
+ languages) supplied by you and linked into this Package in order
+ to emulate subroutines and variables of the language defined by
+ this Package shall not be considered part of this Package, but
+ are the equivalent of input as in Paragraph 6, provided these
+ subroutines do not change the language in any way that would
+ cause it to fail the regression tests for the language.</P>
+
+ <P>Aggregation of this Package with a commercial distribution is
+ always permitted provided that the use of this Package is
+ embedded; that is, when no overt attempt is made to make this
+ Package's interfaces visible to the end user of the commercial
+ distribution. Such use shall not be construed as a distribution
+ of this Package.</P>
+
+ <P>The name of the Copyright Holder may not be used to endorse or
+ promote products derived from this software without specific
+ prior written permission.</P>
+
+ <P>THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+ WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE.</P>
+
+ <DIV STYLE="text-align: center;">The End</DIV>
+ </BODY>
+</HTML>
diff --git a/doc/common/block_title_bottom.png b/doc/common/block_title_bottom.png
new file mode 100644
index 0000000..b14bead
Binary files /dev/null and b/doc/common/block_title_bottom.png differ
diff --git a/doc/common/block_title_mid.png b/doc/common/block_title_mid.png
new file mode 100644
index 0000000..9d0e6ef
Binary files /dev/null and b/doc/common/block_title_mid.png differ
diff --git a/doc/common/block_title_top.png b/doc/common/block_title_top.png
new file mode 100644
index 0000000..7491703
Binary files /dev/null and b/doc/common/block_title_top.png differ
diff --git a/doc/common/bsd-license.html b/doc/common/bsd-license.html
new file mode 100644
index 0000000..422bb33
--- /dev/null
+++ b/doc/common/bsd-license.html
@@ -0,0 +1,45 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>BSD License</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="BSD License">
+ <META NAME="keywords" CONTENT="BSD, bsd, Bsd, license, licence, software, free software, softwarelicense, BSD Software license">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+ <H1>BSD License</H1>
+
+ <P>Redistribution and use in source and binary forms, with or
+ without modification, are permitted provided that the following
+ conditions are met:</P>
+
+ <OL>
+ <LI>Redistributions of source code must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer.</LI>
+
+ <LI>Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following
+ disclaimer in the documentation and/or other materials
+ provided with the distribution.</LI>
+ </OL>
+
+ <P>THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY
+ EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+ PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
+ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+ IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ THE POSSIBILITY OF SUCH DAMAGE.</P>
+ </BODY>
+</HTML>
diff --git a/doc/common/ccbysa4-license.html b/doc/common/ccbysa4-license.html
new file mode 100644
index 0000000..6cdce87
--- /dev/null
+++ b/doc/common/ccbysa4-license.html
@@ -0,0 +1,141 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>CC BY-SA 4.0 International</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="CC BY-SA 4.0 free documentation license (for inclusion in documentation files)">
+ <META NAME="keywords" CONTENT="creative, commons, CC, license, licence, software, free software, software license, software licence, CC BY-SA, GNU General Public License, documentation licence, documentation license, documentation, Attribution-ShareAlike 4.0 International">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+<h3>Creative Commons Attribution-ShareAlike 4.0 International Public License</h3>
+<p>By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.</p>
+<p id="s1"><strong>Section 1 – Definitions.</strong></p>
+<ol type="a">
+<li id="s1a"><strong>Adapted Material</strong> means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.</li>
+<li id="s1b"><strong>Adapter's License</strong> means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.</li>
+<li id="s1c"><strong>BY-SA Compatible License</strong> means a license listed at <a href="//creativecommons.org/compatiblelicenses"> creativecommons.org/compatiblelicenses</a>, approved by Creative Commons as essentially the equivalent of this Public License.</li>
+<li id="s1d"><strong>Copyright and Similar Rights</strong> means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section <a href="#s2b">2(b)(1)-(2)</a> are not Copyright and Similar Rights.</li>
+<li id="s1e"><strong>Effective Technological Measures</strong> means those measures that, in the absence of proper authority, may not
+be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar
+international agreements.</li>
+<li id="s1f"><strong>Exceptions and Limitations</strong> means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.</li>
+<li id="s1g"><strong>License Elements</strong> means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike.</li>
+<li id="s1h"><strong>Licensed Material</strong> means the artistic or literary work, database, or other material to which the Licensor applied this Public License.</li>
+<li id="s1i"><strong>Licensed Rights</strong> means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.</li>
+<li id="s1j"><strong>Licensor</strong> means the individual(s) or entity(ies) granting rights under this Public License.</li>
+<li id="s1k"><strong>Share</strong> means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.</li>
+<li id="s1l"><strong>Sui Generis Database Rights</strong> means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.</li>
+<li id="s1m"><strong>You</strong> means the individual or entity exercising the Licensed Rights under this Public License. <strong>Your</strong> has a corresponding meaning.</li>
+</ol>
+<p id="s2"><strong>Section 2 – Scope.</strong></p>
+<ol type="a">
+<li id="s2a"><strong>License grant</strong>.
+<ol>
+<li id="s2a1">Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
+<ol type="A">
+<li id="s2a1A">reproduce and Share the Licensed Material, in whole or in part; and</li>
+<li id="s2a1B">produce, reproduce, and Share Adapted Material.</li>
+</ol>
+<li id="s2a2"><span style="text-decoration: underline;">Exceptions and Limitations</span>. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.</li>
+<li id="s2a3"><span style="text-decoration: underline;">Term</span>. The term of this Public License is specified in Section <a href="#s6a">6(a)</a>.</li>
+<li id="s2a4"><span style="text-decoration: underline;">Media and formats; technical modifications allowed</span>. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section <a href="#s2a4">2(a)(4)</a> never produces Adapted Material.</li>
+<li id="s2a5"><span style="text-decoration: underline;">Downstream recipients</span>.
+<div class="para">
+<ol type="A">
+<li id="s2a5A"><span style="text-decoration: underline;">Offer from the Licensor – Licensed Material</span>. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.</li>
+<li id="s2a5B"><span style="text-decoration: underline;">Additional offer from the Licensor – Adapted Material</span>. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply.</li>
+<li id="s2a5C"><span style="text-decoration: underline;">No downstream restrictions</span>. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.</li>
+</ol>
+</div>
+<li id="s2a6"><span style="text-decoration: underline;">No endorsement</span>. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section <a href="#s3a1Ai">3(a)(1)(A)(i)</a>.</li>
+</ol>
+<li id="s2b"><p><strong>Other rights</strong>.</p>
+<ol>
+<li id="s2b1">Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.</li>
+<li id="s2b2">Patent and trademark rights are not licensed under this Public License.</li>
+<li id="s2b3">To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.</li>
+</ol>
+</li>
+</ol>
+<p id="s3"><strong>Section 3 – License Conditions.</strong></p>
+<p>Your exercise of the Licensed Rights is expressly made subject to the following conditions.</p>
+<ol type="a">
+<li id="s3a"><p><strong>Attribution</strong>.</p>
+<ol>
+<li id="s3a1"><p>If You Share the Licensed Material (including in modified form), You must:</p>
+<ol type="A">
+<li id="s3a1A">retain the following if it is supplied by the Licensor with the Licensed Material:
+<ol type="i">
+<li id="s3a1Ai">identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);</li>
+<li id="s3a1Aii">a copyright notice;</li>
+<li id="s3a1Aiii">a notice that refers to this Public License; </li>
+<li id="s3a1Aiv">a notice that refers to the disclaimer of warranties;</li>
+<li id="s3a1Av">a URI or hyperlink to the Licensed Material to the extent reasonably practicable;</li>
+</ol>
+<li id="s3a1B">indicate if You modified the Licensed Material and retain an indication of any previous modifications; and</li>
+<li id="s3a1C">indicate the Licensed Material is licensed under this Public License,
+and include the text of, or the URI or hyperlink to, this Public
+License.</li>
+</ol>
+</li>
+<li id="s3a2">You may satisfy the conditions in Section <a href="#s3a1">3(a)(1)</a> in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.</li>
+<li id="s3a3">If requested by the Licensor, You must remove any of the information required by Section <a href="#s3a1A">3(a)(1)(A)</a> to the extent reasonably practicable.</li>
+</ol>
+</li>
+<li id="s3b"><strong>ShareAlike</strong>.
+<p>In addition to the conditions in Section <a href="#s3a">3(a)</a>, if You Share Adapted Material You produce, the following conditions also apply.</p>
+<ol>
+<li id="s3b1">The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License.</li>
+<li id="s3b2">You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material.</li>
+<li id="s3b3">You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply.</li>
+</ol>
+</li>
+</ol>
+<p id="s4"><strong>Section 4 – Sui Generis Database Rights.</strong></p>
+<p>Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:</p>
+<ol type="a">
+<li id="s4a">for the avoidance of doubt, Section <a href="#s2a1">2(a)(1)</a> grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;</li>
+<li id="s4b">if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section <a href="#s3b">3(b)</a>; and</li>
+<li id="s4c">You must comply with the conditions in Section <a href="#s3a">3(a)</a> if You Share all or a substantial portion of the contents of the database.</li>
+</ol>
+For the avoidance of doubt, this Section <a href="#s4">4</a> supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
+<p id="s5"><strong>Section 5 – Disclaimer of Warranties and Limitation of Liability.</strong></p>
+<ol style="font-weight: bold;" type="a">
+<li id="s5a"><strong>Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.</strong></li>
+<li id="s5b"><strong>To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.</strong></li>
+</ol>
+<ol start="3" type="a">
+<li id="s5c">The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.</li>
+</ol>
+<p id="s6"><strong>Section 6 – Term and Termination.</strong></p>
+<ol type="a">
+<li id="s6a">This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.</li>
+<li id="s6b">
+<p>Where Your right to use the Licensed Material has terminated under Section <a href="#s6a">6(a)</a>, it reinstates:</p>
+<ol>
+<li id="s6b1">automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or</li>
+<li id="s6b2">upon express reinstatement by the Licensor.</li>
+</ol>
+For the avoidance of doubt, this Section <a href="#s6b">6(b)</a> does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.</li>
+<li id="s6c">For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.</li>
+<li id="s6d">Sections <a href="#s1">1</a>, <a href="#s5">5</a>, <a href="#s6">6</a>, <a href="#s7">7</a>, and <a href="#s8">8</a> survive termination of this Public License.</li>
+</ol>
+<p id="s7"><strong>Section 7 – Other Terms and Conditions.</strong></p>
+<ol type="a">
+<li id="s7a">The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.</li>
+<li id="s7b">Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.</li>
+</ol>
+<p id="s8"><strong>Section 8 – Interpretation.</strong></p>
+<ol type="a">
+<li id="s8a">For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.</li>
+<li id="s8b">To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.</li>
+<li id="s8c">No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.</li>
+<li id="s8d">Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.</li>
+</ol>
+ </BODY>
+</HTML>
diff --git a/doc/common/fdl-license.html b/doc/common/fdl-license.html
new file mode 100644
index 0000000..9ce378a
--- /dev/null
+++ b/doc/common/fdl-license.html
@@ -0,0 +1,512 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>GNU Free Documentation License - version 1.1</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="GNU free documentation license (for inclusion in documentation files)">
+ <META NAME="keywords" CONTENT="gnu, Gnu, GNU, license, licence, software, free software, software license, software licence, GNU general public license, GNU General Public License, documentation licence, documentation license, documentation, GNU free documentation license, GNU Free Documentation License">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+<h3>GNU Free Documentation License</h3>
+<p>
+ Version 1.2, November 2002
+</p>
+
+<pre>
+ Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+</pre>
+
+<p>
+ <strong>0. PREAMBLE</strong>
+</p>
+
+<p>
+ The purpose of this License is to make a manual, textbook, or other
+ functional and useful document "free" in the sense of freedom: to
+ assure everyone the effective freedom to copy and redistribute it,
+ with or without modifying it, either commercially or noncommercially.
+ Secondarily, this License preserves for the author and publisher a way
+ to get credit for their work, while not being considered responsible
+ for modifications made by others.
+</p>
+
+<p>
+ This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense. It
+ complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+</p>
+
+<p>
+ We have designed this License in order to use it for manuals for free
+ software, because free software needs free documentation: a free
+ program should come with manuals providing the same freedoms that the
+ software does. But this License is not limited to software manuals;
+ it can be used for any textual work, regardless of subject matter or
+ whether it is published as a printed book. We recommend this License
+ principally for works whose purpose is instruction or reference.
+</p>
+
+<p>
+ <strong>1. APPLICABILITY AND DEFINITIONS</strong>
+</p>
+
+<p>
+ This License applies to any manual or other work, in any medium, that
+ contains a notice placed by the copyright holder saying it can be
+ distributed under the terms of this License. Such a notice grants a
+ world-wide, royalty-free license, unlimited in duration, to use that
+ work under the conditions stated herein. The "Document", below,
+ refers to any such manual or work. Any member of the public is a
+ licensee, and is addressed as "you". You accept the license if you
+ copy, modify or distribute the work in a way requiring permission
+ under copyright law.
+</p>
+
+<p>
+ A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+</p>
+
+<p>
+ A "Secondary Section" is a named appendix or a front-matter section of
+ the Document that deals exclusively with the relationship of the
+ publishers or authors of the Document to the Document's overall subject
+ (or to related matters) and contains nothing that could fall directly
+ within that overall subject. (Thus, if the Document is in part a
+ textbook of mathematics, a Secondary Section may not explain any
+ mathematics.) The relationship could be a matter of historical
+ connection with the subject or with related matters, or of legal,
+ commercial, philosophical, ethical or political position regarding
+ them.
+</p>
+
+<p>
+ The "Invariant Sections" are certain Secondary Sections whose titles
+ are designated, as being those of Invariant Sections, in the notice
+ that says that the Document is released under this License. If a
+ section does not fit the above definition of Secondary then it is not
+ allowed to be designated as Invariant. The Document may contain zero
+ Invariant Sections. If the Document does not identify any Invariant
+ Sections then there are none.
+</p>
+
+<p>
+ The "Cover Texts" are certain short passages of text that are listed,
+ as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+ the Document is released under this License. A Front-Cover Text may
+ be at most 5 words, and a Back-Cover Text may be at most 25 words.
+</p>
+
+<p>
+ A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, that is suitable for revising the document
+ straightforwardly with generic text editors or (for images composed of
+ pixels) generic paint programs or (for drawings) some widely available
+ drawing editor, and that is suitable for input to text formatters or
+ for automatic translation to a variety of formats suitable for input
+ to text formatters. A copy made in an otherwise Transparent file
+ format whose markup, or absence of markup, has been arranged to thwart
+ or discourage subsequent modification by readers is not Transparent.
+ An image format is not Transparent if used for any substantial amount
+ of text. A copy that is not "Transparent" is called "Opaque".
+</p>
+
+<p>
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format, SGML
+ or XML using a publicly available DTD, and standard-conforming simple
+ HTML, PostScript or PDF designed for human modification. Examples of
+ transparent image formats include PNG, XCF and JPG. Opaque formats
+ include proprietary formats that can be read and edited only by
+ proprietary word processors, SGML or XML for which the DTD and/or
+ processing tools are not generally available, and the
+ machine-generated HTML, PostScript or PDF produced by some word
+ processors for output purposes only.
+</p>
+
+<p>
+ The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the material
+ this License requires to appear in the title page. For works in
+ formats which do not have any title page as such, "Title Page" means
+ the text near the most prominent appearance of the work's title,
+ preceding the beginning of the body of the text.
+</p>
+
+<p>
+ A section "Entitled XYZ" means a named subunit of the Document whose
+ title either is precisely XYZ or contains XYZ in parentheses following
+ text that translates XYZ in another language. (Here XYZ stands for a
+ specific section name mentioned below, such as "Acknowledgements",
+ "Dedications", "Endorsements", or "History".) To "Preserve the Title"
+ of such a section when you modify the Document means that it remains a
+ section "Entitled XYZ" according to this definition.
+</p>
+
+<p>
+ The Document may include Warranty Disclaimers next to the notice which
+ states that this License applies to the Document. These Warranty
+ Disclaimers are considered to be included by reference in this
+ License, but only as regards disclaiming warranties: any other
+ implication that these Warranty Disclaimers may have is void and has
+ no effect on the meaning of this License.
+</p>
+
+<p>
+ <strong>2. VERBATIM COPYING</strong>
+</p>
+
+<p>
+ You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License applies
+ to the Document are reproduced in all copies, and that you add no other
+ conditions whatsoever to those of this License. You may not use
+ technical measures to obstruct or control the reading or further
+ copying of the copies you make or distribute. However, you may accept
+ compensation in exchange for copies. If you distribute a large enough
+ number of copies you must also follow the conditions in section 3.
+</p>
+
+<p>
+ You may also lend copies, under the same conditions stated above, and
+ you may publicly display copies.
+</p>
+
+<p>
+ <strong>3. COPYING IN QUANTITY</strong>
+</p>
+
+<p>
+ If you publish printed copies (or copies in media that commonly have
+ printed covers) of the Document, numbering more than 100, and the
+ Document's license notice requires Cover Texts, you must enclose the
+ copies in covers that carry, clearly and legibly, all these Cover
+ Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+ the back cover. Both covers must also clearly and legibly identify
+ you as the publisher of these copies. The front cover must present
+ the full title with all words of the title equally prominent and
+ visible. You may add other material on the covers in addition.
+ Copying with changes limited to the covers, as long as they preserve
+ the title of the Document and satisfy these conditions, can be treated
+ as verbatim copying in other respects.
+</p>
+
+<p>
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto adjacent
+ pages.
+</p>
+
+<p>
+ If you publish or distribute Opaque copies of the Document numbering
+ more than 100, you must either include a machine-readable Transparent
+ copy along with each Opaque copy, or state in or with each Opaque copy
+ a computer-network location from which the general network-using
+ public has access to download using public-standard network protocols
+ a complete Transparent copy of the Document, free of added material.
+ If you use the latter option, you must take reasonably prudent steps,
+ when you begin distribution of Opaque copies in quantity, to ensure
+ that this Transparent copy will remain thus accessible at the stated
+ location until at least one year after the last time you distribute an
+ Opaque copy (directly or through your agents or retailers) of that
+ edition to the public.
+</p>
+
+<p>
+ It is requested, but not required, that you contact the authors of the
+ Document well before redistributing any large number of copies, to give
+ them a chance to provide you with an updated version of the Document.
+</p>
+
+<p>
+ <strong>4. MODIFICATIONS</strong>
+</p>
+
+<p>
+ You may copy and distribute a Modified Version of the Document under
+ the conditions of sections 2 and 3 above, provided that you release
+ the Modified Version under precisely this License, with the Modified
+ Version filling the role of the Document, thus licensing distribution
+ and modification of the Modified Version to whoever possesses a copy
+ of it. In addition, you must do these things in the Modified Version:
+</p>
+
+<ul>
+ <li><strong>A.</strong> Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.</li>
+ <li><strong>B.</strong> List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.</li>
+ <li><strong>C.</strong> State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.</li>
+ <li><strong>D.</strong> Preserve all the copyright notices of the Document.</li>
+ <li><strong>E.</strong> Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.</li>
+ <li><strong>F.</strong> Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.</li>
+ <li><strong>G.</strong> Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.</li>
+ <li><strong>H.</strong> Include an unaltered copy of this License.</li>
+ <li><strong>I.</strong> Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.</li>
+ <li><strong>J.</strong> Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.</li>
+ <li><strong>K.</strong> For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.</li>
+ <li><strong>L.</strong> Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.</li>
+ <li><strong>M.</strong> Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.</li>
+ <li><strong>N.</strong> Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.</li>
+ <li><strong>O.</strong> Preserve any Warranty Disclaimers.</li>
+</ul>
+
+<p>
+ If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no material
+ copied from the Document, you may at your option designate some or all
+ of these sections as invariant. To do this, add their titles to the
+ list of Invariant Sections in the Modified Version's license notice.
+ These titles must be distinct from any other section titles.
+</p>
+
+<p>
+ You may add a section Entitled "Endorsements", provided it contains
+ nothing but endorsements of your Modified Version by various
+ parties--for example, statements of peer review or that the text has
+ been approved by an organization as the authoritative definition of a
+ standard.
+</p>
+
+<p>
+ You may add a passage of up to five words as a Front-Cover Text, and a
+ passage of up to 25 words as a Back-Cover Text, to the end of the list
+ of Cover Texts in the Modified Version. Only one passage of
+ Front-Cover Text and one of Back-Cover Text may be added by (or
+ through arrangements made by) any one entity. If the Document already
+ includes a cover text for the same cover, previously added by you or
+ by arrangement made by the same entity you are acting on behalf of,
+ you may not add another; but you may replace the old one, on explicit
+ permission from the previous publisher that added the old one.
+</p>
+
+<p>
+ The author(s) and publisher(s) of the Document do not by this License
+ give permission to use their names for publicity for or to assert or
+ imply endorsement of any Modified Version.
+</p>
+
+<p>
+ <strong>5. COMBINING DOCUMENTS</strong>
+</p>
+
+<p>
+ You may combine the Document with other documents released under this
+ License, under the terms defined in section 4 above for modified
+ versions, provided that you include in the combination all of the
+ Invariant Sections of all of the original documents, unmodified, and
+ list them all as Invariant Sections of your combined work in its
+ license notice, and that you preserve all their Warranty Disclaimers.
+</p>
+
+<p>
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name but
+ different contents, make the title of each such section unique by
+ adding at the end of it, in parentheses, the name of the original
+ author or publisher of that section if known, or else a unique number.
+ Make the same adjustment to the section titles in the list of
+ Invariant Sections in the license notice of the combined work.
+</p>
+
+<p>
+ In the combination, you must combine any sections Entitled "History"
+ in the various original documents, forming one section Entitled
+ "History"; likewise combine any sections Entitled "Acknowledgements",
+ and any sections Entitled "Dedications". You must delete all sections
+ Entitled "Endorsements."
+</p>
+
+<p>
+ <strong>6. COLLECTIONS OF DOCUMENTS</strong>
+</p>
+
+<p>
+ You may make a collection consisting of the Document and other documents
+ released under this License, and replace the individual copies of this
+ License in the various documents with a single copy that is included in
+ the collection, provided that you follow the rules of this License for
+ verbatim copying of each of the documents in all other respects.
+</p>
+
+<p>
+ You may extract a single document from such a collection, and distribute
+ it individually under this License, provided you insert a copy of this
+ License into the extracted document, and follow this License in all
+ other respects regarding verbatim copying of that document.
+</p>
+
+<p>
+ <strong>7. AGGREGATION WITH INDEPENDENT WORKS</strong>
+</p>
+
+<p>
+ A compilation of the Document or its derivatives with other separate
+ and independent documents or works, in or on a volume of a storage or
+ distribution medium, is called an "aggregate" if the copyright
+ resulting from the compilation is not used to limit the legal rights
+ of the compilation's users beyond what the individual works permit.
+ When the Document is included in an aggregate, this License does not
+ apply to the other works in the aggregate which are not themselves
+ derivative works of the Document.
+</p>
+
+<p>
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one half of
+ the entire aggregate, the Document's Cover Texts may be placed on
+ covers that bracket the Document within the aggregate, or the
+ electronic equivalent of covers if the Document is in electronic form.
+ Otherwise they must appear on printed covers that bracket the whole
+ aggregate.
+</p>
+
+<p>
+ <strong>8. TRANSLATION</strong>
+</p>
+
+<p>
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section 4.
+ Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License, and all the license notices in the
+ Document, and any Warranty Disclaimers, provided that you also include
+ the original English version of this License and the original versions
+ of those notices and disclaimers. In case of a disagreement between
+ the translation and the original version of this License or a notice
+ or disclaimer, the original version will prevail.
+</p>
+
+<p>
+ If a section in the Document is Entitled "Acknowledgements",
+ "Dedications", or "History", the requirement (section 4) to Preserve
+ its Title (section 1) will typically require changing the actual
+ title.
+</p>
+
+<p>
+ <strong>9. TERMINATION</strong>
+</p>
+
+<p>
+ You may not copy, modify, sublicense, or distribute the Document except
+ as expressly provided for under this License. Any other attempt to
+ copy, modify, sublicense or distribute the Document is void, and will
+ automatically terminate your rights under this License. However,
+ parties who have received copies, or rights, from you under this
+ License will not have their licenses terminated so long as such
+ parties remain in full compliance.
+</p>
+
+<p>
+ <strong>10. FUTURE REVISIONS OF THIS LICENSE</strong>
+</p>
+
+<p>
+ The Free Software Foundation may publish new, revised versions
+ of the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ http://www.gnu.org/copyleft/.
+</p>
+
+<p>
+ Each version of the License is given a distinguishing version number.
+ If the Document specifies that a particular numbered version of this
+ License "or any later version" applies to it, you have the option of
+ following the terms and conditions either of that specified version or
+ of any later version that has been published (not as a draft) by the
+ Free Software Foundation. If the Document does not specify a version
+ number of this License, you may choose any version ever published (not
+ as a draft) by the Free Software Foundation.
+</p>
+
+<h3>How to use this License for your documents</h3>
+
+<p>
+ To use this License in a document you have written, include a copy of
+ the License in the document and put the following copyright and
+ license notices just after the title page:
+</p>
+
+<pre>
+ Copyright (c) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+</pre>
+
+<p>
+ If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+ replace the "with...Texts." line with this:
+</p>
+
+<pre>
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+</pre>
+
+<p>
+ If you have Invariant Sections without Cover Texts, or some other
+ combination of the three, merge those two alternatives to suit the
+ situation.
+</p>
+
+<p>
+ If your document contains nontrivial examples of program code, we
+ recommend releasing these examples in parallel under your choice of
+ free software license, such as the GNU General Public License,
+ to permit their use in free software.
+</p>
+ </BODY>
+</HTML>
diff --git a/doc/common/fdl-notice.html b/doc/common/fdl-notice.html
new file mode 100644
index 0000000..862f09e
--- /dev/null
+++ b/doc/common/fdl-notice.html
@@ -0,0 +1,15 @@
+<html>
+<head>
+<title>FDL Notice</title>
+</head>
+
+<body>
+
+<p>Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or any
+later version published by the Free Software Foundation; with no Invariant
+Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy
+of the license is included <a href="fdl-license.html">here</a>.</p>
+
+</body>
+</html>
diff --git a/doc/common/fdl-translated.html b/doc/common/fdl-translated.html
new file mode 100644
index 0000000..9ce378a
--- /dev/null
+++ b/doc/common/fdl-translated.html
@@ -0,0 +1,512 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>GNU Free Documentation License - version 1.1</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="GNU free documentation license (for inclusion in documentation files)">
+ <META NAME="keywords" CONTENT="gnu, Gnu, GNU, license, licence, software, free software, software license, software licence, GNU general public license, GNU General Public License, documentation licence, documentation license, documentation, GNU free documentation license, GNU Free Documentation License">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+<h3>GNU Free Documentation License</h3>
+<p>
+ Version 1.2, November 2002
+</p>
+
+<pre>
+ Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+</pre>
+
+<p>
+ <strong>0. PREAMBLE</strong>
+</p>
+
+<p>
+ The purpose of this License is to make a manual, textbook, or other
+ functional and useful document "free" in the sense of freedom: to
+ assure everyone the effective freedom to copy and redistribute it,
+ with or without modifying it, either commercially or noncommercially.
+ Secondarily, this License preserves for the author and publisher a way
+ to get credit for their work, while not being considered responsible
+ for modifications made by others.
+</p>
+
+<p>
+ This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense. It
+ complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+</p>
+
+<p>
+ We have designed this License in order to use it for manuals for free
+ software, because free software needs free documentation: a free
+ program should come with manuals providing the same freedoms that the
+ software does. But this License is not limited to software manuals;
+ it can be used for any textual work, regardless of subject matter or
+ whether it is published as a printed book. We recommend this License
+ principally for works whose purpose is instruction or reference.
+</p>
+
+<p>
+ <strong>1. APPLICABILITY AND DEFINITIONS</strong>
+</p>
+
+<p>
+ This License applies to any manual or other work, in any medium, that
+ contains a notice placed by the copyright holder saying it can be
+ distributed under the terms of this License. Such a notice grants a
+ world-wide, royalty-free license, unlimited in duration, to use that
+ work under the conditions stated herein. The "Document", below,
+ refers to any such manual or work. Any member of the public is a
+ licensee, and is addressed as "you". You accept the license if you
+ copy, modify or distribute the work in a way requiring permission
+ under copyright law.
+</p>
+
+<p>
+ A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+</p>
+
+<p>
+ A "Secondary Section" is a named appendix or a front-matter section of
+ the Document that deals exclusively with the relationship of the
+ publishers or authors of the Document to the Document's overall subject
+ (or to related matters) and contains nothing that could fall directly
+ within that overall subject. (Thus, if the Document is in part a
+ textbook of mathematics, a Secondary Section may not explain any
+ mathematics.) The relationship could be a matter of historical
+ connection with the subject or with related matters, or of legal,
+ commercial, philosophical, ethical or political position regarding
+ them.
+</p>
+
+<p>
+ The "Invariant Sections" are certain Secondary Sections whose titles
+ are designated, as being those of Invariant Sections, in the notice
+ that says that the Document is released under this License. If a
+ section does not fit the above definition of Secondary then it is not
+ allowed to be designated as Invariant. The Document may contain zero
+ Invariant Sections. If the Document does not identify any Invariant
+ Sections then there are none.
+</p>
+
+<p>
+ The "Cover Texts" are certain short passages of text that are listed,
+ as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+ the Document is released under this License. A Front-Cover Text may
+ be at most 5 words, and a Back-Cover Text may be at most 25 words.
+</p>
+
+<p>
+ A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, that is suitable for revising the document
+ straightforwardly with generic text editors or (for images composed of
+ pixels) generic paint programs or (for drawings) some widely available
+ drawing editor, and that is suitable for input to text formatters or
+ for automatic translation to a variety of formats suitable for input
+ to text formatters. A copy made in an otherwise Transparent file
+ format whose markup, or absence of markup, has been arranged to thwart
+ or discourage subsequent modification by readers is not Transparent.
+ An image format is not Transparent if used for any substantial amount
+ of text. A copy that is not "Transparent" is called "Opaque".
+</p>
+
+<p>
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format, SGML
+ or XML using a publicly available DTD, and standard-conforming simple
+ HTML, PostScript or PDF designed for human modification. Examples of
+ transparent image formats include PNG, XCF and JPG. Opaque formats
+ include proprietary formats that can be read and edited only by
+ proprietary word processors, SGML or XML for which the DTD and/or
+ processing tools are not generally available, and the
+ machine-generated HTML, PostScript or PDF produced by some word
+ processors for output purposes only.
+</p>
+
+<p>
+ The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the material
+ this License requires to appear in the title page. For works in
+ formats which do not have any title page as such, "Title Page" means
+ the text near the most prominent appearance of the work's title,
+ preceding the beginning of the body of the text.
+</p>
+
+<p>
+ A section "Entitled XYZ" means a named subunit of the Document whose
+ title either is precisely XYZ or contains XYZ in parentheses following
+ text that translates XYZ in another language. (Here XYZ stands for a
+ specific section name mentioned below, such as "Acknowledgements",
+ "Dedications", "Endorsements", or "History".) To "Preserve the Title"
+ of such a section when you modify the Document means that it remains a
+ section "Entitled XYZ" according to this definition.
+</p>
+
+<p>
+ The Document may include Warranty Disclaimers next to the notice which
+ states that this License applies to the Document. These Warranty
+ Disclaimers are considered to be included by reference in this
+ License, but only as regards disclaiming warranties: any other
+ implication that these Warranty Disclaimers may have is void and has
+ no effect on the meaning of this License.
+</p>
+
+<p>
+ <strong>2. VERBATIM COPYING</strong>
+</p>
+
+<p>
+ You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License applies
+ to the Document are reproduced in all copies, and that you add no other
+ conditions whatsoever to those of this License. You may not use
+ technical measures to obstruct or control the reading or further
+ copying of the copies you make or distribute. However, you may accept
+ compensation in exchange for copies. If you distribute a large enough
+ number of copies you must also follow the conditions in section 3.
+</p>
+
+<p>
+ You may also lend copies, under the same conditions stated above, and
+ you may publicly display copies.
+</p>
+
+<p>
+ <strong>3. COPYING IN QUANTITY</strong>
+</p>
+
+<p>
+ If you publish printed copies (or copies in media that commonly have
+ printed covers) of the Document, numbering more than 100, and the
+ Document's license notice requires Cover Texts, you must enclose the
+ copies in covers that carry, clearly and legibly, all these Cover
+ Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+ the back cover. Both covers must also clearly and legibly identify
+ you as the publisher of these copies. The front cover must present
+ the full title with all words of the title equally prominent and
+ visible. You may add other material on the covers in addition.
+ Copying with changes limited to the covers, as long as they preserve
+ the title of the Document and satisfy these conditions, can be treated
+ as verbatim copying in other respects.
+</p>
+
+<p>
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto adjacent
+ pages.
+</p>
+
+<p>
+ If you publish or distribute Opaque copies of the Document numbering
+ more than 100, you must either include a machine-readable Transparent
+ copy along with each Opaque copy, or state in or with each Opaque copy
+ a computer-network location from which the general network-using
+ public has access to download using public-standard network protocols
+ a complete Transparent copy of the Document, free of added material.
+ If you use the latter option, you must take reasonably prudent steps,
+ when you begin distribution of Opaque copies in quantity, to ensure
+ that this Transparent copy will remain thus accessible at the stated
+ location until at least one year after the last time you distribute an
+ Opaque copy (directly or through your agents or retailers) of that
+ edition to the public.
+</p>
+
+<p>
+ It is requested, but not required, that you contact the authors of the
+ Document well before redistributing any large number of copies, to give
+ them a chance to provide you with an updated version of the Document.
+</p>
+
+<p>
+ <strong>4. MODIFICATIONS</strong>
+</p>
+
+<p>
+ You may copy and distribute a Modified Version of the Document under
+ the conditions of sections 2 and 3 above, provided that you release
+ the Modified Version under precisely this License, with the Modified
+ Version filling the role of the Document, thus licensing distribution
+ and modification of the Modified Version to whoever possesses a copy
+ of it. In addition, you must do these things in the Modified Version:
+</p>
+
+<ul>
+ <li><strong>A.</strong> Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.</li>
+ <li><strong>B.</strong> List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.</li>
+ <li><strong>C.</strong> State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.</li>
+ <li><strong>D.</strong> Preserve all the copyright notices of the Document.</li>
+ <li><strong>E.</strong> Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.</li>
+ <li><strong>F.</strong> Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.</li>
+ <li><strong>G.</strong> Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.</li>
+ <li><strong>H.</strong> Include an unaltered copy of this License.</li>
+ <li><strong>I.</strong> Preserve the section Entitled "History", Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.</li>
+ <li><strong>J.</strong> Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the "History" section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.</li>
+ <li><strong>K.</strong> For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.</li>
+ <li><strong>L.</strong> Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.</li>
+ <li><strong>M.</strong> Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.</li>
+ <li><strong>N.</strong> Do not retitle any existing section to be Entitled "Endorsements"
+ or to conflict in title with any Invariant Section.</li>
+ <li><strong>O.</strong> Preserve any Warranty Disclaimers.</li>
+</ul>
+
+<p>
+ If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no material
+ copied from the Document, you may at your option designate some or all
+ of these sections as invariant. To do this, add their titles to the
+ list of Invariant Sections in the Modified Version's license notice.
+ These titles must be distinct from any other section titles.
+</p>
+
+<p>
+ You may add a section Entitled "Endorsements", provided it contains
+ nothing but endorsements of your Modified Version by various
+ parties--for example, statements of peer review or that the text has
+ been approved by an organization as the authoritative definition of a
+ standard.
+</p>
+
+<p>
+ You may add a passage of up to five words as a Front-Cover Text, and a
+ passage of up to 25 words as a Back-Cover Text, to the end of the list
+ of Cover Texts in the Modified Version. Only one passage of
+ Front-Cover Text and one of Back-Cover Text may be added by (or
+ through arrangements made by) any one entity. If the Document already
+ includes a cover text for the same cover, previously added by you or
+ by arrangement made by the same entity you are acting on behalf of,
+ you may not add another; but you may replace the old one, on explicit
+ permission from the previous publisher that added the old one.
+</p>
+
+<p>
+ The author(s) and publisher(s) of the Document do not by this License
+ give permission to use their names for publicity for or to assert or
+ imply endorsement of any Modified Version.
+</p>
+
+<p>
+ <strong>5. COMBINING DOCUMENTS</strong>
+</p>
+
+<p>
+ You may combine the Document with other documents released under this
+ License, under the terms defined in section 4 above for modified
+ versions, provided that you include in the combination all of the
+ Invariant Sections of all of the original documents, unmodified, and
+ list them all as Invariant Sections of your combined work in its
+ license notice, and that you preserve all their Warranty Disclaimers.
+</p>
+
+<p>
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name but
+ different contents, make the title of each such section unique by
+ adding at the end of it, in parentheses, the name of the original
+ author or publisher of that section if known, or else a unique number.
+ Make the same adjustment to the section titles in the list of
+ Invariant Sections in the license notice of the combined work.
+</p>
+
+<p>
+ In the combination, you must combine any sections Entitled "History"
+ in the various original documents, forming one section Entitled
+ "History"; likewise combine any sections Entitled "Acknowledgements",
+ and any sections Entitled "Dedications". You must delete all sections
+ Entitled "Endorsements."
+</p>
+
+<p>
+ <strong>6. COLLECTIONS OF DOCUMENTS</strong>
+</p>
+
+<p>
+ You may make a collection consisting of the Document and other documents
+ released under this License, and replace the individual copies of this
+ License in the various documents with a single copy that is included in
+ the collection, provided that you follow the rules of this License for
+ verbatim copying of each of the documents in all other respects.
+</p>
+
+<p>
+ You may extract a single document from such a collection, and distribute
+ it individually under this License, provided you insert a copy of this
+ License into the extracted document, and follow this License in all
+ other respects regarding verbatim copying of that document.
+</p>
+
+<p>
+ <strong>7. AGGREGATION WITH INDEPENDENT WORKS</strong>
+</p>
+
+<p>
+ A compilation of the Document or its derivatives with other separate
+ and independent documents or works, in or on a volume of a storage or
+ distribution medium, is called an "aggregate" if the copyright
+ resulting from the compilation is not used to limit the legal rights
+ of the compilation's users beyond what the individual works permit.
+ When the Document is included in an aggregate, this License does not
+ apply to the other works in the aggregate which are not themselves
+ derivative works of the Document.
+</p>
+
+<p>
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one half of
+ the entire aggregate, the Document's Cover Texts may be placed on
+ covers that bracket the Document within the aggregate, or the
+ electronic equivalent of covers if the Document is in electronic form.
+ Otherwise they must appear on printed covers that bracket the whole
+ aggregate.
+</p>
+
+<p>
+ <strong>8. TRANSLATION</strong>
+</p>
+
+<p>
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section 4.
+ Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License, and all the license notices in the
+ Document, and any Warranty Disclaimers, provided that you also include
+ the original English version of this License and the original versions
+ of those notices and disclaimers. In case of a disagreement between
+ the translation and the original version of this License or a notice
+ or disclaimer, the original version will prevail.
+</p>
+
+<p>
+ If a section in the Document is Entitled "Acknowledgements",
+ "Dedications", or "History", the requirement (section 4) to Preserve
+ its Title (section 1) will typically require changing the actual
+ title.
+</p>
+
+<p>
+ <strong>9. TERMINATION</strong>
+</p>
+
+<p>
+ You may not copy, modify, sublicense, or distribute the Document except
+ as expressly provided for under this License. Any other attempt to
+ copy, modify, sublicense or distribute the Document is void, and will
+ automatically terminate your rights under this License. However,
+ parties who have received copies, or rights, from you under this
+ License will not have their licenses terminated so long as such
+ parties remain in full compliance.
+</p>
+
+<p>
+ <strong>10. FUTURE REVISIONS OF THIS LICENSE</strong>
+</p>
+
+<p>
+ The Free Software Foundation may publish new, revised versions
+ of the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ http://www.gnu.org/copyleft/.
+</p>
+
+<p>
+ Each version of the License is given a distinguishing version number.
+ If the Document specifies that a particular numbered version of this
+ License "or any later version" applies to it, you have the option of
+ following the terms and conditions either of that specified version or
+ of any later version that has been published (not as a draft) by the
+ Free Software Foundation. If the Document does not specify a version
+ number of this License, you may choose any version ever published (not
+ as a draft) by the Free Software Foundation.
+</p>
+
+<h3>How to use this License for your documents</h3>
+
+<p>
+ To use this License in a document you have written, include a copy of
+ the License in the document and put the following copyright and
+ license notices just after the title page:
+</p>
+
+<pre>
+ Copyright (c) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+</pre>
+
+<p>
+ If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+ replace the "with...Texts." line with this:
+</p>
+
+<pre>
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+</pre>
+
+<p>
+ If you have Invariant Sections without Cover Texts, or some other
+ combination of the three, merge those two alternatives to suit the
+ situation.
+</p>
+
+<p>
+ If your document contains nontrivial examples of program code, we
+ recommend releasing these examples in parallel under your choice of
+ free software license, such as the GNU General Public License,
+ to permit their use in free software.
+</p>
+ </BODY>
+</HTML>
diff --git a/doc/common/gpl-license.html b/doc/common/gpl-license.html
new file mode 100644
index 0000000..26ae3af
--- /dev/null
+++ b/doc/common/gpl-license.html
@@ -0,0 +1,381 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>GNU General Public License</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="GNU general public license (for inclusion in distributions)">
+ <META NAME="keywords" CONTENT="gnu, Gnu, GNU, license, licence, software, free software, software license, software licence, GNU general public license, GNU General Public License">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+<H1>GNU General Public License</H1>
+<P>Version 2, June 1991</P>
+
+<P>Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA<BR>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.</P>
+
+<H2>Preamble</H2>
+
+<P>The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.) You can apply it to
+your programs, too.</P>
+
+<P>When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.</P>
+
+<P>To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.</P>
+
+<P>For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.</P>
+
+<P>We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.</P>
+
+<P>Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.</P>
+
+<P>Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.</P>
+
+<P>The precise terms and conditions for copying, distribution and
+modification follow.</P>
+
+<H2><A NAME="show-c">GNU General Public License<BR>
+Terms And Conditions For Copying, Distribution And Modification</A></H2>
+
+<P>0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License. The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language. (Hereinafter, translation is included without limitation in
+the term "modification".) Each licensee is addressed as "you".</P>
+
+<P>Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.</P>
+
+<P>1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.</P>
+
+<P>You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.</P>
+
+<P>2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:</P>
+
+<OL STYLE="list-style-type: lower-alpha;">
+<LI>
+<P>You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.</P>
+</LI>
+
+<LI>
+<P>You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.</P>
+</LI>
+
+<LI>
+<P>If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License. (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)</P>
+</LI>
+</OL>
+
+<P>These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.</P>
+
+<P>Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.</P>
+
+<P>In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.</P>
+
+<P>3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:</P>
+
+<OL STYLE="list-style-type: lower-alpha;">
+<LI>
+<P>Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,</P>
+</LI>
+
+<LI>
+<P>Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,</P>
+</LI>
+
+<LI>
+<P>Accompany it with the information you received as to the offer
+to distribute corresponding source code. (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)</P>
+</LI>
+</OL>
+
+<P>The source code for a work means the preferred form of the work for
+making modifications to it. For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable. However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.</P>
+
+<P>If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.</P>
+
+<P>4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.</P>
+
+<P>5. You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Program or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.</P>
+
+<P>6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.</P>
+
+<P>7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.</P>
+
+<P>If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.</P>
+
+<P>It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.</P>
+
+<P>This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.</P>
+
+<P>8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.</P>
+
+<P>9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.</P>
+
+<P>Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.</P>
+
+<P>10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.</P>
+
+<H2><A NAME="show-w">No Warranty</A></H2>
+
+<P>11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.</P>
+
+<P>12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.</P>
+
+<DIV STYLE="text-align: center;">END OF TERMS AND CONDITIONS</DIV>
+
+<hr>
+
+<h2>How to Apply These Terms to Your New Programs</h2>
+
+<p>If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.</p>
+
+
+<p>To do so, attach the following notices to the program. It is
+safest to attach them to the start of each source file to most
+effectively convey the exclusion of warranty; and each file should
+have at least the "copyright" line and a pointer to where the full
+notice is found.</p>
+
+
+<pre> <one line to give the program's name and a brief idea of what it does.>
+ Copyright (C) 19yy <name of author>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA</pre>
+
+<p>Also add information on how to contact you by electronic and paper
+mail.</p>
+
+<p>If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:</p>
+
+<pre> Gnomovision version 69, Copyright (C) 19yy name of author
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.</pre>
+
+<p>The hypothetical commands "show w" and "show c" should show the appropriate
+parts of the General Public License. Of course, the commands you use may
+be called something other than "show w" and "show c"; they could even be
+mouse-clicks or menu items--whatever suits your program.</p>
+
+<p>You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. Here is a sample; alter the names:</p>
+
+<pre> Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+ `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+ <signature of Ty Coon>, 1 April 1989
+ Ty Coon, President of Vice</pre>
+
+<p>This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Library General
+Public License instead of this License.</p>
+
+
+
+ </BODY>
+</HTML>
diff --git a/doc/common/gpl-translated.html b/doc/common/gpl-translated.html
new file mode 100644
index 0000000..26ae3af
--- /dev/null
+++ b/doc/common/gpl-translated.html
@@ -0,0 +1,381 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>GNU General Public License</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="GNU general public license (for inclusion in distributions)">
+ <META NAME="keywords" CONTENT="gnu, Gnu, GNU, license, licence, software, free software, software license, software licence, GNU general public license, GNU General Public License">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+<H1>GNU General Public License</H1>
+<P>Version 2, June 1991</P>
+
+<P>Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA<BR>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.</P>
+
+<H2>Preamble</H2>
+
+<P>The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.) You can apply it to
+your programs, too.</P>
+
+<P>When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.</P>
+
+<P>To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.</P>
+
+<P>For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.</P>
+
+<P>We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.</P>
+
+<P>Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.</P>
+
+<P>Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.</P>
+
+<P>The precise terms and conditions for copying, distribution and
+modification follow.</P>
+
+<H2><A NAME="show-c">GNU General Public License<BR>
+Terms And Conditions For Copying, Distribution And Modification</A></H2>
+
+<P>0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License. The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language. (Hereinafter, translation is included without limitation in
+the term "modification".) Each licensee is addressed as "you".</P>
+
+<P>Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.</P>
+
+<P>1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.</P>
+
+<P>You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.</P>
+
+<P>2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:</P>
+
+<OL STYLE="list-style-type: lower-alpha;">
+<LI>
+<P>You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.</P>
+</LI>
+
+<LI>
+<P>You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.</P>
+</LI>
+
+<LI>
+<P>If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License. (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)</P>
+</LI>
+</OL>
+
+<P>These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.</P>
+
+<P>Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.</P>
+
+<P>In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.</P>
+
+<P>3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:</P>
+
+<OL STYLE="list-style-type: lower-alpha;">
+<LI>
+<P>Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,</P>
+</LI>
+
+<LI>
+<P>Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,</P>
+</LI>
+
+<LI>
+<P>Accompany it with the information you received as to the offer
+to distribute corresponding source code. (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)</P>
+</LI>
+</OL>
+
+<P>The source code for a work means the preferred form of the work for
+making modifications to it. For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable. However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.</P>
+
+<P>If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.</P>
+
+<P>4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.</P>
+
+<P>5. You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Program or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.</P>
+
+<P>6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.</P>
+
+<P>7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.</P>
+
+<P>If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.</P>
+
+<P>It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.</P>
+
+<P>This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.</P>
+
+<P>8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.</P>
+
+<P>9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.</P>
+
+<P>Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.</P>
+
+<P>10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.</P>
+
+<H2><A NAME="show-w">No Warranty</A></H2>
+
+<P>11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.</P>
+
+<P>12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.</P>
+
+<DIV STYLE="text-align: center;">END OF TERMS AND CONDITIONS</DIV>
+
+<hr>
+
+<h2>How to Apply These Terms to Your New Programs</h2>
+
+<p>If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.</p>
+
+
+<p>To do so, attach the following notices to the program. It is
+safest to attach them to the start of each source file to most
+effectively convey the exclusion of warranty; and each file should
+have at least the "copyright" line and a pointer to where the full
+notice is found.</p>
+
+
+<pre> <one line to give the program's name and a brief idea of what it does.>
+ Copyright (C) 19yy <name of author>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA</pre>
+
+<p>Also add information on how to contact you by electronic and paper
+mail.</p>
+
+<p>If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:</p>
+
+<pre> Gnomovision version 69, Copyright (C) 19yy name of author
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.</pre>
+
+<p>The hypothetical commands "show w" and "show c" should show the appropriate
+parts of the General Public License. Of course, the commands you use may
+be called something other than "show w" and "show c"; they could even be
+mouse-clicks or menu items--whatever suits your program.</p>
+
+<p>You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. Here is a sample; alter the names:</p>
+
+<pre> Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+ `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+ <signature of Ty Coon>, 1 April 1989
+ Ty Coon, President of Vice</pre>
+
+<p>This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Library General
+Public License instead of this License.</p>
+
+
+
+ </BODY>
+</HTML>
diff --git a/doc/common/kde-default.css b/doc/common/kde-default.css
new file mode 100644
index 0000000..6996496
--- /dev/null
+++ b/doc/common/kde-default.css
@@ -0,0 +1,341 @@
+/*
+ KDE-wide default CSS for HTML documentation (all media types).
+ Copyright (C) 2000 Frederik Fouvry
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+ Send comments, suggestions, etc. to Frederik Fouvry
+ <fouvry at sfs.nphil.uni-tuebingen.de>. */
+
+/*
+ Important note: these setting may be overridden by localised CSS. Do not
+ add here any localization-sensitive style declarations.
+
+ Any updates should be validated, e.g. https://jigsaw.w3.org/css-validator/ */
+
+/* Note: "should be inherit" means that in a proper browser inherit should work.
+ Somehow Netscape manages to interpret "inherit" as bright green.
+ Yuck. */
+
+body {
+ background: white none;
+ color: black;
+ font-family: sans-serif;
+ padding: 0 15px 0 0;
+ margin: 0;
+}
+
+.legalnotice, .copyright {
+ padding: 0;
+ margin: 0;
+}
+
+.abstract {
+ font-weight: bolder;
+ padding-right: 1em;
+}
+
+.toc, .list-of-tables {
+ padding-left: 1em;
+}
+
+.sect1, .chapter, .synopsis, .appendix, .preface, .article, .refsect1, .index, .glossary, .glossdiv, .gloss-article, .section {
+ padding-left: 1em;
+}
+
+.gloss-article, .glossdiv {
+ padding-right: 1em;
+}
+
+.toc .chapter {
+padding: 0em 0em 0em 1em;
+}
+
+.author {
+ color: rgb(82,80,82);
+ font-weight: bolder;
+ padding: 0;
+ margin: 0;
+}
+
+.othercredit {
+ line-height: 1em;
+}
+
+.chapter .sect1, .chapter .titlepage, .sect1 .titlepage, .article .titlepage {
+ padding: 0em;
+}
+
+.titlepage {
+ padding-left: 1em;
+ padding-right: 1em;
+}
+
+/* Nice link colors for the main text */
+
+:link {
+ color: #41597A;
+}
+
+a, :visited {
+ color: #597ba8;
+}
+
+.navLeft {
+ position: absolute;
+ left: 20px;
+}
+
+.navRight {
+ position: absolute;
+ right: 20px;
+}
+
+.navCenter {
+ text-align: center;
+ align: center;
+}
+
+.bannerBottomLeft {
+ position: absolute; left: 0px;
+}
+
+.bannerBottomRight {
+ position: absolute; right: 0px;
+}
+
+.header {
+ background: #54a3d8 none;
+ border-top: 1px solid white;
+ color: white;
+ font-size: small;
+ height: 1.7em;
+ line-height: 1em;
+ margin: 0px;
+ padding: 0px;
+ vertical-align: middle;
+}
+
+.bottom-nav {
+ background-color: #3E91EB;
+ border-bottom: 1px solid #206dcd;
+ border-top: 1px solid white;
+ color: white;
+ font-size: small;
+ height: 1.7em;
+ line-height: 1em;
+ margin: 0px;
+ padding-bottom: 0px;
+ padding-left: 1em;
+ padding-right: 0px;
+ padding-top: 10px;
+ vertical-align: middle;
+}
+
+/* A little bit of padding makes the tables for keybindings etc much easier to read */
+
+table {
+ padding: 5px;
+}
+
+dl {
+ margin-top: 0em;
+ margin-bottom: 0.5em;
+}
+
+dt {
+ margin-top: 1em;
+}
+div.toc dt {
+ margin-top: 0px;
+}
+div.screenshot {
+ margin-bottom: 1em;
+ margin-top: 1em;
+}
+
+div.informalexample {
+ border-style: dotted;
+ padding: 10px;
+}
+
+/* But no padding for navigation elements */
+
+.toplogo, .navbackground {
+ padding: 0px;
+}
+
+table.programlisting
+table.screen {
+ border-style: none;
+ background-color: rgb(224,224,224);
+ table-layout: auto; /* 100%? */
+ color: rgb(0,0,0); /* should be inherit */
+}
+
+/* Same as previous block, but more general (previous is HTML only)
+ Not all browsers understand this yet.
+ TABLE[class~=programlisting]
+ TABLE[class~=screen] { border-style: none;
+ background-color: rgb(224,224,224);
+ table-layout: auto;
+ color: inherit;
+}
+*/
+
+p {
+ text-align: justify;
+}
+
+/* More specific settings */
+/* Temporary patch: browsers break on bad HTML */
+/* P, H1, H2, H3, H4, H5, TD, TH { font-family: Helvetica, Arial, sans-serif;
+ } */
+
+p, h1, h2, h3, h4, h5, h6, td, th {
+ font-family: sans-serif;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color: #525052;
+ background-color: transparent;
+ font-weight: 550;
+}
+
+h1,h2,h3 {
+ line-height: 1.5em;
+}
+
+/* Visual cues for GUI elements etc in the text */
+
+.guimenu, .guimenuitem, .guisubmenu {
+ background-color: rgb(220,220,220);
+ color: rgb(0,0,0); /* should be inherit */
+}
+
+.guilabel, .interface, .guibutton, .guiicon {
+ background-color: rgb(220,220,220);
+ color: rgb(0,0,0); /* should be inherit */
+}
+
+.shortcut {
+ background-color: rgb(220,220,220);
+ color: rgb(0,0,0); /* should be inherit */
+}
+
+.shortcut .keycap {
+ background-color: rgb(220,220,220);
+ color: rgb(0,0,0); /* should be inherit */
+}
+
+.keycap {
+ margin-left: 4px;
+}
+
+.question {
+ font-weight: bolder;
+}
+
+.accel {
+ background-color: rgb(220,220,220);
+ color: rgb(0,0,0);
+ text-decoration: underline;
+}
+
+.option, .command {
+ background-color: rgb(255,255,255);
+ color: rgb(0,96,160);
+ font-weight: bold;
+}
+
+.arg, .parameter, .replaceable {
+ background-color: rgb(255,255,255);
+ color: rgb(0,128,64);
+ font-style: italic;
+}
+
+.screen, .programlisting {
+ background-color: rgb(220,220,220);
+ color: rgb(0,0,0); /* should be inherit */
+ border-style: dotted;
+ border-color: rgb(0,0,0);
+ border-width: thin;
+ padding: 5px;
+}
+
+
+/* This one is set in inches because the admonitions are set in inches
+ and they're more difficult to change. We can live with it in here,
+ for the meantime, it gives consistent margins */
+
+.example {
+ margin-left: 0.5in;
+ margin-right: 0.5in;
+}
+
+div.mediaobject, div.mediaobjectco {
+ /* float: right; */
+ /* might make it much nicer. although someone has to
+ understand the rules ;-) You also don't want it to be
+ surrounded by text it doesn't refer to ... But that
+ may be among others a question of writing style. */
+ text-align: center; /* a bit of a hack: it should
+ position _images_ */
+}
+
+.caption {
+ margin: 0em 2em 0em 2em;
+ text-align: center;
+}
+
+.inlinemediaobject {
+ vertical-align: baseline;
+}
+
+/* An idea that could be nice: a search engine looking for specific
+classes could display them in some conspicuous color. All that is
+needed is an on the fly generated style element/style sheet. */
+
+/* Only used in the hand-made HTML license texts */
+body.license {
+ background-color: rgb(255,255,255);
+ text-align: justify;
+ color: rgb(0,0,0);
+}
+pre.license {
+ background-color: rgb(255,255,255);
+ font-family: monospace;
+ color: rgb(0,0,0);
+}
+code.email {
+ font-size: 87.5%;
+ color: #e83e8c;
+ word-break: break-word;
+}
+a {
+ color: #007bff;
+ text-decoration: none;
+ background-color: transparent;
+}
+a:hover {
+ color: #0056b3;
+ text-decoration: underline;
+}
+dt {
+ font-weight: 500;
+}
+.date {
+ margin-right: 4px;
+}
diff --git a/doc/common/kde-docs.css b/doc/common/kde-docs.css
new file mode 100644
index 0000000..d9275a7
--- /dev/null
+++ b/doc/common/kde-docs.css
@@ -0,0 +1,329 @@
+/*
+ * kde-docs.css -- Style sheets for the KDE documentation generated
+ * HTML.
+ *
+ * Started by Michael Pyne <mpyne at kde.org>
+ */
+html, body {
+ padding: 0;
+ width: 100%;
+ height: 100%;
+ font-size: 1rem;
+ font-weight: 400;
+ line-height: 1.5;
+ color: #212529;
+ text-align: left;
+}
+
+/* These two divs force the content to fill up at least the viewport, which
+ * is needed in order to force the footer to the bottom of short pages.
+ */
+#content {
+ min-height: 100%;
+ position: relative;
+}
+
+#contentBody {
+ padding: 0;
+ padding-bottom: 1em;
+ margin: 0;
+ width: 100%;
+}
+
+/* This is for the header's navigation bar */
+#content > .navCenter {
+ background: #F8F8F8;
+ border-bottom: 1px solid #DDD;
+}
+
+/* Standard nav bar elements */
+div.navCenter table {
+ empty-cells: show;
+ border: 0px;
+ width: 100%;
+}
+
+div.navCenter td {
+ font-weight: normal;
+}
+
+div.navCenter td.prevCell {
+ padding-left: 20px;
+ text-align: left;
+}
+
+div.navCenter td.nextCell {
+ padding-right: 20px;
+ text-align: right;
+}
+
+div.navCenter td.upCell {
+ text-align: center;
+}
+
+/* Actual documentation styling */
+div.table table {
+ text-align: left; /* Disable justification */
+ border: 1px solid black;
+ border-collapse: collapse;
+}
+
+/* Give alternating row colors */
+div.table tr:nth-child(odd) {
+ background-color: #eee;
+}
+
+div.table tr:nth-child(even) {
+ background-color: white;
+}
+
+div.table th {
+ background-color: white;
+ font-weight: normal;
+ text-align: center;
+ vertical-align: middle;
+ border-bottom: 1px solid black;
+}
+
+div.table td {
+ text-align: left;
+ padding: 4px;
+}
+
+div.tip, div.note, div.warning, div.important {
+ padding: 6pt;
+ padding-top: 3pt;
+ border-radius: 3px;
+}
+
+div.tip > .title, div.warning > .title, div.note > .title, div.important > .title {
+ font-weight: 550;
+}
+
+div.tip {
+ border: 2px solid #3daee9;
+ background: #cbe3ef;
+}
+
+div.important {
+ border: 2px solid #f67400;
+ background: #f0d7c1;
+}
+
+div.note {
+ border: 2px solid #27ae60;
+ background: #c7e2d4;
+}
+
+div.warning {
+ border: 2px solid #da4453;
+ background: #ebced1;
+}
+
+/* Make the content wrapping div have a nice margin. */
+body div.chapter, body div.sect1, body div.book, body div.article {
+ margin-left: 2em;
+ margin-right: 2em;
+}
+
+div.sect2 {
+ width: 100%;
+}
+
+.programlisting, pre.screen {
+ -khtml-border-radius: 7px;
+
+ /* This will work someday */
+ border-radius: 7px;
+
+ /* To support border radius on our OSS browser friends when
+ * viewing online */
+ -webkit-border-radius: 7px;
+ -moz-border-radius: 7px;
+}
+
+.programlisting {
+ border: 1px solid black;
+ background: white;
+}
+
+.guimenu, .guimenuitem, .guisubmenu,
+.guilabel, .interface, .guibutton {
+ background-color: rgb(220, 220, 220);
+ color: black;
+ border: 1px solid rgb(190, 190, 190);
+
+ -khtml-border-radius: 3px;
+ -moz-border-radius: 3px;
+ -webkit-border-radius: 3px;
+ border-radius: 3px;
+}
+
+.shortcut {
+ background-color: #DDF;
+ border: 1px dotted #BBF;
+ font-weight: normal;
+
+ -khtml-border-radius: 2px;
+ -moz-border-radius: 2px;
+ -webkit-border-radius: 2px;
+ border-radius: 2px;
+}
+
+.keycap, .keysym {
+ background-color: #DFDFFF;
+ font-weight: bold;
+
+ -khtml-border-radius: 2px;
+ -moz-border-radius: 2px;
+ -webkit-border-radius: 2px;
+ border-radius: 2px;
+}
+
+pre.screen {
+ border: 2px solid gray;
+ background: black;
+
+ color: white;
+ font-weight: normal;
+ font-family: monospace;
+}
+
+/* Make a screen black on white */
+pre.screen * {
+ color: white;
+ background: black;
+ font-weight: normal;
+ font-family: monospace;
+}
+
+pre.screen .userinput {
+ color: green;
+}
+
+.informalexample {
+ margin: 0px;
+ padding: 0px;
+ border: 0px;
+ border-left: 1px dotted black;
+ padding-left: 4px;
+}
+
+div.tip {
+ margin-bottom: 12pt;
+}
+
+div.tip:last-child() {
+ margin-bottom: 0pt;
+}
+
+pre:last-child() {
+ margin-bottom: 0px;
+}
+
+div.titlepage {
+ margin-left: 0px;
+}
+
+h3.title {
+ margin-left: 0cm;
+}
+
+.screenshot, .informalfigure {
+ border: 1px solid gray;
+ background-color: rgb(240,240,240);
+}
+
+/* We no longer render <hr>s around <mediaobject>s, but this hides them in case
+ * old generated HTML is displayed with the new style.
+ */
+.mediaobject hr, .mediaobjectco hr {
+ display: none;
+}
+
+/*
+ * This gives us the styling for the header and footer.
+ * See customization/kde-navig.xsl for where it's used.
+ */
+#header {
+ width: 100%;
+ height: 51px;
+ color: white;
+ font-height: 3em;
+ background: #54a3d8;
+}
+
+#header_content {
+ margin-left: 1em;
+ background: white;
+ height: 47px;
+}
+#header_left {
+ background: #54a3d8;
+ display: inline-block;
+ height: 47px;
+ padding-right: 1em;
+}
+
+#header_right img {
+ position: relative;
+ top: 8px; /* Vertically center */
+}
+
+/* Used for the text and footer area at the bottom. */
+#footer {
+ width: 100%;
+ background-color: #eeeeee;
+ border: 0px;
+
+ /* Force footer to bottom of viewport/page */
+ /* Either should be position:fixed to stay always at the bottom of the viewport, or
+ removed to be at the bottom of the page. I chose bottom of the page.
+ position: absolute; */
+ bottom: 0;
+ height: 8.7em;
+}
+
+#footer_text {
+ text-align:center;
+ vertical-align: middle;
+ padding-top: 12pt;
+}
+
+#footer .navCenter {
+ border-top: 1px solid #DDD;
+ border-bottom: 1px solid #AAA;
+}
+
+/* Two rows on this navCenter, so make the cells equal width */
+#footer .navCenter td {
+ width: 33%;
+}
+
+a.footer_email {
+ color: #282828;
+ text-decoration: underline;
+}
+
+ at media print {
+ #header_right {
+ color: black;
+ text-shadow: gray 2px 2px 2px;
+ }
+
+ .navCenter {
+ display: none;
+ }
+
+ #footer {
+ border-top: 1px solid #DDD;
+ }
+}
+
+img {
+ max-width: 100%;
+}
+
+.productname {
+ margin-left: 5px;
+}
diff --git a/doc/common/kde_logo.png b/doc/common/kde_logo.png
new file mode 100644
index 0000000..336bfd8
Binary files /dev/null and b/doc/common/kde_logo.png differ
diff --git a/doc/common/kde_logo_bg.png b/doc/common/kde_logo_bg.png
new file mode 100644
index 0000000..40df05f
Binary files /dev/null and b/doc/common/kde_logo_bg.png differ
diff --git a/doc/common/kmenu.png b/doc/common/kmenu.png
new file mode 100644
index 0000000..fc7fb40
Binary files /dev/null and b/doc/common/kmenu.png differ
diff --git a/doc/common/lgpl-license.html b/doc/common/lgpl-license.html
new file mode 100644
index 0000000..343576d
--- /dev/null
+++ b/doc/common/lgpl-license.html
@@ -0,0 +1,502 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>GNU Lesser General Public License</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="GNU lesser general public license (for inclusion in library distributions)">
+ <META NAME="keywords" CONTENT="gnu, Gnu, GNU, license, licence, software, free software, software license, software licence, GNU general public license, GNU General Public License, library licence, library license, software library, software libraries, GNU lesser general public license, GNU Lesser General Public License">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+<H1>GNU LESSER GENERAL PUBLIC LICENSE</H1>
+<P>Version 2.1, February 1999</P>
+
+<P>Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA<BR>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.</P>
+
+<P>[This is the first released version of the Lesser GPL. It also counts
+as the successor of the GNU Library Public License, version 2, hence
+the version number 2.1.]</P>
+
+<H2>Preamble</H2>
+
+<P>The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.</P>
+
+<P>This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it. You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations below.</P>
+
+<P>When we speak of free software, we are referring to freedom of use,
+not price. Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.</P>
+
+<P>To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights. These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.</P>
+
+<P>For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you. You must make sure that they, too, receive or can get the source
+code. If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it. And you must show them these terms so they know their rights.</P>
+
+<P>We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.</P>
+
+<P>To protect each distributor, we want to make it very clear that
+there is no warranty for the free library. Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.</P>
+
+<P>Finally, software patents pose a constant threat to the existence of
+any free program. We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder. Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.</P>
+
+<P>Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License. This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License. We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.</P>
+
+<P>When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library. The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom. The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.</P>
+
+<P>We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License. It also provides other free software developers Less
+of an advantage over competing non-free programs. These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries. However, the Lesser license provides advantages in certain
+special circumstances.</P>
+
+<P>For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard. To achieve this, non-free programs must be
+allowed to use the library. A more frequent case is that a free
+library does the same job as widely used non-free libraries. In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.</P>
+
+<P>In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software. For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.</P>
+
+<P>Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.</P>
+
+<P>The precise terms and conditions for copying, distribution and
+modification follow. Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library". The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.</P>
+
+<H2>GNU Lesser General Public License<BR>
+Terms And Conditions For Copying, Distribution And Modification</H2>
+
+<P>0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".</P>
+
+<P>A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.</P>
+
+<P>The "Library", below, refers to any such software library or work
+which has been distributed under these terms. A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language. (Hereinafter, translation is
+included without limitation in the term "modification".)</P>
+
+<P>"Source code" for a work means the preferred form of the work for
+making modifications to it. For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.</P>
+
+<P>Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it). Whether that is true depends on what the Library does
+and what the program that uses the Library does.</P>
+
+<P>1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.</P>
+
+<P>You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.</P>
+
+<P>2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:</P>
+
+<OL STYLE="list-style-type: lower-alpha;">
+<LI>
+<P>The modified work must itself be a software library.</P>
+</LI>
+
+<LI>
+<P>You must cause the files modified to carry prominent notices
+stating that you changed the files and the date of any change.</P>
+</LI>
+
+<LI>
+<P>You must cause the whole of the work to be licensed at no
+charge to all third parties under the terms of this License.</P>
+</LI>
+
+<LI>
+<P>If a facility in the modified Library refers to a function or a
+table of data to be supplied by an application program that uses
+the facility, other than as an argument passed when the facility
+is invoked, then you must make a good faith effort to ensure that,
+in the event an application does not supply such function or
+table, the facility still operates, and performs whatever part of
+its purpose remains meaningful.</P>
+
+<P>(For example, a function in a library to compute square roots has
+a purpose that is entirely well-defined independent of the
+application. Therefore, Subsection 2d requires that any
+application-supplied function or table used by this function must
+be optional: if the application does not supply it, the square
+root function must still compute square roots.)</P>
+</LI>
+</OL>
+
+<P>These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.</P>
+
+<P>Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.</P>
+
+<P>In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.</P>
+
+<P>3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library. To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License. (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.) Do not make any other change in
+these notices.</P>
+
+<P>Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.</P>
+
+<P>This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.</P>
+
+<P>4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.</P>
+
+<P>If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.</P>
+
+<P>5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library". Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.</P>
+
+<P>However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library". The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.</P>
+
+<P>When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library. The
+threshold for this to be true is not precisely defined by law.</P>
+
+<P>If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work. (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)</P>
+
+<P>Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.</P>
+
+<P>6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.</P>
+
+<P>You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License. You must supply a copy of this License. If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License. Also, you must do one
+of these things:</P>
+
+<OL STYLE="list-style-type: lower-alpha;">
+<LI>
+<P>Accompany the work with the complete corresponding
+machine-readable source code for the Library including whatever
+changes were used in the work (which must be distributed under
+Sections 1 and 2 above); and, if the work is an executable linked
+with the Library, with the complete machine-readable "work that
+uses the Library", as object code and/or source code, so that the
+user can modify the Library and then relink to produce a modified
+executable containing the modified Library. (It is understood
+that the user who changes the contents of definitions files in the
+Library will not necessarily be able to recompile the application
+to use the modified definitions.)</P>
+</LI>
+
+<LI>
+<P>Use a suitable shared library mechanism for linking with the
+Library. A suitable mechanism is one that (1) uses at run time a
+copy of the library already present on the user's computer system,
+rather than copying library functions into the executable, and (2)
+will operate properly with a modified version of the library, if
+the user installs one, as long as the modified version is
+interface-compatible with the version that the work was made with.</P>
+</LI>
+
+<LI>
+<P>Accompany the work with a written offer, valid for at
+least three years, to give the same user the materials
+specified in Subsection 6a, above, for a charge no more
+than the cost of performing this distribution.</P>
+</LI>
+
+<LI>
+<P>If distribution of the work is made by offering access to copy
+from a designated place, offer equivalent access to copy the above
+specified materials from the same place.</P>
+</LI>
+
+<LI>
+<P>Verify that the user has already received a copy of these
+materials or that you have already sent this user a copy.</P>
+</LI>
+</OL>
+
+<P>For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it. However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.</P>
+
+<P>It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system. Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.</P>
+
+<P>7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:</P>
+
+<OL STYLE="list-style-type: lower-alpha;">
+<LI>
+<P>Accompany the combined library with a copy of the same work
+based on the Library, uncombined with any other library
+facilities. This must be distributed under the terms of the
+Sections above.</P>
+</LI>
+
+<LI>
+<P>Give prominent notice with the combined library of the fact
+that part of it is a work based on the Library, and explaining
+where to find the accompanying uncombined form of the same work.</P>
+</LI>
+</OL>
+
+<P>8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License. Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License. However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.</P>
+
+<P>9. You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Library or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.</P>
+
+<P>10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.</P>
+
+<P>11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all. For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.</P>
+
+<P>If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.</P>
+
+<P>It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.</P>
+
+<P>This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.</P>
+
+<P>12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded. In such case, this License incorporates the limitation as if
+written in the body of this License.</P>
+
+<P>13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.</P>
+
+<P>Each version is given a distinguishing version number. If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation. If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.</P>
+
+<P>14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission. For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this. Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.</P>
+
+<H2>No Warranty</H2>
+
+<P>15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</P>
+
+<P>16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.</P>
+
+<DIV STYLE="text-align: center;">END OF TERMS AND CONDITIONS</DIV>
+ </BODY>
+</HTML>
diff --git a/doc/common/lgpl-translated.html b/doc/common/lgpl-translated.html
new file mode 100644
index 0000000..343576d
--- /dev/null
+++ b/doc/common/lgpl-translated.html
@@ -0,0 +1,502 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>GNU Lesser General Public License</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="GNU lesser general public license (for inclusion in library distributions)">
+ <META NAME="keywords" CONTENT="gnu, Gnu, GNU, license, licence, software, free software, software license, software licence, GNU general public license, GNU General Public License, library licence, library license, software library, software libraries, GNU lesser general public license, GNU Lesser General Public License">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+<H1>GNU LESSER GENERAL PUBLIC LICENSE</H1>
+<P>Version 2.1, February 1999</P>
+
+<P>Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA<BR>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.</P>
+
+<P>[This is the first released version of the Lesser GPL. It also counts
+as the successor of the GNU Library Public License, version 2, hence
+the version number 2.1.]</P>
+
+<H2>Preamble</H2>
+
+<P>The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.</P>
+
+<P>This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it. You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations below.</P>
+
+<P>When we speak of free software, we are referring to freedom of use,
+not price. Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.</P>
+
+<P>To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights. These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.</P>
+
+<P>For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you. You must make sure that they, too, receive or can get the source
+code. If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it. And you must show them these terms so they know their rights.</P>
+
+<P>We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.</P>
+
+<P>To protect each distributor, we want to make it very clear that
+there is no warranty for the free library. Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.</P>
+
+<P>Finally, software patents pose a constant threat to the existence of
+any free program. We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder. Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.</P>
+
+<P>Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License. This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License. We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.</P>
+
+<P>When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library. The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom. The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.</P>
+
+<P>We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License. It also provides other free software developers Less
+of an advantage over competing non-free programs. These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries. However, the Lesser license provides advantages in certain
+special circumstances.</P>
+
+<P>For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard. To achieve this, non-free programs must be
+allowed to use the library. A more frequent case is that a free
+library does the same job as widely used non-free libraries. In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.</P>
+
+<P>In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software. For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.</P>
+
+<P>Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.</P>
+
+<P>The precise terms and conditions for copying, distribution and
+modification follow. Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library". The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.</P>
+
+<H2>GNU Lesser General Public License<BR>
+Terms And Conditions For Copying, Distribution And Modification</H2>
+
+<P>0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".</P>
+
+<P>A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.</P>
+
+<P>The "Library", below, refers to any such software library or work
+which has been distributed under these terms. A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language. (Hereinafter, translation is
+included without limitation in the term "modification".)</P>
+
+<P>"Source code" for a work means the preferred form of the work for
+making modifications to it. For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.</P>
+
+<P>Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it). Whether that is true depends on what the Library does
+and what the program that uses the Library does.</P>
+
+<P>1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.</P>
+
+<P>You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.</P>
+
+<P>2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:</P>
+
+<OL STYLE="list-style-type: lower-alpha;">
+<LI>
+<P>The modified work must itself be a software library.</P>
+</LI>
+
+<LI>
+<P>You must cause the files modified to carry prominent notices
+stating that you changed the files and the date of any change.</P>
+</LI>
+
+<LI>
+<P>You must cause the whole of the work to be licensed at no
+charge to all third parties under the terms of this License.</P>
+</LI>
+
+<LI>
+<P>If a facility in the modified Library refers to a function or a
+table of data to be supplied by an application program that uses
+the facility, other than as an argument passed when the facility
+is invoked, then you must make a good faith effort to ensure that,
+in the event an application does not supply such function or
+table, the facility still operates, and performs whatever part of
+its purpose remains meaningful.</P>
+
+<P>(For example, a function in a library to compute square roots has
+a purpose that is entirely well-defined independent of the
+application. Therefore, Subsection 2d requires that any
+application-supplied function or table used by this function must
+be optional: if the application does not supply it, the square
+root function must still compute square roots.)</P>
+</LI>
+</OL>
+
+<P>These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.</P>
+
+<P>Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.</P>
+
+<P>In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.</P>
+
+<P>3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library. To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License. (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.) Do not make any other change in
+these notices.</P>
+
+<P>Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.</P>
+
+<P>This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.</P>
+
+<P>4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.</P>
+
+<P>If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.</P>
+
+<P>5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library". Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.</P>
+
+<P>However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library". The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.</P>
+
+<P>When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library. The
+threshold for this to be true is not precisely defined by law.</P>
+
+<P>If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work. (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)</P>
+
+<P>Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.</P>
+
+<P>6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.</P>
+
+<P>You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License. You must supply a copy of this License. If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License. Also, you must do one
+of these things:</P>
+
+<OL STYLE="list-style-type: lower-alpha;">
+<LI>
+<P>Accompany the work with the complete corresponding
+machine-readable source code for the Library including whatever
+changes were used in the work (which must be distributed under
+Sections 1 and 2 above); and, if the work is an executable linked
+with the Library, with the complete machine-readable "work that
+uses the Library", as object code and/or source code, so that the
+user can modify the Library and then relink to produce a modified
+executable containing the modified Library. (It is understood
+that the user who changes the contents of definitions files in the
+Library will not necessarily be able to recompile the application
+to use the modified definitions.)</P>
+</LI>
+
+<LI>
+<P>Use a suitable shared library mechanism for linking with the
+Library. A suitable mechanism is one that (1) uses at run time a
+copy of the library already present on the user's computer system,
+rather than copying library functions into the executable, and (2)
+will operate properly with a modified version of the library, if
+the user installs one, as long as the modified version is
+interface-compatible with the version that the work was made with.</P>
+</LI>
+
+<LI>
+<P>Accompany the work with a written offer, valid for at
+least three years, to give the same user the materials
+specified in Subsection 6a, above, for a charge no more
+than the cost of performing this distribution.</P>
+</LI>
+
+<LI>
+<P>If distribution of the work is made by offering access to copy
+from a designated place, offer equivalent access to copy the above
+specified materials from the same place.</P>
+</LI>
+
+<LI>
+<P>Verify that the user has already received a copy of these
+materials or that you have already sent this user a copy.</P>
+</LI>
+</OL>
+
+<P>For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it. However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.</P>
+
+<P>It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system. Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.</P>
+
+<P>7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:</P>
+
+<OL STYLE="list-style-type: lower-alpha;">
+<LI>
+<P>Accompany the combined library with a copy of the same work
+based on the Library, uncombined with any other library
+facilities. This must be distributed under the terms of the
+Sections above.</P>
+</LI>
+
+<LI>
+<P>Give prominent notice with the combined library of the fact
+that part of it is a work based on the Library, and explaining
+where to find the accompanying uncombined form of the same work.</P>
+</LI>
+</OL>
+
+<P>8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License. Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License. However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.</P>
+
+<P>9. You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Library or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.</P>
+
+<P>10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.</P>
+
+<P>11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all. For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.</P>
+
+<P>If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.</P>
+
+<P>It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.</P>
+
+<P>This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.</P>
+
+<P>12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded. In such case, this License incorporates the limitation as if
+written in the body of this License.</P>
+
+<P>13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.</P>
+
+<P>Each version is given a distinguishing version number. If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation. If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.</P>
+
+<P>14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission. For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this. Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.</P>
+
+<H2>No Warranty</H2>
+
+<P>15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</P>
+
+<P>16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.</P>
+
+<DIV STYLE="text-align: center;">END OF TERMS AND CONDITIONS</DIV>
+ </BODY>
+</HTML>
diff --git a/doc/common/part_of_the_kde_family_horizontal_190.png b/doc/common/part_of_the_kde_family_horizontal_190.png
new file mode 100644
index 0000000..566d6b6
Binary files /dev/null and b/doc/common/part_of_the_kde_family_horizontal_190.png differ
diff --git a/doc/common/qpl-license.html b/doc/common/qpl-license.html
new file mode 100644
index 0000000..19a863b
--- /dev/null
+++ b/doc/common/qpl-license.html
@@ -0,0 +1,164 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>The Q Public License - version 1.0</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="Q Public License">
+ <META NAME="keywords" CONTENT="Q, q, Q Public License, Q public license, q public license, public license, Q Public Licence, Q public licence, q public licence, public licence, license, licence, software, softwarelicense, Troll, troll, Troll License, troll license, Troll Licence, troll licence">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+ <H1>The Q Public License</H1>
+ <P>version 1.0</P>
+
+ <P>Copyright (C) 1999-2000 Troll Tech AS, Norway.<BR>
+ Everyone is permitted to copy and distribute this license
+ document.
+ </P>
+
+ <P>The intent of this license is to establish freedom to share and
+ change the software regulated by this license under the open
+ source model.</P>
+
+ <P>This license applies to any software containing a notice placed
+ by the copyright holder saying that it may be distributed under
+ the terms of the Q Public License version 1.0. Such software is
+ herein referred to as the Software. This license covers
+ modification and distribution of the Software, use of
+ third-party application programs based on the Software, and
+ development of free software which uses the Software.</P>
+
+ <H2>Granted Rights</H2>
+
+ <OL STYLE="list-style-type: decimal;">
+ <LI>
+ <P>You are granted the non-exclusive rights set forth in this
+ license provided you agree to and comply with any and all
+ conditions in this license. Whole or partial distribution
+ of the Software, or software items that link with the
+ Software, in any form signifies acceptance of this
+ license.</P>
+ </LI>
+
+ <LI>
+ <P>You may copy and distribute the Software in unmodified form
+ provided that the entire package, including - but not
+ restricted to - copyright, trademark notices and
+ disclaimers, as released by the initial developer of the
+ Software, is distributed.</P></LI>
+
+ <LI>
+ <P>You may make modifications to the Software and distribute
+ your modifications, in a form that is separate from the
+ Software, such as patches. The following restrictions apply
+ to modifications:</P>
+
+ <OL STYLE="list-style-type: lower-alpha;">
+ <LI>
+ <P>Modifications must not alter or remove any copyright
+ notices in the Software.</P></LI>
+ <LI>
+ <P>When modifications to the Software are released under
+ this license, a non-exclusive royalty-free right is
+ granted to the initial developer of the Software to
+ distribute your modification in future versions of the
+ Software provided such versions remain available under
+ these terms in addition to any other license(s) of the
+ initial developer.</P>
+ </LI>
+ </OL>
+
+ <LI>
+ <P>You may distribute machine-executable forms of the Software
+ or machine-executable forms of modified versions of the
+ Software, provided that you meet these restrictions:</P>
+
+ <OL STYLE="list-style-type: lower-alpha;">
+ <LI>
+ <P>You must include this license document in the
+ distribution.</P>
+ </LI>
+
+ <LI>
+ <P>You must ensure that all recipients of the
+ machine-executable forms are also able to receive the
+ complete machine-readable source code to the distributed
+ Software, including all modifications, without any
+ charge beyond the costs of data transfer, and place
+ prominent notices in the distribution explaining
+ this.</P>
+ </LI>
+
+ <LI>
+ <P>You must ensure that all modifications included in the
+ machine-executable forms are available under the terms
+ of this license.</P>
+ </LI>
+ </OL>
+ </LI>
+
+ <LI>
+ <P>You may use the original or modified versions of the
+ Software to compile, link and run application programs
+ legally developed by you or by others.</P>
+ </LI>
+
+ <LI>
+ <P>You may develop application programs, reusable components
+ and other software items that link with the original or
+ modified versions of the Software. These items, when
+ distributed, are subject to the following requirements:</P>
+
+ <OL STYLE="list-style-type: lower-alpha;">
+ <LI>
+ <P>You must ensure that all recipients of
+ machine-executable forms of these items are also able to
+ receive and use the complete machine-readable source
+ code to the items without any charge beyond the costs of
+ data transfer.</P>
+ </LI>
+
+ <LI>
+ <P>You must explicitly license all recipients of your
+ items to use and re-distribute original and modified
+ versions of the items in both machine-executable and
+ source code forms. The recipients must be able to do so
+ without any charges whatsoever, and they must be able to
+ re-distribute to anyone they choose.</P>
+ </LI>
+
+ <LI>
+ <P>If the items are not available to the general public,
+ and the initial developer of the Software requests a
+ copy of the items, then you must supply one.</P>
+ </LI>
+ </OL>
+ </LI>
+ </OL>
+
+ <H2>Limitations of Liability</H2>
+
+ <P>In no event shall the initial developers or copyright holders
+ be liable for any damages whatsoever, including - but not
+ restricted to - lost revenue or profits or other direct,
+ indirect, special, incidental or consequential damages, even if
+ they have been advised of the possibility of such damages,
+ except to the extent invariable law, if any, provides
+ otherwise.</P>
+
+ <H2>No Warranty</H2>
+
+ <P>The Software and this license document are provided AS IS with
+ NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN,
+ MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.</P>
+
+ <H2>Choice of Law</H2>
+
+ <P>This license is governed by the Laws of Norway. Disputes shall
+ be settled by Oslo City Court.</P>
+ </BODY>
+</HTML>
diff --git a/doc/common/top-kde.jpg b/doc/common/top-kde.jpg
new file mode 100644
index 0000000..31323b1
Binary files /dev/null and b/doc/common/top-kde.jpg differ
diff --git a/doc/common/top-left.jpg b/doc/common/top-left.jpg
new file mode 100644
index 0000000..23c31c7
Binary files /dev/null and b/doc/common/top-left.jpg differ
diff --git a/doc/common/top-right.jpg b/doc/common/top-right.jpg
new file mode 100644
index 0000000..22d2a29
Binary files /dev/null and b/doc/common/top-right.jpg differ
diff --git a/doc/common/top.jpg b/doc/common/top.jpg
new file mode 100644
index 0000000..8be8caa
Binary files /dev/null and b/doc/common/top.jpg differ
diff --git a/doc/common/x11-license.html b/doc/common/x11-license.html
new file mode 100644
index 0000000..444a27b
--- /dev/null
+++ b/doc/common/x11-license.html
@@ -0,0 +1,45 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html40/strict.dtd">
+<HTML LANG="en-US">
+ <HEAD>
+ <TITLE>X Window System License - X11R6.4</TITLE>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-US">
+ <META NAME="description" CONTENT="X Window System License - X11R6.4">
+ <META NAME="keywords" CONTENT="X, x, X Window, x window, X Windows, x windows, X Window System License, x window system license, X Window System Licence, x window system licence, X11R6.4, x11r6.4, x11r64, license, licence, software, softwarelicense">
+ <META NAME="robots" CONTENT="none">
+ <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+ <LINK REL="stylesheet" HREF="kde-default.css" TYPE="text/css">
+ </HEAD>
+ <BODY CLASS="license">
+ <H1>X Window System License - X11R6.4</H1>
+
+ <P>Copyright (c) 1998 The Open Group</P>
+
+ <P>Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation files
+(the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software,
+and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:</P>
+
+ <P>The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.</P>
+
+ <P>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.</P>
+
+ <P>Except as contained in this notice, the name of The Open Group
+shall not be used in advertising or otherwise to promote the sale, use
+or other dealings in this Software without prior written authorization
+from The Open Group.</P>
+
+ <P>X Window System is a trademark of The Open Group</P>
+ </BODY>
+</HTML>
diff --git a/doc/common/xml.dcl b/doc/common/xml.dcl
new file mode 100644
index 0000000..fed2103
--- /dev/null
+++ b/doc/common/xml.dcl
@@ -0,0 +1,179 @@
+<!SGML -- SGML Declaration for valid XML documents --
+ "ISO 8879:1986 (WWW)"
+
+ CHARSET
+ BASESET
+ "ISO Registration Number 176//CHARSET
+ ISO/IEC 10646-1:1993 UCS-4 with implementation
+ level 3//ESC 2/5 2/15 4/6"
+ DESCSET
+ 0 9 UNUSED
+ 9 2 9
+ 11 2 UNUSED
+ 13 1 13
+ 14 18 UNUSED
+ 32 95 32
+ 127 1 UNUSED
+ 128 32 UNUSED
+ -- use this instead of the official declaration because SP only
+ supports 16-bit characters --
+ 160 65374 160
+ 65534 2 UNUSED
+ -- 55296 2048 UNUSED
+ 57344 8190 57344
+ 65534 2 UNUSED
+ 65536 1048576 65536 --
+ CAPACITY NONE
+
+ SCOPE DOCUMENT
+
+ SYNTAX
+ SHUNCHAR NONE
+ BASESET "ISO Registration Number 176//CHARSET
+ ISO/IEC 10646-1:1993 UCS-4 with implementation
+ level 3//ESC 2/5 2/15 4/6"
+ DESCSET
+ 0 1114112 0
+ FUNCTION
+ RE 13
+ RS 10
+ SPACE 32
+ TAB SEPCHAR 9
+
+ NAMING
+ LCNMSTRT ""
+ UCNMSTRT ""
+ NAMESTRT
+ 58 95 192-214 216-246 248-305 308-318 321-328
+ 330-382 384-451 461-496 500-501 506-535 592-680
+ 699-705 902 904-906 908 910-929 931-974 976-982
+ 986 988 990 992 994-1011 1025-1036 1038-1103
+ 1105-1116 1118-1153 1168-1220 1223-1224
+ 1227-1228 1232-1259 1262-1269 1272-1273
+ 1329-1366 1369 1377-1414 1488-1514 1520-1522
+ 1569-1594 1601-1610 1649-1719 1722-1726
+ 1728-1742 1744-1747 1749 1765-1766 2309-2361
+ 2365 2392-2401 2437-2444 2447-2448 2451-2472
+ 2474-2480 2482 2486-2489 2524-2525 2527-2529
+ 2544-2545 2565-2570 2575-2576 2579-2600
+ 2602-2608 2610-2611 2613-2614 2616-2617
+ 2649-2652 2654 2674-2676 2693-2699 2701
+ 2703-2705 2707-2728 2730-2736 2738-2739
+ 2741-2745 2749 2784 2821-2828 2831-2832
+ 2835-2856 2858-2864 2866-2867 2870-2873 2877
+ 2908-2909 2911-2913 2949-2954 2958-2960
+ 2962-2965 2969-2970 2972 2974-2975 2979-2980
+ 2984-2986 2990-2997 2999-3001 3077-3084
+ 3086-3088 3090-3112 3114-3123 3125-3129
+ 3168-3169 3205-3212 3214-3216 3218-3240
+ 3242-3251 3253-3257 3294 3296-3297 3333-3340
+ 3342-3344 3346-3368 3370-3385 3424-3425
+ 3585-3630 3632 3634-3635 3648-3653 3713-3714
+ 3716 3719-3720 3722 3725 3732-3735 3737-3743
+ 3745-3747 3749 3751 3754-3755 3757-3758 3760
+ 3762-3763 3773 3776-3780 3904-3911 3913-3945
+ 4256-4293 4304-4342 4352 4354-4355 4357-4359
+ 4361 4363-4364 4366-4370 4412 4414 4416 4428
+ 4430 4432 4436-4437 4441 4447-4449 4451 4453
+ 4455 4457 4461-4462 4466-4467 4469 4510 4520
+ 4523 4526-4527 4535-4536 4538 4540-4546 4587
+ 4592 4601 7680-7835 7840-7929 7936-7957
+ 7960-7965 7968-8005 8008-8013 8016-8023 8025
+ 8027 8029 8031-8061 8064-8116 8118-8124 8126
+ 8130-8132 8134-8140 8144-8147 8150-8155
+ 8160-8172 8178-8180 8182-8188 8486 8490-8491
+ 8494 8576-8578 12295 12321-12329 12353-12436
+ 12449-12538 12549-12588 19968-40869 44032-55203
+
+ LCNMCHAR ""
+ UCNMCHAR ""
+ NAMECHAR
+ 45-46 183 720-721 768-837 864-865 903 1155-1158
+ 1425-1441 1443-1465 1467-1469 1471 1473-1474
+ 1476 1600 1611-1618 1632-1641 1648 1750-1764
+ 1767-1768 1770-1773 1776-1785 2305-2307 2364
+ 2366-2381 2385-2388 2402-2403 2406-2415
+ 2433-2435 2492 2494-2500 2503-2504 2507-2509
+ 2519 2530-2531 2534-2543 2562 2620 2622-2626
+ 2631-2632 2635-2637 2662-2673 2689-2691 2748
+ 2750-2757 2759-2761 2763-2765 2790-2799
+ 2817-2819 2876 2878-2883 2887-2888 2891-2893
+ 2902-2903 2918-2927 2946-2947 3006-3010
+ 3014-3016 3018-3021 3031 3047-3055 3073-3075
+ 3134-3140 3142-3144 3146-3149 3157-3158
+ 3174-3183 3202-3203 3262-3268 3270-3272
+ 3274-3277 3285-3286 3302-3311 3330-3331
+ 3390-3395 3398-3400 3402-3405 3415 3430-3439
+ 3633 3636-3642 3654-3662 3664-3673 3761
+ 3764-3769 3771-3772 3782 3784-3789 3792-3801
+ 3864-3865 3872-3881 3893 3895 3897 3902-3903
+ 3953-3972 3974-3979 3984-3989 3991 3993-4013
+ 4017-4023 4025 8400-8412 8417 12293 12330-12335
+ 12337-12341 12441-12442 12445-12446 12540-12542
+
+ NAMECASE
+ GENERAL NO
+ ENTITY NO
+
+ DELIM
+ GENERAL SGMLREF
+ HCRO "&#x" -- 38 is the number for ampersand --
+ NESTC "/"
+ NET ">"
+ PIC "?>"
+ SHORTREF NONE
+
+ NAMES
+ SGMLREF
+
+ QUANTITY NONE
+
+ ENTITIES
+ "amp" 38
+ "lt" 60
+ "gt" 62
+ "quot" 34
+ "apos" 39
+
+ FEATURES
+ MINIMIZE
+ DATATAG NO
+ OMITTAG NO
+ RANK NO
+ SHORTTAG
+ STARTTAG
+ EMPTY NO
+ UNCLOSED NO
+ NETENABL IMMEDNET
+ ENDTAG
+ EMPTY NO
+ UNCLOSED NO
+ ATTRIB
+ DEFAULT YES
+ OMITNAME NO
+ VALUE NO
+ EMPTYNRM YES
+ IMPLYDEF
+ ATTLIST NO
+ DOCTYPE NO
+ ELEMENT NO
+ ENTITY NO
+ NOTATION NO
+ LINK
+ SIMPLE NO
+ IMPLICIT NO
+ EXPLICIT NO
+ OTHER
+ CONCUR NO
+ SUBDOC NO
+ FORMAL NO
+ URN NO
+ KEEPRSRE YES
+ VALIDITY TYPE
+ ENTITIES
+ REF ANY
+ INTEGRAL YES
+ APPINFO NONE
+ SEEALSO "ISO 8879:1986//NOTATION
+ Extensible Markup Language (XML) 1.0//EN"
+>
diff --git a/doc/rkwardplugins/building_the_plugin_package.html b/doc/rkwardplugins/building_the_plugin_package.html
new file mode 100644
index 0000000..eb98b5e
--- /dev/null
+++ b/doc/rkwardplugins/building_the_plugin_package.html
@@ -0,0 +1,6 @@
+<html><head><title>Building the plugin package</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="external_plugins.html" title="Chapter 14. Share your work with others"><link rel="prev" href="structure_of_a_plugin_package.html" title="Structure of a plugin package"><link rel="next" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Building the plugin package</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="structure_of_a_plugin_package.html">Prev</a></td><td align="center" class="navCenter" width="34%">Share your work with others</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="rkwarddev.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="building_the_plugin_package"></a>Building the plugin package</h2></div></div></div><p>As explained earlier, external <span class="application">RKWard</span> plugins are in effect <span class="application">R</span> packages, and therefore the packaging process is identical. In contrast to "real" <span class="application">R</span> packages, a pure plugin package does not carry any further <span class="application">R</span> code (although you can of course add <span class="application">RKWard</span> plugins to usual <span class="application">R</span> 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 <code class="filename">DESCRIPTION</code> file and adhere to the file hierarchy explained in <a class="link" href="structure_of_a_plugin_package.html" title="Structure of a plugin package">previous sections</a>.</p><p>The easiest way to actually build and test your plugin is to use the <span class="application">R</span> command on the command line, for example:</p><p><strong class="userinput"><code>
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>R</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="option"><code class="option">CMD build</code></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code><code class="filename">SquaretheCircle</code></code></em></span>
+ </code></strong></p><p><strong class="userinput"><code>
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>R</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="option"><code class="option">CMD INSTALL</code></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code><code class="filename">SquaretheCircle_0.1-3.tar.gz</code></code></em></span>
+ </code></strong></p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>You do not have to build the package like this on the command line. If you use the function <code class="function">rk.build.package()</code> from the <a class="link" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><span class="application">rkwarddev</span> package</a>, it will build and/or check your plugin package for you.</p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="structure_of_a_plugin_package.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="rkwarddev.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Structure of a plugin package </td><td width="34%" align="center" class="navCenter"><a href="external_plugins.html">Up</a></td><td width="33%" align="right" class="navRight"> Plugin development with the <span class="application">rkwarddev</span> package</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/ch10s02.html b/doc/rkwardplugins/ch10s02.html
new file mode 100644
index 0000000..586c11f
--- /dev/null
+++ b/doc/rkwardplugins/ch10s02.html
@@ -0,0 +1,86 @@
+<html><head><title>Previews for data, output and other results</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="specialized_plugins.html" title="Chapter 10. Concepts for use in specialized plugins"><link rel="prev" href="specialized_plugins.html" title="Chapter 10. Concepts for use in specialized plugins"><link rel="next" href="contextualized_plugins.html" title="Context-dependent plugins"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Previews for data, output and other results</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="specialized_plugins.html">Prev</a></td><td align="center" class="navCenter" width="34%">Concepts for use in specialized plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="contextualized_plugins.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm983"></a>Previews for data, output and other results</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="preview_output"></a>Previews of (HTML) output</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This section discusses adding preview functionality to plugins creating output / HTML printouts. It is recommended that you read the separate section on <a class="link" href="specialized_plugins.html#preview_plots" title="Adding preview functionality">plot previews</a>, before this section.</p></div><p>
+ Creating a preview of HTML output is almost the same procedure as creating a plot preview. In this case, simply make sure that the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>preview()</strong></span></span> generates the relevant
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rk.print()/rk.results()</strong></span></span> commands. It is generally a good idea to omit the header statements in the preview, however. Here is a stripped-down example:
+ </p><pre class="programlisting">
+ <!-- In the plugin's XML file -->>
+ <dialog label="Import CSV data" >
+ <browser id="file" type="file" label="File name"/>
+ <!-- [...] -->>
+ <preview id="preview" mode="output"/>
+ </dialog>>
+ </pre><p>
+ Note the specification of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>mode="output"</code></em></span> in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><preview></strong></span></span> element.
+ </p><pre class="programlisting">
+ // In the plugin's JS file
+ function preview () {
+ // generates the code used for preview
+ printout (true);
+ }
+
+ function printout (is_preview) {
+ // only generates a header if is_preview==false
+ if (!is_preview) {
+ new Header ("This is a caption").print ();
+ }
+ echo ('rk.print (result)');
+ }
+ </pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="preview_data"></a>Previews of (imported) data</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This section discusses adding preview functionality to plugins creating (importing) data. It is recommended that you read the separate section on <a class="link" href="specialized_plugins.html#preview_plots" title="Adding preview functionality">plot previews</a>, before this section.</p></div><p>
+ Creating a preview of imported data (any type of data that <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rk.edit()</strong></span></span> can handle), is very similar to creating a <a class="link" href="specialized_plugins.html#preview_plots" title="Adding preview functionality">plot preview</a>. The following stripped down example should help illustrate how to create a data preview:
+ </p><pre class="programlisting">
+ <!-- In the plugin's XML file -->>
+ <dialog label="Import CSV data" >
+ <browser id="file" type="file" label="File name"/>
+ <!-- [...] -->>
+ <preview id="preview" active="true" mode="data"/>
+ </dialog>>
+ </pre><p>
+ Note that the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><preview></strong></span></span> element specifies <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>mode="data"</code></em></span> this time. <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>active="true"</code></em></span> simply makes the preview active by
+ default.
+ </p><pre class="programlisting">
+ // In the plugin's JS file
+ function preview () {
+ // generates the code used for preview
+ calculate (true);
+ }
+
+ function calculate (is_preview) {
+ echo ('imported <- read.csv (file="' + getString ("file") /* [+ options] */);
+ if (is_preview) {
+ echo ('preview_data <- imported\n');
+ } else {
+ echo ('.GlobalEnv$' + getString ("name") + ' >- imported\n');
+ }
+ }
+
+ function printout () {
+ // [...]
+ }
+ </pre><p>
+ Again, the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>preview()</strong></span></span> function generates almost the same <span class="application">R</span> code as the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>calculate()</strong></span></span> function, so we create a helper function <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>doCalcuate()</strong></span></span> to factor out the common parts. The most important thing to note is that you will have to assign the imported data to a object called
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>preview_data</code></em></span> (inside the current - local - environment). <span class="emphasis"><em>Everything else will happen automatically</em></span> (roughly speaking, <span class="application">RKWard</span> will call <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rk.edit(preview_data)</strong></span></span>, wrapped inside a call to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>.rk.with.window.hints()</strong></span></span>).
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+ While previews are a great feature, they do consume resources. In the case of data previews, there may be cases, where previews can cause significant performance issues. This could be
+ for importing huge datasets (which are just too large to be opened for editing in <span class="application">RKWard</span>'s editor window), but also "normal" datasets could be mis-imported, creating a huge number of rows or columns. <span class="emphasis"><em>It is very much recommended that you limit the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>preview_data</code></em></span></em></span> to a dimension that provides a useful preview, without the danger of
+ creating noticable performance issues (<abbr class="abbrev">e.g.</abbr> 50 rows by 50 columns should be more than enough in most cases).
+ </p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="preview_custom"></a>Custom previews</h3></div></div></div><p>
+ The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><preview></strong></span></span> element can be used to create previews for any type of "document" window that can be attached to <span class="application">RKWard</span>'s workplace. In addition to <a class="link" href="specialized_plugins.html#preview_plots" title="Adding preview functionality">plots</a> and <a class="link" href="ch10s02.html#preview_data" title="Previews of (imported) data">data windows</a>, this includes HTML files, <span class="application">R</span> scripts, and object summary windows. For the latter ones, you will have to use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><preview mode="custom"></strong></span></span>.
+ </p><p>
+ If you have read the sections describing plot preview and data previews, you should have a general idea on the procedure, but "custom" previews require slightly more manual work behind the scenes. The most important <span class="application">R</span> function to look at is <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rk.assign.preview.data()</strong></span></span>, here. The following short listing shows what your generated (preview) <span class="application">R</span> code could look like for a plugin creating a text file output:
+ </p><pre class="programlisting">
+ ## To be generated in the preview() code section of a plugin
+ pdata <- rk.get.preview.data("SOMEID")
+ if (is.null (pdata)) {
+ outfile <- rk.get.tempfile.name(prefix="preview", extension=".txt")
+ pdata <- list(filename=outfile, on.delete=function (id) {
+ unlink(rk.get.preview.data(id)$filename)
+ })
+ rk.assign.preview.data("SOMEID", pdata)
+ }
+ try ({
+ cat ("This is a test", pdata$filename)
+ rk.edit.files(file=pdata$filename)
+ })
+ </pre><p>
+ Here you should get the value <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>SOMEID</code></em></span> from the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> property of the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><preview></strong></span></span>-element. I.e. using <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>getString ("preview.id")</strong></span></span> in the plugin's .js file.
+ </p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="specialized_plugins.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="contextualized_plugins.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Concepts for use in specialized plugins </td><td width="34%" align="center" class="navCenter"><a href="specialized_plugins.html">Up</a></td><td width="33%" align="right" class="navRight"> Context-dependent plugins</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/chapter_about_information.html b/doc/rkwardplugins/chapter_about_information.html
new file mode 100644
index 0000000..bf6764f
--- /dev/null
+++ b/doc/rkwardplugins/chapter_about_information.html
@@ -0,0 +1,39 @@
+<html><head><title>Chapter 13. Author, license and version information</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="i18n_translators.html" title="Writing plugin translations"><link rel="next" href="external_plugins.html" title="Chapter 14. Share your work with others"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Author, license and version information</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="i18n_translators.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="external_plugins.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="chapter_about_information"></a>Chapter 13. Author, license and version information</h1></div></div></div><p>So you have written a set of plugins, and you are getting ready to <a class="link" href="external_plugins.html" title="Chapter 14. Share your work with others">share your work</a>. To make sure users will know what your work is all about, under what terms they can use and distribute it, and whom they should contact about issues or ideas, you should add some information <span class="emphasis"><em>about</em></span> your plugins. This can be done using the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><about></strong></span></span> element. It can be used in either the <code class="literal">.pluginmap</code> or in individual plugin <code class="literal">.xml</code> files (in both cases as a direct child of the document tag). When specified in the <code class="literal">.pluginmap</code> it will apply to all plugins. If <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><about></strong></span></span> is specified in both places, the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><about></strong></span></span> information in the plugin <code class="literal">.xml</code> file will override that in the <code class="literal">.pluginmap</code> file. You can also add an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><about></strong></span></span> element to .rkh-pages, which are not connected to a plugin, if there is a need for that.</p><p>Here is an example <code class="literal">.pluginmap</code> file with only a few explanations, below. In cases of doubt, more information may be available from the reference.</p><pre class="programlisting">
+<document
+ namespace="rkward"
+ id="SquaretheCircle_rkward"
+>
+ <about
+ name="Square the Circle"
+ shortinfo="Squares the circle using Heisenberg compensation."
+ version="0.1-3"
+ releasedate="2011-09-19"
+ url="http://eternalwondermaths.example.org/23/stc.html"
+ license="GPL"
+ category="Geometry"
+ >
+ <author
+ given="E.A."
+ family="Dölle"
+ email="doelle at eternalwondermaths.example.org"
+ role="aut"
+ />
+ <author
+ given="A."
+ family="Assistant"
+ email="alterego at eternalwondermaths.example.org"
+ role="cre, ctb"
+ />
+ </about>
+ <dependencies>
+ ...
+ </dependencies>
+ <components>
+ ...
+ </components>
+ <hierarchy>
+ ...
+ </hierarchy>
+</document>
+</pre><p>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. </p><p>The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>category</code></em></span> element in <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><about></strong></span></span> 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. </p><p>At least one <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><author></strong></span></span> with a valid email address and the role <span class="quote">“<span class="quote">aut</span>”</span> (<span class="quote">“<span class="quote">author</span>”</span>) 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 <span class="quote">“<span class="quote">ctb</span>”</span> for code contributors or <span class="quote">“<span class="quote">cre</span>”</span> for package maintenance, please refer to the <a class="ulink" href="http://stat.ethz.ch/R-manual/R-patched/library/utils/html/person.html" target="_top">R documentation on <code class="function">person()</code></a>. </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Remember that you can use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><include></strong></span></span> and / or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><insert></strong></span></span> to repeat information across several <code class="literal">.xml</code> files (<abbr class="abbrev">e.g.</abbr> information on an author who was involved with several plugins). <a class="link" href="plugin_series.html#sect_similar_plugins" title="Overview on different approaches">More information</a>.</p></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>You do not have to write this <acronym class="acronym">XML</acronym> code by hand. If you use the function <code class="function">rk.plugin.skeleton()</code> from the <a class="link" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><span class="application">rkwarddev</span> package</a> and provide all necessary information via the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>about</code></em></span> option, it will automatically create a <code class="literal">.pluginmap</code> file with a working <about> section for you.</p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="i18n_translators.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="external_plugins.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Writing plugin translations </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Share your work with others</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/chapter_dependencies.html b/doc/rkwardplugins/chapter_dependencies.html
new file mode 100644
index 0000000..a4aea35
--- /dev/null
+++ b/doc/rkwardplugins/chapter_dependencies.html
@@ -0,0 +1,15 @@
+<html><head><title>Chapter 11. Handling dependencies and compatibility issues</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="optionset.html" title="Repeating (a set of) options"><link rel="next" href="sect_dependencies_r_version.html" title="R version compatibility"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Handling dependencies and compatibility issues</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="optionset.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="sect_dependencies_r_version.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="chapter_dependencies"></a>Chapter 11. Handling dependencies and compatibility issues</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="chapter_dependencies.html#sect_dependencies_rkward_version"><span class="application">RKWard</span> version compatibility</a></span></dt><dt><span class="sect1"><a href="sect_dependencies_r_version.html"><span class="application">R</span> version compatibility</a></span></dt><dt><span class="sect1"><a href="sect_dependencies_r_packages.html">Dependencies on <span class="application">R</span> packages</a></span></dt><dt><span class="sect1"><a href="sect_dependencies_other_pluginmaps.html">Dependencies on other <span class="application">RKWard</span> <code class="literal">.pluginmap</code>s</a></span></dt><dt><span class="sect1"><a href="sect_dependencies_example.html">An example</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_dependencies_rkward_version"></a><span class="application">RKWard</span> version compatibility</h2></div></div></div><p>We do our best to make sure that plugins developed for an old version of <span class="application">RKWard</span> will remain functional in later versions of <span class="application">RKWard</span>. However, the reverse is not always true as new features are been added. Since not all users are running the latest version of <span class="application">RKWard</span>, this means your plugin may not work for everybody.</p><p>When you are aware of such compatibility issues, you should make sure to document this fact in your <code class="literal">.pluginmap</code> file, using the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dependencies></strong></span></span> element. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dependencies></strong></span></span> can either be specified as a direct child of the <code class="literal">.pluginmap</code>'s <document> element, or as a child element of individual <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><component></strong></span></span> definitions. In the first case, the dependencies apply to <span class="emphasis"><em>all</em></span> plugins in the map. In the latter case only to the individual <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><component></strong></span></span>(s). You can also mix top "global" and "specific" dependencies. In this case the "global" dependencies are added to those of the individual component.</p><p>Let's look at a small example:</p><pre class="programlisting">
+<document ...>
+ <dependencies rkward_min_version="0.5.0c" />
+ <components ...>
+ <component id="myplugin" file="reduced_version_of_myplugin.xml" ...>
+ <dependencies rkward_max_version="0.6.0z" />
+ </component>
+ <component id="myplugin" file="fancy_version_of_myplugin.xml" ...>
+ <dependencies rkward_min_version="0.6.1" />
+ </component>
+ ...
+x </components ...>
+</document>
+ </pre><p>In this example, all plugins are known to require at least version 0.5.0c of <span class="application">RKWard</span>. One plugin, with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>id="myplugin"</code></em></span> is provided in two alternative variants. The first, stripped down, version will be used for <span class="application">RKWard</span> versions before 0.6.1. The latter utilizes features that are new in <span class="application">RKWard</span> 0.6.1, and will only be used from <span class="application">RKWard</span> 0.6.1 onwards.</p><p>Providing alternative variants like this is a very user friendly way to make use of new features, while still keeping support for earlier versions of <span class="application">RKWard</span>. Alternative versions should share the same <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> (warnings will be produced, otherwise), and may only be defined <span class="emphasis"><em>within the same</em></span> <code class="literal">.pluginmap</code> file.</p><p>Plugin which are not compatible with the running version of <span class="application">RKWard</span>, and which do not come with an alternative version will be ignored with a warning.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Actually <span class="application">RKWard</span> 0.6.1 is the first version to interpret dependencies - and to report dependency errors - at all. Thus, contrary to what the example may suggest, specifying any earlier versions in the dependencies will not have any direct effect (but may still be a good idea for documentation purposes).</p></div><p><span class="emphasis"><em>Sometimes</em></span> it will even be possible to handle version incompatibility issues <span class="emphasis"><em>inside</em></span> a single <code class="literal">.pluginmap</code> file, using the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dependency_check></strong></span></span> element, described in the following section.</p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="optionset.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="sect_dependencies_r_version.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Repeating (a set of) options </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> <span class="application">R</span> version compatibility</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/contextualized_plugins.html b/doc/rkwardplugins/contextualized_plugins.html
new file mode 100644
index 0000000..00ff316
--- /dev/null
+++ b/doc/rkwardplugins/contextualized_plugins.html
@@ -0,0 +1,63 @@
+<html><head><title>Context-dependent plugins</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="specialized_plugins.html" title="Chapter 10. Concepts for use in specialized plugins"><link rel="prev" href="ch10s02.html" title="Previews for data, output and other results"><link rel="next" href="querying_r_for_info.html" title="Querying R for information"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Context-dependent plugins</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="ch10s02.html">Prev</a></td><td align="center" class="navCenter" width="34%">Concepts for use in specialized plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="querying_r_for_info.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="contextualized_plugins"></a>Context-dependent plugins</h2></div></div></div><p>
+ 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 <span class="application">R</span> 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.
+ </p><p>
+ We call such plugins context-dependent. Correspondingly, in the <a class="link" href="pluginmap.html" title="Chapter 3. Creating menu entries"><code class="literal">.pluginmap</code> file</a>, they are not (or not only) placed in the main <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><hierarchy></strong></span></span> but rather into a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><context></strong></span></span> element. So far only two different contexts are supported (more will come later): x11 and file import. We will deal with those in turn. Even if you are only interested in the import context, please also read the section on the x11 context, as this is slightly more elaborate.
+ </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="context_x11"></a>X11 device context</h3></div></div></div><p>
+ To use a plugin in the context of an x11 device - that is place it in the menubar of the window you get when you call <code class="function">x11()</code> in the console, first declare it as usual in the <a class="link" href="pluginmap.html" title="Chapter 3. Creating menu entries"><code class="literal">.pluginmap</code> file</a>:
+ </p><pre class="programlisting">
+<document [...]>
+ <components>
+ [...]
+ <component id="my_x11_plugin" file="my_x11_plugin.xml" label="An X11 context plugin"/>
+ [...]
+ </components>
+ </pre><p>
+ However, you do not need to define it in the hierarchy (you can, if it is also meaningful as a top-level plugin):
+ </p><pre class="programlisting">
+ <hierarchy>
+ [...]
+ </hierarchy>
+ </pre><p>
+ Instead, add a definition of the "x11" context, and add it to the menus there:
+ </p><pre class="programlisting">
+ <context id="x11">
+ [...]
+ <menu id="edit">
+ [...]
+ <entry id="my_x11_plugin"/>
+ </menu>
+ </context>
+</document>
+ </pre><p>
+ In the <a class="link" href="logic.html" title="Chapter 7. Logic interactions between GUI elements">logic section of the plugin xml</a>, you can now declare two <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><external></strong></span></span> properties: <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>devnum</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>context</code></em></span>. <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>context</code></em></span> (if declared) will be set to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"x11"</code></em></span> when the plugin is invoked in this context. <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>devnum</code></em></span> will be set to the number of the graphics device to operate on. And that is all.
+ </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="context_import"></a>Import data context</h3></div></div></div><p>
+ Before reading this section, please make sure to read the section on the <a class="link" href="contextualized_plugins.html#context_x11" title="X11 device context">X11 device context</a>, as that explains the basic concepts.
+ </p><p>
+ The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"import"</code></em></span> context is used to declare import file filter plugins. You simply place those in a context with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"import"</code></em></span> in the <code class="literal">.pluginmap</code> 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:
+ </p><pre class="programlisting">
+<document [...]>
+ <components>
+ [...]
+ <component id="my_xyz_import_plugin" file="my_xyz_import_plugin.xml" label="Import XYZ files">
+ <attribute id="format" value="*.xyz *.zyx" label="XYZ data files"/>
+ </component>
+ [...]
+ </components>
+ <hierarchy>
+ [...]
+ </hierarchy>
+ <context id="import">
+ [...]
+ <menu id="import">
+ [...]
+ <entry id="my_xyz_import_plugin"/>
+ </menu>
+ </context>
+ [...]
+</document>
+ </pre><p>
+ The attribute line simply says, that the associate filename extensions for XYZ files are <code class="literal">*.xyz</code> or <code class="literal">*.zyx</code>, and that the filter should be labeled <span class="quote">“<span class="quote">XYZ data files</span>”</span> in the file selection dialog.
+ </p><p>
+ You can declare two <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><external></strong></span></span> properties in your plugin. <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>filename</code></em></span> will be set to the selected file name, and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>context</code></em></span> will be set to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"import"</code></em></span>.
+ </p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="ch10s02.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="querying_r_for_info.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Previews for data, output and other results </td><td width="34%" align="center" class="navCenter"><a href="specialized_plugins.html">Up</a></td><td width="33%" align="right" class="navRight"> Querying <span class="application">R</span> for information</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/current_object.html b/doc/rkwardplugins/current_object.html
new file mode 100644
index 0000000..0b90d05
--- /dev/null
+++ b/doc/rkwardplugins/current_object.html
@@ -0,0 +1,7 @@
+<html><head><title>Referencing the current object or current file</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="specialized_plugins.html" title="Chapter 10. Concepts for use in specialized plugins"><link rel="prev" href="querying_r_for_info.html" title="Querying R for information"><link rel="next" href="optionset.html" title="Repeating (a set of) options"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Referencing the current object or current file</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="querying_r_for_info.html">Prev</a></td><td align="center" class="navCenter" width="34%">Concepts for use in specialized plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="optionset.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="current_object"></a>Referencing the current object or current file</h2></div></div></div><p>
+ For many plugins it is desirable to work on the <span class="quote">“<span class="quote">current</span>”</span> object. For instance a <span class="quote">“<span class="quote">sort</span>”</span> plugin could pre-select the data.frame that is currently being edited for sorting. The name of the current object is available to plugins as a pre-defined property called <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>current_object</code></em></span>. You can connect to this property in the usual way. If no object is current, the property equates to an empty string. Similarly, the <acronym class="acronym">URL</acronym> of the current script file
+ is accessible as a pre-defined property called <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>current_filename</code></em></span>. That property is empty if no script file is currently being edited, or the script file has not been saved, yet.
+ </p><p>
+ Currently the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>current_object</code></em></span> can only be of class <code class="function">data.frame</code>, but please do not rely on this, since this will be extended to other types of data in the future. If you are interested in <code class="function">data.frame</code> objects, only, connect to the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>current_dataframe</code></em></span> property, instead. Alternatively, you can enforce type requirements by using appropriate constraints on your <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span>s, or by using <a class="link" href="logic_scripted.html" title="Scripted GUI logic"><acronym class="acronym">GUI</acronym> logic scripting</a>.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="querying_r_for_info.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="optionset.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Querying <span class="application">R</span> for information </td><td width="34%" align="center" class="navCenter"><a href="specialized_plugins.html">Up</a></td><td width="33%" align="right" class="navRight"> Repeating (a set of) options</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/elementproperties.html b/doc/rkwardplugins/elementproperties.html
new file mode 100644
index 0000000..fb801d9
--- /dev/null
+++ b/doc/rkwardplugins/elementproperties.html
@@ -0,0 +1,24 @@
+<html><head><title>Properties of plugin elements</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="reference.html" title="Appendix A. Reference"><link rel="prev" href="xmlelements.html" title="Elements to be used in the XML description of the plugin"><link rel="next" href="standard_embeddable_plugins.html" title="Embeddable plugins shipped with the official RKWard release"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Properties of plugin elements</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="xmlelements.html">Prev</a></td><td align="center" class="navCenter" width="34%">Reference</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="standard_embeddable_plugins.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="elementproperties"></a>Properties of plugin elements</h2></div></div></div><p>All <a class="link" href="xmlelements.html#layoutelements" title="Layout elements">layout elements</a>, and all <a class="link" href="xmlelements.html#activeelements" title="Active elements">active elements</a> hold the following properties, accessible via "id_of_element.name_of_property":
+</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">visible</span></dt><dd><p>Whether the <acronym class="acronym">GUI</acronym> element is visible or not (boolean)</p></dd><dt><span class="term">enabled</span></dt><dd><p>Whether the <acronym class="acronym">GUI</acronym> element is enabled or not (boolean)</p></dd><dt><span class="term">required</span></dt><dd><p>Whether the <acronym class="acronym">GUI</acronym> element is required (to hold a valid setting) or not. Note that any element which is disabled or hidden is also implicitly non-required (boolean).</p></dd></dl></div><p>
+ In addition to this, some elements have additional properties you can connect to. Most active elements also have a "default" property whose value will be returned on calls to <code class="function">getBoolean/getString/getList ("...")</code>, if no specific property was named, as described below.
+</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><text></span></dt><dd><p>Default property is text
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">text</span></dt><dd><p>The text displayed (text)</p></dd></dl></div></dd><dt><span class="term"><varselector></span></dt><dd><p>No default property
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">selected</span></dt><dd><p>The objects currently selected. You probably do not want to use this. Used internally (RObject)</p></dd><dt><span class="term">root</span></dt><dd><p>The root/parent object of the objects offered for selection (RObject)</p></dd></dl></div></dd><dt><span class="term"><varslot></span></dt><dd><p>Default property is "available"
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">available</span></dt><dd><p>All objects held in the varslot (RObject)</p></dd><dt><span class="term">selected</span></dt><dd><p>Of the objects held in the varslot, those that are currently selected. You probably do not want to use this. Used internally (RObject)</p></dd><dt><span class="term">source</span></dt><dd><p>A copy of the objects selected in the corresponding varselector. You probably do not want to use this. Used internally (RObject)</p></dd></dl></div></dd><dt><span class="term"><valueselector></span></dt><dd><p>Default property is "selected"
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">selected</span></dt><dd><p>The strings currently selected. Modifier "labeled" to retrieve the corresponding labels. In a <valueselector> you probably do not want to use this, directly (only in a <select>). (read/write StringList)</p></dd><dt><span class="term">available</span></dt><dd><p>The list of string values to select from. (read/write StringList)</p></dd><dt><span class="term">labels</span></dt><dd><p>Labels to display for the string values. (read/write StringList)</p></dd></dl></div></dd><dt><span class="term"><valueslot></span></dt><dd><p>Same as <varslot>, but the properties are lists of strings, instead of RObjects.</p></dd><dt><span class="term"><radio></span></dt><dd><p>Default property is "string"
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">string</span></dt><dd><p>The value of the currently selected option (string)</p></dd><dt><span class="term">number</span></dt><dd><p>The number of the currently selected option (options are numbered top-to-bottom, starting at 0) (integer)</p></dd></dl></div></dd><dt><span class="term"><dropdown></span></dt><dd><p>Same as <radio></p></dd><dt><span class="term"><select></span></dt><dd><p>Same as <valueselector></p></dd><dt><span class="term"><option></span></dt><dd><p>No default property. "enabled" is the *only* property, and it is not currently available for options inside a <select> or <valueselector>. <option> does not have the "visible" or "required" properties.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">enabled</span></dt><dd><p>Whether this single option should be enabled or disabled. In most cases you will enable/disable the entire <radio< or <dropdown<, instead. But this can be used to dynamically set the enabledness of a single option inside a <radio< or <dropdown< (bool)</p></dd></dl></div></dd><dt><span class="term"><checkbox></span></dt><dd><p>Default property is "state.labeled", which means that the values specified by the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>value</code></em></span>, and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>value_unchecked</code></em></span>-attributes are returned, <span class="emphasis"><em>not</em></span> the displayed label of the check box.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">state</span></dt><dd><p>State of the check box (on or off). Note that useful modifiers of this property (as of all boolean properties) are "not" and "labeled" (see <a class="link" href="reference.html#propertytypes" title="Types of properties/Modifiers">types of properties</a>). However, often it is most useful to connect to the property with no modifier, <abbr class="abbrev">i.e.</abbr> "<span class="emphasis"><em>checkbox_id</em></span>.state", which will return the state of the check box in a format suitable for use in an if statement (0 or 1). (boolean)</p></dd></dl></div></dd><dt><span class="term"><frame></span></dt><dd><p>Default property is "checked", if - and only if - the frame is checkable. For non-checkable frames, there is no default property.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">checked</span></dt><dd><p>Available for checkable frames, only: state of the check box (on or off). Note that useful modifiers of this property (as of all boolean properties) are "not" and "numeric" (see <a class="link" href="reference.html#propertytypes" title="Types of properties/Modifiers">types of properties</a>). (boolean)</p></dd></dl></div></dd><dt><span class="term"><input></span></dt><dd><p>Default property is "text"
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">text</span></dt><dd><p>Current text in the input field (string)</p></dd></dl></div></dd><dt><span class="term"><matrix></span></dt><dd><p>Default property is "cbind".
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">rows</span></dt><dd><p>Number of rows in the matrix (integer). If the matrix allows the user to add / remove rows, this property should be treated as read-only. Otherwise, changing it, will change the size of the matrix.</p></dd><dt><span class="term">columns</span></dt><dd><p>Number of columns in the matrix (integer). If the matrix allows the user to add / remove columns, this property should be treated as read-only. Otherwise, changing it, will change the size of the matrix.</p></dd><dt><span class="term">tsv</span></dt><dd><p>Data in the matrix in tsv format (string; read-write). Note that compared to the usual tsv layout, <span class="emphasis"><em>columns</em></span>, not rows, are separated by newline characters, and cells within a column are separated by tabulator characters.</p></dd><dt><span class="term">0,1,2...</span></dt><dd><p>The data from a single column (0 for leftmost column). <code class="function">getValue()</code>/<code class="function">getString()</code> returns this as a single string, separated by "\n". However, the recommended way to get this is using <code class="function">getList()</code>, which returns this column as an array of strings.</p></dd><dt><span class="term">row.0,row.1,row.2...</span></dt><dd><p>The data from a single row (0 for topmost row). <code class="function">getValue()</code>/<code class="function">getString()</code> returns this as a single string, separated by "\n". However, the recommended way to get this is using <code class="function">getList()</code>, which returns this row as an array of strings.</p></dd><dt><span class="term">cbind</span></dt><dd><p>Data in a format suitable for pasting to <span class="application">R</span>, wrapped in a cbind statement (string; read-only).</p></dd></dl></div></dd><dt><span class="term"><optionset></span></dt><dd><p>No default property.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">row_count</span></dt><dd><p>Number of items in the optionset (integer). Read-only.</p></dd><dt><span class="term">current_row</span></dt><dd><p>Currently active item in the optionset (integer). -1 for no active item. Read-write.</p></dd><dt><span class="term"><span class="emphasis"><em>optioncolumn_ids</em></span></span></dt><dd><p>For each <optioncolumn> you define, a string list property will be created with the specified id.</p></dd></dl></div></dd><dt><span class="term"><browser></span></dt><dd><p>Default property is "selection"
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">selection</span></dt><dd><p>Current text (selected file name) in the browser (string)</p></dd></dl></div></dd><dt><span class="term"><saveobject></span></dt><dd><p>Default property is "selection"
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">selection</span></dt><dd><p>Full name of the selected object (string; read-only - to set this programmatically, use "parent", and "objectname")</p></dd><dt><span class="term">parent</span></dt><dd><p>The parent object of the selected object. This is always an existing <span class="application">R</span> object of a type that can contain other objects (<abbr class="abbrev">e.g.</abbr> a list or data.frame). When set to an empty string or an invalid object, ".GlobalEnv" is assumed (RObject)</p></dd><dt><span class="term">objectname</span></dt><dd><p>The base-name of the selected object, <abbr class="abbrev">i.e.</abbr> the string entered by the user (changed to a valid <span class="application">R</span> name, if necessary) (string)</p></dd><dt><span class="term">active</span></dt><dd><p>For checkable saveobjects, only: Whether the control is checked/enabled. Always true for non-checkable saveobjects (bool)</p></dd></dl></div></dd><dt><span class="term"><spinbox></span></dt><dd><p>Default property is either "int" or "real.formatted" depending on the spinbox's mode
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">int</span></dt><dd><p>Integer value held by the spinbox, or nearest integer, if in real mode (integer)</p></dd><dt><span class="term">real</span></dt><dd><p>Real value held by the spinbox (and integer, if in integer) (real)</p></dd></dl></div></dd><dt><span class="term"><formula></span></dt><dd><p>Default property is "model"
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">model</span></dt><dd><p>The current model string (string)</p></dd><dt><span class="term">table</span></dt><dd><p>The data.frame holding the required variables. If variables from only one data.frame are used, the name of that data.frame is returned. Otherwise a new data.frame is constructed as required (string)</p></dd><dt><span class="term">labels</span></dt><dd><p>If variables from multiple data.frames are involved, their names may get mangled (for instance, if both data.frames contain a variable named "x"). This returns a list with the mangled names as indices and the descriptive label as value (string)</p></dd><dt><span class="term">fixed_factors</span></dt><dd><p>The fixed factors. You probably do not want to use this. Used internally (RObject)</p></dd><dt><span class="term">dependent</span></dt><dd><p>The dependent variable(s). You probably do not want to use this. Used internally (RObject)</p></dd></dl></div></dd><dt><span class="term"><embed></span></dt><dd><p>No default property
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">code</span></dt><dd><p>The code generated by the embedded plugin (code)</p></dd></dl></div></dd><dt><span class="term"><preview></span></dt><dd><p>Default property is "state"
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">state</span></dt><dd><p>Whether the preview box is checked (not necessarily whether the preview has already been shown) (boolean)</p></dd></dl></div></dd><dt><span class="term"><convert></span></dt><dd><p>This element (used in the <logic> section) is special, in that is technically *is* a property, instead of just holding one or more properties. It is of boolean kind. Note that useful modifiers of this property (as of all boolean properties) are "not" and "numeric" (see <a class="link" href="reference.html#propertytypes" title="Types of properties/Modifiers">types of properties</a>)</p></dd><dt><span class="term"><switch></span></dt><dd><p>This element (used in the <logic> section) is special, in that is technically *is* a (string) property, instead of just holding one or more properties. It allows to switch between several target properties depending on the value of a condition property, or to re-map values of the condition property. Any modifiers that you supply are passed on to the target properties, thus, <abbr class="abbrev">e.g.</abbr> if all target
+properties are RObject properties, you can use the "shortname" modifier on the switch, too. However, if the target properties are of
+different types, using modifiers may lead to errors. For <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>fixed_value</code></em></span>s, any modifier is dropped, silently. Note that target properties, when accessed through a switch, are always read-only.</p></dd></dl></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="xmlelements.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="standard_embeddable_plugins.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Elements to be used in the <acronym class="acronym">XML</acronym> description of the plugin </td><td width="34%" align="center" class="navCenter"><a href="reference.html">Up</a></td><td width="33%" align="right" class="navRight"> Embeddable plugins shipped with the official <span class="application">RKWard</span> release</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/embedding.html b/doc/rkwardplugins/embedding.html
new file mode 100644
index 0000000..c0fc8da
--- /dev/null
+++ b/doc/rkwardplugins/embedding.html
@@ -0,0 +1,6 @@
+<html><head><title>Chapter 8. Embedding Plugins into Plugins</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="logic_scripted.html" title="Scripted GUI logic"><link rel="next" href="embedding_dialog.html" title="Embedding inside a dialog"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Embedding Plugins into Plugins</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="logic_scripted.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="embedding_dialog.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="embedding"></a>Chapter 8. Embedding Plugins into Plugins</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="embedding.html#sect_embedding">Use cases for embedding</a></span></dt><dt><span class="sect1"><a href="embedding_dialog.html">Embedding inside a dialog</a></span></dt><dt><span class="sect1"><a href="embedding_code.html">Code generation when embedding</a></span></dt><dt><span class="sect1"><a href="embedding_wizard.html">Embedding inside a wizard</a></span></dt><dt><span class="sect1"><a href="embedding_as_button.html">Less embedded embedding: Further Options button</a></span></dt><dt><span class="sect1"><a href="embedding_incomplete.html">Embedding/defining incomplete plugins</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_embedding"></a>Use cases for embedding</h2></div></div></div><p>
+ When writing plugins, you will often find that you are creating a number of plugins that only differ in some respects, but have a lot more in common. For instance, for plotting, there are a number of generic <span class="application">R</span> options that can be used with mostly all types of plots. Should you create a <acronym class="acronym">GUI</acronym> and JS-template for those over and over again?
+ </p><p>
+ Obviously that would be quite a hassle. Fortunately, you do not have to do that. Rather you create the common functionality once, and later you can embed it into several plugins. In fact it is possible to embed any plugin into any other plugin, even if the original author of the embedded plugin never thought, somebody would want to embed their plugin into another one.
+ </p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="logic_scripted.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="embedding_dialog.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Scripted <acronym class="acronym">GUI</acronym> logic </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Embedding inside a dialog</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/embedding_as_button.html b/doc/rkwardplugins/embedding_as_button.html
new file mode 100644
index 0000000..7ee0fc3
--- /dev/null
+++ b/doc/rkwardplugins/embedding_as_button.html
@@ -0,0 +1,23 @@
+<html><head><title>Less embedded embedding: Further Options button</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins"><link rel="prev" href="embedding_wizard.html" title="Embedding inside a wizard"><link rel="next" href="embedding_incomplete.html" title="Embedding/defining incomplete plugins"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Less embedded embedding: Further Options button</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="embedding_wizard.html">Prev</a></td><td align="center" class="navCenter" width="34%">Embedding Plugins into Plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="embedding_incomplete.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="embedding_as_button"></a>Less embedded embedding: Further Options button</h2></div></div></div><p>
+ While embedding is cool, you should be careful not to overdo it. Too many functions inside a <acronym class="acronym">GUI</acronym> 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 <code class="function">plot()</code>), but as those are really optional, you do not want them prominently in your <acronym class="acronym">GUI</acronym>.
+ </p><p>
+ An alternative is to embed those options <span class="quote">“<span class="quote">as a button</span>”</span>:
+ </p><pre class="programlisting">
+<dialog>
+ <tabbook>
+ [...]
+ <tab label="Options">
+ [...]
+ <embed id="plotoptions" component="rkward::plot_options" as_button="true" label="Specify plotting options"/>
+ </tab>
+ [...]
+ </tabbook>
+</dialog>
+</pre><p>
+ In this case, a single push button will be added to your plugin, labeled <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guibutton">Specify plotting options</span></span>. When you press that button, a separate dialog will come up, with all the options of the embedded plugin. Even while this embedded <acronym class="acronym">GUI</acronym> is not visible most of the time, you can fetch its settings just as described <a class="link" href="embedding_code.html" title="Code generation when embedding">above</a>.
+ </p><p>
+ </p><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p>
+ Probably the <span class="quote">“<span class="quote">button</span>”</span> 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.
+ </p></div><p>
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="embedding_wizard.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="embedding_incomplete.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Embedding inside a wizard </td><td width="34%" align="center" class="navCenter"><a href="embedding.html">Up</a></td><td width="33%" align="right" class="navRight"> Embedding/defining incomplete plugins</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/embedding_code.html b/doc/rkwardplugins/embedding_code.html
new file mode 100644
index 0000000..1143419
--- /dev/null
+++ b/doc/rkwardplugins/embedding_code.html
@@ -0,0 +1,12 @@
+<html><head><title>Code generation when embedding</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins"><link rel="prev" href="embedding_dialog.html" title="Embedding inside a dialog"><link rel="next" href="embedding_wizard.html" title="Embedding inside a wizard"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Code generation when embedding</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="embedding_dialog.html">Prev</a></td><td align="center" class="navCenter" width="34%">Embedding Plugins into Plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="embedding_wizard.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="embedding_code"></a>Code generation when embedding</h2></div></div></div><p>
+ So far so good, but what about the generated code? How are the code for the embedding and embedded plugin merged? In the embedding plugin's JS code, simply write something like this:
+ </p><pre class="programlisting">
+function printout () {
+ // ...
+ echo ("myplotfunction ([...]" + getString ("plotoptions.code.printout"); + ")\n");
+ // ...
+}
+ </pre><p>
+ So essentially, we are fetching the code generated by the embedded plugin just like we are fetching any other <acronym class="acronym">GUI</acronym> setting. Here the string <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"plotoptions.code.printout"</code></em></span> can be deparsed to: <span class="quote">“<span class="quote">The printout section of the generated code of the element with the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> plotoptions</span>”</span> (plotoptions is the ID we gave for the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><embed></strong></span></span> tag above). And yes, if you want advanced control, you can even fetch the values of individual <acronym class="acronym">GUI</acronym> elements inside the embedded plugin (but not the other way around, as the embedded plugin does not know anything about its surroundings).
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="embedding_dialog.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="embedding_wizard.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Embedding inside a dialog </td><td width="34%" align="center" class="navCenter"><a href="embedding.html">Up</a></td><td width="33%" align="right" class="navRight"> Embedding inside a wizard</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/embedding_dialog.html b/doc/rkwardplugins/embedding_dialog.html
new file mode 100644
index 0000000..53702ea
--- /dev/null
+++ b/doc/rkwardplugins/embedding_dialog.html
@@ -0,0 +1,22 @@
+<html><head><title>Embedding inside a dialog</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins"><link rel="prev" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins"><link rel="next" href="embedding_code.html" title="Code generation when embedding"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Embedding inside a dialog</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="embedding.html">Prev</a></td><td align="center" class="navCenter" width="34%">Embedding Plugins into Plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="embedding_code.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="embedding_dialog"></a>Embedding inside a dialog</h2></div></div></div><p>
+ OK, enough said. How does it work? Simple: Just use the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><embed></strong></span></span> tag. Here is a stripped down example:
+ </p><pre class="programlisting">
+<dialog>
+ <tabbook>
+ <tab [...]>
+ [...]
+ </tab>
+ <tab label="Plot Options" i18n_context="Options concerning the plot">
+ <embed id="plotoptions" component="rkward::plot_options"/>
+ </tab>
+ <tab [...]>
+ [...]
+ </tab>
+ </tabbook>
+</dialog>
+ </pre><p>
+ What happens here, is that the entire <acronym class="acronym">GUI</acronym> or the plot options plugin (except of course for the standard elements like <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guibutton">Submit</span></span> button, <abbr class="abbrev">etc.</abbr>) is embedded right into your plugin (try it!).
+ </p><p>
+ As you can see the syntax of the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><embed></strong></span></span>-tag is fairly simple. It takes an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> as most elements. The parameter component specifies which plugin to embed, as defined in the <code class="literal">.pluginmap</code> file (<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"rkward::plot_options"</code></em></span> is the result of concatenating the namespace <span class="quote">“<span class="quote">rkward</span>”</span>, a separator <span class="quote">“<span class="quote">::</span>”</span>, and the name of the component <span class="quote">“<span class="quote">plot_options</span>”</span>).
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="embedding.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="embedding_code.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Embedding Plugins into Plugins </td><td width="34%" align="center" class="navCenter"><a href="embedding.html">Up</a></td><td width="33%" align="right" class="navRight"> Code generation when embedding</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/embedding_incomplete.html b/doc/rkwardplugins/embedding_incomplete.html
new file mode 100644
index 0000000..b128a8a
--- /dev/null
+++ b/doc/rkwardplugins/embedding_incomplete.html
@@ -0,0 +1,28 @@
+<html><head><title>Embedding/defining incomplete plugins</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins"><link rel="prev" href="embedding_as_button.html" title="Less embedded embedding: Further Options button"><link rel="next" href="plugin_series.html" title="Chapter 9. Dealing with many similar plugins"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Embedding/defining incomplete plugins</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="embedding_as_button.html">Prev</a></td><td align="center" class="navCenter" width="34%">Embedding Plugins into Plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="plugin_series.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="embedding_incomplete"></a>Embedding/defining incomplete plugins</h2></div></div></div><p>
+ Some plugins -- and as a matter of fact, the plot_options used as an example above, is one of them -- are not complete by themselves. They simply do not have the <acronym class="acronym">GUI</acronym> elements to select some important values. They are meant to be used only embedded into other plugins.
+ </p><p>
+ In how far is the plot_options plugin incomplete? Well, for some option settings, it needs to know the name of the objects/expressions for the x and y axes (actually it will do fine if it only has either, but it needs at least one to function properly). However, it does not have a mechanism of selecting those objects, or entering them any other way. So how does it know about them?
+ </p><p>
+ In the logic section of the plot_options plugin there are two additional lines, not covered, yet:
+ </p><pre class="programlisting">
+ <logic>
+ <external id="xvar" />
+ <external id="yvar" />
+
+ [...]
+ </logic>
+ </pre><p>
+ This defines two additional properties in the plot_options plugin, whose sole purpose is to be connected to some (yet unknown) properties of the embedding plugin. In the plot_options plugin those two properties are simply used like any other, and for instance there are calls to <code class="function">getString("xvar")</code> in the plot_options JS template.
+ </p><p>
+ Now, for the incomplete plugin there is no way of knowing, where it will be embedded, and what the relevant settings in the embedding plugin will be called. So we need to add two additional lines in the embedding plugin's logic section as well:
+ </p><pre class="programlisting">
+ <logic>
+ [...]
+
+ <connect client="plotoptions.xvar" governor="xvarslot.available" />
+ <connect client="plotoptions.yvar" governor="yvarslot.available" />
+ </logic>
+ </pre><p>
+ This is nothing new in principle, we have covered <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><connect></strong></span></span> statements in the <a class="link" href="logic.html" title="Chapter 7. Logic interactions between GUI elements">chapter of <acronym class="acronym">GUI</acronym> logic</a>. You simply connect the values in two varlots (called <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"xvarslot"</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"yvarslot"</code></em></span> in this example) to the receiving <span class="quote">“<span class="quote">external</span>”</span> properties of the embedded plugin. That is it. Everything else is taken care of automatically.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="embedding_as_button.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="plugin_series.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Less embedded embedding: Further Options button </td><td width="34%" align="center" class="navCenter"><a href="embedding.html">Up</a></td><td width="33%" align="right" class="navRight"> Dealing with many similar plugins</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/embedding_wizard.html b/doc/rkwardplugins/embedding_wizard.html
new file mode 100644
index 0000000..b2e897f
--- /dev/null
+++ b/doc/rkwardplugins/embedding_wizard.html
@@ -0,0 +1,18 @@
+<html><head><title>Embedding inside a wizard</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins"><link rel="prev" href="embedding_code.html" title="Code generation when embedding"><link rel="next" href="embedding_as_button.html" title="Less embedded embedding: Further Options button"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Embedding inside a wizard</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="embedding_code.html">Prev</a></td><td align="center" class="navCenter" width="34%">Embedding Plugins into Plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="embedding_as_button.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="embedding_wizard"></a>Embedding inside a wizard</h2></div></div></div><p>
+ If your plugin provides a wizard <acronym class="acronym">GUI</acronym>, embedding works basically in the same way. You will generally use:
+ </p><pre class="programlisting">
+ <wizard [...]>
+ [...]
+ <page id="page12">
+ [...]
+ </page>
+ <embed id="plotoptions" component="rkward::plot_options"/>
+ <page id="page13">
+ [...]
+ </page>
+ [...]
+ </wizard>
+ </pre><p>
+ If the embedded plugin provides a wizard interface, its pages will be inserted right between <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"page12"</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"page13"</code></em></span> of your plugin. If the embedded plugin provides a dialog interface only, a single new page will be added between your pages <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"page12"</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"page13"</code></em></span>. The user will never notice.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="embedding_code.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="embedding_as_button.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Code generation when embedding </td><td width="34%" align="center" class="navCenter"><a href="embedding.html">Up</a></td><td width="33%" align="right" class="navRight"> Less embedded embedding: Further Options button</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/external_plugins.html b/doc/rkwardplugins/external_plugins.html
new file mode 100644
index 0000000..d6dc456
--- /dev/null
+++ b/doc/rkwardplugins/external_plugins.html
@@ -0,0 +1,10 @@
+<html><head><title>Chapter 14. Share your work with others</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="chapter_about_information.html" title="Chapter 13. Author, license and version information"><link rel="next" href="why_external_plugins.html" title="Why external plugins?"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Share your work with others</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="chapter_about_information.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="why_external_plugins.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="external_plugins"></a>Chapter 14. Share your work with others</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="external_plugins.html#sect_external_plugins">External plugins</a></span></dt><dt><span class="sect1"><a href="why_external_plugins.html">Why external plugins?</a></span></dt><dt><span class="sect1"><a href="structure_of_a_plugin_package.html">Structure of a plugin package</a></span></dt><dd><dl><dt><span class="sect2"><a href="structure_of_a_plugin_package.html#file_hierarchy">File hierarchy</a></span></dt></dl></dd><dt><span class="sect1"><a href="building_the_plugin_package.html">Building the plugin package</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_external_plugins"></a>External plugins</h2></div></div></div><p>
+ As of version 0.5.5, <span class="application">RKWard</span> provides a comfortable way to install additional third party plugins which do not belong to the core package itself. We call these <span class="quote">“<span class="quote">external plugins</span>”</span>. They come in form of an <span class="application">R</span> package and can be managed directly via the usual package management features of <span class="application">R</span> and/or <span class="application">RKWard</span>.
+ </p><p>
+ This section of the documentation describes how external plugins are to be packaged, so that <span class="application">RKWard</span> 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.
+ </p><p>
+ 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.
+ </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+ 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 <a class="link" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><span class="application">rkwarddev</span> package</a>, which was designed to automate a lot of the writing process.
+ </p></div></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="chapter_about_information.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="why_external_plugins.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Author, license and version information </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Why external plugins?</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/globalxmlelements.html b/doc/rkwardplugins/globalxmlelements.html
new file mode 100644
index 0000000..0f4a755
--- /dev/null
+++ b/doc/rkwardplugins/globalxmlelements.html
@@ -0,0 +1,5 @@
+<html><head><title>General purpose elements to be used in any XML file (.xml, .rkh, .pluginmap)</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="reference.html" title="Appendix A. Reference"><link rel="prev" href="reference.html" title="Appendix A. Reference"><link rel="next" href="xmlelements.html" title="Elements to be used in the XML description of the plugin"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>General purpose elements to be used in any <acronym class="acronym">XML</acronym> file (<code class="literal">.xml</code>, <code class="literal">.rkh</code>, <code class="literal">.pluginmap</code>)</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="reference.html">Prev</a></td><td align="center" class="navCenter" width="34%">Reference</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="xmlelements.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="globalxmlelements"></a>General purpose elements to be used in any <acronym class="acronym">XML</acronym> file (<code class="literal">.xml</code>, <code class="literal">.rkh</code>, <code class="literal">.pluginmap</code>)</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><snippets></span></dt><dd><p>Allowed as a direct child of the <document> node and only there. Should be placed near the top of the file. See <a class="link" href="snippets.html" title="Using <snippets>">section on using snippets</a>. Only one <snippets> element may be present. Optional, no attributes.</p></dd><dt><span class="term"><snippet></span></dt><dd><p>Defines a single snippet. Allowed only as a direct child of the <snippets/> element. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><id></span></dt><dd><p>An identifier string for the snippet. Required.</p></dd></dl></div></dd><dt><span class="term"><insert></span></dt><dd><p>Insert the contents of a <snippet>. Allowed anywhere. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><snippet></span></dt><dd><p>The identifier string of the snippet to insert. Required.</p></dd></dl></div></dd><dt><span class="term"><include></span></dt><dd><p>Include the contents of another <acronym class="acronym">XML</acronym> file (everything inside the <document> element of that file). Allowed anywhere. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><file></span></dt><dd><p>The filename, relative to the directory, the current file is in. Required.</p></dd></dl></div></dd></dl></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="reference.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="xmlelements.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Reference </td><td width="34%" align="center" class="navCenter"><a href="reference.html">Up</a></td><td width="33%" align="right" class="navRight"> Elements to be used in the <acronym class="acronym">XML</acronym> description of the plugin</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/guilogic_functions.html b/doc/rkwardplugins/guilogic_functions.html
new file mode 100644
index 0000000..1bbe8b4
--- /dev/null
+++ b/doc/rkwardplugins/guilogic_functions.html
@@ -0,0 +1,4 @@
+<html><head><title>Functions available for GUI logic scripting</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="reference.html" title="Appendix A. Reference"><link rel="prev" href="helpfileelements.html" title="Elements for use in .rkh (help) files"><link rel="next" href="troubleshooting.html" title="Appendix B. Troubleshooting during plugin development"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Functions available for <acronym class="acronym">GUI</acronym> logic scripting</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="helpfileelements.html">Prev</a></td><td align="center" class="navCenter" width="34%">Reference</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="troubleshooting.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="guilogic_functions"></a>Functions available for <acronym class="acronym">GUI</acronym> logic scripting</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">Class "Component"</span></dt><dd><p>Class which represents a single component or component-property. The most important instance of this class is the variable "gui" which is predefined as the root property of the current component. The following methods are available for instances of class "Component":
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">absoluteId(base_id)</span></dt><dd><p>Returns the absolute ID of <span class="emphasis"><em>base_id</em></span>, or - if base_id is omitted - the identifier of the component.</p></dd><dt><span class="term">getValue(id)</span></dt><dd><p>Discouraged. Use <code class="function">getString(), getBoolean(), or getList()</code>, instead. Returns the value of the given child property. Returns the value of this property, if ID is omitted.</p></dd><dt><span class="term">getString(id)</span></dt><dd><p>Returns the value of the given child property as a string. Returns the value of this property, if ID is omitted.</p></dd><dt><span class="term">getBoolean(id)</span></dt><dd><p>Returns the value of the given child property as a boolean (if possible). Returns the value of this property, if ID is omitted.</p></dd><dt><span class="term">getList(id)</span></dt><dd><p>Returns the value of the given child property as an array of strings (if possible). Returns the value of this property, if ID is omitted.</p></dd><dt><span class="term">setValue(id, value)</span></dt><dd><p>Set the value of the given child property to <span class="emphasis"><em>value</em></span>.</p></dd><dt><span class="term">getChild(id)</span></dt><dd><p>Return an instance of the child-property with the given <span class="emphasis"><em>id</em></span>.</p></dd><dt><span class="term">addChangeCommand(id, command)</span></dt><dd><p>Execute <span class="emphasis"><em>command</em></span> whenever the child property given by <span class="emphasis"><em>id</em></span> changes.</p></dd></dl></div></dd><dt><span class="term">Class "RObject"</span></dt><dd><p>Class which represents a single <span class="application">R</span> object. An instance of this class can be obtained by using <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>makeRObject(objectname)</strong></span></span>. The following methods are available for instances of class "RObject": </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>If any commands are still pending in the backend, the information provided by these methods can be out-of-date by the time that the plugin code is run. Do <span class="emphasis"><em>not</em></span> rely on it for critical operations (risking loss of data).</p></div><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">getName()</span></dt><dd><p>Returns the absolute name of the object.</p></dd><dt><span class="term">exists()</span></dt><dd><p>Returns whether the object exists. You should generally check this before using any of the methods listed below.</p></dd><dt><span class="term">dimensions()</span></dt><dd><p>Returns an array of dimensions (similar to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>dim()</strong></span></span> in R).</p></dd><dt><span class="term">classes()</span></dt><dd><p>Returns an array of classes (similar to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>class()</strong></span></span> in R).</p></dd><dt><span class="term">isClass(class)</span></dt><dd><p>Returns true, if the object is of class <span class="emphasis"><em>class</em></span>.</p></dd><dt><span class="term">isDataFrame()</span></dt><dd><p>Returns true, if the object is a data.frame.</p></dd><dt><span class="term">isMatrix()</span></dt><dd><p>Returns true, if the object is a matrix.</p></dd><dt><span class="term">isList()</span></dt><dd><p>Returns true, if the object is a list.</p></dd><dt><span class="term">isFunction()</span></dt><dd><p>Returns true, if the object is a function.</p></dd><dt><span class="term">isEnvironment()</span></dt><dd><p>Returns true, if the object is an environment.</p></dd><dt><span class="term">isDataNumeric()</span></dt><dd><p>Returns true, if the object is a vector of numeric data.</p></dd><dt><span class="term">isDataFactor()</span></dt><dd><p>Returns true, if the object is a vector of factor data.</p></dd><dt><span class="term">isDataCharacter()</span></dt><dd><p>Returns true, if the object is a vector of character data.</p></dd><dt><span class="term">isDataLogical()</span></dt><dd><p>Returns true, if the object is a vector of logical data.</p></dd><dt><span class="term">parent()</span></dt><dd><p>Returns an instance of "RObject" representing the parent of this object.</p></dd><dt><span class="term">child(childname)</span></dt><dd><p>Returns an instance of "RObject" representing the child <span class="emphasis"><em>childname</em></span> of this object.</p></dd></dl></div></dd><dt><span class="term">Class "RObjectArray"</span></dt><dd><p>An array of RObject instances. An instance of this class can be obtained by using <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>makeRObjectArray(objectnames)</strong></span></span>. It is particularly useful when dealing with varslots which allow to select multiple objects.</p></dd><dt><span class="term">include()-function</span></dt><dd><p><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>include(filename)</strong></span></span> can be used to include a separate JS file.</p></dd><dt><span class="term">doRCommand()-function</span></dt><dd><p><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>doRCommand(command, callback)</strong></span></span> can be used to query <span class="application">R</span> for information. Please read the section on <a class="link" href="querying_r_for_info.html" title="Querying R for information">querying <span class="application">R</span> from inside a plugin</a> for details, and caveats.</p></dd></dl></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="helpfileelements.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="troubleshooting.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Elements for use in .rkh (help) files </td><td width="34%" align="center" class="navCenter"><a href="reference.html">Up</a></td><td width="33%" align="right" class="navRight"> Troubleshooting during plugin development</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/helpfileelements.html b/doc/rkwardplugins/helpfileelements.html
new file mode 100644
index 0000000..d469ac2
--- /dev/null
+++ b/doc/rkwardplugins/helpfileelements.html
@@ -0,0 +1,7 @@
+<html><head><title>Elements for use in .rkh (help) files</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="reference.html" title="Appendix A. Reference"><link rel="prev" href="pluginmapelements.html" title="Elements for use in .pluginmap files"><link rel="next" href="guilogic_functions.html" title="Functions available for GUI logic scripting"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Elements for use in .rkh (help) files</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="pluginmapelements.html">Prev</a></td><td align="center" class="navCenter" width="34%">Reference</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="guilogic_functions.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="helpfileelements"></a>Elements for use in .rkh (help) files</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><document></span></dt><dd><p>Needs to be present in each <code class="literal">.xml</code> file as the root-node (exactly once). No attributes.</p></dd><dt><span class="term"><title></span></dt><dd><p>Title of the help page. This is <span class="emphasis"><em>not</em></span> interpreted for help pages for a plugin (this takes the title from the plugin itself), only for stand-alone pages. No attributes. The text contained within the <title> tag will become the caption of the help page. May only be defined once, as a direct child of the <document> node.</p></dd><dt><span class="term"><summary></span></dt><dd><p>A short summary of the help page (or what this plugin is used for). This will always be shown at the top of the help page. No attributes. The text contained within the <summary> tag will be displayed. Recommended but not required. May only be defined once, as a direct child of the <document> node.</p></dd><dt><span class="term"><usage></span></dt><dd><p>A slightly more elaborate summary of the usage. This will always be shown directly after the <summary>. No attributes. The text contained within the <usage> tag will be displayed. Recommended for plugin help pages, but not required. May only be defined once, as a direct child of the <document> node.</p></dd><dt><span class="term"><section></span></dt><dd><p>A general purposes section. May be used any number of times as a direct child of the <document> node. These sections are displayed in the order of their definition, but all <span class="emphasis"><em>after</em></span> the <usage> section and <span class="emphasis"><em>before</em></span> the <settings> section. The text contained within the <section> tag will be displayed.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">id</span></dt><dd><p>An identifier needed to jump to this section from the navigation bar (or a link). Needs to be unique within the file. Required, no default.</p></dd><dt><span class="term">title</span></dt><dd><p>The title (caption) of this section. Required, no default.</p></dd><dt><span class="term">short_title</span></dt><dd><p>A short title suitable to be displayed in the navigation bar. Optional, defaults to the full title.</p></dd></dl></div></dd><dt><span class="term"><settings></span></dt><dd><p>Defines the section containing reference on the various <acronym class="acronym">GUI</acronym> settings. Only meaningful and only used for plugin related help pages. Use as a direct child of the <document>. May contain only <setting> and <caption> elements as direct children. No attributes.</p></dd><dt><span class="term"><setting></span></dt><dd><p>Explains a single setting in the <acronym class="acronym">GUI</acronym>. Only allowed as a direct child of the <settings> element. The text contained within the element is displayed.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">id</span></dt><dd><p>The ID of the setting in the plugin <code class="literal">.xml</code>. Required, no default.</p></dd><dt><span class="term">title</span></dt><dd><p>An optional title for the setting. If omitted (omission is recommended in most cases), the title will be taken from the plugin <code class="literal">.xml</code>.</p></dd></dl></div></dd><dt><span class="term"><caption></span></dt><dd><p>A caption to visually group several settings. May only be used as a direct child of the <settings> element.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">id</span></dt><dd><p>The ID of the corresponding element (typically a <frame>, <page> or <tab>) in the plugin <code class="literal">.xml</code>.</p></dd><dt><span class="term">title</span></dt><dd><p>An optional title for the caption. If omitted (omission is recommended in most cases), the title will be taken from the plugin <code class="literal">.xml</code>.</p></dd></dl></div></dd><dt><span class="term"><related></span></dt><dd><p>Defines a section containing links to further related information. Will always be displayed after the <settings> section. No attributes. The text contained within the <related> tag will be displayed. Typically this will contain an <acronym class="acronym">HTML</acronym>-style list. Recommended for plugin help pages, but not required. May only be defined once, as a direct child of the <document> node.</p></dd><dt><span class="term"><technical></span></dt><dd><p>Defines a section containing technical information of no relevance to end users (such as internal structure of the plugin). Will always be displayed last in a help page. No attributes. The text contained within the <related> tag will be displayed. Not required, and not recommended for most plugin help pages. May only be defined once, as a direct child of the <document> node.</p></dd><dt><span class="term"><link></span></dt><dd><p>A link. Can be used in any of the sections described above.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">href</span></dt><dd><p>The target <acronym class="acronym">URL</acronym>. Note that several <span class="application">RKWard</span> specific <acronym class="acronym">URL</acronym>s are available. See <a class="link" href="pluginhelp.html" title="Chapter 6. Writing a help page">section on writing help pages</a> for details.</p></dd></dl></div></dd><dt><span class="term"><label></span></dt><dd><p>Inserts the value of a UI label. Can be used in any of the sections described above.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">id</span></dt><dd><p>The id of the element in the plugin, of which to copy the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>label</code></em></span>-attribute.</p></dd></dl></div></dd><dt><span class="term"><various <acronym class="acronym">HTML</acronym> tags></span></dt><dd><p>Most basic <acronym class="acronym">HTML</acronym> tags are allowed within the sections. Please keep manual formatting to a minimum, however.</p></dd></dl></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="pluginmapelements.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="guilogic_functions.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Elements for use in <code class="literal">.pluginmap</code> files </td><td width="34%" align="center" class="navCenter"><a href="reference.html">Up</a></td><td width="33%" align="right" class="navRight"> Functions available for <acronym class="acronym">GUI</acronym> logic scripting</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/i18n.html b/doc/rkwardplugins/i18n.html
new file mode 100644
index 0000000..d290e9c
--- /dev/null
+++ b/doc/rkwardplugins/i18n.html
@@ -0,0 +1,14 @@
+<html><head><title>Chapter 12. Plugin translations</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="sect_dependencies_example.html" title="An example"><link rel="next" href="i18n_xml.html" title="i18n in RKWard's xml files"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Plugin translations</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="sect_dependencies_example.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="i18n_xml.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="i18n"></a>Chapter 12. Plugin translations</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="i18n.html#i18n_general">General considerations</a></span></dt><dt><span class="sect1"><a href="i18n_xml.html">i18n in <span class="application">RKWard</span>'s xml files</a></span></dt><dt><span class="sect1"><a href="i18n_js.html">i18n in <span class="application">RKWard</span>'s js files and sections</a></span></dt><dd><dl><dt><span class="sect2"><a href="i18n_js.html#i18n_js_quoting">i18n and quotes</a></span></dt></dl></dd><dt><span class="sect1"><a href="i18n_workflow.html">Translation maintainance</a></span></dt><dt><span class="sect1"><a href="i18n_translators.html">Writing plugin translations</a></span></dt></dl></div><p>
+ So far we have used a few concepts regarding translations or "i18n" (short for "internationalization", which has 18 characters between i and n) in passing. In this chapter we
+ give a more in-depth account of what i18n functionally for <span class="application">RKWard</span> plugins. For the most part you will <span class="emphasis"><em>not</em></span> need all of this in your plugins. However,
+ it may be a good idea to read over this chapter in full, as understanding these concepts should help you creating plugins that are fully translatable, and that allow for a high
+ quality of translations.
+ </p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n_general"></a>General considerations</h2></div></div></div><p>
+ One important point to understand about software translations, in contrast to translations of other text materials, is that translators will often have a rather hard
+ time getting a complete picture of <span class="emphasis"><em>what</em></span> they are translating. Software translations are necessarily based on rather short fragments of text: Every
+ label you give to an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><option></strong></span></span> in a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span>, every string that you mark for translation in an
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18n()</strong></span></span>-function call, will form a separate "translation unit". In essence, each such fragment will be presented to the translator in isolation. Well,
+ not complete isolation, as we do try to provide translator with as much meaningful context as can be extracted, automatically. But at some points translators will need
+ additional context to make sense of a string, especially where strings are short.
+ </p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="sect_dependencies_example.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="i18n_xml.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">An example </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> i18n in <span class="application">RKWard</span>'s xml files</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/i18n_js.html b/doc/rkwardplugins/i18n_js.html
new file mode 100644
index 0000000..98c40d2
--- /dev/null
+++ b/doc/rkwardplugins/i18n_js.html
@@ -0,0 +1,34 @@
+<html><head><title>i18n in RKWard's js files and sections</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="i18n.html" title="Chapter 12. Plugin translations"><link rel="prev" href="i18n_xml.html" title="i18n in RKWard's xml files"><link rel="next" href="i18n_workflow.html" title="Translation maintainance"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>i18n in <span class="application">RKWard</span>'s js files and sections</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="i18n_xml.html">Prev</a></td><td align="center" class="navCenter" width="34%">Plugin translations</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="i18n_workflow.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n_js"></a>i18n in <span class="application">RKWard</span>'s js files and sections</h2></div></div></div><p>
+ In contrast to the <code class="literal">.xml</code> files, making the <code class="literal">.js</code> files of a plugin translatable requires more custom work. The key difference, here, is that there is no decent automatic way to tell,
+ whether a string is meant to be displayed as a human readable string, or a piece of code. So you need to mark this up, yourself. We have already shown examples of this, all along. Here
+ is a more complete description of the i18n-functions available in js code, and some hints for more complex cases:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18n (msgid, [...])</strong></span></span></span></dt><dd><p>The most important function. Marks the string for translation. The string (whether translated or not) is returned quoted using double quotes ('"'). An arbitrary
+ number of placeholders can be used in the string like shown below. Using such placeholders instead of concatenating small substrings is much easier for translators:</p><pre class="programlisting">
+ i18n ("Compare objects %1 and %2", getString ('x'), getString ('y'));
+ </pre></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18nc (msgctxt, msgid, [...])</strong></span></span></span></dt><dd><p>Same as <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18n()</strong></span></span>, but additionally providing a message context:</p><pre class="programlisting">
+ i18nc ("proper name, not state of mind", "Mood test");
+ </pre></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18np (msgid_singular, msgid_plural, n, [...])</strong></span></span></span></dt><dd><p>Same as <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18n()</strong></span></span>, but for messages that may be different in singular or plural form (and some languages have differentiate yet more numerical forms). Note
+ that just like with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18n()</strong></span></span>, you can use an arbitrary number of replacements, but the first ('%1') is required, and has to be an integer.</p><pre class="programlisting">
+ i18np ("Comparing a single pair", "Comparing %1 distinct pairs", n_pairs);
+ </pre></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18ncp (msgctxt, msgid_singular, msgid_plural, n, [...])</strong></span></span></span></dt><dd><p><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18np()</strong></span></span> with added message context.</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>comment (comment, [indentation])</strong></span></span></span></dt><dd><p>Echos a code comment, marked for translation. In contrast to the other i18n() functions, this is not quoted, but a '#' is added to each line of the comment.</p><pre class="programlisting">
+ comment ("Transpose the matrix");
+ echo ('x <- t (x)\n');
+ </pre></dd></dl></div><p>
+ To add comments to the translators (see <a class="link" href="i18n_xml.html" title="i18n in RKWard's xml files">above</a> for a discussion of the differences between comment and context), add a comment starting with "i18n:" or
+ "translators:" directly above the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18n()</strong></span></span>-call to comment. E.g.:
+ </p><pre class="programlisting">
+ // i18n: Spelling is correct: Scree plot.
+ echo ('rk.header (' + i18n ("Scree plot") + ')\n');
+ </pre><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n_js_quoting"></a>i18n and quotes</h3></div></div></div><p>
+ For the most part, you will not have to worry about i18n() behavior with respect to quotes. As, typically, translatable strings are string literals, quoting them is just the
+ right thing to do, and saves you some typing. Also, in functions like <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>makeHeaderCode()/Header()</strong></span></span> that usually quote their arguments, i18n()'ed strings are protected
+ from duplicate quoting. Essentially, this works, by sending the translated string first through <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>quote()</strong></span></span> (to make it quoted), then through
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>noquote()</strong></span></span> (to protect it from additional quoting). Should you require a translatable string that is not quoted, use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18n(noquote ("My message"))</strong></span></span>.
+ Should you require a translatable string to be quoted, a second time, send it through <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>quote()</strong></span></span>, <span class="emphasis"><em>twice</em></span>.
+ </p><p>
+ That said, it is generally not a good idea to make bits like function names or variable names translatable. For one thing, <span class="application">R</span>, the programming language, is inherently in English,
+ and there is no internationalization of the language itself. Code comments are a different beast, but you should use the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>comment()</strong></span></span>-function for those. Secondly,
+ making syntactically relevant parts of the generated code translatable means that translations could actually break your plugin.
+ E.g. if an unsuspecting translator translates a string meant as a variable name in two distinct words with a space in between.
+ </p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="i18n_xml.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="i18n_workflow.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">i18n in <span class="application">RKWard</span>'s xml files </td><td width="34%" align="center" class="navCenter"><a href="i18n.html">Up</a></td><td width="33%" align="right" class="navRight"> Translation maintainance</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/i18n_translators.html b/doc/rkwardplugins/i18n_translators.html
new file mode 100644
index 0000000..81d1069
--- /dev/null
+++ b/doc/rkwardplugins/i18n_translators.html
@@ -0,0 +1,10 @@
+<html><head><title>Writing plugin translations</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="i18n.html" title="Chapter 12. Plugin translations"><link rel="prev" href="i18n_workflow.html" title="Translation maintainance"><link rel="next" href="chapter_about_information.html" title="Chapter 13. Author, license and version information"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Writing plugin translations</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="i18n_workflow.html">Prev</a></td><td align="center" class="navCenter" width="34%">Plugin translations</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="chapter_about_information.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n_translators"></a>Writing plugin translations</h2></div></div></div><p>
+ We assume you know your trade as a translator, or are willing to read up on it, elsewhere. A few words specifically about translations of <span class="application">RKWard</span> plugins, though:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="application">RKWard</span> plugins were not translatable until version 0.6.3, and were mostly not written with i18n in mind, before then. Thus you are going to encounter rather
+ more ambiguous strings, and other i18n problems than in other mature projects. Please do not just silently work around these, but let us (or the plugin maintainers)
+ know, so we can fix these issues.</p></li><li class="listitem"><p>Many <span class="application">RKWard</span> plugins refer to highly specialized terms, from data handling and statistics, but also from other fields of science. In many cases, a good translation
+ will require at least basic knowledge of these fields. In some cases, there <span class="emphasis"><em>is</em></span> no good translation for a technical term, and the best option may
+ be to leave the term untranslated, or to include the English term in parentheses. Do not focus too much on the 100% mark of translated strings, focus on providing
+ a good translation, even if that means skipping some strings (or even skipping some message catalogs as a whole). Other users may be able to fill in any gaps in technical
+ terms.</p></li></ul></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="i18n_workflow.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="chapter_about_information.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Translation maintainance </td><td width="34%" align="center" class="navCenter"><a href="i18n.html">Up</a></td><td width="33%" align="right" class="navRight"> Author, license and version information</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/i18n_workflow.html b/doc/rkwardplugins/i18n_workflow.html
new file mode 100644
index 0000000..2f48974
--- /dev/null
+++ b/doc/rkwardplugins/i18n_workflow.html
@@ -0,0 +1,15 @@
+<html><head><title>Translation maintainance</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="i18n.html" title="Chapter 12. Plugin translations"><link rel="prev" href="i18n_js.html" title="i18n in RKWard's js files and sections"><link rel="next" href="i18n_translators.html" title="Writing plugin translations"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Translation maintainance</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="i18n_js.html">Prev</a></td><td align="center" class="navCenter" width="34%">Plugin translations</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="i18n_translators.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n_workflow"></a>Translation maintainance</h2></div></div></div><p>
+ Now that you have made your plugin translatable, how do you actually get it translated? In general you only need to worry about this, when developing an <a class="link" href="external_plugins.html" title="Chapter 14. Share your work with others">
+ external plugin</a>. For plugins in <span class="application">RKWard</span>'s main repository, all the magic is done for you. Here is the basic workflow for a external plugins. Note that you need the "gettext" tools, installed:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Mark up all strings, providing context and comments as needed</p></li><li class="listitem"><p>Run <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>python3 scripts/update_plugin_messages.py --extract-only /path/to/my.pluginmap</strong></span></span>. scripts/update_plugin_messages.py is not currently part of the source
+ releases, but can be found in a source repository checkout.</p></li><li class="listitem"><p>Distribute the resulting <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rkward__<span class="replaceable"><em class="replaceable"><code>POID</code></em></span>.pot</strong></span></span> file to your translators. For external plugins, it is recommended to place it
+ in a subfolder "po" in inst/rkward.</p></li><li class="listitem"><p>Translator opens the file in a translation tool such as <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>lokalize</strong></span></span>. Actually, even if you are not going to prepare any translation, yourself,
+ you should try this step for yourself. Browse the extracted strings looking out for problems / ambiguities.</p></li><li class="listitem"><p>Translator saves the translation as <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rkward__<span class="replaceable"><em class="replaceable"><code>POID</code></em></span>.<span class="replaceable"><em class="replaceable"><code>xx</code></em></span>.po</strong></span></span> (where
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>xx</code></em></span> is the language code), and sends it back to you.</p></li><li class="listitem"><p>Copy <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rkward__<span class="replaceable"><em class="replaceable"><code>POID</code></em></span>.<span class="replaceable"><em class="replaceable"><code>xx</code></em></span>.po</strong></span></span> to your sources, next to
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rkward__<span class="replaceable"><em class="replaceable"><code>POID</code></em></span>.pot</strong></span></span>. Run <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>python3 scripts/update_plugin_messages.py /path/to/my.pluginmap</strong></span></span> (Note: without
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>--extract-only</code></em></span>, this time). This will merge the translation with any interim string changes, compile the translation, and install it into
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><span class="replaceable"><em class="replaceable"><code>DIR_OF_PLUGINMAP</code></em></span>/po/<span class="replaceable"><em class="replaceable"><code>xx</code></em></span>/LC_MESSAGES/rkward__<span class="replaceable"><em class="replaceable"><code>POID</code></em></span>.mo</strong></span></span> (where
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>xx</code></em></span> is the language code, again).</p></li><li class="listitem"><p>You should also include the non-compiled translation (<abbr class="abbrev">i.e.</abbr> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rkward__<span class="replaceable"><em class="replaceable"><code>POID</code></em></span>.<span class="replaceable"><em class="replaceable"><code>xx</code></em></span>.po</strong></span></span>) in
+ your distribution, in the "po" subdirectory.</p></li><li class="listitem"><p>For any update of your plugin, run <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>python3 scripts/update_plugin_messages.py /path/to/my.pluginmap</strong></span></span> to update the .pot file, but also the
+ existing .po-files, and the compiled message catalogs.</p></li></ul></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="i18n_js.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="i18n_translators.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">i18n in <span class="application">RKWard</span>'s js files and sections </td><td width="34%" align="center" class="navCenter"><a href="i18n.html">Up</a></td><td width="33%" align="right" class="navRight"> Writing plugin translations</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/i18n_xml.html b/doc/rkwardplugins/i18n_xml.html
new file mode 100644
index 0000000..7ffa930
--- /dev/null
+++ b/doc/rkwardplugins/i18n_xml.html
@@ -0,0 +1,45 @@
+<html><head><title>i18n in RKWard's xml files</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="i18n.html" title="Chapter 12. Plugin translations"><link rel="prev" href="i18n.html" title="Chapter 12. Plugin translations"><link rel="next" href="i18n_js.html" title="i18n in RKWard's js files and sections"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>i18n in <span class="application">RKWard</span>'s xml files</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="i18n.html">Prev</a></td><td align="center" class="navCenter" width="34%">Plugin translations</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="i18n_js.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n_xml"></a>i18n in <span class="application">RKWard</span>'s xml files</h2></div></div></div><p>
+ For <span class="application">RKWard</span>'s <acronym class="acronym">XML</acronym> files, i18n will mostly just work. If you are writing your own <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>.pluginmap</strong></span></span> (<abbr class="abbrev">e.g.</abbr> for an <a class="link" href="external_plugins.html" title="Chapter 14. Share your work with others">external plugin</a>),
+ you will have to specify a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>po_id</code></em></span> next to the pluginmap's <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>id</code></em></span>. This defines the "message catalog" to use. In general this should
+ be set identical to the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>id</code></em></span> of your <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>.pluginmap</strong></span></span>, but if you provide several related <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>.pluginmap</strong></span></span>s in a single package, you will
+ probably want to specify a common <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>po_id</code></em></span> in your maps. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>po_id</code></em></span> of a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>.pluginmap</strong></span></span> file is inherited by all plugins
+ declared in it, unless that declares a different <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>po_id</code></em></span>.
+ </p><p>
+ For plugins and help pages, you do not need to tell <span class="application">RKWard</span> which strings are to be translated, because that is generally evident from their usage. However, as explained above,
+ you should keep an eye out for strings that may be ambiguous or need some explaining in order to be translated, correctly. For strings that could have different meanings, provide
+ an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>i18n_context</code></em></span> like this:
+ </p><pre class="programlisting">
+<checkbox id="scale" label="Scale" i18n_context="Show the scale"/>
+<checkbox id="scale" label="Scale" i18n_context="Scale the plot"/>
+ </pre><p>
+ Providing <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>i18n_context</code></em></span> will cause the two strings to be translated separately. Otherwise they would share a single translation. In addition, the context
+ is shown to the translator. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>i18n_context</code></em></span>-attribute is supported on all elements that can have translatable strings, somewhere, including elements that
+ contain text inside them (<abbr class="abbrev">e.g.</abbr> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><text></strong></span></span>-elements).
+ </p><p>
+ In other cases the string to translate has a single non-ambiguous meaning, but may still need some explaining. In this case you can add a comment that will be shown to translators.
+ Examples might include:
+ </p><pre class="programlisting">
+<!-- i18n: No, this is not a typo for screen plot! -->
+<component id="scree_plot" label="Scree plot"/>
+
+<!-- i18n: If you can, please make this string short. Having more than some 15 chars
+looks really ugly at this point, and the meaning should be mostly self-evident to the
+user (selection from a list of values shown next to this element) -->
+<valueslot id="selected" label="Pick one"/>
+ </pre><p>
+ Note that such comments must precede the element they apply to, and must start with either "i18n:" or "TRANSLATORS:".
+ </p><p>
+ Finally, in rare cases, you may want to exclude certain strings from translation. This may make sense, for example, if you offer a choice between
+ several <span class="application">R</span> function names in a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span>-control. You do not want these to be translated, then (but depending on the context,
+ you should consider giving a descriptive label, instead):
+ </p><pre class="programlisting">
+<radio id="transformation" label="R function to apply">
+ <option id="as.list" noi18n_label="as.list()"/>
+ <option id="as.vector" noi18n_label="as.vector()"/>
+ [...]
+</radio>
+ </pre><p>
+ Note that you will omit the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>label</code></em></span>-attribute, then, and specify <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>noi18n_label</code></em></span>, instead. Also, note that in contrast to
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>i18n_context</code></em></span> and comments, using <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>noi18n_label</code></em></span> will make your plugin incompatible with versions of <span class="application">RKWard</span> prior to 0.6.3.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="i18n.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="i18n_js.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Plugin translations </td><td width="34%" align="center" class="navCenter"><a href="i18n.html">Up</a></td><td width="33%" align="right" class="navRight"> i18n in <span class="application">RKWard</span>'s js files and sections</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/include_js.html b/doc/rkwardplugins/include_js.html
new file mode 100644
index 0000000..fa8cd4c
--- /dev/null
+++ b/doc/rkwardplugins/include_js.html
@@ -0,0 +1,56 @@
+<html><head><title>Using the JS include statement</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="plugin_series.html" title="Chapter 9. Dealing with many similar plugins"><link rel="prev" href="plugin_series.html" title="Chapter 9. Dealing with many similar plugins"><link rel="next" href="include_xml.html" title="Including .xml files"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Using the JS include statement</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="plugin_series.html">Prev</a></td><td align="center" class="navCenter" width="34%">Dealing with many similar plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="include_xml.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="include_js"></a>Using the JS include statement</h2></div></div></div><p>
+ You can easily include one script file into another in <span class="application">RKWard</span> 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 <code class="literal">.js</code> file, and include this in all the plugin <code class="literal">.js</code> files. For example, as in:
+ </p><pre class="programlisting">
+// this is a file called "common_functions.js"
+
+function doCommonStuff () {
+ // perhaps fetch some options, etc.
+ // ...
+ comment ("This is R code you want in several different plugins\n");
+ // ...
+}
+ </pre><pre class="programlisting">
+// this is one of your regular plugin <code class="literal">.js</code> files
+
+// include the common functions
+include ("common_functions.js");
+
+function calculate () {
+ // do something
+ // ...
+
+ // insert the common code
+ doCommonStuff ();
+}
+ </pre><p>
+ Note that sometimes it is even more useful to reverse this, and define the <span class="quote">“<span class="quote">skeleton</span>”</span> of <code class="function">preprocess()</code>, <code class="function">calculate()</code>, and <code class="function">printout()</code> functions is a common file, and make these call back for those part which are different across plugins. E.g.:
+ </p><pre class="programlisting">
+// this is a file called "common_functions.js"
+
+function calculate () {
+ // do some things which are the same in all plugins
+ // ...
+
+ // add in something that is different across plugins
+ getSpecifics ();
+
+ // ...
+}
+ </pre><pre class="programlisting">
+// this is one of your regular plugin <code class="literal">.js</code> files
+
+// include the common functions
+include ("common_functions.js");
+
+// note: no calculate() function is defined in here.
+// it in the common_functions.js, instead.
+
+function getSpecifics () {
+ // print some R code
+}
+ </pre><p>
+ One issue you should be aware of when using this technique is variable scoping. See the JS manual on variable scopes.
+ </p><p>
+ This technique is heavily used in the distribution plot and distribution CLT plot plugins, so you may want to look there for examples.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="plugin_series.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="include_xml.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Dealing with many similar plugins </td><td width="34%" align="center" class="navCenter"><a href="plugin_series.html">Up</a></td><td width="33%" align="right" class="navRight"> Including <code class="literal">.xml</code> files</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/include_snippets_vs_embedding.html b/doc/rkwardplugins/include_snippets_vs_embedding.html
new file mode 100644
index 0000000..0481328
--- /dev/null
+++ b/doc/rkwardplugins/include_snippets_vs_embedding.html
@@ -0,0 +1,10 @@
+<html><head><title><include> and <snippets> vs. <embed></title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="plugin_series.html" title="Chapter 9. Dealing with many similar plugins"><link rel="prev" href="snippets.html" title="Using <snippets>"><link rel="next" href="specialized_plugins.html" title="Chapter 10. Concepts for use in specialized plugins"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1><include> and <snippets> vs. <embed></h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="snippets.html">Prev</a></td><td align="center" class="navCenter" width="34%">Dealing with many similar plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="specialized_plugins.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="include_snippets_vs_embedding"></a><include> and <snippets> vs. <embed></h2></div></div></div><p>
+ At first glance, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><include></strong></span></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><snippets></strong></span></span> provides functionality rather similar to <a class="link" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins">embedding</a>: It allows to reuse some portions of code across plugins. So what is the difference between these approaches, and when should you use which?
+ </p><p>
+ The key difference between these concepts is that embeddable plugins are a more tight bundle. They combine a complete <acronym class="acronym">GUI</acronym>, code to generate <span class="application">R</span> 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.
+ </p><p>
+ 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.
+ </p><p>
+ Hence the rule of thumb is this: include and insert are great if the relevant options are only needed for a clearly limited group of plugins. Embedded plugins are better, if the group of plugins it may be useful to is not clearly defined, and if the functionality can easily be modularized. Another rule of thumb: If you can put the common portions into a single <span class="quote">“<span class="quote">chunk</span>”</span>, then do so, and use embedding. If you need lots of small snippets to define the common portions -- well, use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><snippets></strong></span></span>. A final way to look at it: If all plugins provide <span class="emphasis"><em>highly</em></span> similar functionality, includes and inserts are probably a good idea. If they merely share one or two common <span class="quote">“<span class="quote">modules</span>”</span>, embedding is likely better.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="snippets.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="specialized_plugins.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Using <snippets> </td><td width="34%" align="center" class="navCenter"><a href="plugin_series.html">Up</a></td><td width="33%" align="right" class="navRight"> Concepts for use in specialized plugins</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/include_xml.html b/doc/rkwardplugins/include_xml.html
new file mode 100644
index 0000000..0eeba0e
--- /dev/null
+++ b/doc/rkwardplugins/include_xml.html
@@ -0,0 +1,12 @@
+<html><head><title>Including .xml files</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="plugin_series.html" title="Chapter 9. Dealing with many similar plugins"><link rel="prev" href="include_js.html" title="Using the JS include statement"><link rel="next" href="snippets.html" title="Using <snippets>"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Including <code class="literal">.xml</code> files</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="include_js.html">Prev</a></td><td align="center" class="navCenter" width="34%">Dealing with many similar plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="snippets.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="include_xml"></a>Including <code class="literal">.xml</code> files</h2></div></div></div><p>
+ Basically the same feature of including files is also available for use in the <code class="literal">.xml</code>, <code class="literal">.pluginmap</code> and <code class="literal">.rkh</code> files. At any place in these files you can place an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><include></strong></span></span> tag as shown below. The effect is that the entire contents of that <acronym class="acronym">XML</acronym> file (to be precise: everything within the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><document></strong></span></span> tag of that file) is included verbatim at this point in the file. Note that you can only include another <acronym class="acronym">XML</acronym> file.
+ </p><pre class="programlisting">
+<document>
+ [...]
+ <include file="another_xml_file.xml"/>
+ [...]
+</document>
+ </pre><p>
+ The attribute <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>file</code></em></span> is the filename relative to the directory the current file is located in.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="include_js.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="snippets.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Using the JS include statement </td><td width="34%" align="center" class="navCenter"><a href="plugin_series.html">Up</a></td><td width="33%" align="right" class="navRight"> Using <snippets></td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/index.html b/doc/rkwardplugins/index.html
new file mode 100644
index 0000000..fbd781a
--- /dev/null
+++ b/doc/rkwardplugins/index.html
@@ -0,0 +1,8 @@
+<html><head><title>Introduction to Writing Plugins for RKWard</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="description" content="This is a guide to writing plugins for RKWard."><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="next" href="introduction.html" title="Chapter 1. Introduction"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Introduction to Writing Plugins for <span class="application">RKWard</span></h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="introduction.html">Next</a></td></tr></tbody></table><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="idm1"></a>Introduction to Writing Plugins for <span class="application">RKWard</span></h1></div><div><div class="authorgroup"><p class="author"><span class="firstname">Thomas</span> <span class="surname">Friedrichsmeier</span> <code class="email"><rkward-devel AT kde DOT org></code></p><p class="author"><span class="firstname">Meik</span> <span class="surname">Michalke</span> <code class="email"><rkward-devel AT kde DOT org></code></p></div></div><div>Revision <span class="releaseinfo">0.7.2 (<span class="date">2020-09-26</span>)</span></div><div><p class="copyright">Copyright © 2006-2020 Thomas Friedrichsmeier</p></div><div><div class="legalnotice"><a name="idm21"></a><p>Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License,
+Version 1.2 or any later version published by the Free Software
+Foundation; with no Invariant Sections, with no Front-Cover Texts, and
+with no Back-Cover Texts. A copy of the license is included in <a class="xref" href="license.html#gnu-fdl">the section entitled "GNU Free Documentation License"</a>.</p></div></div><div><div><div class="abstract"><p>
+This is a guide to writing plugins for <span class="application">RKWard</span>.
+</p></div></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="introduction.html">1. Introduction</a></span></dt><dt><span class="chapter"><a href="whatareplugins.html">2. Preliminaries: What are plugins in <span class="application">RKWard</span>? How do they work?</a></span></dt><dt><span class="chapter"><a href="pluginmap.html">3. Creating menu entries</a></span></dt><dd><dl><dt><span class="sect1"><a href="pluginmap.html#pluginmap_grouping">Controlling the order of menu entries</a></span></dt></dl></dd><dt><span class="chapter"><a href="mainxml.html">4. Defining the <acronym class="acronym">GUI</acronym></a></span></dt><dd><dl><dt><span class="sect1"><a href="mainxml.html#sect_defining_the_GUI">Defining a dialog</a></span></dt><dt><span class="sect1"><a href="wizard_interface.html">Adding a wizard interface</a></span></dt><dt><span class="sect1"><a href="mainxmltips.html">Some considerations on <acronym class="acronym">GUI</acronym> design</a></span></dt><dd><dl><dt><span class="sect2"><a href="mainxmltips.html#radio_vs_checkbox_vs_dropdown"><radio> vs. <checkbox> vs. <dropdown></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="jstemplate.html">5. Generating <span class="application">R</span> code from <acronym class="acronym">GUI</acronym> settings</a></span></dt><dd><dl><dt><span class="sect1"><a href="jstemplate.html#sect_generating_R_code">Using JavaScript in <span class="application">RKWard</span> plugins</a></span></dt><dd><dl><dt><span class="sect2"><a href="jstemplate.html#sect_JS_preprocess">preprocess()</a></span></dt><dt><span class="sect2"><a href="jstemplate.html#sect_JS_calculate">calculate()</a></span></dt><dt><span class="sect2"><a href="jstemplate.html#sect_JS_printout">printout()</a></span></dt></dl></dd><dt><span class="sect1"><a href="jsconventions.html">Conventions, policies, and background</a></span></dt><dd><dl><dt><span class="sect2"><a href="jsconventions.html#policylocal">Understanding the <code class="function">local()</code> environment</a></span></dt><dt><span class="sect2"><a href="jsconventions.html#policyformatting">Code formatting</a></span></dt><dt><span class="sect2"><a href="jsconventions.html#policysimplicity">Dealing with complex options</a></span></dt></dl></dd><dt><span class="sect1"><a href="jstips.html">Tips and tricks</a></span></dt></dl></dd><dt><span class="chapter"><a href="pluginhelp.html">6. Writing a help page</a></span></dt><dt><span class="chapter"><a href="logic.html">7. Logic interactions between <acronym class="acronym">GUI</acronym> elements</a></span></dt><dd><dl><dt><span class="sect1"><a href="logic.html#sect_GUI_logic"><acronym class="acronym">GUI</acronym> logic</a></span></dt><dt><span class="sect1"><a href="logic_scripted.html">Scripted <acronym class="acronym">GUI</acronym> logic</a></span></dt></dl></dd><dt><span class="chapter"><a href="embedding.html">8. Embedding Plugins into Plugins</a></span></dt><dd><dl><dt><span class="sect1"><a href="embedding.html#sect_embedding">Use cases for embedding</a></span></dt><dt><span class="sect1"><a href="embedding_dialog.html">Embedding inside a dialog</a></span></dt><dt><span class="sect1"><a href="embedding_code.html">Code generation when embedding</a></span></dt><dt><span class="sect1"><a href="embedding_wizard.html">Embedding inside a wizard</a></span></dt><dt><span class="sect1"><a href="embedding_as_button.html">Less embedded embedding: Further Options button</a></span></dt><dt><span class="sect1"><a href="embedding_incomplete.html">Embedding/defining incomplete plugins</a></span></dt></dl></dd><dt><span class="chapter"><a href="plugin_series.html">9. Dealing with many similar plugins</a></span></dt><dd><dl><dt><span class="sect1"><a href="plugin_series.html#sect_similar_plugins">Overview on different approaches</a></span></dt><dt><span class="sect1"><a href="include_js.html">Using the JS include statement</a></span></dt><dt><span class="sect1"><a href="include_xml.html">Including <code class="literal">.xml</code> files</a></span></dt><dt><span class="sect1"><a href="snippets.html">Using <snippets></a></span></dt><dt><span class="sect1"><a href="include_snippets_vs_embedding.html"><include> and <snippets> vs. <embed></a></span></dt></dl></dd><dt><span class="chapter"><a href="specialized_plugins.html">10. Concepts for use in specialized plugins</a></span></dt><dd><dl><dt><span class="sect1"><a href="specialized_plugins.html#specialized_plugins_plots">Plugins that produce a plot</a></span></dt><dd><dl><dt><span class="sect2"><a href="specialized_plugins.html#rk_graph_on">Drawing a plot to the output window</a></span></dt><dt><span class="sect2"><a href="specialized_plugins.html#preview_plots">Adding preview functionality</a></span></dt><dt><span class="sect2"><a href="specialized_plugins.html#plot_options">Generic plot options</a></span></dt><dt><span class="sect2"><a href="specialized_plugins.html#plot_plugin_example">A canonical example</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch10s02.html">Previews for data, output and other results</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch10s02.html#preview_output">Previews of (HTML) output</a></span></dt><dt><span class="sect2"><a href="ch10s02.html#preview_data">Previews of (imported) data</a></span></dt><dt><span class="sect2"><a href="ch10s02.html#preview_custom">Custom previews</a></span></dt></dl></dd><dt><span class="sect1"><a href="contextualized_plugins.html">Context-dependent plugins</a></span></dt><dd><dl><dt><span class="sect2"><a href="contextualized_plugins.html#context_x11">X11 device context</a></span></dt><dt><span class="sect2"><a href="contextualized_plugins.html#context_import">Import data context</a></span></dt></dl></dd><dt><span class="sect1"><a href="querying_r_for_info.html">Querying <span class="application">R</span> for information</a></span></dt><dt><span class="sect1"><a href="current_object.html">Referencing the current object or current file</a></span></dt><dt><span class="sect1"><a href="optionset.html">Repeating (a set of) options</a></span></dt><dd><dl><dt><span class="sect2"><a href="optionset.html#optionset_driven">"Driven" optionsets</a></span></dt><dt><span class="sect2"><a href="optionset.html#optionset_alternatives">Alternatives: When not to use optionsets</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="chapter_dependencies.html">11. Handling dependencies and compatibility issues</a></span></dt><dd><dl><dt><span class="sect1"><a href="chapter_dependencies.html#sect_dependencies_rkward_version"><span class="application">RKWard</span> version compatibility</a></span></dt><dt><span class="sect1"><a href="sect_dependencies_r_version.html"><span class="application">R</span> version compatibility</a></span></dt><dt><span class="sect1"><a href="sect_dependencies_r_packages.html">Dependencies on <span class="application">R</span> packages</a></span></dt><dt><span class="sect1"><a href="sect_dependencies_other_pluginmaps.html">Dependencies on other <span class="application">RKWard</span> <code class="literal">.pluginmap</code>s</a></span></dt><dt><span class="sect1"><a href="sect_dependencies_example.html">An example</a></span></dt></dl></dd><dt><span class="chapter"><a href="i18n.html">12. Plugin translations</a></span></dt><dd><dl><dt><span class="sect1"><a href="i18n.html#i18n_general">General considerations</a></span></dt><dt><span class="sect1"><a href="i18n_xml.html">i18n in <span class="application">RKWard</span>'s xml files</a></span></dt><dt><span class="sect1"><a href="i18n_js.html">i18n in <span class="application">RKWard</span>'s js files and sections</a></span></dt><dd><dl><dt><span class="sect2"><a href="i18n_js.html#i18n_js_quoting">i18n and quotes</a></span></dt></dl></dd><dt><span class="sect1"><a href="i18n_workflow.html">Translation maintainance</a></span></dt><dt><span class="sect1"><a href="i18n_translators.html">Writing plugin translations</a></span></dt></dl></dd><dt><span class="chapter"><a href="chapter_about_information.html">13. Author, license and version information</a></span></dt><dt><span class="chapter"><a href="external_plugins.html">14. Share your work with others</a></span></dt><dd><dl><dt><span class="sect1"><a href="external_plugins.html#sect_external_plugins">External plugins</a></span></dt><dt><span class="sect1"><a href="why_external_plugins.html">Why external plugins?</a></span></dt><dt><span class="sect1"><a href="structure_of_a_plugin_package.html">Structure of a plugin package</a></span></dt><dd><dl><dt><span class="sect2"><a href="structure_of_a_plugin_package.html#file_hierarchy">File hierarchy</a></span></dt></dl></dd><dt><span class="sect1"><a href="building_the_plugin_package.html">Building the plugin package</a></span></dt></dl></dd><dt><span class="chapter"><a href="rkwarddev.html">15. Plugin development with the <span class="application">rkwarddev</span> package</a></span></dt><dd><dl><dt><span class="sect1"><a href="rkwarddev.html#rkdev_overview">Overview</a></span></dt><dt><span class="sect1"><a href="rkdev_example.html">Practical example</a></span></dt><dd><dl><dt><span class="sect2"><a href="rkdev_example.html#rkdev_gui"><acronym class="acronym">GUI</acronym> description</a></span></dt><dt><span class="sect2"><a href="rkdev_example.html#rkdev_jscode">JavaScript code</a></span></dt><dt><span class="sect2"><a href="rkdev_example.html#rkdev_pluginmap">Plugin map</a></span></dt><dt><span class="sect2"><a href="rkdev_example.html#rkdev_rkh">Help page</a></span></dt><dt><span class="sect2"><a href="rkdev_example.html#rkdev_plugin_generator">Generate the plugin files</a></span></dt><dt><span class="sect2"><a href="rkdev_example.html#rkdev_ttest_script">The full script</a></span></dt></dl></dd><dt><span class="sect1"><a href="rkwarddev_rkh.html">Adding help pages</a></span></dt><dt><span class="sect1"><a href="rkwarddev_i18n.html">Translating plugins</a></span></dt></dl></dd><dt><span class="appendix"><a href="reference.html">A. Reference</a></span></dt><dd><dl><dt><span class="sect1"><a href="reference.html#propertytypes">Types of properties/Modifiers</a></span></dt><dt><span class="sect1"><a href="globalxmlelements.html">General purpose elements to be used in any <acronym class="acronym">XML</acronym> file (<code class="literal">.xml</code>, <code class="literal">.rkh</code>, <code class="literal">.pluginmap</code>)</a></span></dt><dt><span class="sect1"><a href="xmlelements.html">Elements to be used in the <acronym class="acronym">XML</acronym> description of the plugin</a></span></dt><dd><dl><dt><span class="sect2"><a href="xmlelements.html#generalelements">General elements</a></span></dt><dt><span class="sect2"><a href="xmlelements.html#interfaceelements">Interface definitions</a></span></dt><dt><span class="sect2"><a href="xmlelements.html#layoutelements">Layout elements</a></span></dt><dt><span class="sect2"><a href="xmlelements.html#activeelements">Active elements</a></span></dt><dt><span class="sect2"><a href="xmlelements.html#logicelements">Logic section</a></span></dt></dl></dd><dt><span class="sect1"><a href="elementproperties.html">Properties of plugin elements</a></span></dt><dt><span class="sect1"><a href="standard_embeddable_plugins.html">Embeddable plugins shipped with the official <span class="application">RKWard</span> release</a></span></dt><dt><span class="sect1"><a href="pluginmapelements.html">Elements for use in <code class="literal">.pluginmap</code> files</a></span></dt><dt><span class="sect1"><a href="helpfileelements.html">Elements for use in .rkh (help) files</a></span></dt><dt><span class="sect1"><a href="guilogic_functions.html">Functions available for <acronym class="acronym">GUI</acronym> logic scripting</a></span></dt></dl></dd><dt><span class="appendix"><a href="troubleshooting.html">B. Troubleshooting during plugin development</a></span></dt><dt><span class="appendix"><a href="license.html">C. License</a></span></dt></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>A.1. <a href="standard_embeddable_plugins.html#idm3422">Standard embeddable plugins</a></dt></dl></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"></td><td width="34%" align="center" valign="top" class="navCenter"> </td><td width="33%" align="right" valign="top" class="navRight"><a href="introduction.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft"> </td><td width="34%" align="center" class="navCenter"> </td><td width="33%" align="right" class="navRight"> Introduction</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/introduction.html b/doc/rkwardplugins/introduction.html
new file mode 100644
index 0000000..15b7a6f
--- /dev/null
+++ b/doc/rkwardplugins/introduction.html
@@ -0,0 +1,22 @@
+<html><head><title>Chapter 1. Introduction</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="next" href="whatareplugins.html" title="Chapter 2. Preliminaries: What are plugins in RKWard? How do they work?"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Introduction</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="index.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="whatareplugins.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="introduction"></a>Chapter 1. Introduction</h1></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+ Documentation as of <span class="application">RKWard</span> release 0.6.4.
+ </p></div><p>
+ This document describes how to write your own plugins. Note, that at the time of this writing, some of the concepts are not yet set in stone. Therefore, this document should be regarded as an introduction to the current approach, and as a basis for discussion. All sorts of comments are welcome.
+ The documentation has grown quite large over time. Do not let that scare you. We recommend reading through the four basic steps (as
+ outlined, below), to get a basic idea of how things work. After that you may want to skim the table of contents to see which advanced
+ topics could be of relevance to you.
+ </p><p>
+ For questions and comments, please write to the <span class="application">RKWard</span> development mailing list.
+ </p><p>
+ <span class="emphasis"><em>You do not need to read this in order to use <span class="application">RKWard</span>.</em></span> This document is about extending <span class="application">RKWard</span>. It is targeted at advanced users, or people willing to help improve <span class="application">RKWard</span>.
+ </p><p>
+ Writing a standard plugin is basically a four-step process:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="link" href="pluginmap.html" title="Chapter 3. Creating menu entries">Placing a new Action in the menu hierarchy</a></p></li><li class="listitem"><p><a class="link" href="mainxml.html" title="Chapter 4. Defining the GUI">Describing the looks and behavior of the plugin <acronym class="acronym">GUI</acronym></a></p></li><li class="listitem"><p><a class="link" href="jstemplate.html" title="Chapter 5. Generating R code from GUI settings">Defining, how R-code is to be generated from the settings, the user makes in the <acronym class="acronym">GUI</acronym></a></p></li><li class="listitem"><p><a class="link" href="pluginhelp.html" title="Chapter 6. Writing a help page">Adding a help page to your plugin</a></p></li></ul></div><p>
+ Those will be dealt with in turn.
+ </p><p>
+ Some advanced concepts may be used in those four steps, but are dealt with in separate chapters, to keep things simple:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="link" href="logic.html" title="Chapter 7. Logic interactions between GUI elements"><acronym class="acronym">GUI</acronym> logic</a></p></li><li class="listitem"><p><a class="link" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins">Embedding Plugins into Plugins</a></p></li><li class="listitem"><p><a class="link" href="plugin_series.html" title="Chapter 9. Dealing with many similar plugins">Useful concepts for creating many series of similar plugins</a></p></li></ul></div><p>
+ </p><p>
+ Also, none of the chapters shows all options, but rather only the basic concepts. A complete <a class="link" href="reference.html" title="Appendix A. Reference">reference</a> of options is provided separately.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="index.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="whatareplugins.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Introduction to Writing Plugins for <span class="application">RKWard</span> </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Preliminaries: What are plugins in <span class="application">RKWard</span>? How do they work?</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/jsconventions.html b/doc/rkwardplugins/jsconventions.html
new file mode 100644
index 0000000..18bfdf9
--- /dev/null
+++ b/doc/rkwardplugins/jsconventions.html
@@ -0,0 +1,46 @@
+<html><head><title>Conventions, policies, and background</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="jstemplate.html" title="Chapter 5. Generating R code from GUI settings"><link rel="prev" href="jstemplate.html" title="Chapter 5. Generating R code from GUI settings"><link rel="next" href="jstips.html" title="Tips and tricks"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Conventions, policies, and background</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="jstemplate.html">Prev</a></td><td align="center" class="navCenter" width="34%">Generating <span class="application">R</span> code from <acronym class="acronym">GUI</acronym> settings</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="jstips.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jsconventions"></a>Conventions, policies, and background</h2></div></div></div><p>
+ There are many ways to write <span class="application">R</span> code for a certain task, and there are even more ways to generate this <span class="application">R</span> 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.
+ </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="policylocal"></a>Understanding the <code class="function">local()</code> environment</h3></div></div></div><p>
+ More often than not you will have to create one or more temporary <span class="application">R</span> 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 <code class="function">local()</code> environment (see <span class="application">R</span> help page on function <code class="function">local()</code>). This means, all variables you create are temporary and will not be saved permanently.
+ </p><p>
+ If the user explicitly asks for a variable to be saved, you will need to assign to that object using <code class="function">.GlobalEnv$objectname <- value</code>. In general, do not use the <code class="function"><<-</code> operator. It will not necessarily assign in .GlobalEnv.
+ </p><p>
+ One important pitfall is using <code class="function">eval()</code>. Here, you need to note that eval will by default use the current environment for evaluation, <abbr class="abbrev">i.e.</abbr> the local one. This will work well most of the times, but not always. Thus, if you need to use <code class="function">eval()</code>, you will probably want to specify the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>envir</code></em></span> parameter: <code class="function">eval(..., envir=globalenv()</code>).
+ </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="policyformatting"></a>Code formatting</h3></div></div></div><p>
+ The most important thing is for your generated <span class="application">R</span> code to work, but it should be also easy to read. Therefore, please also keep an eye on formatting. Some considerations:
+ </p><p>
+ Normal top-level <span class="application">R</span> statements should be left aligned.
+ </p><p>
+ Statements in a lower block should be indented with one tab (see example below).
+ </p><p>
+ If you do very complex calculations, add a comment here and there, esp. to mark up logical sections. Note that there is a dedicated function <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>comment()</strong></span></span> for inserting
+ translatable comments in the generated code.
+ </p><p>
+ For example, generated code might look like this. The same code without indentation or comments would be pretty hard to read, despite its modest complexity:
+ </p><pre class="programlisting">
+# first determine the wobble and rotation
+my.wobble <- wobble (x, y)
+my.rotation <- wobble.rotation (my.wobble, z)
+
+# boggling method needs to be chosen according to rotation
+if (my.rotation > wobble.rotation.limit (x)) {
+ method <- "foo"
+ result <- boggle.foo (my.wobble, my.rotation)
+} else {
+ method <- "bar"
+ result <- boggle.bar (my.wobble, my.rotation)
+}
+ </pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="policysimplicity"></a>Dealing with complex options</h3></div></div></div><p>
+ Many plugins can do more than one thing. For instance, the <span class="quote">“<span class="quote">Descriptive Statistics</span>”</span> plugin can compute mean, range, sum, product, median, length, <abbr class="abbrev">etc.</abbr> However, typically the user will only choose to have some of those calculations performed. In this case, please try to keep the generated code as simple as possible. It should only contain portions relevant to the options that are actually selected. To achieve this, here is an example of a common design patterns as you would use it (in JS; here, "domean", "domedian", and "dosd" would be <checkbox> elements):
+ </p><pre class="programlisting">
+function calculate () {
+ echo ('x <- <' + getString ("x") + ')\n');
+ echo ('results <- list ()\n');
+
+ if (getBoolean ("domean.state")) echo ("results$" + i18n ("Mean value") + " <- mean (x)\n");
+ if (getBoolean ("domedian.state")) echo ("results$" + i18n ("Median") + " <- median (x)\n");
+ if (getBoolean ("dosd.state")) echo ("results$" + i18n ("Standard deviation") + " <- sd (x)\n");
+ //...
+}
+ </pre></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="jstemplate.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="jstips.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Generating <span class="application">R</span> code from <acronym class="acronym">GUI</acronym> settings </td><td width="34%" align="center" class="navCenter"><a href="jstemplate.html">Up</a></td><td width="33%" align="right" class="navRight"> Tips and tricks</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/jstemplate.html b/doc/rkwardplugins/jstemplate.html
new file mode 100644
index 0000000..d57a925
--- /dev/null
+++ b/doc/rkwardplugins/jstemplate.html
@@ -0,0 +1,57 @@
+<html><head><title>Chapter 5. Generating R code from GUI settings</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="mainxmltips.html" title="Some considerations on GUI design"><link rel="next" href="jsconventions.html" title="Conventions, policies, and background"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Generating <span class="application">R</span> code from <acronym class="acronym">GUI</acronym> settings</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="mainxmltips.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="jsconventions.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="jstemplate"></a>Chapter 5. Generating <span class="application">R</span> code from <acronym class="acronym">GUI</acronym> settings</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="jstemplate.html#sect_generating_R_code">Using JavaScript in <span class="application">RKWard</span> plugins</a></span></dt><dd><dl><dt><span class="sect2"><a href="jstemplate.html#sect_JS_preprocess">preprocess()</a></span></dt><dt><span class="sect2"><a href="jstemplate.html#sect_JS_calculate">calculate()</a></span></dt><dt><span class="sect2"><a href="jstemplate.html#sect_JS_printout">printout()</a></span></dt></dl></dd><dt><span class="sect1"><a href="jsconventions.html">Conventions, policies, and background</a></span></dt><dd><dl><dt><span class="sect2"><a href="jsconventions.html#policylocal">Understanding the <code class="function">local()</code> environment</a></span></dt><dt><span class="sect2"><a href="jsconventions.html#policyformatting">Code formatting</a></span></dt><dt><span class="sect2"><a href="jsconventions.html#policysimplicity">Dealing with complex options</a></span></dt></dl></dd><dt><span class="sect1"><a href="jstips.html">Tips and tricks</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_generating_R_code"></a>Using JavaScript in <span class="application">RKWard</span> plugins</h2></div></div></div><p>
+ Now we have a <acronym class="acronym">GUI</acronym> defined, but we still need to generate some <span class="application">R</span> code from that. For that, we need another text file, <code class="filename">code.js</code>, located in the same directory as the <a class="link" href="mainxml.html" title="Chapter 4. Defining the GUI"><code class="filename">description.xml</code></a>. 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 (<abbr class="abbrev">e.g.</abbr>: <a class="ulink" href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide" target="_top">https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide</a>). But for most purposes you will not need to know much about JS at all, as we will only use some very basic features.
+ </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+ After reading this chapter, have a look at the <a class="link" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><span class="application">rkwarddev</span> package</a> as well. It provides some <span class="application">R</span> functions to create JavaScript code commonly used in <span class="application">RKWard</span>. It can also autodetect variables used in a plugin <acronym class="acronym">XML</acronym> file and create basic JavaScript code from that for you to start with.
+ </p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+ Plugin <code class="literal">.js</code> files are assumed to be UTF-8 encoded. Be sure to check you editor's encoding, if using any non-ascii characters.
+ </p></div><p>
+ For the two variable t-test, the <code class="filename">code.js</code> file looks as follows (with comments in between):
+ </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="sect_JS_preprocess"></a>preprocess()</h3></div></div></div><pre class="programlisting">
+function preprocess () {
+}
+ </pre><p>
+ The JS file is organized into three separate functions: <code class="function">preprocess()</code>, <code class="function">calculate()</code>, and <code class="function">printout()</code>. 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).
+ </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="sect_JS_calculate"></a>calculate()</h3></div></div></div><pre class="programlisting">
+function calculate () {
+ echo ('res <- t.test (x=' + getString ("x") + ', y=' + getString ("y") + ', hypothesis="' + getString ("hypothesis") + '"' + getString ("varequal"));
+ var conflevel = getString ("conflevel");
+ if (conflevel != "0.95") echo (', conf.level=' + conflevel);
+ echo (')\n');
+}
+ </pre><p>
+ This function generates the actual <span class="application">R</span> syntax to be run from the <acronym class="acronym">GUI</acronym> settings. Let's look at this in detail: The code to be used is generated using <code class="function">echo()</code> statement. Looking at the <code class="function">echo()</code> statement step by step, the first part of it is
+ </p><pre class="screen">
+res <- t.test (
+ </pre><p>
+ as plain text. Next we need to fill in the value, the user selected as the first variable. We fetch this using <code class="function">getString ("x")</code>, and append it to the string to be <span class="quote">“<span class="quote">echoed</span>”</span>. This prints out the value of the <acronym class="acronym">GUI</acronym>-element with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"x"</code></em></span>: our first <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><checkbox></strong></span></span>. Next, we append a ', ', and do the same to fetch the value of the element <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"y"</code></em></span> - the second <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><checkbox></strong></span></span>. For the hypothesis (the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span> group), and the equal variances <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><checkbox></strong></span></span>, the procedure is very similar.
+ </p><p>
+ Note that instead of concatenating the output snippets with <span class="quote">“<span class="quote">+</span>”</span>, you can also use several <code class="function">echo()</code> statements. Everything is printed on a single line. To produce a line break in the generated code, insert a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"\n"</code></em></span> in the echoed string. In theory, you can even produce many lines with a single echo-statement, but please keep it to one line (or less) of generated code per <code class="function">echo()</code>.
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Besides <code class="function">getString()</code>, there are also functions <code class="function">getBoolean()</code>, which will try to return the value as a logical (suitable for using in an <code class="function">if()</code>-statement), and <code class="function">getList()</code>, which will try to return list-like data in a JS <code class="function">Array()</code>. We will show examples of those, later.</p><p>When looking at existing plugins, you will also find plenty of plugins using <code class="function">getValue()</code>, instead of <code class="function">getString()</code>, and in fact the two are <span class="emphasis"><em>almost</em></span> identical. However using <code class="function">getString()</code>, <code class="function">getBoolean()</code> and <code class="function">getList()</code> is the recommended practice since version 0.6.1.
+ </p></div><p>
+ It gets a little more tricky for the confidence level. For reasons of aesthetics, we do not want to explicitly specify the confidence level to use, if it corresponds to the default value. Hence, instead of printing the value unconditionally, we first fetch into a variable. Then we check, whether that variable differs from <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"0.95"</code></em></span> and if so print out an additional argument. Finally, we echo a closing bracket and a line break: <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>")\n"</code></em></span>. That is all for the calculate function.
+ </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="sect_JS_printout"></a>printout()</h3></div></div></div><pre class="programlisting">
+function printout () {
+ echo ('rk.header (' + i18n ("Two Variable t-Test") + ')\n');
+ echo ('rk.print (res)\n');
+}
+ </pre><p>
+ And this was all there is to the printout function in most cases. <code class="function">rk.header()</code> prints a standard headline for the results. Note that in the <code class="literal">.js</code> files, you have to
+ mark up all translatable strings by hand, using <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>i18n()</strong></span></span>, or some alternative commands. More on this in the <a class="link" href="i18n_js.html" title="i18n in RKWard's js files and sections">chapter on internationalization</a>.
+ You can also add some more information to this, if you like, <abbr class="abbrev">e.g.</abbr>:
+ </p><pre class="programlisting">
+function printout () {
+ new Header (i18n ("Two Variable t-Test"))
+ .addFromUI ("varequal")
+ .add (i18n ("Confidence level"), getString ("conflevel")) // Note: written like this for illustration purposes. More automatic:
+ // .addFromUI ("conflevel")
+ .print ();
+echo ('rk.print (res)\n');
+}
+ </pre><p>
+ <code class="function">rk.print()</code> utilizes the R2HTML package to provide <acronym class="acronym">HTML</acronym> formatted output. Another helpful function is <code class="function">rk.results()</code>, which can also output different kinds of result tables. If in doubt, however, just use <code class="function">rk.print()</code>, and be done with. The JS class <code class="function">Header</code> is a JS level helper to generate a call to <code class="function">rk.header()</code> (just take a look at the generated <span class="application">R</span> code). In some cases you may want to call <code class="function">echo ('rk.header (...)')</code> directly to print a header for your output.
+ </p><p>
+ Note that internally, the output is just a plain <acronym class="acronym">HTML</acronym> document at this point of time. Therefore you might be tempted to add custom <acronym class="acronym">HTML</acronym> using <code class="function">rk.cat.output()</code>. While this will work, please do not do this. The output format may change (<abbr class="abbrev">e.g.</abbr> to ODF) in the future, so it is best not to introduce <acronym class="acronym">HTML</acronym> specific code. Rather keep things simple with <code class="function">rk.header()</code>, <code class="function">rk.print()</code>, <code class="function">rk.results()</code>, and -- if needed -- <code class="function">rk.print.literal()</code>. If those do not seem to satisfy your formatting needs, contact us on the mailing list for help.
+ </p><p>
+ Congratulations! You created your first plugin. Read on in the next chapters for more advanced concepts.
+ </p></div></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="mainxmltips.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="jsconventions.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Some considerations on <acronym class="acronym">GUI</acronym> design </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Conventions, policies, and background</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/jstips.html b/doc/rkwardplugins/jstips.html
new file mode 100644
index 0000000..8268de5
--- /dev/null
+++ b/doc/rkwardplugins/jstips.html
@@ -0,0 +1,28 @@
+<html><head><title>Tips and tricks</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="jstemplate.html" title="Chapter 5. Generating R code from GUI settings"><link rel="prev" href="jsconventions.html" title="Conventions, policies, and background"><link rel="next" href="pluginhelp.html" title="Chapter 6. Writing a help page"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Tips and tricks</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="jsconventions.html">Prev</a></td><td align="center" class="navCenter" width="34%">Generating <span class="application">R</span> code from <acronym class="acronym">GUI</acronym> settings</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="pluginhelp.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jstips"></a>Tips and tricks</h2></div></div></div><p>
+ Here are a few assorted tricks which may make writing plugins less tedious:
+ </p><p>
+ If you need the value of a <acronym class="acronym">GUI</acronym> setting at several places in you plugin's code, consider assigning it to a variable in JS, and using that instead of fetching it again and again with <code class="function">getString()/getBoolean()/getList()</code>. This is faster, more readable, and less typing all at the same time:
+ </p><pre class="programlisting">
+function calculate () {
+ var narm = ""; // na.rm=FALSE is the default in all functions below
+ if (getBoolean ("remove_nas")) {
+ $narm = ", na.rm=TRUE";
+ }
+ // ...
+ echo ("results$foo <- foo (x" + narm + ")\n");
+ echo ("results$bar <- bar (x" + narm + ")\n");
+ echo ("results$foobar <- foobar (x" + narm "\n");
+ // ...
+}
+ </pre><p>
+ The simple helper function <code class="function">makeOption()</code> can make it easier to omit parameters that are at their default value, in many cases:
+ </p><pre class="programlisting">
+function calculate () {
+ var options
+ //...
+ // This will do nothing, if VALUE is 0.95 (the default). Otherwise it will append ', conf.int=VALUE' to options.
+ options += makeOption ("conf.int", getString ("confint"), "0.95");
+ //...
+}
+ </pre></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="jsconventions.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="pluginhelp.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Conventions, policies, and background </td><td width="34%" align="center" class="navCenter"><a href="jstemplate.html">Up</a></td><td width="33%" align="right" class="navRight"> Writing a help page</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/license.html b/doc/rkwardplugins/license.html
new file mode 100644
index 0000000..eec3c93
--- /dev/null
+++ b/doc/rkwardplugins/license.html
@@ -0,0 +1,3 @@
+<html><head><title>Appendix C. License</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="troubleshooting.html" title="Appendix B. Troubleshooting during plugin development"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>License</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="troubleshooting.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ </td></tr></tbody></table><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a name="license"></a>Appendix C. License</h1></div></div></div><p><a name="gnu-fdl"></a>This documentation is licensed under the terms of the <a class="ulink" href="fdl-license.html" target="_top">GNU Free Documentation
+License</a>.</p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="troubleshooting.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"></td></tr><tr><td width="33%" align="left" class="navLeft">Troubleshooting during plugin development </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> </td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/logic.html b/doc/rkwardplugins/logic.html
new file mode 100644
index 0000000..caadccc
--- /dev/null
+++ b/doc/rkwardplugins/logic.html
@@ -0,0 +1,55 @@
+<html><head><title>Chapter 7. Logic interactions between GUI elements</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="pluginhelp.html" title="Chapter 6. Writing a help page"><link rel="next" href="logic_scripted.html" title="Scripted GUI logic"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Logic interactions between <acronym class="acronym">GUI</acronym> elements</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="pluginhelp.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="logic_scripted.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="logic"></a>Chapter 7. Logic interactions between <acronym class="acronym">GUI</acronym> elements</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="logic.html#sect_GUI_logic"><acronym class="acronym">GUI</acronym> logic</a></span></dt><dt><span class="sect1"><a href="logic_scripted.html">Scripted <acronym class="acronym">GUI</acronym> logic</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_GUI_logic"></a><acronym class="acronym">GUI</acronym> logic</h2></div></div></div><p>
+ All the basic concepts of creating a plugin for <span class="application">RKWard</span> 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 <acronym class="acronym">GUI</acronym> behaves.
+ </p><p>
+ 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:
+ </p><pre class="programlisting">
+<!DOCTYPE rkplugin>
+<document>
+ <code file="code.js"/>
+
+ <dialog label="T-Test">
+ <row>
+ <varselector id="vars"/>
+ <column>
+ <varslot id="x" types="number" source="vars" required="true" label="compare"/>
+ <radio id="mode" label="Compare against">
+ <option value="variable" checked="true" label="another variable (select below)"/>
+ <option value="constant" label="a constant value (set below)"/>
+ </radio>
+ <varslot id="y" types="number" source="vars" required="true" label="variable" i18n_context="Noun; a variable"/>
+ <spinbox id="constant" initial="0" label="constant" i18n_context="Noun; a constant"/>
+ </column>
+ </row>
+ </dialog>
+</document>
+ </pre><p>
+ So far so good, but there are a number of problems with this <acronym class="acronym">GUI</acronym>. First, both the varslot and the spinbox are always shown, whereas only one of the two is really used. Worse, the varslot always requires a valid selection, even if you compare against a constant. Obviously, if we create a multi-purpose <acronym class="acronym">GUI</acronym> like this, we want more flexibility. Enter: the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><logic></strong></span></span> section (inserted at the same level as <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><code></strong></span></span>, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dialog></strong></span></span>, or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><wizard></strong></span></span>).
+ </p><pre class="programlisting">
+ [...]
+ <code file="code.js"/>
+
+ <logic>
+ <convert id="varmode" mode="equals" sources="mode.string" standard="variable" />
+
+ <connect client="y.visible" governor="varmode" />
+ <connect client="constant.visible" governor="varmode.not" />
+ </logic>
+
+ <dialog label="T-Test">
+ [...]
+ </pre><p>
+ The first line inside the logic section is a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><convert></strong></span></span> tag. Basically, this provides a new boolean (on or off, true or false) property, which can be used later on. This property (<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"varmode"</code></em></span>) is true, whenever the upper radio button is selected and false whenever the lower radio button is selected. How is this done?
+ </p><p>
+ First, under <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>sources</code></em></span>, the source properties to work on are listed (in this case only one each; you could list several as <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>sources=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"mode.string;somethingelse"</code></em></span>, then <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"varmode"</code></em></span> would only be true, if both <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"mode.string"</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"somethingelse"</code></em></span> are equal to the string <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"variable"</code></em></span>). Note that in this case we do not just write <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"mode"</code></em></span> (as we would in <code class="function">getString("mode")</code>), but <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"mode.string"</code></em></span>. This is actually the internal way a radio control works: It has a property <span class="quote">“<span class="quote">string</span>”</span>, which holds its string value. <code class="function">getString("mode")</code> is just a shorthand, and equivalent to <code class="function">getString("mode.string")</code>. See the reference for all properties of the different <acronym class="acronym">GUI</acronym> elements.
+ </p><p>
+ Second, we set the mode of conversion to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>mode=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"equals"</code></em></span>. This means, we want to check, whether the source(s) is (are) equal to a certain value. Finally standard is the value to compare against, so with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>standard=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"variable"</code></em></span>, we check whether the property <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"mode.string"</code></em></span> is equal to the string <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"variable"</code></em></span> (the value of the upper radio option). If it is equal, then the property varmode is true, else it is false.
+ </p><p>
+ Now to the real stuff: We <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><connect></strong></span></span> the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"varmode"</code></em></span> property to y.visible, which controls whether the varslot <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"y"</code></em></span> is shown or not. Note that any element which is made invisible is implicitly non-required. Thus, if the upper radio-option is selected, the varslot <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"y"</code></em></span> is required, and visible. Else it is not required and hidden.
+ </p><p>
+ For the spinbox, we want the exact reverse. Fortunately, we do not need another <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><convert></strong></span></span> for this: Boolean
+ properties can be negated very easily by appending the modifier <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"not"</code></em></span>, so we <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><connect></strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"varmode.not"</code></em></span> to the spinbox's visibility property. In effect, either
+ the varslot is shown and required, <span class="emphasis"><em>or</em></span> the spinbox is shown and required - depending on which option is selected in the radio control. The <acronym class="acronym">GUI</acronym> is changing itself according to the radio option. Try the example, if you like.
+ </p><p>
+ For a complete list of properties, refer to the <a class="link" href="reference.html" title="Appendix A. Reference">reference</a>. One more property, however, is special in that all <acronym class="acronym">GUI</acronym> elements have it: <span class="quote">“<span class="quote">enabled</span>”</span>. This is slightly less drastic than <span class="quote">“<span class="quote">visible</span>”</span>. It does not show/hide the <acronym class="acronym">GUI</acronym> element, but only enables/disables it. Disabled elements are typically shown grayed out, and do not react to user input.
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Besides <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><convert></strong></span></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><connect></strong></span></span>, there are several further elements for use in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><logic></strong></span></span> section. E.g. conditional constructs can also be implemented using the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><switch></strong></span></span>-element. Refer to the <a class="link" href="xmlelements.html#logicelements" title="Logic section">reference on logic elements</a> for details.</p></div></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="pluginhelp.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="logic_scripted.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Writing a help page </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Scripted <acronym class="acronym">GUI</acronym> logic</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/logic_scripted.html b/doc/rkwardplugins/logic_scripted.html
new file mode 100644
index 0000000..ebde45e
--- /dev/null
+++ b/doc/rkwardplugins/logic_scripted.html
@@ -0,0 +1,31 @@
+<html><head><title>Scripted GUI logic</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="logic.html" title="Chapter 7. Logic interactions between GUI elements"><link rel="prev" href="logic.html" title="Chapter 7. Logic interactions between GUI elements"><link rel="next" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Scripted <acronym class="acronym">GUI</acronym> logic</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="logic.html">Prev</a></td><td align="center" class="navCenter" width="34%">Logic interactions between <acronym class="acronym">GUI</acronym> elements</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="embedding.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="logic_scripted"></a>Scripted <acronym class="acronym">GUI</acronym> logic</h2></div></div></div><p>
+ While connecting properties as described above is often enough, sometimes it is more flexible or more convenient to use JS to script the <acronym class="acronym">GUI</acronym> logic. In this way, the above example could be re-written as:
+ </p><pre class="programlisting">
+ [...]
+ <code file="code.js"/>
+'
+ <logic>
+ <script><![CDATA[
+ // ECMAScript code in this block
+ // the top-level statement is only called once
+ gui.addChangeCommand ("mode.string", "modeChanged ()");
+
+ // this function is called whenever the "mode" was changed
+ modeChanged = function () {
+ var varmode = (gui.getString ("mode.string") == "variable");
+ gui.setValue ("y.enabled", varmode);
+ gui.setValue ("constant.enabled", !varmode);
+ }
+ ]]></script>
+ </logic>
+
+ <dialog label="T-Test">
+ [...]
+ </pre><p>
+ The first line of code tells <span class="application">RKWard</span> to call the function <code class="function">modeChanged()</code> whenever the value of the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"mode"</code></em></span> radio box changes. Inside this function, we define a helper-variable <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"varmode"</code></em></span> which is true when the mode is <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"variable"</code></em></span>, false as it is <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"constant"</code></em></span>. Then we use <code class="function">gui.setValue()</code> to set the <span class="quote">“<span class="quote">enabled</span>”</span> properties of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"y"</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"constant"</code></em></span>, in just the same way as we did using <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><connect></strong></span></span> statements, before.
+ </p><p>
+ The scripted approach to <acronym class="acronym">GUI</acronym> logic becomes particularly useful when you want to change the available option according to the type of object that the user has selected. See <a class="link" href="guilogic_functions.html" title="Functions available for GUI logic scripting">the reference</a> for available functions.
+ </p><p>
+ Note that the scripted approach to <acronym class="acronym">GUI</acronym> logic can be mixed with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><connect></strong></span></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><convert></strong></span></span>-statements if you like. Also note that the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><script></strong></span></span> tag allows to specify a script file name in addition to or as an alternative to inlining the script code. Typically, inlining the script code as shown above is most convenient, however.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="logic.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="embedding.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Logic interactions between <acronym class="acronym">GUI</acronym> elements </td><td width="34%" align="center" class="navCenter"><a href="logic.html">Up</a></td><td width="33%" align="right" class="navRight"> Embedding Plugins into Plugins</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/mainxml.html b/doc/rkwardplugins/mainxml.html
new file mode 100644
index 0000000..1b73634
--- /dev/null
+++ b/doc/rkwardplugins/mainxml.html
@@ -0,0 +1,95 @@
+<html><head><title>Chapter 4. Defining the GUI</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="pluginmap.html" title="Chapter 3. Creating menu entries"><link rel="next" href="wizard_interface.html" title="Adding a wizard interface"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Defining the <acronym class="acronym">GUI</acronym></h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="pluginmap.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="wizard_interface.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="mainxml"></a>Chapter 4. Defining the <acronym class="acronym">GUI</acronym></h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="mainxml.html#sect_defining_the_GUI">Defining a dialog</a></span></dt><dt><span class="sect1"><a href="wizard_interface.html">Adding a wizard interface</a></span></dt><dt><span class="sect1"><a href="mainxmltips.html">Some considerations on <acronym class="acronym">GUI</acronym> design</a></span></dt><dd><dl><dt><span class="sect2"><a href="mainxmltips.html#radio_vs_checkbox_vs_dropdown"><radio> vs. <checkbox> vs. <dropdown></a></span></dt></dl></dd></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_defining_the_GUI"></a>Defining a dialog</h2></div></div></div><p>
+ In the <a class="link" href="pluginmap.html" title="Chapter 3. Creating menu entries">previous chapter</a> you have seen how to register a plugin with <span class="application">RKWard</span>. The most important ingredient was specifying the path to an <acronym class="acronym">XML</acronym> file with a description of what the plugin actually looks like. In this chapter you will learn how to create this <acronym class="acronym">XML</acronym> file.
+ </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+ After reading this chapter, have a look at the <a class="link" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><span class="application">rkwarddev</span> package</a> as well. It provides some <span class="application">R</span> functions to create most of <span class="application">RKWard</span>'s <acronym class="acronym">XML</acronym> tags for you.
+ </p></div><p>
+ Once again we will walk you through an example. The example is a (slightly simplified) version of the two variable t-Test.
+ </p><pre class="programlisting">
+<!DOCTYPE rkplugin>
+ </pre><p>
+ The doctype is not really interpreted, yet. Set it to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>rkplugin</code></em></span>, anyway.
+ </p><pre class="programlisting">
+<document>
+ <code file="t_test_two_vars.js"/>
+ </pre><p>
+ All plugins generate some code. Currently the only way to do so is using JS, as detailed in <a class="link" href="jstemplate.html" title="Chapter 5. Generating R code from GUI settings">the next chapter</a>. This defines, where to look for the JS code. The filename is relative to the directory the plugin <acronym class="acronym">XML</acronym> is in.
+ </p><pre class="programlisting">
+ <help file="t_test_two_vars.rkh"/>
+ </pre><p>
+ It is usually a good idea to also provide a help page for your plugin. The filename of that help page is given, here, relative to the directory, the plugin <acronym class="acronym">XML</acronym> is in. Writing help pages is documented <a class="link" href="pluginhelp.html" title="Chapter 6. Writing a help page">here</a>. If you do not provide a help file, omit this line.
+ </p><pre class="programlisting">
+ <dialog label="Two Variable t-Test">
+ </pre><p>
+ As you know, plugins may have either a dialog or a wizard interface or both. Here we start defining a dialog interface. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span> attribute specifies the caption of the dialog.
+ </p><pre class="programlisting">
+ <tabbook>
+ <tab label="Basic settings">
+ </pre><p>
+ <acronym class="acronym">GUI</acronym> elements can be organized using a tabbook. Here we define a tabbook as the first element in the dialog. Use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><tabbook></strong></span></span>[...]<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong></tabbook></strong></span></span> to define the tabbook and then for each page in the tabbook use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><tab></strong></span></span>[...]<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong></tab></strong></span></span>. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span> attribute in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><tab></strong></span></span> element allows you to specify a caption for that page of the tabbook.
+ </p><pre class="programlisting">
+ <row id="main_settings_row">
+ </pre><p>
+ The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><row></strong></span></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><column></strong></span></span> tags specify the layout of the <acronym class="acronym">GUI</acronym> elements. Here you say, that you would like to place some elements side-by-side (left to right). The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> attribute is not strictly necessary, but we will use it later on, when adding a wizard interface to our plugin. The first element to place in the row, is:
+ </p><pre class="programlisting">
+ <varselector id="vars"/>
+ </pre><p>
+ Using this simple tag you create a list from which the user can select variables. You have to specify an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> for this element, so <span class="application">RKWard</span> knows how to find it.
+ </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
+ You may NOT use a dot (.) in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> string.
+ </p></div><pre class="programlisting">
+ <column>
+ </pre><p>
+ Next, we nest a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><column></strong></span></span> inside the row. That is the following elements will be placed above each other (top-to-bottom), and all will be to the right of the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varselector></strong></span></span>.
+ </p><pre class="programlisting">
+ <varslot types="number" id="x" source="vars" required="true" label="compare"/>
+ <varslot types="number" id="y" source="vars" required="true" label="against" i18n_context="compare against"/>
+ </pre><p>
+ These elements are the counterpart to the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varselector></strong></span></span>. They represent <span class="quote">“<span class="quote">slots</span>”</span> into which the user can put variables. You will note that the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>source</code></em></span> is set to the same value as the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> of the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varselector></strong></span></span>. This means, the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span>s will each take their variables from the varselector. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span>s also have to be given an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span>. They may have a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span>, and they may be set to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>required</code></em></span>. This means that the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guibutton">Submit</span></span> button will not be enabled until the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span> holds a valid value. Finally the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>type</code></em></span> 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 <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span>.
+ </p><p>
+ In case you are wondering about the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>i18n_context</code></em></span>-attribute: This is to provide context to help the correct translation of the word "against", used as the
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span>'s label, but does not affect the functionality of the plugin, directly. More on this in <a class="link" href="i18n.html#i18n_general" title="General considerations">a separate chapter</a>.
+ </p><pre class="programlisting">
+ <radio id="hypothesis" label="using test hypothesis">
+ <option value="two.sided" label="Two-sided"/>
+ <option value="greater" label="First is greater"/>
+ <option value="less" label="Second is greater"/>
+ </radio>
+ </pre><p>
+ Here, you define a group of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span> exclusive buttons. The group has a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span> and an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span>. Each <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><option></strong></span></span> (button) has a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span> and is assigned a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>value</code></em></span>. This is the value the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span> element will return when the option is selected.
+ </p><pre class="programlisting">
+ </column>
+ </row>
+ </tab>
+ </pre><p>
+ Each tag has to be closed. We have put all the elements we wanted (the two <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslots></strong></span></span> and the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span>) in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><column></strong></span></span>. We put all elements we wanted (the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varselector></strong></span></span> and the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><column></strong></span></span> with those elements) in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><row></strong></span></span>. And we have put all the elements we wanted into the first page in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><tabbook></strong></span></span>. We are not yet done defining the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><tabbook></strong></span></span> (more pages to come), and of course there is more to come in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dialog></strong></span></span>, too. But this screenshot is basically what we have done so far:
+ </p><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><img src="t_test_plugin_example.png" alt="t-Test plugin"></div></div><p>
+ Note that we have not specified the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guibutton">Submit</span></span>, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guibutton">Close</span></span>, <abbr class="abbrev">etc.</abbr> buttons or the code view. Those elements get generated automatically. But of course we still have to define the second page of the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><tabbook></strong></span></span>:
+ </p><pre class="programlisting">
+ <tab label="Options">
+ <checkbox id="varequal" label="assume equal variances" value=", var.equal=TRUE"/>
+ </pre><p>
+ By default elements will be placed top-to-bottom like in a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><column></strong></span></span>. Since that is what we want here, we do not have to explicitly state a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><row></strong></span></span> or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><column></strong></span></span> layout. The first element we define is a checkbox. Just like the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><option></strong></span></span>s, the checkbox has a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span> and a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>value</code></em></span>. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>value</code></em></span> is what gets returned, if the check box is checked. Of course the checkbox also needs an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span>.
+ </p><pre class="programlisting">
+ <frame label="Confidence Interval" id="frame_conf_int">
+ </pre><p>
+ Here is yet another layout element: In order to signal that the two elements below belong together, we draw a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><frame></strong></span></span> (box). That frame may have a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span> (caption). Since the frame is just a passive layout element, it does not need an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span>, we still define one here, as we will refer to it later, when defining an additional wizard interface.
+ </p><pre class="programlisting">
+ <checkbox id="confint" label="print confidence interval" value="1" checked="true"/>
+ <spinbox type="real" id="conflevel" label="confidence level" min="0" max="1" initial="0.95"/>
+ </frame>
+ </pre><p>
+ Inside the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><frame></strong></span></span> we place another <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><checkbox></strong></span></span> (using <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>checked=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"true"</code></em></span>, we signal that check box should be checked by default), and a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><spinbox></strong></span></span>. The spinbox allows the user to select a value between <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"min"</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"max"</code></em></span> with the default/initial value <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"0.95"</code></em></span>. Setting the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>type</code></em></span> to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"real"</code></em></span> signals that real numbers are accepted as opposed to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>type=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"integer"</code></em></span> which would accept integers only.
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+ It is also possible, and often preferable, to make the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><frame></strong></span></span> itself checkable, instead of adding a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><checkbox></strong></span></span> inside. See the reference for details. This is not done here, for illustrational purposes.
+ </p></div><pre class="programlisting">
+ </tab>
+ </tabbook>
+ </dialog>
+ </pre><p>
+ That is all for the second page of the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><tabbook></strong></span></span>, all pages in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><tabbook></strong></span></span> and all elements in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dialog></strong></span></span>. We are finished defining what the dialog looks like.
+ </p><pre class="programlisting">
+</document>
+ </pre><p>
+ Finally we close the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><document></strong></span></span> tag, and that is it. The <acronym class="acronym">GUI</acronym> is defined. You can save the file now. But how does <span class="application">R</span> syntax get generated from the <acronym class="acronym">GUI</acronym> settings? We will deal with that in the <a class="link" href="jstemplate.html" title="Chapter 5. Generating R code from GUI settings">next chapter</a>. First, however, we will look into adding a wizard interface, and some general considerations.
+ </p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="pluginmap.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="wizard_interface.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Creating menu entries </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Adding a wizard interface</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/mainxmltips.html b/doc/rkwardplugins/mainxmltips.html
new file mode 100644
index 0000000..91a69b9
--- /dev/null
+++ b/doc/rkwardplugins/mainxmltips.html
@@ -0,0 +1,10 @@
+<html><head><title>Some considerations on GUI design</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="mainxml.html" title="Chapter 4. Defining the GUI"><link rel="prev" href="wizard_interface.html" title="Adding a wizard interface"><link rel="next" href="jstemplate.html" title="Chapter 5. Generating R code from GUI settings"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Some considerations on <acronym class="acronym">GUI</acronym> design</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="wizard_interface.html">Prev</a></td><td align="center" class="navCenter" width="34%">Defining the <acronym class="acronym">GUI</acronym></td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="jstemplate.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mainxmltips"></a>Some considerations on <acronym class="acronym">GUI</acronym> design</h2></div></div></div><p>
+ This section contains some general considerations on which <acronym class="acronym">GUI</acronym> elements to use where. If this is your first attempt of creating a plugin, feel free to skip over this section, as it is not relevant to getting a basic <acronym class="acronym">GUI</acronym> working. Come back here, later, to see, whether you can refine your plugin's <acronym class="acronym">GUI</acronym> in some way or another.
+ </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="radio_vs_checkbox_vs_dropdown"></a><radio> vs. <checkbox> vs. <dropdown></h3></div></div></div><p>
+ The three elements <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span>, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><checkbox></strong></span></span>, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dropdown></strong></span></span>, all serve a similar function: To select one out of several options. Obviously, a check box only allows to choose between two options: checked or not checked, so you cannot use it, if there are more than two options to choose from. But when to use which of the elements? Some rules of thumb:
+ </p><p>
+ If you find yourself creating a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span> or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dropdown></strong></span></span> with only two options, ask yourself, whether the question is essentially a yes / no type of question. E.g. a choice between <span class="quote">“<span class="quote">adjust results</span>”</span> and <span class="quote">“<span class="quote">do not adjust results</span>”</span>, or between <span class="quote">“<span class="quote">remove missing values</span>”</span> and <span class="quote">“<span class="quote">keep missing values</span>”</span>. In this case a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><checkbox></strong></span></span> is the best choice: It uses little space, will have the least words of labels, and is easiest to read for the user. There are very few situations where you should choose a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span> over a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><checkbox></strong></span></span>, when there are only two options. An example of that might be: <span class="quote">“<span class="quote">Method of calculation: 'pearson'/'spearman'</span>”</span>. Here, more methods might be thinkable, and they do not really form a pair of opposites.
+ </p><p>
+ Choosing between a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span> and a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dropdown></strong></span></span> is mostly a question of space. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dropdown></strong></span></span> has the advantage of using little space, even if there are a lot of options to choose from. On the other hand, a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span> has the advantage of making all possible choices visible to the user at once, without clicking on the dropdown arrow. Generally, if there are six or more options to choose from, a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dropdown></strong></span></span> is preferable. If there are five or less options, a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span> is the better choice.
+ </p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="wizard_interface.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="jstemplate.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Adding a wizard interface </td><td width="34%" align="center" class="navCenter"><a href="mainxml.html">Up</a></td><td width="33%" align="right" class="navRight"> Generating <span class="application">R</span> code from <acronym class="acronym">GUI</acronym> settings</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/optionset.html b/doc/rkwardplugins/optionset.html
new file mode 100644
index 0000000..208e1a9
--- /dev/null
+++ b/doc/rkwardplugins/optionset.html
@@ -0,0 +1,117 @@
+<html><head><title>Repeating (a set of) options</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="specialized_plugins.html" title="Chapter 10. Concepts for use in specialized plugins"><link rel="prev" href="current_object.html" title="Referencing the current object or current file"><link rel="next" href="chapter_dependencies.html" title="Chapter 11. Handling dependencies and compatibility issues"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Repeating (a set of) options</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="current_object.html">Prev</a></td><td align="center" class="navCenter" width="34%">Concepts for use in specialized plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="chapter_dependencies.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="optionset"></a>Repeating (a set of) options</h2></div></div></div><p>
+ Sometimes you want to repeat a set of options for an arbitrary number of items. E.g. suppose you want to implement a plugin for sorting a data.frame. You may want to allow for sorting by an arbitrary number of columns (in case of ties among the first column(s)). This could simply be realized by allowing the user to select multiple variables in a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span> with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>multi="true"</code></em></span>. But if you want to extend this, <abbr class="abbrev">e.g.</abbr> allowing the user to specify for each variable whether it should be converted to character / numeric, or whether sorting should be ascending or descending, you need more flexibility. Other examples would be plotting multiple lines in one plot (allowing to select object, line style, line color, <abbr class="abbrev">etc.</abbr> for each line), or specifying a mapping for recoding from a set of old values to new values.
+ </p><p>
+ Enter the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span>. Let's look at a simple example, first:
+ </p><pre class="programlisting">
+<dialog [...]>
+ [...]
+ <optionset id="set" min_rows="1">
+ <content>
+ <row>
+ <input id="firstname" label="Given name(s)" size="small">
+ <input id="lastname" label="Family name" size="small">
+ <radio id="gender" label="Gender">
+ <optioncolumn label="Male" value="m"/>
+ <optioncolumn label="Female" value="f"/>
+ </radio>
+ </row>
+ </content>
+
+ <optioncolumn id="firstnames" label="Given name(s)" connect="firstname.text">
+ <optioncolumn id="lastnames" label="Family name" connect="lastname.text">
+ <optioncolumn id="gender" connect="gender.string">
+ </optionset>
+ [...]
+</dialog>
+ </pre><p>
+ Here, we created a UI for specifying a number of persons (<abbr class="abbrev">e.g.</abbr> authors). The UI requires at least one entry (<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min_rows="1"</code></em></span>). Inside the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span>-element, we begin by specifying the
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><content></strong></span></span>, <abbr class="abbrev">i.e.</abbr> those elements that belong to the option set. You will be familiar with most elements
+ inside the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><content></strong></span></span>.
+ </p><p>
+ Next we specify the variables of interest that we will want to read from the option set in our JS file. As we will be dealing with
+ an arbitrary number of items, we cannot just read <code class="function">getString ("firstname")</code> in JS. Rather, for each value of
+ interest, we specify an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optioncolumn></strong></span></span>. For the first optioncolumn in the example, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><connect="firstname.text"></strong></span></span> means that the content of the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><input></strong></span></span>
+ element "firstname" is read for each item. <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optioncolumn></strong></span></span>s for which a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span> is given,
+ will be shown in the display, in a column by that label. In JS, we can now fetch the first names for all authors using <code class="function">getList("set.firstname")</code>, <code class="function">getList("set.lastnames")</code> for the family
+ names, and <code class="function">getList("set.gender")</code> for an array of "m"/"f" strings.
+ </p><p>
+ Note that there are no restrictions on what you can place inside an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span>. You can even use <a class="link" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins">embedded</a> components. Just as with any other element, all you have to do is to collect the output
+ variables of interest in an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optioncolumn></strong></span></span>-specification. In the case of embedded plugins, this is often a section of the "code" property. E.g.:
+ </p><pre class="programlisting">
+<dialog [...]>
+ [...]
+ <optionset id="set" min_rows="1">
+ <content>
+ [...]
+ <embed id="color" component="rkward::color_chooser" label="Color"/>
+ </content>
+
+ [...]
+ <optioncolumn id="color_params" connect="color.code.printout">
+ </optionset>
+ [...]
+</dialog>
+ </pre><p>
+ Of course you can also use <a class="link" href="logic.html" title="Chapter 7. Logic interactions between GUI elements">UI logic</a> inside an optionset. There are two options for doing this: You can do so by making connection (or scripting) in the main <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><logic></strong></span></span> section of your plugin, as usual. However, you will access the UI elements in the contents region as (<abbr class="abbrev">e.g.</abbr>) "set.contents.firstname.XYZ". Note the prefix "set" (the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> you have assigned to the set and "contents"). Alternatively, you can add a separate <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><logic></strong></span></span> section as a child element of your <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span>. In this case, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span>s will be addressed relative to the contents region, <abbr class="abbrev">e.g.</abbr> "firstname.XYZ". Only the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><script></strong></span></span>-element is not allowed in the logic section of an optionset. If you want to use scripting,
+ you will have to utilize the plugin's main <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><logic></strong></span></span> section.
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+ When scripting logic in an optionset, all you can do is access the <span class="emphasis"><em>current</em></span> content region. Thus, typically,
+ it is only meaningful to connect elements inside the contents region to each other. Connecting a property outside the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span> to a property inside the content region, may be useful for initialization. However,
+ modifying the contents region after initialization will <span class="emphasis"><em>not</em></span> apply to items that the user has already
+ defined. Only to the currently selected item in the set.
+ </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="optionset_driven"></a>"Driven" optionsets</h3></div></div></div><p>
+ So far we have considered an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span> that provides buttons for adding / removing items. However,
+ in some cases, it is much more natural to select items outside the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span>, and only provide
+ options for customizing some aspects of each item in an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span>. E.g. suppose you want to allow
+ the user to plot several objects inside one plot. For each object, the user should be able to specify line color.
+ You <span class="emphasis"><em>could</em></span> solve this by placing a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varselector></strong></span></span> and
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span> inside the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><content></strong></span></span> area, allowing the user to select one item
+ at a time. However, it will mean much less clicks for the user, if you use a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot multi="true"></strong></span></span>
+ <span class="emphasis"><em>outside</em></span> the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span>, instead. Then you will connect this selection of objects
+ to a so-called "driven" optionset. Here is how:
+ </p><pre class="programlisting">
+<dialog [...]>
+ <logic>
+ <connect client="set.vars" governor="vars.available"/>
+ <connect client="set.varnames" governor="vars.available.shortname"/>
+ </logic>
+ [...]
+ <varselector id="varsel"/>
+ <varslot id="vars" label="Objects to plot"/>
+ <optionset id="set" keycolumn="var">
+ <content>
+ [...]
+ <embed id="color" component="rkward::color_chooser" label="Line color"/>
+ </content>
+
+ [...]
+ <optioncolumn id="vars" external="true">
+ <optioncolumn id="varnames" external="true" label="Variable">
+ <optioncolumn id="color_params" connect="color.code.printout">
+ </optionset>
+ [...]
+</dialog>
+ </pre><p>
+ We will start looking at the example at the bottom. You will note that two <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optioncolumn></strong></span></span> specifications have
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>external="true"</code></em></span>. This tells <span class="application">RKWard</span> that these are controlled from outside the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span>. Here, the sole purpose of the "varnames"-optioncolumn is to provide easy-to-read labels in the
+ optionset display (it is connected to the "shortname" modifier of the property holding the selected
+ objects). The purpose of the "vars"-optioncolumn is to serve as the "key" column, as specified by
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset keycolumn="vars"...></strong></span></span>. This means that for each entry in this list, the set will offer
+ one set of options, and options are logically tied to these entries. This column is connected to the property holding the
+ selected objects in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span>. That is for each object that is selected there, the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span> will allow to specify line color.
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+ External column can also be <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>connect</code></em></span>ed to properties inside the
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><content></strong></span></span> region. However, it is important to note that optioncolumns declared
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>external="true"</code></em></span> should never be modified from inside the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span>, and
+ optioncolumns declared <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>external="false"</code></em></span> (the default) should never be modified from outside the
+ <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optionset></strong></span></span>.
+ </p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="optionset_alternatives"></a>Alternatives: When not to use optionsets</h3></div></div></div><p>
+ Optionsets are a powerful tool, but they can sometimes do more harm than good, as they add considerable complexity, both
+ from the perspective of a plugin developer, and from the perspective of a user. Thus, think twice, when using them. Here is
+ some advice:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>For some simple cases, the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><matrix></strong></span></span> element may provide a useful lightweight alternative.</p></li><li class="listitem"><p>Do not make your plugin do too much. We gave the example of using an optionset for a plugin to
+ draw several lines within one plot. But in general it is not a good idea to create a plugin that will produce individual
+ plots for each item in an optionset. Rather make the plugin produce one plot, and the user can call it multiple times.
+ </p></li><li class="listitem"><p>If you do not expect more than two or three items in a set, consider repeating the options, manually,
+ instead.</p></li></ul></div></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="current_object.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="chapter_dependencies.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Referencing the current object or current file </td><td width="34%" align="center" class="navCenter"><a href="specialized_plugins.html">Up</a></td><td width="33%" align="right" class="navRight"> Handling dependencies and compatibility issues</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/plugin_series.html b/doc/rkwardplugins/plugin_series.html
new file mode 100644
index 0000000..977bc12
--- /dev/null
+++ b/doc/rkwardplugins/plugin_series.html
@@ -0,0 +1,10 @@
+<html><head><title>Chapter 9. Dealing with many similar plugins</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="embedding_incomplete.html" title="Embedding/defining incomplete plugins"><link rel="next" href="include_js.html" title="Using the JS include statement"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Dealing with many similar plugins</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="embedding_incomplete.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="include_js.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="plugin_series"></a>Chapter 9. Dealing with many similar plugins</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="plugin_series.html#sect_similar_plugins">Overview on different approaches</a></span></dt><dt><span class="sect1"><a href="include_js.html">Using the JS include statement</a></span></dt><dt><span class="sect1"><a href="include_xml.html">Including <code class="literal">.xml</code> files</a></span></dt><dt><span class="sect1"><a href="snippets.html">Using <snippets></a></span></dt><dt><span class="sect1"><a href="include_snippets_vs_embedding.html"><include> and <snippets> vs. <embed></a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_similar_plugins"></a>Overview on different approaches</h2></div></div></div><p>
+ Sometimes, you may wish to develop plugins for a series of similar functions. As an example, consider the distribution plots. These generate fairly similar code, and of course it is desirable to make the graphical interfaces look similar to each other. Finally large sections of the help files can be identical. Only a few parameters are different for each plugin.
+ </p><p>
+ The naive approach to this is to develop one plugin, then basically copy and paste the entire contents of the <code class="literal">.js</code>, <code class="literal">.xml</code>, and <code class="literal">.rkh</code> files, then changing the few portions that are different. However, what if sometime later you find a spelling mistake that has been copied and pasted to all plugins? What if you want to add support for a new feature? You would have to visit all plugins again, and change each single one. A tiresome and tedious process.
+ </p><p>
+ A second approach would be to use <a class="link" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins">embedding</a>. However, in some cases this does not lend itself well to the problem at hand, mostly because the <span class="quote">“<span class="quote">chunks</span>”</span> you can embed are sometimes too large to be useful, and it places some constraints on the layout. For these cases, the concepts <a class="link" href="include_js.html" title="Using the JS include statement">including <code class="literal">.js</code> files</a>, <a class="link" href="include_xml.html" title="Including .xml files">including <code class="literal">.xml</code> files</a> and <a class="link" href="snippets.html" title="Using <snippets>">snippets</a> can be very useful (but see the <a class="link" href="include_snippets_vs_embedding.html" title="<include> and <snippets> vs. <embed>">thoughts on when it is preferable to use embedding</a>).
+ </p><p>
+ 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.
+ </p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="embedding_incomplete.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="include_js.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Embedding/defining incomplete plugins </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Using the JS include statement</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/pluginhelp.html b/doc/rkwardplugins/pluginhelp.html
new file mode 100644
index 0000000..214a6be
--- /dev/null
+++ b/doc/rkwardplugins/pluginhelp.html
@@ -0,0 +1,106 @@
+<html><head><title>Chapter 6. Writing a help page</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="jstips.html" title="Tips and tricks"><link rel="next" href="logic.html" title="Chapter 7. Logic interactions between GUI elements"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Writing a help page</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="jstips.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="logic.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="pluginhelp"></a>Chapter 6. Writing a help page</h1></div></div></div><p>
+ 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 <span class="application">R</span> functions.
+ </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+ After reading this chapter, have a look at the <a class="link" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><span class="application">rkwarddev</span> package</a> as well. It provides some <span class="application">R</span> functions to create most of <span class="application">RKWard</span>'s <acronym class="acronym">XML</acronym> tags for you. It is also capable of creating basic help file skeletons from existing plugin <acronym class="acronym">XML</acronym> files for you to start with.
+ </p></div><p>
+ You may recall putting this inside your plugin <acronym class="acronym">XML</acronym> (if you have not put this in, do so now):
+ </p><pre class="programlisting">
+<document>
+ [...]
+ <help file="filename.rkh" />
+ [...]
+</document>
+ </pre><p>
+ Where, obviously, you would replace <code class="filename">filename</code> with a more appropriate name. Now it is time to create this <code class="literal">.rkh</code> file. Here is a self-descriptive example:
+ </p><pre class="programlisting">
+<!DOCTYPE rkhelp>
+<document>
+ <summary>
+In this section, you will put some short, very basic information about what the plugin does.
+This section will always show up on the very top of the help page.
+ </summary>
+
+ <usage>
+The usage section may contain a little more practical information. It does not explain all
+the settings in detail (that is done in the "settings" section), however.
+
+To start a new paragraph, insert an empty line, as shown above.
+This line, in contrast, will be in the same paragraph.
+
+In all sections you can insert some simple HTML code, such as <b>bold</b> or
+<i>italic</i> text. Please keep formatting to the minimum needed, however.
+
+The usage section is always the second section shown in a help page.
+ </usage>
+
+ <section id="sectionid" title="Generic section" short_title="Generic">
+If you need to, you can add additional sections between the usage and settings sections.
+However, usually, you will not need this while documenting plugins. The "id"-attribute
+provides an anchor point to jump to this section from the navigation menu. The "short_title"
+attribute provides a short title to use in the navigation bar. This is optional, by default
+the main "title" will be used both as a heading to the section, and as the link name in the
+navigation bar.
+
+In any section you may want to insert links to further information. You do this by adding
+
+<link href="URL">link name</link>
+
+Where URL could be an external link such as https://rkward.kde.org .
+Several special URLs are supported in the help pages:
+
+<link href="rkward://page/path/page_id"/>
+
+This links to a top level rkward help page (not for a plugin).
+
+<link href="rkward://component/[namespace/]component_id"/>
+
+This links to the help page of another plugin. The [namespace/] part may be omitted
+(in this case, rkward is assumed as the standard namespace, e.g.:
+<link href="rkward://component/import_spss"/> or
+<link href="rkward://component/rkward/import_spss"/> are equivalent).
+The component_id is the same that you specified in the <a class="link" href="pluginmap.html" title="Chapter 3. Creating menu entries"><code class="literal">.pluginmap</code></a>.
+
+<link href="rkward://rhelp/rfunction"/>
+
+Links to the <span class="application">R</span> help page on "rfunction".
+
+Note that the link names will be generated automatically for these types of links.
+ </section>
+
+ <settings>
+ <caption id="id_of_tab_or_frame"/>
+ <setting id="id_of_element">
+Description of the GUI element identified by the given id
+ </setting>
+ <setting id="id_of_elementb" title="description">
+Usually the title of the GUI element will be extracted from the
+<a class="link" href="mainxml.html" title="Chapter 4. Defining the GUI"><acronym class="acronym">XML</acronym> definition of the plugin</a>, automatically. However,
+for some GUI elements, this description may not be enough to identify them, reliably.
+In this case, you can add an explicit title using the "title" attribute.
+ </setting>
+ <setting id="id_of_elementc">
+Description of the GUI element identified by "id_of_elementc"
+ </setting>
+ [...]
+ </settings>
+
+ <related>
+The related section typically just contains some links, such as:
+
+<ul>
+ <li><link href="rkward://rhelp/mean"/></li>
+ <li><link href="rkward://rhelp/median"/></li>
+ <li><link href="rkward://component/related_component"/></li>
+</ul>
+ </related>
+
+ <technical>
+The technical section (optional, always last) may contain some technical details of the plugin
+implementation, which are of interest only to RKWard developers. This is particularly relevant
+for plugins that are designed to be embedded in many other plugins, and could detail, which
+options are available to customize the embedded plugin, and which code sections contain which
+R code.
+ </technical>
+</document>
+ </pre></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="jstips.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="logic.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Tips and tricks </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Logic interactions between <acronym class="acronym">GUI</acronym> elements</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/pluginmap.html b/doc/rkwardplugins/pluginmap.html
new file mode 100644
index 0000000..2ce69ee
--- /dev/null
+++ b/doc/rkwardplugins/pluginmap.html
@@ -0,0 +1,101 @@
+<html><head><title>Chapter 3. Creating menu entries</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="whatareplugins.html" title="Chapter 2. Preliminaries: What are plugins in RKWard? How do they work?"><link rel="next" href="mainxml.html" title="Chapter 4. Defining the GUI"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Creating menu entries</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="whatareplugins.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="mainxml.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="pluginmap"></a>Chapter 3. Creating menu entries</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="pluginmap.html#pluginmap_grouping">Controlling the order of menu entries</a></span></dt></dl></div><p>
+ When you create a new plugin, you need to tell <span class="application">RKWard</span> about it. So the first thing to do, is to write a <code class="literal">.pluginmap</code> file (or modify an existing one). The format of <code class="literal">.pluginmap</code> is <acronym class="acronym">XML</acronym>. I will walk you through an example (also of course, be sure you have <span class="application">RKWard</span> configured to load your <code class="literal">.pluginmap</code> -- <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">Settings</span></span> → <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Configure <span class="application">RKWard</span></span></span> → <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Plugins</span></span>):
+ </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+ After reading this chapter, have a look at the <a class="link" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><span class="application">rkwarddev</span> package</a> as well. It provides some <span class="application">R</span> functions to create most of <span class="application">RKWard</span>'s <acronym class="acronym">XML</acronym> tags for you.
+ </p></div><pre class="programlisting">
+<!DOCTYPE rkpluginmap>
+ </pre><p>
+ The doctype is not really interpreted, but set it to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"rkpluginmap"</code></em></span> anyway.
+ </p><pre class="programlisting">
+<document base_prefix="" namespace="myplugins" id="mypluginmap">
+ </pre><p>
+ The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>base_prefix</code></em></span> attribute can be used, if all your plugins reside in a common directory. Basically, then you can omit that directory from the filenames specified below. It safe to leave this at <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>""</code></em></span>.
+ </p><p>
+ As you will see below, all plugins get a unique identifier, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span>. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>namespace</code></em></span> is a way to organize those IDs, and make it less likely to create a duplicate identifier accidentally. Internally, basically the namespace and then a <span class="quote">“<span class="quote">::</span>”</span> gets prepended to all the identifiers you specify in this <code class="literal">.pluginmap</code>. In general, if you intend to <a class="link" href="external_plugins.html#sect_external_plugins" title="External plugins">distribute your plugins in an <span class="application">R</span> package</a>, it is a good idea to use the package name as <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>namespace</code></em></span> parameter. Plugins shipped with the official <span class="application">RKWard</span> distribution have <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>namespace="rkward"</code></em></span>.
+ </p><p>
+ The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> attribute is optional, but specifying an id for your <code class="literal">.pluginmap</code> makes it possible for other people to make their <code class="literal">.pluginmap</code>s load your <code class="literal">.pluginmap</code>, automatically (see <a class="link" href="chapter_dependencies.html" title="Chapter 11. Handling dependencies and compatibility issues">the section on dependencies</a>).
+ </p><pre class="programlisting">
+ <components>
+ </pre><p>
+ Components? Are not we talking about plugins? Yes, but in the future, plugins will be no more than a special class of components. What we do here, then, is to register all components/plugins with <span class="application">RKWard</span>. Let's look at an example entry:
+ </p><pre class="programlisting">
+ <component type="standard" id="t_test_two_vars" file="t_test_two_vars.xml" label="Two Variable t-Test" />
+ </pre><p>
+ First the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>type</code></em></span> attribute: Leave this to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"standard"</code></em></span> for now. Further types are not yet implemented. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> we have already hinted at. Each component has to be given a unique (in its namespace) identifier. Pick one that is easily recognizable. Avoid spaces and any special characters. Those are not banned, so far, but might have special meanings. With the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>file</code></em></span> attribute, you specify where the <a class="link" href="mainxml.html" title="Chapter 4. Defining the GUI">description of the actual plugin itself</a> is located. This is relative to the directory the <code class="literal">.pluginmap</code> file is in, and the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>base_prefix</code></em></span> above. Finally, give the component a label. This label will be shown wherever the plugin is placed in the menu (or in the future perhaps in other places as well).
+ </p><p>
+ Typically a <code class="literal">.pluginmap</code> file will contain several components, so here are a few more:
+ </p><pre class="programlisting">
+ <component type="standard" id="unimplemented_test" file="means/unimplemented.xml" />
+ <component type="standard" id="fictional_t_test" file="means/ttests/fictional.xml" label="This is a fictional t-test" />
+ <component type="standard" id="descriptive" file="descriptive.xml" label="Descriptive Statistics" />
+ <component type="standard" id="corr_matrix" file="corr_matrix.xml" label="Correlation Matrix" />
+ <component type="standard" id="simple_anova" file="simple_anova.xml" label="Simple Anova" />
+ </components>
+ </pre><p>
+ OK, this was the first step. <span class="application">RKWard</span> now knows those plugins exist. But how to invoke them? They need to be placed in a menu hierarchy:
+ </p><pre class="programlisting">
+ <hierarchy>
+ <menu id="analysis" label="Analysis">
+ </pre><p>
+ Right below the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><hierarchy></strong></span></span> tag, you start describing, in which <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><menu></strong></span></span> your plugins should go. With the above line, you basically say, that your plugin should be in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">Analysis</span></span> menu (not necessarily directly there, but in a submenu). The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">Analysis</span></span> menu is standard in <span class="application">RKWard</span>, so it does not actually have to be created from scratch. However, if it did not exist yet, using the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span> attribute you would give it its name.
+ Finally, the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> once again identifies this <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><menu></strong></span></span>. This is needed, so several <code class="literal">.pluginmap</code> files can place their plugins in the same menus. They do this by looking for a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><menu></strong></span></span> with the given <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span>. If the ID does not yet exist, a new menu will be created. Otherwise the entries will be added to the existing menu.
+ </p><pre class="programlisting">
+ <menu id="means" label="Means">
+ </pre><p>
+ Basically the same thing here: Now we define a submenu to the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">Analysis</span></span> menu. It is to be called <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Means</span></span>.
+ </p><pre class="programlisting">
+ <menu id="ttests" label="t-Tests">
+ </pre><p>
+ And a final level in the menu hierarchy: A submenu of the submenu <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Means</span></span>.
+ </p><pre class="programlisting">
+ <entry component="t_test_two_vars" />
+ </pre><p>
+ Now, finally, this is the menu we want to place the plugin in. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><entry></strong></span></span> tag signals, this actually is the real thing, instead of another submenu. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>component</code></em></span> attribute refers to the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> you gave the plugin/component above.
+ </p><pre class="programlisting">
+ <entry component="fictional_t_test" />
+ </menu>
+ <entry component="fictional_t_test" />
+ </menu>
+ <menu id="frequency" label="Frequency" index="2"/>
+ </pre><p>
+ In case you have lost track: This is another submenu to the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">Analysis</span></span> menu. See the screenshot below. We will skip some of what is not visible, marked with [...].
+ </p><pre class="programlisting">
+ [...]
+ </menu>
+ <entry component="corr_matrix"/>
+ <entry component="descriptive"/>
+ <entry component="simple_anova"/>
+ </menu>
+ </pre><p>
+ These are the final entries visible in the screenshots below.
+ </p><pre class="programlisting">
+ <menu id="plots" label="Plots">
+ [...]
+ </menu>
+ </pre><p>
+ Of course you can also place your plugins in menus other than <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">Analysis</span></span>.
+ </p><pre class="programlisting">
+ <menu id="file" label="File">
+ [...]
+ </menu>
+ </pre><p>
+ Even in standard-menus such as <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">File</span></span>. All you need is the correct <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span>.
+ </p><pre class="programlisting">
+ </hierarchy>
+</document>
+ </pre><p>
+ That is how to do it. And this screenshot shows the result:
+ </p><div class="screenshot"><div xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="mediaobject"><img src="menu_hierarchy_example.png" alt="Menu hierarchy created by the code shown above"></div></div><p>
+ Confused? The easiest way to get started is probably taking some of the existing <code class="literal">.pluginmap</code> files shipped with the distribution, and modifying them to your needs. Also, if you need help, do not hesitate to write to the development mailing list.
+ </p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pluginmap_grouping"></a>Controlling the order of menu entries</h2></div></div></div><p>By default, all items (entries / submenus) inside a menu will be sorted alphabetically, automatically. In <span class="emphasis"><em>some</em></span> cases you may want more control. In this case you can group elements as follows:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>You can define groups inside any menu like this. All elements belonging to the same group will be grouped together:</p><pre class="programlisting">
+ <group id="somegroup"/>
+ </pre></li><li class="listitem"><p>If you want the group to be visually separated from other entries, use:</p><pre class="programlisting">
+ <group id="somegroup" separated="true"/>
+ </pre></li><li class="listitem"><p>Entries, menus, and groups can be appended to a specified group, using:</p><pre class="programlisting">
+ <entry component="..." group="somegroup"/>
+ </pre></li><li class="listitem"><p>In fact, it is also possible to define groups (without separator lines) implicitly:</p><pre class="programlisting">
+ <entry component="first" group="a"/>
+ <entry component="third"/>
+ <entry component="second" group="a"/>
+ </pre></li><li class="listitem"><p>Group names are specific to each menu. Group "a" in menu "Data" does not conflict with group "a" in menu "Analysis", for example.</p></li><li class="listitem"><p>The most common use case is defining groups at the top, or at the bottom of a menu. For this, there are pre-defined groups "top" and "bottom" in each menu.</p></li><li class="listitem"><p>Entries within each group are sorted, alphabetically. Groups appear in the order of declaration (unless appended to another group, of course).</p></li><li class="listitem"><p>Menus and entries without group specification logically form a group (""), too.</p></li></ul></div></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="whatareplugins.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="mainxml.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Preliminaries: What are plugins in <span class="application">RKWard</span>? How do they work? </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Defining the <acronym class="acronym">GUI</acronym></td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/pluginmapelements.html b/doc/rkwardplugins/pluginmapelements.html
new file mode 100644
index 0000000..68aad7d
--- /dev/null
+++ b/doc/rkwardplugins/pluginmapelements.html
@@ -0,0 +1,17 @@
+<html><head><title>Elements for use in .pluginmap files</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="reference.html" title="Appendix A. Reference"><link rel="prev" href="standard_embeddable_plugins.html" title="Embeddable plugins shipped with the official RKWard release"><link rel="next" href="helpfileelements.html" title="Elements for use in .rkh (help) files"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Elements for use in <code class="literal">.pluginmap</code> files</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="standard_embeddable_plugins.html">Prev</a></td><td align="center" class="navCenter" width="34%">Reference</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="helpfileelements.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pluginmapelements"></a>Elements for use in <code class="literal">.pluginmap</code> files</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><document></span></dt><dd><p>Needs to be present in each <code class="literal">.pluginmap</code> file as the root-node (exactly once). Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">base_prefix</span></dt><dd><p>Filenames specified in the <code class="literal">.pluginmap</code> file are assumed to be relative to the directory of the <code class="literal">.pluginmap</code> file + the prefix you specify here. Useful, esp., if all your components are located below a single subdirectory.</p></dd><dt><span class="term">namespace</span></dt><dd><p>A namespace for the component ids. When looking up components for embedding, the components will be retrievable via a string "namespace::component_id". Set to "rkward" for now.</p></dd><dt><span class="term">id</span></dt><dd><p>An optional identifier string for this <code class="literal">.pluginmap</code>. Specifying this allows third authors to refer to and load your <code class="literal">.pluginmap</code> from theirs (see <a class="link" href="chapter_dependencies.html" title="Chapter 11. Handling dependencies and compatibility issues">chapter on handling dependencies</a>).</p></dd><dt><span class="term">priority</span></dt><dd><p>One of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"hidden"</code></em></span>, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"low"</code></em></span>, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"medium"</code></em></span>, or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"high"</code></em></span>. <code class="literal">.pluginmap</code>s with priority "medium" or "high" are activated, automatically, when <span class="application">RKWard</span> first finds them. Use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>priority="hidden"</code></em></span> for <code class="literal">.pluginmap</code>s that are not meant to be activated, directory (only meant for inclusion). In the current implementation this does not actually hide the <code class="literal">.pluginmap</code>, however. (Optional, defaults to "medium").</p></dd></dl></div></dd><dt><span class="term"><dependencies></span></dt><dd><p>This element, specifying dependencies, is allowed as a direct child of the <document> element (once), and as a child of <component> elements (once for each <component> element). Specifies the dependencies that must be met in order to use the plugin(s). See the <a class="link" href="chapter_dependencies.html" title="Chapter 11. Handling dependencies and compatibility issues">chapter on dependencies</a> for an overview. Attributes:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">rkward_min_version, rkward_max_version</span></dt><dd><p>Minimum and maximum allowed version of <span class="application">RKWard</span>. Version specifications may include non-numeric suffixes, like "0.5.7z-devel1". If a specified dependency is not met, the plugin(s) it applies to <span class="emphasis"><em>will be ignored</em></span>. <a class="link" href="chapter_dependencies.html#sect_dependencies_rkward_version" title="RKWard version compatibility">More information</a>. Optional; if not specified, no minimum / maximum version of <span class="application">RKWard</span> will be required.</p></dd><dt><span class="term">R_min_version, R_max_version</span></dt><dd><p>Minimum and maximum allowed version of <span class="application">R</span>. Version specifications may <span class="emphasis"><em>not</em></span> include non-numeric suffixes, like "0.5.7z-devel1". The <span class="application">R</span> version dependency will be shown on the plugins' help pages, but does not have any direct effect, as of <span class="application">RKWard</span> 0.6.1. <a class="link" href="sect_dependencies_r_version.html" title="R version compatibility">More information</a>. Optional; if not specified, no minimum / maximum version of <span class="application">R</span> will be required.</p></dd></dl></div><p>Child elements:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><package></span></dt><dd><p>Adds a dependency on a specific <span class="application">R</span> package. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">name</span></dt><dd><p>Package name (required).</p></dd><dt><span class="term">min_version, max_version</span></dt><dd><p>Minimum / maximum allowed version (optional).</p></dd><dt><span class="term">repository</span></dt><dd><p>Repository where the package can be found. Optional, but highly recommended, if the package is not available on CRAN.</p></dd></dl></div><p>
+ </p></dd><dt><span class="term"><pluginmap></span></dt><dd><p>Adds a dependency on a specific <span class="application">RKWard</span> <code class="literal">.pluginmap</code>. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">name</span></dt><dd><p>Id string of the required <code class="literal">.pluginmap</code> (required).</p></dd><dt><span class="term">min_version, max_version</span></dt><dd><p>Minimum / maximum allowed version (optional).</p></dd><dt><span class="term">url</span></dt><dd><p><acronym class="acronym">URL</acronym> where the <code class="literal">.pluginmap</code> can be found. Required.</p></dd></dl></div><p>
+ </p></dd></dl></div></dd><dt><span class="term"><about></span></dt><dd><p>May be present exactly once as a direct child of the <document> element. Contains meta information on the <code class="literal">.pluginmap</code> (or plugin). See the <a class="link" href="chapter_about_information.html" title="Chapter 13. Author, license and version information">chapter on 'about' information</a> for an overview. Attributes:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">name</span></dt><dd><p>User visible name. Optional. Does not have to be the same as the "id".</p></dd><dt><span class="term">version</span></dt><dd><p>Version number. Optional. The format is not restricted, but to be on the safe side, please follow common versioning schemes such as "x.y.z".</p></dd><dt><span class="term">releasedate</span></dt><dd><p>Release date specification. Optional in format "YYYY-MM-DD".</p></dd><dt><span class="term">shortinfo</span></dt><dd><p>A <span class="emphasis"><em>short</em></span> description of the plugin / <code class="literal">.pluginmap</code>. Optional.</p></dd><dt><span class="term">url</span></dt><dd><p><acronym class="acronym">URL</acronym> where more information can be found. Optional, but recommended.</p></dd><dt><span class="term">copyright</span></dt><dd><p>Copyright specification, <abbr class="abbrev">e.g.</abbr> "2012-2013 by John Doe". Optional, but recommended.</p></dd><dt><span class="term">licence</span></dt><dd><p>License specification, <abbr class="abbrev">e.g.</abbr> "GPL" or "BSD". Please make sure to accompany your files with a complete copy of the relevant licence. Optional, but recommended.</p></dd><dt><span class="term">category</span></dt><dd><p>Category of plugin(s), <abbr class="abbrev">e.g.</abbr> "Item response theory". As of <span class="application">RKWard</span> 0.6.1, no categories are predefined. Optional.</p></dd></dl></div><p>Child elements:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><author></span></dt><dd><p>Adds information on an author. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">name, given, family</span></dt><dd><p>Either specify the full name for <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>name</code></em></span>, or specify both <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>given</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>family</code></em></span>, separately.</p></dd><dt><span class="term">role</span></dt><dd><p>Author role description (optional).</p></dd><dt><span class="term">email</span></dt><dd><p>E-mail address, where author can be contacted. Required. May be set to the rkward-devel mailing list, if you are subscribed, and your plugin is meant to be included in the official <span class="application">RKWard</span> release.</p></dd><dt><span class="term">url</span></dt><dd><p><acronym class="acronym">URL</acronym> with more information on the author, <abbr class="abbrev">e.g.</abbr> homepage (optional).</p></dd></dl></div><p>
+ </p></dd></dl></div></dd><dt><span class="term"><components></span></dt><dd><p>Needs to be present exactly once as a direct child of the <document> element. Contains the individual <component>-elements described below. No attributes.</p></dd><dt><span class="term"><component></span></dt><dd><p>One or more <component> elements should be given as direct children of the <components> element (and only there). Registers a component/plugin with rkward. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">type</span></dt><dd><p>For future extension: The type of component/plugin. Always set to "standard" for now (the only type currently supported).</p></dd><dt><span class="term">id</span></dt><dd><p>The ID by which this component can be retrieved (for placing it in the menu (see below), or for embedding). See <document>-namespace above.</p></dd><dt><span class="term">file</span></dt><dd><p>Required at least for components of type="standard": The filename of the <acronym class="acronym">XML</acronym> file describing the <acronym class="acronym">GUI</acronym>.</p></dd><dt><span class="term">label</span></dt><dd><p>The label for this component, when placed in the menu hierarchy.</p></dd></dl></div></dd><dt><span class="term"><attribute></span></dt><dd><p>Defines an attribute of a component. Only meaningful for <a class="link" href="contextualized_plugins.html#context_import" title="Import data context">import plugins</a> so far. Only allowed as a direct child of <component>. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">id</span></dt><dd><p>Id of the attribute</p></dd><dt><span class="term">value</span></dt><dd><p>Value of the attribute</p></dd><dt><span class="term">labels</span></dt><dd><p>Label associated with the attribute</p></dd></dl></div></dd><dt><span class="term"><hierarchy></span></dt><dd><p>Needs to be present exactly once as a direct child of the <document> element. Describes where the components declared above should be placed in the menu hierarchy. Accepts only <menu> elements as direct children. No attributes.</p></dd><dt><span class="term"><menu></span></dt><dd><p>One or more <menu> elements should be given as direct children of the <hierarchy> element. Declares a new (sub-)menu. If a menu by the given ID (see below) already exists, the two menus are merged. The <menu> element is allowed either as a direct child of the <hierarchy> element (top level menu), or as the direct child on any other <menu> element (sub-menu). Conversely, the <menu> element accepts other <menu> elements or <entry> elements as children. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">id</span></dt><dd><p>An identifier string of the menu. Useful, when menu definitions are read from several <code class="literal">.pluginmap</code> files, to make sure plugins can be placed in the same menu(s). Some menu-ids such as "file" refer to predefined menus (in this case the "File" menu). Be sure to check with existing <code class="literal">.pluginmap</code> files to use consistent ids.</p></dd><dt><span class="term">label</span></dt><dd><p>A label for the menu.</p></dd><dt><span class="term">group</span></dt><dd><p>Allows to control ordering of menu entries. See <a class="link" href="pluginmap.html#pluginmap_grouping" title="Controlling the order of menu entries">menu item ordering</a>. Optional.</p></dd></dl></div></dd><dt><span class="term"><entry></span></dt><dd><p>A menu entry, <abbr class="abbrev">i.e.</abbr> a menu option to invoke a plugin. May be used only as a direct child of a <menu> element, accepts no child elements. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">component</span></dt><dd><p>The ID of the component that should be invoked, when this menu entry is activated.</p></dd><dt><span class="term">group</span></dt><dd><p>Allows to control ordering of menu entries. See <a class="link" href="pluginmap.html#pluginmap_grouping" title="Controlling the order of menu entries">menu item ordering</a>. Optional.</p></dd></dl></div></dd><dt><span class="term"><group></span></dt><dd><p>Declares a group of items in the menu. See <a class="link" href="pluginmap.html#pluginmap_grouping" title="Controlling the order of menu entries">menu item ordering</a>. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">id</span></dt><dd><p>The name of this group.</p></dd><dt><span class="term">separated</span></dt><dd><p>Optional. If set to "true" the item in this group will be visually separated from surrounding items.</p></dd><dt><span class="term">group</span></dt><dd><p>The name of the group to append this group to (optional).</p></dd></dl></div></dd><dt><span class="term"><context></span></dt><dd><p>Declares the entries in a <a class="link" href="contextualized_plugins.html" title="Context-dependent plugins">context</a>. Only allowed as a direct child of the <document> tag. Accepts only <menu> tags as direct children. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">id</span></dt><dd><p>The ID of the context. Only two contexts are implemented so far: "x11" and "import".</p></dd></dl></div></dd><dt><span class="term"><require></span></dt><dd><p>Include another <code class="literal">.pluginmap</code> file. This <code class="literal">.pluginmap</code> file is only loaded once, even if it is <require>d from several other files. The most important use case is to include a pluginmap file, which declares some components, which are embedded by components declared in this <code class="literal">.pluginmap</code>. <require>-elements are only allowed as direct children of the <document>-node. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">file</span></dt><dd><p>The filename of the <code class="literal">.pluginmap</code> to include. This is seen relative to the directory of the current <code class="literal">.pluginmap</code> file + the base_prefix (see above, <document>-element). If you do not know the relative path to the <code class="literal">.pluginmap</code> to be included, use the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>map</code></em></span> attribute to refer to it by id, instead.</p></dd><dt><span class="term">map</span></dt><dd><p>To include a <code class="literal">.pluginmap</code> file from a different package (or an <span class="application">RKWard</span> <code class="literal">.pluginmap</code> from your external <code class="literal">.pluginmap</code>), you can refer to it by its <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>namespacename::id</code></em></span>, as specified in the required <code class="literal">.pluginmap</code>s <document> element. Inclusion will fail, if no <code class="literal">.pluginmap</code> by that id is known (<abbr class="abbrev">e.g.</abbr> not installed on the user's system). You should use this method for including <code class="literal">.pluginmap</code>s outside your package, only. For maps inside your package, specifying a relative path (<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>file</code></em></span> attribute) is faster, and more reliable.
+ </p></dd></dl></div></dd></dl></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="standard_embeddable_plugins.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="helpfileelements.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Embeddable plugins shipped with the official <span class="application">RKWard</span> release </td><td width="34%" align="center" class="navCenter"><a href="reference.html">Up</a></td><td width="33%" align="right" class="navRight"> Elements for use in .rkh (help) files</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/querying_r_for_info.html b/doc/rkwardplugins/querying_r_for_info.html
new file mode 100644
index 0000000..5000c58
--- /dev/null
+++ b/doc/rkwardplugins/querying_r_for_info.html
@@ -0,0 +1,33 @@
+<html><head><title>Querying R for information</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="specialized_plugins.html" title="Chapter 10. Concepts for use in specialized plugins"><link rel="prev" href="contextualized_plugins.html" title="Context-dependent plugins"><link rel="next" href="current_object.html" title="Referencing the current object or current file"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Querying <span class="application">R</span> for information</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="contextualized_plugins.html">Prev</a></td><td align="center" class="navCenter" width="34%">Concepts for use in specialized plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="current_object.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="querying_r_for_info"></a>Querying <span class="application">R</span> for information</h2></div></div></div><p>In some cases, you may want to fetch further information from <span class="application">R</span>, to be presented in your plugin's UI. For instance, you may want to offer a selection of the levels of a factor that the user
+ has selected for analysis. Since version 0.6.2 of <span class="application">RKWard</span> it is possible to do so. Before we start, it is important that you are aware of some caveats:</p><p>R Code run from inside the plugin's UI logic is evaluated in R's event loop, meaning they can be run <span class="emphasis"><em>while</em></span> other computations are running. This is to make sure your plugin's UI will be usable, even while <span class="application">R</span> is busy doing other things. However, this makes it really important, that your code does not have side effects. In particular:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Do <span class="emphasis"><em>not</em></span> make any assignments in .GlobalEnv or any other non-local environment.</p></li><li class="listitem"><p>Do <span class="emphasis"><em>not</em></span> print anything to the output file.</p></li><li class="listitem"><p>Do <span class="emphasis"><em>not</em></span> plot anything on-screen.</p></li><li class="listitem"><p>In general, do <span class="emphasis"><em>not</em></span> do anything that has side-effects. Your code may <span class="emphasis"><em>read in information</em></span>, not "<span class="emphasis"><em>do</em></span>" anything.</p></li></ul></div><p>With this in mind, here is the general pattern. You will use this inside a <a class="link" href="logic_scripted.html" title="Scripted GUI logic">scripted UI logic</a> section:</p><pre class="programlisting">
+ <script><![CDATA[
+ last_command_id = -1;
+ gui.addChangeCommand ("variable", "update ()");
+ update = function () {
+ gui.setValue ("selector.enabled", 0);
+ variable = gui.getValue ("variable");
+ if (variable == "") return;
+
+ last_command_id = doRCommand ('levels (' + variable + ')', "commandFinished");
+ }
+
+ commandFinished = function (result, id) {
+ if (id != last_command_id) return; // another result is about to arrive
+ if (typeof (result) == "undefined") {
+ gui.setListValue ("selector.available", Array ("ERROR"));
+ return;
+ }
+ gui.setValue ("selector.enabled", 1);
+ gui.setListValue ("selector.available", result);
+ }
+ ]]></script>
+ </pre><p>Here, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>variable</code></em></span> is a property holding an object name (<abbr class="abbrev">e.g.</abbr> inside a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span>). Whenever that changes, you will want to update the display
+ of levels inside the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><valueselector></strong></span></span>, named <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>selector</code></em></span>. The key function here is <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>doRCommand()</strong></span></span>, taking as first parameter
+ the command string to run, and as second parameter the name of a function to call, when the command has finished. Note that the command is running asynchronously, and this makes things
+ a bit more complex. For one thing you want to make sure, that your <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><valueselector></strong></span></span> remains disabled, while it does not contain up-to-date information. Another
+ thing is that you could potentially have queued more than one command, before you get the first results. This is why every command is given an "id", and we store that in <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>last_command_id</code></em></span> for later reference.</p><p>When the command is done, the specified callback is called (<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>commandFinished</code></em></span>, in this case) with two parameters: The result itself, and the id of the corresponding
+ command. The result will be of a type resembling the representation in <span class="application">R</span>, <abbr class="abbrev">i.e.</abbr> a numeric Array, if the result is numeric, <abbr class="abbrev">etc.</abbr> It can even be an <span class="application">R</span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>list()</strong></span></span>, but in this case
+ it will be represented as a JS <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>Array()</strong></span></span> without names.</p><p>Note that even this example is somewhat simplified. In reality you should take additional precautions, <abbr class="abbrev">e.g.</abbr> to avoid putting an extreme amount of levels into the selector. The good news
+ is that probably you do not have to do all this yourself. The above example is taken from the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rkward::level_select</strong></span></span> plugin, for instance, which you can simply <a class="link" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins">embed</a> in your own
+ plugin. This even allows you to specify a different expression to run in place of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>levels()</strong></span></span>.</p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="contextualized_plugins.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="current_object.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Context-dependent plugins </td><td width="34%" align="center" class="navCenter"><a href="specialized_plugins.html">Up</a></td><td width="33%" align="right" class="navRight"> Referencing the current object or current file</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/reference.html b/doc/rkwardplugins/reference.html
new file mode 100644
index 0000000..1faa371
--- /dev/null
+++ b/doc/rkwardplugins/reference.html
@@ -0,0 +1,10 @@
+<html><head><title>Appendix A. Reference</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="rkwarddev_i18n.html" title="Translating plugins"><link rel="next" href="globalxmlelements.html" title="General purpose elements to be used in any XML file (.xml, .rkh, .pluginmap)"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Reference</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="rkwarddev_i18n.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="globalxmlelements.html">Next</a></td></tr></tbody></table><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a name="reference"></a>Appendix A. Reference</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="reference.html#propertytypes">Types of properties/Modifiers</a></span></dt><dt><span class="sect1"><a href="globalxmlelements.html">General purpose elements to be used in any <acronym class="acronym">XML</acronym> file (<code class="literal">.xml</code>, <code class="literal">.rkh</code>, <code class="literal">.pluginmap</code>)</a></span></dt><dt><span class="sect1"><a href="xmlelements.html">Elements to be used in the <acronym class="acronym">XML</acronym> description of the plugin</a></span></dt><dd><dl><dt><span class="sect2"><a href="xmlelements.html#generalelements">General elements</a></span></dt><dt><span class="sect2"><a href="xmlelements.html#interfaceelements">Interface definitions</a></span></dt><dt><span class="sect2"><a href="xmlelements.html#layoutelements">Layout elements</a></span></dt><dt><span class="sect2"><a href="xmlelements.html#activeelements">Active elements</a></span></dt><dt><span class="sect2"><a href="xmlelements.html#logicelements">Logic section</a></span></dt></dl></dd><dt><span class="sect1"><a href="elementproperties.html">Properties of plugin elements</a></span></dt><dt><span class="sect1"><a href="standard_embeddable_plugins.html">Embeddable plugins shipped with the official <span class="application">RKWard</span> release</a></span></dt><dt><span class="sect1"><a href="pluginmapelements.html">Elements for use in <code class="literal">.pluginmap</code> files</a></span></dt><dt><span class="sect1"><a href="helpfileelements.html">Elements for use in .rkh (help) files</a></span></dt><dt><span class="sect1"><a href="guilogic_functions.html">Functions available for <acronym class="acronym">GUI</acronym> logic scripting</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="propertytypes"></a>Types of properties/Modifiers</h2></div></div></div><p>
+ At some places in this introduction we have talked about <span class="quote">“<span class="quote">properties</span>”</span> of <acronym class="acronym">GUI</acronym> elements or otherwise. In fact there are several different types of properties. Usually you do not need to worry about this, as you can use common sense to connect any property to any other property. However, internally, there are different types of properties. What this matters for, is when fetching some special values in the JS-template. In getString ("id")/getBoolean ("id")/getList ("id") statements you can also specify some so called <span class="quote">“<span class="quote">modifiers</span>”</span> like this: <code class="function">getString ("id.modifier")</code>. This modifier will affect, in which way the value is printed. Read on for the list of properties, and the modifiers they each make available:
+</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">String properties</span></dt><dd><p>The most simple type of property, used to simply hold a piece of text. Modifiers:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">No modifier ("")</span></dt><dd><p>The string as defined / set.</p></dd><dt><span class="term">quoted</span></dt><dd><p>The string in quoted form (suitable for passing to <span class="application">R</span> as character).</p></dd></dl></div></dd><dt><span class="term">Boolean properties</span></dt><dd><p>Properties that can either be on or off, true or false. For instance the properties created by <convert>-tags, also the property accompanying a <checkbox> (see below). The following values will be returned according to the given modifier:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">No modifier ("")</span></dt><dd><p>By default the property will return 1 if it is true, and 0 otherwise. The recommended way to fetch boolean values is using <code class="function">getBoolean()</code>. Note that for <code class="function">getString()</code>, the string "0" will be returned when the property is false. This string would evaluate to true, not to false in JS.</p></dd><dt><span class="term">"labeled"</span></dt><dd><p>Returns the string "true" when true, "false", when false, or whichever custom strings have been specified (typically in a <checkbox>).</p></dd><dt><span class="term">"true"</span></dt><dd><p>Return the string as if the property was true, even if it is false</p></dd><dt><span class="term">"false"</span></dt><dd><p>Return the string as if the property was false, even if it is true</p></dd><dt><span class="term">"not"</span></dt><dd><p>This actually returns another Boolean property, which is the reverse of the current (<abbr class="abbrev">i.e.</abbr> false if true, true if false)</p></dd><dt><span class="term">"numeric"</span></dt><dd><p>Obsolete, provided for backwards compatibility. Same as no modifier "". Return "1" if the property is true, or "0" if it is false.</p></dd></dl></div></dd><dt><span class="term">Integer properties</span></dt><dd><p>A property designed to hold an integer value (but of course it still returns a numeric character string to the JS-template). It does not accept any modifiers. Used in <spinbox>es (see below)</p></dd><dt><span class="term">Real number properties</span></dt><dd><p>A property designed to hold a real number value (but of course it still returns a numeric character string to the JS-template). Used in <spinbox>es (see below)
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">No modifier ("")</span></dt><dd><p>For <code class="function">getValue() / getString()</code>, this returns the same as "formatted". In future versions, it will be possible to obtain a numeric representation, instead.</p></dd><dt><span class="term">"formatted"</span></dt><dd><p>Returns the formatted number (as a string).</p></dd></dl></div></dd><dt><span class="term">RObject properties</span></dt><dd><p>A property designed a selection of one or more <span class="application">R</span> objects. Used most prominently in varselectors and varslots. The following values will be returned according to the given modifier:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">No modifier ("")</span></dt><dd><p>By default the property will return the full name of the selected object. If more than one object is selected, the object names will be separated by line breaks ("\n").</p></dd><dt><span class="term">"shortname"</span></dt><dd><p>Like above, but returns only short name(s) for the object(s). For instance an object inside a list would only be given the name it has inside the list, without the name of the list.</p></dd><dt><span class="term">"label"</span></dt><dd><p>Like above, but returns the <span class="application">RKWard</span> label(s) of the object(s) (if no label available, this is the same as shortname)</p></dd></dl></div></dd><dt><span class="term">String list properties</span></dt><dd><p>This property holds a list of strings.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">No modifier ("")</span></dt><dd><p>For <code class="function">getValue()/getString()</code>, this returns all strings separated by "\n". Any "\n" characters in each item are escaped as literal "\n". However, the recommended usage is to fetch the value with <code class="function">getList()</code>, instead, which will return an array of strings.</p></dd><dt><span class="term">"joined"</span></dt><dd><p>Returns the list as a single string, with items joined by "\n". In contrast to no modifier (""), the individual strings are _not_ escaped.</p></dd></dl></div></dd><dt><span class="term">Code properties</span></dt><dd><p>A property held by plugins that generated code. This is important for embedding plugins, in order to embed the code generated by the embedded plugin into the code generated by the embedding (top-level) plugin. The following values will be returned according to the given modifier:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">No modifier ("")</span></dt><dd><p>Returns the full code, <abbr class="abbrev">i.e.</abbr> the sections "preprocess", "calculate", "printout", and (but not "preview") concatenated to one string.</p></dd><dt><span class="term">"preprocess"</span></dt><dd><p>Returns only the preprocess section of the code</p></dd><dt><span class="term">"calculate"</span></dt><dd><p>Returns only the calculate section of the code</p></dd><dt><span class="term">"printout"</span></dt><dd><p>Returns only the printout section of the code</p></dd><dt><span class="term">"preview"</span></dt><dd><p>Returns the preview section of the code</p></dd></dl></div></dd></dl></div></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="rkwarddev_i18n.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="globalxmlelements.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Translating plugins </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> General purpose elements to be used in any <acronym class="acronym">XML</acronym> file (<code class="literal">.xml</code>, <code class="literal">.rkh</code>, <code class="literal">.pluginmap</code>)</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/rkdev_example.html b/doc/rkwardplugins/rkdev_example.html
new file mode 100644
index 0000000..ebdcfc2
--- /dev/null
+++ b/doc/rkwardplugins/rkdev_example.html
@@ -0,0 +1,207 @@
+<html><head><title>Practical example</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><link rel="prev" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><link rel="next" href="rkwarddev_rkh.html" title="Adding help pages"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Practical example</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="rkwarddev.html">Prev</a></td><td align="center" class="navCenter" width="34%">Plugin development with the <span class="application">rkwarddev</span> package</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="rkwarddev_rkh.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rkdev_example"></a>Practical example</h2></div></div></div><p>To get you an idea how <span class="quote">“<span class="quote">scripting a plugin</span>”</span> looks like, compared to the direct approach you have seen in the previous chapters, we will create the full t-test plugin once again -- this time only with the <span class="application">R</span> functions of the <span class="application">rkwarddev</span> package.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>The package will add a new <acronym class="acronym">GUI</acronym> dialog to <span class="application">RKWard</span> under <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">File</span></span> → <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Export</span></span> → <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Create <span class="application">RKWard</span> plugin script</span></span>. Like the name suggests, you can create plugin skeletons for further editing with it. This dialog itself was in turn generated by an <span class="application">rkwarddev</span> script which you can find in the <span class="quote">“<span class="quote">demo</span>”</span> directory of the installed package and package sources, as an additional example. You can also run it by calling <code class="function">demo("skeleton_dialog")</code></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rkdev_gui"></a><acronym class="acronym">GUI</acronym> description</h3></div></div></div><p>You will immediately notice that the workflow is considerably different: Contrary to writing the XML code directly, you do not begin with the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><document></strong></span></span> definition, but directly with the plugin elements you would like to have in the dialog. You can assign each interface element -- be it check boxes, dropdown menus, variable slots or anything else -- to individual <span class="application">R</span> objects, and then combine these objects to the actual <acronym class="acronym">GUI</acronym>. The package has functions for <a class="link" href="xmlelements.html#interfaceelements" title="Interface definitions">each XML tag</a> that can be used to define the plugin <acronym class="acronym">GUI</acronym>, and most of them even have the same name, only with the prefix <code class="function">rk.XML.*</code>. For example, defining a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varselector></strong></span></span> and two <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span> elements for the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"x"</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"y"</code></em></span> variable of the t-test example can be done by:</p><pre class="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")
+ </pre><p>The most interesting detail is probably <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>source=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>variables</code></em></span>: A prominent feature of the package is that all functions can generate automatic IDs, so you do not have to bother with either thinking of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> values or remembering them to refer to a specific plugin element. You can simply give the <span class="application">R</span> objects as reference, as all functions who need an ID from some other element can also read it from these objects. <code class="function">rk.XML.varselector()</code> 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 <code class="function">rk.XML.varslot()</code> would not need the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id.name</code></em></span> arguments here, so this would suffice:</p><pre class="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)
+ </pre><p>In order to recreate the example code to the point, you would have to set all ID values manually. But since the package shall make our lives easier, from now on we will no longer care about that.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+ <span class="application">rkwarddev</span> is capable of a lot of automation to help you build your plugins. However, it might be preferable to not use it to its full extend. If your goal is to produce code that is not only working but can also be easily read and compared to your generator script by a human being, you should consider to always set useful IDs with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id.name</code></em></span>. Naming your <span class="application">R</span> objects identical to these IDs will also help in getting script code that is easy to understand.
+ </p></div><p>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 <span class="quote">“<span class="quote">var.x</span>”</span> in your <span class="application">R</span> session, you should see something like this:</p><pre class="programlisting">
+<varslot id="vrsl_compare" label="compare" source="vars" types="number" required="true" />
+ </pre><p>Some tags are only useful in the context of others. Therefore, for instance, you will not find a function for the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><option></strong></span></span> tag. Instead, both radio buttons and dropdown lists are defined including their options as a named list, where the names represent the labels to be shown in the dialog, and their value is a named vector which can have two entries, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>val</code></em></span> for the value of an option and the boolean <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>chk</code></em></span> to specify if this option is checked by default.</p><pre class="programlisting">
+test.hypothesis <- rk.XML.radio("using test hypothesis",
+ options=list(
+ "Two-sided"=c(val="two.sided"),
+ "First is greater"=c(val="greater"),
+ "Second is greater"=c(val="less")
+ )
+)
+ </pre><p>The result looks like this:</p><pre class="programlisting">
+<radio id="rad_usngtsth" label="using test hypothesis">
+ <option label="Two-sided" value="two.sided" />
+ <option label="First is greater" value="greater" />
+ <option label="Second is greater" value="less" />
+</radio>
+ </pre><p>All that is missing from the elements of the <span class="quote">“<span class="quote">Basic settings</span>”</span> tab is the check box for paired samples, and the structuring of all of these elements in rows and columns:</p><pre class="programlisting">
+check.paired <- rk.XML.cbox("Paired sample", value="1", un.value="0")
+basic.settings <- rk.XML.row(variables, rk.XML.col(var.x, var.y, test.hypothesis, check.paired))
+ </pre><p><code class="function">rk.XML.cbox()</code> is a rare exception where the function name does not contain the full tag name, to save some typing for this often used element. This is what <code class="function">basic.settings</code> now contains:</p><pre class="programlisting">
+<row id="row_vTFSPP10TF">
+ <varselector id="vars" />
+ <column id="clm_vrsTFSPP10">
+ <varslot id="vrsl_compare" label="compare" source="vars" types="number" required="true" />
+ <varslot id="vrsl_against" label="against" i18n_context="compare against" source="vars" types="number" required="true" />
+ <radio id="rad_usngtsth" label="using test hypothesis">
+ <option label="Two-sided" value="two.sided" />
+ <option label="First is greater" value="greater" />
+ <option label="Second is greater" value="less" />
+ </radio>
+ <checkbox id="chc_Pardsmpl" label="Paired sample" value="1" value_unchecked="0" />
+ </column>
+</row>
+ </pre><p>In a similar manner, the next lines will create <span class="application">R</span> objects for the elements of the <span class="quote">“<span class="quote">Options</span>”</span> tab, introducing functions for spinboxes, frames and stretch:</p><pre class="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)
+check.conf <- rk.XML.cbox("print confidence interval", val="1", chk=TRUE)
+conf.frame <- rk.XML.frame(conf.level, check.conf, rk.XML.stretch(), label="Confidence Interval")
+ </pre><p>Now all we need to do is to put the objects together in a tabbook, and place that in a dialog section:</p><pre class="programlisting">
+full.dialog <- rk.XML.dialog(
+ label="Two Variable t-Test",
+ rk.XML.tabbook(tabs=list("Basic settings"=basic.settings, "Options"=list(check.eqvar, conf.frame)))
+)
+ </pre><p>We can also create the wizard section with its two pages using the same objects, so their IDs will be extracted for the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><copy></strong></span></span> tags:</p><pre class="programlisting">
+full.wizard <- rk.XML.wizard(
+ label="Two Variable t-Test",
+ rk.XML.page(
+ rk.XML.text("As a first step, select the two variables you want to compare against
+ each other. And specify, which one you theorize to be greater. Select two-sided,
+ if your theory does not tell you, which variable is greater."),
+ rk.XML.copy(basic.settings)),
+ rk.XML.page(
+ rk.XML.text("Below are some advanced options. It is generally safe not to assume the
+ variables have equal variances. An appropriate correction will be applied then.
+ Choosing \"assume equal variances\" may increase test-strength, however."),
+ rk.XML.copy(check.eqvar),
+ rk.XML.text("Sometimes it is helpful to get an estimate of the confidence interval of
+ the difference in means. Below you can specify whether one should be shown, and
+ which confidence-level should be applied (95% corresponds to a 5% level of
+ significance)."),
+ rk.XML.copy(conf.frame)))
+ </pre><p>That is it for the <acronym class="acronym">GUI</acronym>. The global document will be combined in the end by <code class="function">rk.plugin.skeleton()</code>.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rkdev_jscode"></a>JavaScript code</h3></div></div></div><p>Until now, using the <span class="application">rkwarddev</span> package might not seem to have helped so much. This is going to change right now.</p><p>First of all, just like we did not have to care about IDs for elements when defining the <acronym class="acronym">GUI</acronym> layout, we do not have to care about JavaScript variable names in the next step. If you want more control, you can write plain JavaScript code and have it pasted to the generated file. But it is probably much more efficient to do it the <span class="application">rkwarddev</span> way.</p><p>Most notably you do not have to define any variable yourself, as <code class="function">rk.plugin.skeleton()</code> can scan your <acronym class="acronym">XML</acronym> code and automatically define all variables you will probably need -- for instance, you would not bother to include a check box if you do not use its value or state afterwards. So we can start writing the actual <span class="application">R</span> code generating JS immediately.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>The function <code class="function">rk.JS.scan()</code> can also scan existing <acronym class="acronym">XML</acronym> files for variables.</p></div><p>The package has some functions for JS code constructs that are commonly used in <span class="application">RKWard</span> plugins, like the <code class="function">echo()</code> function or <code class="function">if() {...} else {...}</code> conditions. There are some differences between JS and <span class="application">R</span>, <abbr class="abbrev">e.g.</abbr>, for <code class="function">paste()</code> in <span class="application">R</span> you use the comma to concatenate character strings, whereas for <code class="function">echo()</code> in JS you use <span class="quote">“<span class="quote">+</span>”</span>, and lines must end with a semicolon. By using the <span class="application">R</span> functions, you can almost forget about these differences and keep writing <span class="application">R</span> code.</p><p>These functions can take different classes of input objects: Either plain text, <span class="application">R</span> objects with <acronym class="acronym">XML</acronym> code like above, or in turn results of some other JS functions of the package. In the end, you will always call <code class="function">rk.paste.JS()</code>, which behaves similar to <code class="function">paste()</code>, but depending on the input objects it will replace them with their <acronym class="acronym">XML</acronym> ID, JavaScript variable name or even complete JavaScript code blocks.</p><p>For the t-test example, we need two JS objects: One to calculate the results, and one to print them in the <code class="function">printout()</code> function:</p><pre class="programlisting">
+JS.calc <- rk.paste.JS(
+ echo("res <- t.test (x=", var.x, ", y=", var.y, ", hypothesis=\"", test.hypothesis, "\""),
+ js(
+ if(check.paired){
+ echo(", paired=TRUE")
+ },
+ if(!check.paired && check.eqvar){
+ echo(", var.equal=TRUE")
+ },
+ if(conf.level != "0.95"){
+ echo(", conf.level=", conf.level)
+ },
+ linebreaks=TRUE
+ ),
+ echo(")\n"),
+ level=2
+)
+
+JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
+ </pre><p>As you can see, <span class="application">rkwarddev</span> also provides an <span class="application">R</span> implementation of the <code class="function">echo()</code> function. It returns exactly one character string with a valid JS version of itself. You might also notice that all of the <span class="application">R</span> 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 <code class="function">id()</code> can be used, which also will return exactly one character string from all the objects it was given (you could say it behaves like <code class="function">paste()</code> with a very specific object substitution).</p><p>The <code class="function">js()</code> function is a wrapper that allows you to use <span class="application">R</span>'s <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>if(){...} else {...}</strong></span></span> conditions like you are used to. They will be translated directly into JS code. It also preserves some operators like <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><</strong></span></span>, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>>=</strong></span></span> or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>||</strong></span></span>, so you can logically compare your <span class="application">R</span> objects without the need for quoting most of the time. Let's have a look at the resulting <span class="quote">“<span class="quote">JS.calc</span>”</span> object, which now contains a character string with this content:</p><pre class="programlisting">
+ echo("res <- t.test (x=" + vrslCompare + ", y=" + vrslAgainst + ", hypothesis=\"" + radUsngtsth + "\"");
+ if(chcPardsmpl) {
+ echo(", paired=TRUE");
+ } else {}
+ if(!chcPardsmpl && chcAssmqlvr) {
+ echo(", var.equal=TRUE");
+ } else {}
+ if(spnCnfdnclv != "0.95") {
+ echo(", conf.level=" + spnCnfdnclv);
+ } else {}
+ echo(")\n");
+ </pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+ Alternatively for <code class="function">if()</code> conditions nested in <code class="function">js()</code>, you can use the <code class="function">ite()</code> function, which behaves similar to <span class="application">R</span>'s <code class="function">ifelse()</code>. However, conditional statements constructed using <code class="function">ite()</code> are usually harder to read and should be replaced by <code class="function">js()</code> whenever possible.
+ </p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rkdev_pluginmap"></a>Plugin map</h3></div></div></div><p>This section is very short: We do not need to write a <code class="literal">.pluginmap</code> at all, as it can be generated automatically by <code class="function">rk.plugin.skeleton()</code>. The menu hierarchy can be specified via the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>pluginmap</code></em></span> option:</p><pre class="programlisting">
+ [...]
+ pluginmap=list(
+ name="Two Variable t-Test",
+ hierarchy=list("analysis", "means", "t-Test"))
+ [...]
+ </pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rkdev_rkh"></a>Help page</h3></div></div></div><p>This section is very short as well: <code class="function">rk.plugin.skeleton()</code> cannot write a whole help page from the information it has. But it can scan the <acronym class="acronym">XML</acronym> document also for elements which probably deserve a help page entry, and automatically create a help page template for our plugin. All we have to do afterwards is to write some lines for each listed section.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>The function <code class="function">rk.rkh.scan()</code> can also scan existing <acronym class="acronym">XML</acronym> files to create a help file skeleton.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rkdev_plugin_generator"></a>Generate the plugin files</h3></div></div></div><p>Now comes the final step, in which we will hand over all generated objects to <code class="function">rk.plugin.skeleton()</code>:</p><pre class="programlisting">
+plugin.dir <- rk.plugin.skeleton("t-Test",
+ xml=list(
+ dialog=full.dialog,
+ wizard=full.wizard),
+ js=list(
+ results.header="Two Variable t-Test",
+ calculate=JS.calc,
+ printout=JS.print),
+ pluginmap=list(
+ name="Two Variable t-Test",
+ hierarchy=list("analysis", "means", "t-Test")),
+ load=TRUE,
+ edit=TRUE,
+ show=TRUE)
+ </pre><p>The files will be created in a temporal directory by default. The last three options are not necessary, but very handy: <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>load=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>TRUE</code></em></span> will automatically add the new plugin to <span class="application">RKWard</span>s configuration (since it is in a temp dir and hence will cease to exist when <span class="application">RKWard</span> is closed, it will automatically be removed again by <span class="application">RKWard</span> during its next start), <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>edit=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>TRUE</code></em></span> will open all created files for editing in <span class="application">RKWard</span> editor tabs, and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>show=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>TRUE</code></em></span> will attempt to directly launch the plugin, so you can examine what it looks like without a click. You might consider adding <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>overwrite=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>TRUE</code></em></span> if you are about to run your script repeatedly (<abbr class="abbrev">e.g.</abbr> after changes to the code), as by default no files will be overwritten.</p><p>The result object <span class="quote">“<span class="quote">plugin.dir</span>”</span> contains the path to the directory in which the plugin was created. This can be useful in combination with the function <code class="function">rk.build.package()</code>, to build an actual <span class="application">R</span> package to share your plugin with others -- <abbr class="abbrev">e.g.</abbr> by sending it to the <span class="application">RKWard</span> development team to be added to our plugin repository.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rkdev_ttest_script"></a>The full script</h3></div></div></div><p>To recapitulate all of the above, here is the full script to create the working t-test example. Adding to the already explained code, it also loads the package if needed, and it uses the <code class="function">local()</code> environment, so all the created objects will not end up in your current workspace (except for <span class="quote">“<span class="quote">plugin.dir</span>”</span>):</p><pre class="programlisting">
+require(rkwarddev)
+
+local({
+ 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)
+ test.hypothesis <- rk.XML.radio("using test hypothesis",
+ options=list(
+ "Two-sided"=c(val="two.sided"),
+ "First is greater"=c(val="greater"),
+ "Second is greater"=c(val="less")
+ )
+ )
+ check.paired <- rk.XML.cbox("Paired sample", value="1", un.value="0")
+ basic.settings <- rk.XML.row(variables, rk.XML.col(var.x, var.y, test.hypothesis, check.paired))
+
+ 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)
+ check.conf <- rk.XML.cbox("print confidence interval", val="1", chk=TRUE)
+ conf.frame <- rk.XML.frame(conf.level, check.conf, rk.XML.stretch(), label="Confidence Interval")
+
+ full.dialog <- rk.XML.dialog(
+ label="Two Variable t-Test",
+ rk.XML.tabbook(tabs=list("Basic settings"=basic.settings, "Options"=list(check.eqvar, conf.frame)))
+ )
+
+ full.wizard <- rk.XML.wizard(
+ label="Two Variable t-Test",
+ rk.XML.page(
+ rk.XML.text("As a first step, select the two variables you want to compare against
+ each other. And specify, which one you theorize to be greater. Select two-sided,
+ if your theory does not tell you, which variable is greater."),
+ rk.XML.copy(basic.settings)),
+ rk.XML.page(
+ rk.XML.text("Below are some advanced options. It is generally safe not to assume the
+ variables have equal variances. An appropriate correction will be applied then.
+ Choosing \"assume equal variances\" may increase test-strength, however."),
+ rk.XML.copy(check.eqvar),
+ rk.XML.text("Sometimes it is helpful to get an estimate of the confidence interval of
+ the difference in means. Below you can specify whether one should be shown, and
+ which confidence-level should be applied (95% corresponds to a 5% level of
+ significance)."),
+ rk.XML.copy(conf.frame)))
+
+ JS.calc <- rk.paste.JS(
+ echo("res <- t.test (x=", var.x, ", y=", var.y, ", hypothesis=\"", test.hypothesis, "\""),
+ js(
+ if(check.paired){
+ echo(", paired=TRUE")
+ },
+ if(!check.paired && check.eqvar){
+ echo(", var.equal=TRUE")
+ },
+ if(conf.level != "0.95"){
+ echo(", conf.level=", conf.level)
+ },
+ linebreaks=TRUE
+ ),
+ echo(")\n"), level=2)
+
+ JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
+
+ plugin.dir <<- rk.plugin.skeleton("t-Test",
+ xml=list(
+ dialog=full.dialog,
+ wizard=full.wizard),
+ js=list(
+ results.header="Two Variable t-Test",
+ calculate=JS.calc,
+ printout=JS.print),
+ pluginmap=list(
+ name="Two Variable t-Test",
+ hierarchy=list("analysis", "means", "t-Test")),
+ load=TRUE,
+ edit=TRUE,
+ show=TRUE,
+ overwrite=TRUE)
+})
+ </pre></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="rkwarddev.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="rkwarddev_rkh.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Plugin development with the <span class="application">rkwarddev</span> package </td><td width="34%" align="center" class="navCenter"><a href="rkwarddev.html">Up</a></td><td width="33%" align="right" class="navRight"> Adding help pages</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/rkwarddev.html b/doc/rkwardplugins/rkwarddev.html
new file mode 100644
index 0000000..790e0d5
--- /dev/null
+++ b/doc/rkwardplugins/rkwarddev.html
@@ -0,0 +1,5 @@
+<html><head><title>Chapter 15. Plugin development with the rkwarddev package</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="building_the_plugin_package.html" title="Building the plugin package"><link rel="next" href="rkdev_example.html" title="Practical example"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Plugin development with the <span class="application">rkwarddev</span> package</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="building_the_plugin_package.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="rkdev_example.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="rkwarddev"></a>Chapter 15. Plugin development with the <span class="application">rkwarddev</span> package</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="rkwarddev.html#rkdev_overview">Overview</a></span></dt><dt><span class="sect1"><a href="rkdev_example.html">Practical example</a></span></dt><dd><dl><dt><span class="sect2"><a href="rkdev_example.html#rkdev_gui"><acronym class="acronym">GUI</acronym> description</a></span></dt><dt><span class="sect2"><a href="rkdev_example.html#rkdev_jscode">JavaScript code</a></span></dt><dt><span class="sect2"><a href="rkdev_example.html#rkdev_pluginmap">Plugin map</a></span></dt><dt><span class="sect2"><a href="rkdev_example.html#rkdev_rkh">Help page</a></span></dt><dt><span class="sect2"><a href="rkdev_example.html#rkdev_plugin_generator">Generate the plugin files</a></span></dt><dt><span class="sect2"><a href="rkdev_example.html#rkdev_ttest_script">The full script</a></span></dt></dl></dd><dt><span class="sect1"><a href="rkwarddev_rkh.html">Adding help pages</a></span></dt><dt><span class="sect1"><a href="rkwarddev_i18n.html">Translating plugins</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rkdev_overview"></a>Overview</h2></div></div></div><p>Writing external plugins involves writing files in three languages (<acronym class="acronym">XML</acronym>, JavaScript and R) and the creation of a standardized hierarchy of directories. To make this a lot easier for willing plugin developers, we are providing the <span class="application">rkwarddev</span> package. It provides a number of simple <span class="application">R</span> functions to create the <acronym class="acronym">XML</acronym> code for all dialog elements like tabbooks, checkboxes, dropdownlists or filebrowsers, as well as functions to create JavaScript code and <span class="application">RKWard</span> help files to start with. The function <code class="function">rk.plugin.skeleton()</code> creates the expected directory tree and all necessary files where they are supposed to be.</p><p>This package is not installed by default, but has to be installed manually from <a class="ulink" href="https://files.kde.org/rkward/R/" target="_top"><span class="application">RKWard</span>'s own repository</a>. You can either do that by using the <acronym class="acronym">GUI</acronym> interface (<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">Settings</span></span> → <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Configure packages</span></span>), or from any running <span class="application">R</span> session:</p><pre class="programlisting">
+ install.packages("rkwarddev", repos="https://files.kde.org/rkward/R")
+ library(rkwarddev)
+ </pre><p><span class="application">rkwarddev</span> depends on another small package called <span class="quote">“<span class="quote">XiMpLe</span>”</span>, which is a very simple <acronym class="acronym">XML</acronym> parser and generator and also present in the same repository.</p><p>The full <a class="ulink" href="https://files.kde.org/rkward/R/pckg/rkwarddev/rkwarddev.pdf" target="_top">documentation in PDF format</a> can also be found there. A more detailed introduction to working with the package can be found in the <a class="ulink" href="https://files.kde.org/rkward/R/pckg/rkwarddev/rkwarddev_vignette.pdf" target="_top">rkwarddev vignette</a>.</p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="building_the_plugin_package.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="rkdev_example.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Building the plugin package </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Practical example</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/rkwarddev_i18n.html b/doc/rkwardplugins/rkwarddev_i18n.html
new file mode 100644
index 0000000..0823fe9
--- /dev/null
+++ b/doc/rkwardplugins/rkwarddev_i18n.html
@@ -0,0 +1,24 @@
+<html><head><title>Translating plugins</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><link rel="prev" href="rkwarddev_rkh.html" title="Adding help pages"><link rel="next" href="reference.html" title="Appendix A. Reference"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Translating plugins</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="rkwarddev_rkh.html">Prev</a></td><td align="center" class="navCenter" width="34%">Plugin development with the <span class="application">rkwarddev</span> package</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="reference.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rkwarddev_i18n"></a>Translating plugins</h2></div></div></div><p>
+ The <span class="application">rkwarddev</span> package is capable of producing external plugins with full i18n support. For instance, all relevant functions generating XML objects offer an optional parameter to specify <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>i18n_context</code></em></span> or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>noi18n_label</code></em></span>:
+ </p><pre class="programlisting">
+varComment <- rk.XML.varselector(id.name="vars", i18n=list(comment="Main variable selector"))
+varContext <- rk.XML.varselector(id.name="vars", i18n=list(context="Main variable selector"))
+cboxNoi18n <- rk.XML.cbox(label="Power", id.name="power", i18n=FALSE)
+ </pre><p>The above examples produce output like this:</p><pre class="programlisting">
+# varComment
+<!-- i18n: Main variable selector -->
+ <varselector id="vars" />
+
+# varContext
+<varselector id="vars" i18n_context="Main variable selector" />
+
+# cboxNoi18n
+<checkbox id="power" noi18n_label="Power" value="true" />
+ </pre><p>
+ There is also support for translatable JS code. In fact, the package tries add <code class="function">i18n()</code> calls by default in places where this is usually helpful. The <code class="function">rk.JS.header()</code> function is a good example:
+ </p><pre class="programlisting">
+jsHeader <- rk.JS.header("Test results")
+ </pre><p>This produces the following JS code:</p><pre class="programlisting">
+new Header(i18n("Test results")).print();
+ </pre><p>But you can also manually mark strings in your JS code as translatable, by using the <code class="function">i18n()</code> function just like you would if you wrote the JS file directly.</p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="rkwarddev_rkh.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="reference.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Adding help pages </td><td width="34%" align="center" class="navCenter"><a href="rkwarddev.html">Up</a></td><td width="33%" align="right" class="navRight"> Reference</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/rkwarddev_rkh.html b/doc/rkwardplugins/rkwarddev_rkh.html
new file mode 100644
index 0000000..87fa77c
--- /dev/null
+++ b/doc/rkwardplugins/rkwarddev_rkh.html
@@ -0,0 +1,22 @@
+<html><head><title>Adding help pages</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><link rel="prev" href="rkdev_example.html" title="Practical example"><link rel="next" href="rkwarddev_i18n.html" title="Translating plugins"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Adding help pages</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="rkdev_example.html">Prev</a></td><td align="center" class="navCenter" width="34%">Plugin development with the <span class="application">rkwarddev</span> package</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="rkwarddev_i18n.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rkwarddev_rkh"></a>Adding help pages</h2></div></div></div><p>
+ If you want to write a help page for your plugin, the most straight forward way to do so is to add the particular instructions directly to the definitions of the <acronym class="acronym">XML</acronym> elements they belong to:
+ </p><pre class="programlisting">
+variables <- rk.XML.varselector(
+ id.name="vars",
+ help="Select the data object you would like to analyse.",
+ component="Data"
+)
+ </pre><p>
+ The text given to the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>help</code></em></span> parameter can then be fetched by <code class="function">rk.rkh.scan()</code> and written to the help page of this plugin component. For this to work technically, however, <code class="function">rk.rkh.scan()</code> must know which <span class="application">R</span> objects belong to one plugin component. This is why you must also provide the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>component</code></em></span> parameter and make sure it is identical for all objects belonging together.
+ </p><p>
+ Since you will usually combine many objects into one dialog and might also like to be able to re-use objects like the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslot></strong></span></span> in multiple components of your plugins, it is possible to globally define a component with the <code class="function">rk.set.comp()</code>. If set, it is assumed that all the following objects used in your script belong to that particular component, until <code class="function">rk.set.comp()</code> is being called again with a different component name. You can then omit the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>component</code></em></span> parameter:
+ </p><pre class="programlisting">
+rk.set.comp("Data")
+variables <- rk.XML.varselector(
+ id.name="vars",
+ help="Select the data object you would like to analyse."
+)
+ </pre><p>
+ To add global sections like <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><summary></strong></span></span> or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><usage></strong></span></span> to the help page, you use functions like <code class="function">rk.rkh.summary()</code> or <code class="function">rk.rkh.usage()</code> accordingly. Their results are then used to set the list elements like <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>summary</code></em></span> or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>usage</code></em></span> in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>rkh</code></em></span> parameter of <code class="function">rk.plugin.component()</code>/<code class="function">rk.plugin.skeleton()</code>.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="rkdev_example.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="rkwarddev_i18n.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Practical example </td><td width="34%" align="center" class="navCenter"><a href="rkwarddev.html">Up</a></td><td width="33%" align="right" class="navRight"> Translating plugins</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/sect_dependencies_example.html b/doc/rkwardplugins/sect_dependencies_example.html
new file mode 100644
index 0000000..173797d
--- /dev/null
+++ b/doc/rkwardplugins/sect_dependencies_example.html
@@ -0,0 +1,32 @@
+<html><head><title>An example</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="chapter_dependencies.html" title="Chapter 11. Handling dependencies and compatibility issues"><link rel="prev" href="sect_dependencies_other_pluginmaps.html" title="Dependencies on other RKWard .pluginmaps"><link rel="next" href="i18n.html" title="Chapter 12. Plugin translations"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>An example</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="sect_dependencies_other_pluginmaps.html">Prev</a></td><td align="center" class="navCenter" width="34%">Handling dependencies and compatibility issues</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="i18n.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_dependencies_example"></a>An example</h2></div></div></div><p>To clarify how dependency definitions can be mixed, here is a combined example:</p><pre class="programlisting">
+<document ...>
+ <dependencies rkward_min_version="0.5.0c">
+ <package
+ name="heisenberg"
+ min_version="0.11-2"
+ repository="http://rforge.r-project.org"
+ />
+ <package
+ name="DreamsOfPi"
+ min_version="0.2"
+ />
+ <pluginmap
+ name="heisenberg_plugins"
+ url="http://eternalwondermaths.example.org/hsb"
+ />
+ <dependencies>
+
+ <require map="heisenberg::heisenberg_plugins"/>
+
+ <components ...>
+ <component id="myplugin" file="reduced_version_of_myplugin.xml" ...>
+ <dependencies rkward_max_version="0.6.0z" />
+ </component>
+ <component id="myplugin" file="fancy_version_of_myplugin.xml" ...>
+ <dependencies rkward_min_version="0.6.1" />
+ </component>
+ ...
+x </components ...>
+</document>
+</pre></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="sect_dependencies_other_pluginmaps.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="i18n.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Dependencies on other <span class="application">RKWard</span> <code class="literal">.pluginmap</code>s </td><td width="34%" align="center" class="navCenter"><a href="chapter_dependencies.html">Up</a></td><td width="33%" align="right" class="navRight"> Plugin translations</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/sect_dependencies_other_pluginmaps.html b/doc/rkwardplugins/sect_dependencies_other_pluginmaps.html
new file mode 100644
index 0000000..9f0d7dc
--- /dev/null
+++ b/doc/rkwardplugins/sect_dependencies_other_pluginmaps.html
@@ -0,0 +1,9 @@
+<html><head><title>Dependencies on other RKWard .pluginmaps</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="chapter_dependencies.html" title="Chapter 11. Handling dependencies and compatibility issues"><link rel="prev" href="sect_dependencies_r_packages.html" title="Dependencies on R packages"><link rel="next" href="sect_dependencies_example.html" title="An example"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Dependencies on other <span class="application">RKWard</span> <code class="literal">.pluginmap</code>s</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="sect_dependencies_r_packages.html">Prev</a></td><td align="center" class="navCenter" width="34%">Handling dependencies and compatibility issues</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="sect_dependencies_example.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_dependencies_other_pluginmaps"></a>Dependencies on other <span class="application">RKWard</span> <code class="literal">.pluginmap</code>s</h2></div></div></div><p>If your plugins depend on plugins defined in another <code class="literal">.pluginmap</code> (that is <span class="emphasis"><em>not</em></span> part of your package) you can define this dependency like this:</p><pre class="programlisting">
+ <dependencies>
+ <pluginmap
+ name="heisenberg_plugins"
+ url="http://eternalwondermaths.example.org/hsb"
+ />
+ </dependencies>
+</pre><p>Currently will neither load, nor install, nor even warn about missing <code class="literal">.pluginmap</code>s, but at least information on dependencies (and where to obtain them) will be shown on the plugin's help page. You do not have to (and you should not) declare dependencies on <code class="literal">.pluginmap</code>s that are shipped with the official <span class="application">RKWard</span> distribution, or on <code class="literal">.pluginmap</code>s that are inside your own package. Further, if a required <code class="literal">.pluginmap</code> is <a class="link" href="external_plugins.html" title="Chapter 14. Share your work with others">distributed as an <span class="application">R</span> package</a>, declare a dependency of the package (as shown in the previous section), rather than on the map.</p><p>To make sure that required <code class="literal">.pluginmap</code>s are actually loaded, use the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><require></strong></span></span>-tag (refer to the <a class="link" href="pluginmapelements.html" title="Elements for use in .pluginmap files">reference</a> for details).</p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="sect_dependencies_r_packages.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="sect_dependencies_example.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Dependencies on <span class="application">R</span> packages </td><td width="34%" align="center" class="navCenter"><a href="chapter_dependencies.html">Up</a></td><td width="33%" align="right" class="navRight"> An example</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/sect_dependencies_r_packages.html b/doc/rkwardplugins/sect_dependencies_r_packages.html
new file mode 100644
index 0000000..17bc2a5
--- /dev/null
+++ b/doc/rkwardplugins/sect_dependencies_r_packages.html
@@ -0,0 +1,10 @@
+<html><head><title>Dependencies on R packages</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="chapter_dependencies.html" title="Chapter 11. Handling dependencies and compatibility issues"><link rel="prev" href="sect_dependencies_r_version.html" title="R version compatibility"><link rel="next" href="sect_dependencies_other_pluginmaps.html" title="Dependencies on other RKWard .pluginmaps"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Dependencies on <span class="application">R</span> packages</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="sect_dependencies_r_version.html">Prev</a></td><td align="center" class="navCenter" width="34%">Handling dependencies and compatibility issues</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="sect_dependencies_other_pluginmaps.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_dependencies_r_packages"></a>Dependencies on <span class="application">R</span> packages</h2></div></div></div><p>Dependencies on specific <span class="application">R</span> packages can be defined, but as of <span class="application">RKWard</span> 0.6.1, these dependencies are neither checked, nor installed / loaded, automatically. They are shown in the plugin help files, however. Here is an example definition:</p><pre class="programlisting">
+ <dependencies>
+ <package
+ name="heisenberg"
+ min_version="0.11-2"
+ repository="http://rforge.r-project.org"
+ />
+ </dependencies>
+</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Always make sure to add appropriate <code class="function">require()</code> calls, if you plugin needs certain packages to be loaded.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If you <a class="link" href="external_plugins.html" title="Chapter 14. Share your work with others">distribute your <code class="literal">.pluginmap</code> as an <span class="application">R</span> package</a>, and all plugins depend on a particular package, then you should define that dependency on the <span class="application">R</span> package level. Defining dependencies to <span class="application">R</span> packages on the level of the <span class="application">RKWard</span> <code class="literal">.pluginmap</code> is most useful, if only some of your plugins need the dependency, the dependency is not available from CRAN, or your <code class="literal">.pluginmap</code> is not distributed as an <span class="application">R</span> package.</p></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="sect_dependencies_r_version.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="sect_dependencies_other_pluginmaps.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft"><span class="application">R</span> version compatibility </td><td width="34%" align="center" class="navCenter"><a href="chapter_dependencies.html">Up</a></td><td width="33%" align="right" class="navRight"> Dependencies on other <span class="application">RKWard</span> <code class="literal">.pluginmap</code>s</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/sect_dependencies_r_version.html b/doc/rkwardplugins/sect_dependencies_r_version.html
new file mode 100644
index 0000000..5a136a0
--- /dev/null
+++ b/doc/rkwardplugins/sect_dependencies_r_version.html
@@ -0,0 +1,16 @@
+<html><head><title>R version compatibility</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="chapter_dependencies.html" title="Chapter 11. Handling dependencies and compatibility issues"><link rel="prev" href="chapter_dependencies.html" title="Chapter 11. Handling dependencies and compatibility issues"><link rel="next" href="sect_dependencies_r_packages.html" title="Dependencies on R packages"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1><span class="application">R</span> version compatibility</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="chapter_dependencies.html">Prev</a></td><td align="center" class="navCenter" width="34%">Handling dependencies and compatibility issues</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="sect_dependencies_r_packages.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect_dependencies_r_version"></a><span class="application">R</span> version compatibility</h2></div></div></div><p>Similar to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>rkward_min_version</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>rkward_max_version</code></em></span>, the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dependencies></strong></span></span> element allows specification of the attributes <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>R_min_version</code></em></span> and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>R_max_version</code></em></span>. However, there are the following differences:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Plugins which fail to meet the <span class="application">R</span> version requirement are <span class="emphasis"><em>not</em></span> currently skipped when reading a <code class="literal">.pluginmap</code> file. The user can still call the plugin, and will not see any immediate warning (in future versions, a warning message will probably be shown)</p></li><li class="listitem"><p>In consequence it is also <span class="emphasis"><em>not</em></span> possible to define alternative versions of a plugin depending on the running version of <span class="application">R</span>.</p></li><li class="listitem"><p>However, it is often easy to achieve backwards compatibility as shown below. If you are aware of <span class="application">R</span> compatibility issues, please consider using this method, instead of defining a dependency on a particular version of <span class="application">R</span>.</p></li></ul></div><p>In many cases, it is easily possible to provide reduced functionality, if a certain feature is not available in the running version of <span class="application">R</span>. Consider the following short example of a plugin <code class="literal">.xml</code> file:</p><pre class="programlisting">
+<dialog [...]>
+ <logic>
+ <dependency_check id="ris210" R_min_version="2.10.0"/>
+ <connect client="compression.xz.enabled" governor="ris210"/>
+ </logic>
+ [...]
+ <radio id="compression" label="Compression method">
+ <option label="None" value="">
+ <option label="gzip" value="gzip">
+ <option id="xz" label="xz" value="xz">
+ </radio>
+ [...]
+</dialog>
+ </pre><p>In this example the compression option "xz" will simply be disabled when the <span class="application">R</span> runtime version is older than 2.10.0 (which did not support xz compression). The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dependency_check></strong></span></span> element supports the same attributes as the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dependencies></strong></span></span> element in <code class="literal">.pluginmap</code> files. It creates a boolean property, which is true, if the specified dependencies are met, false otherwise.</p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="chapter_dependencies.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="sect_dependencies_r_packages.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Handling dependencies and compatibility issues </td><td width="34%" align="center" class="navCenter"><a href="chapter_dependencies.html">Up</a></td><td width="33%" align="right" class="navRight"> Dependencies on <span class="application">R</span> packages</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/snippets.html b/doc/rkwardplugins/snippets.html
new file mode 100644
index 0000000..41c17be
--- /dev/null
+++ b/doc/rkwardplugins/snippets.html
@@ -0,0 +1,90 @@
+<html><head><title>Using <snippets></title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="plugin_series.html" title="Chapter 9. Dealing with many similar plugins"><link rel="prev" href="include_xml.html" title="Including .xml files"><link rel="next" href="include_snippets_vs_embedding.html" title="<include> and <snippets> vs. <embed>"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Using <snippets></h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="include_xml.html">Prev</a></td><td align="center" class="navCenter" width="34%">Dealing with many similar plugins</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="include_snippets_vs_embedding.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="snippets"></a>Using <snippets></h2></div></div></div><p>
+ While including files as shown in the <a class="link" href="include_xml.html" title="Including .xml files">previous section</a> is fairly powerful, it become most useful when used in combination with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><snippets></strong></span></span>. Snippets are really smaller sections which you can insert at another point in the file. An example illustrates this best:
+ </p><pre class="programlisting">
+<document>
+ <snippets>
+ <snippet id="note">
+ <frame>
+ <text>
+ This will be inserted at two places in the GUI
+ </text>
+ </frame>
+ </snippet>
+ </snippets>
+ <dialog label="test">
+ <column>
+ <insert snippet="note"/>
+ [...]
+ <insert snippet="note"/>
+ </column>
+ </dialog>
+</document>
+ </pre><p>
+ Hence, you define the snippet at one place at the top of the <acronym class="acronym">XML</acronym> file, and then you <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><insert></strong></span></span> it at any place(s) you wish.
+ </p><p>
+ While this example is not too useful in itself, think about combining this with an <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><include></strong></span></span>d <code class="literal">.xml</code> file. Note that you can also place snippets for the <code class="literal">.rkh</code> file in the same file. You would simply <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><include></strong></span></span> the file there as well, and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><insert></strong></span></span> the relevant snippet:
+ </p><pre class="programlisting">
+<!-- This is a file called "common_snippets.xml" -->
+<document>
+ <snippet id="common_options">
+ <spinbox id="something" [...]/>
+ [...]
+ </snippet>
+ <snippet id="common_note">
+ <text>An important note for this type of plugin</text>
+ </snippet>
+
+ <snippet id="common_help">
+ <setting id="something">This does something</setting>
+ [...]
+ </snippet>
+</document>
+ </pre><pre class="programlisting">
+<!-- This is the .xml file of the plugin -->
+<document>
+ <snippets>
+ <!-- Import the common snippets -->
+ <include file="common_snippets.xml"/>
+ </snippets>
+
+ <dialog label="test2">
+ <insert snippet="common_note"/>
+ <spinbox id="something_plugin_specific" [...] />
+ <insert snippet="common_options"/>
+ </dialog>
+</document>
+ </pre><p>
+ Similar to <a class="link" href="include_js.html" title="Using the JS include statement">inclusion in JS</a>, the reverse approach is often even more useful:
+ </p><pre class="programlisting">
+<!-- This is a file called "common_layout.xml" -->
+<document>
+ <column>
+ <insert snippet="note">
+ [...]
+ <insert snippet="plugin_parameters">
+ </column>
+ [...]
+</document>
+ </pre><pre class="programlisting">
+<!-- This is the .xml file of the plugin -->
+<document>
+ <snippets>
+ <snippet id="note">
+ <text>The note used for this specific plugin</text>
+ </snippet>
+
+ <snippet id="plugin_parameters">
+ <frame label="Parameters specific to this plugin">
+ [...]
+ </frame>
+ </snippet>
+ </snippets>
+
+ <dialog label="test3">
+ <include file="common_layout.xml"/>
+ </dialog>
+</document>
+ </pre><p>
+ Finally, it is also possible to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><insert></strong></span></span> snippets into other snippets, provided that: a) there is only one level of nesting, and b) the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><snippets></strong></span></span> section is placed at the top of the file (before a nested snippet is inserted); this is because <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><insert></strong></span></span> statements are resolved from top to bottom.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="include_xml.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="include_snippets_vs_embedding.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Including <code class="literal">.xml</code> files </td><td width="34%" align="center" class="navCenter"><a href="plugin_series.html">Up</a></td><td width="33%" align="right" class="navRight"> <include> and <snippets> vs. <embed></td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/specialized_plugins.html b/doc/rkwardplugins/specialized_plugins.html
new file mode 100644
index 0000000..8d61476
--- /dev/null
+++ b/doc/rkwardplugins/specialized_plugins.html
@@ -0,0 +1,101 @@
+<html><head><title>Chapter 10. Concepts for use in specialized plugins</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="include_snippets_vs_embedding.html" title="<include> and <snippets> vs. <embed>"><link rel="next" href="ch10s02.html" title="Previews for data, output and other results"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Concepts for use in specialized plugins</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="include_snippets_vs_embedding.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="ch10s02.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="specialized_plugins"></a>Chapter 10. Concepts for use in specialized plugins</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="specialized_plugins.html#specialized_plugins_plots">Plugins that produce a plot</a></span></dt><dd><dl><dt><span class="sect2"><a href="specialized_plugins.html#rk_graph_on">Drawing a plot to the output window</a></span></dt><dt><span class="sect2"><a href="specialized_plugins.html#preview_plots">Adding preview functionality</a></span></dt><dt><span class="sect2"><a href="specialized_plugins.html#plot_options">Generic plot options</a></span></dt><dt><span class="sect2"><a href="specialized_plugins.html#plot_plugin_example">A canonical example</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch10s02.html">Previews for data, output and other results</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch10s02.html#preview_output">Previews of (HTML) output</a></span></dt><dt><span class="sect2"><a href="ch10s02.html#preview_data">Previews of (imported) data</a></span></dt><dt><span class="sect2"><a href="ch10s02.html#preview_custom">Custom previews</a></span></dt></dl></dd><dt><span class="sect1"><a href="contextualized_plugins.html">Context-dependent plugins</a></span></dt><dd><dl><dt><span class="sect2"><a href="contextualized_plugins.html#context_x11">X11 device context</a></span></dt><dt><span class="sect2"><a href="contextualized_plugins.html#context_import">Import data context</a></span></dt></dl></dd><dt><span class="sect1"><a href="querying_r_for_info.html">Querying <span class="application">R</span> for information</a></span></dt><dt><span class="sect1"><a href="current_object.html">Referencing the current object or current file</a></span></dt><dt><span class="sect1"><a href="optionset.html">Repeating (a set of) options</a></span></dt><dd><dl><dt><span class="sect2"><a href="optionset.html#optionset_driven">"Driven" optionsets</a></span></dt><dt><span class="sect2"><a href="optionset.html#optionset_alternatives">Alternatives: When not to use optionsets</a></span></dt></dl></dd></dl></div><p>
+This chapter contains information on some topics that are useful only to certain classes of plugins.
+</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="specialized_plugins_plots"></a>Plugins that produce a plot</h2></div></div></div><p>
+ Creating a plot from a plugin is easy to do. However, there are a few subtle gotchas to avoid, and also some great generic functionality that you should be aware of. This section shows you the basic concepts, and concludes with a canonical example that you should follow whenever creating plot plugins.
+ </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rk_graph_on"></a>Drawing a plot to the output window</h3></div></div></div><p>
+ In order to draw a plot to the output window, use <code class="function">rk.graph.on()</code> directly before creating the plot, and
+ <code class="function">rk.graph.off()</code>, directly afterwards. This is similar to <abbr class="abbrev">e.g.</abbr> calling <code class="function">postscript()</code> and
+ <code class="function">dev.off()</code> in a regular <span class="application">R</span> session.
+ </p><p>
+ Importantly, however, you must <span class="emphasis"><em>always</em></span> call <code class="function">rk.graph.off()</code> after calling <code class="function">rk.graph.on()</code>. Otherwise the output file will be left in a broken state. To ensure <code class="function">rk.graph.off()</code> really gets called, you should wrap <span class="emphasis"><em>all</em></span> <span class="application">R</span> commands between the two calls in
+ <code class="function">try()</code> statement. Never heard of that? Do not worry, it is easy. All you need to do is follow the pattern shown in
+ <a class="link" href="specialized_plugins.html#plot_plugin_example" title="A canonical example">example</a>, below.
+ </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="preview_plots"></a>Adding preview functionality</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This section discusses adding preview functionality to plugins producing plots. There are separate sections on <a class="link" href="ch10s02.html#preview_output" title="Previews of (HTML) output">previews of (<acronym class="acronym">HTML</acronym>) output</a>, <a class="link" href="ch10s02.html#preview_data" title="Previews of (imported) data">previews of (imported) data</a>, and <a class="link" href="ch10s02.html#preview_custom" title="Custom previews">custom previews</a>. However, it is recommended that you read this section first, as the approach is similar in each case.</p></div><p>
+ A very useful feature for all plugins generating a plot/graph is to provide an automatically updating preview. To do so, you will need two things: Adding a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><preview></strong></span></span> check box to your <a class="link" href="mainxml.html" title="Chapter 4. Defining the GUI"><acronym class="acronym">GUI</acronym> definition</a>, and adjusting the <a class="link" href="jstemplate.html" title="Chapter 5. Generating R code from GUI settings">generated code</a> for the preview.
+ </p><p>
+ Adding a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><preview></strong></span></span> check box is simple. Just place the following somewhere in your <acronym class="acronym">GUI</acronym>. It will take care of all the behind-the-scenes magic of creating a preview device, updating the preview whenever the setting have changed, <abbr class="abbrev">etc.</abbr> Example:
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Starting with version 0.6.5 of <span class="application">RKWard</span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><preview></strong></span></span> preview elements are special-cased in plugin dialogs (not wizards): They will be placed in the button-column, irrespective of where exactly they are defined in the UI. It is still a good idea to define them at a sensible place in the layout, for backwards compatibility.
+ </p></div><pre class="programlisting">
+ <document>
+ [...]
+ <dialog [...]>
+ [...]
+ <preview id="preview"/>
+ [...]
+ </dialog>
+ [...]
+ </document>
+ </pre><p>
+ And that is it for the <acronym class="acronym">GUI</acronym> definition.
+ </p><p>
+ Adjusting the JS template is a little more work. You will have to create a new function called <code class="function">preview()</code> in addition to the <code class="function">preprocess()</code>, <code class="function">calculate()</code>, <abbr class="abbrev">etc.</abbr> functions. This function should generate the code needed to produce the plot, and only that. Esp. no printing of headers, <code class="function">rk.graphics.on()</code>, or similar calls. See the <a class="link" href="specialized_plugins.html#plot_plugin_example" title="A canonical example">example</a>, below for the typical pattern that you will use.
+ </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="plot_options"></a>Generic plot options</h3></div></div></div><p>
+ You will have noticed that most plotting plugins in <span class="application">RKWard</span> provide a wide range of generic options <abbr class="abbrev">e.g.</abbr> for customizing axis titles or figure margins. Adding these options to your plugin is easy. They are provided by an <a class="link" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins">embeddable</a> plugin called <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rkward::plot_options</strong></span></span>. Embed this in your plugin UI like this:
+ </p><pre class="programlisting">
+ <document>
+ [...]
+ <logic [...]>
+ <connect client="plotoptions.xvar" governor="x.available"/>
+ <set id="plotoptions.allow_type" to="true"/>
+ <set id="plotoptions.allow_ylim" to="true"/>
+ <set id="plotoptions.allow_xlim" to="false"/>
+ <set id="plotoptions.allow_log" to="false"/>
+ <set id="plotoptions.allow_grid" to="true"/>
+ </logic>
+ <dialog [...]>
+ [...]
+ <embed id="plotoptions" component="rkward::plot_options" as_button="true" label="Plot Options"/>
+ [...]
+ </dialog>
+ [...]
+ </document>
+ </pre><p>
+ This will add a button to your UI to bring up a window with plot options. The logic section is just an example. It allows you some control over the plot options plugin. Read more in the plot_options plugin's help page (linked from the help page of any plugin providing the generic options).
+ </p><p>
+ Next you need to make sure that the code corresponding to your plot options is added to the generated code for your plot. To do so,
+ fetch the properties <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>code.preprocess</strong></span></span>, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>code.printout</strong></span></span>, and <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>code.calculate</strong></span></span> from the embedded plot options plugin, and insert them into your code as shown in the <a class="link" href="specialized_plugins.html#plot_plugin_example" title="A canonical example">example</a>, below.
+ </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="plot_plugin_example"></a>A canonical example</h3></div></div></div><p>
+ Here is an example .JS file that you should use as a template, whenever you create a plotting plugin:
+ </p><pre class="programlisting">
+ function preprocess () {
+ // the "somepackage" is needed to create the plot
+ echo ("require (somepackage)\n");
+ }
+
+ function preview () {
+ // we call all stages of the general code. Only the printout () function needs to be called slightly different for the plot preview
+ preprocess ();
+ // calculate (); // in this example, the plugin has no calculate () function.
+ printout (true); // in this case, 'true' means: Create the plot, but not any headers or other output.
+ }
+
+ function printout (is_preview) {
+ // If "is_preview" is set to false, it generates the full code, including headers.
+ // If "is_preview" is set to true, only the essentials will be generated.
+
+ if (!is_preview) {
+ echo ('rk.header (' + i18n ("An example plot") + ')\n\n');
+ echo ('rk.graph.on ()\n');
+ }
+ // only the following section will be generated for is_preview==true
+
+ // remember: everything between rk.graph.on() and rk.graph.off() should be wrapped inside a try() statement:
+ echo ('try ({\n');
+ // insert any option-setting code that should be run before the actual plotting commands.
+ // The code itself is provided by the embedded plot options plugin. printIndentedUnlessEmpty() takes care of pretty formatting.
+ printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.preprocess"), '', '\n');
+
+ // create the actual plot. plotoptions.code.printout provides the part of the generic plot options
+ // that have to be added to the plotting call, itself.
+ echo ('plot (5, 5' + getString ("plotoptions.code.printout") + ')\n');
+
+ // insert any option-setting code that should be run after the actual plot.
+ printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.calculate"), '\n');
+ echo ('})'\n); // the closure of the try() statement
+
+ if (!is_preview) {
+ echo ('rk.graph.off ()\n');
+ }
+ }
+ </pre></div></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="include_snippets_vs_embedding.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="ch10s02.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft"><include> and <snippets> vs. <embed> </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Previews for data, output and other results</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/standard_embeddable_plugins.html b/doc/rkwardplugins/standard_embeddable_plugins.html
new file mode 100644
index 0000000..b86d010
--- /dev/null
+++ b/doc/rkwardplugins/standard_embeddable_plugins.html
@@ -0,0 +1,4 @@
+<html><head><title>Embeddable plugins shipped with the official RKWard release</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="reference.html" title="Appendix A. Reference"><link rel="prev" href="elementproperties.html" title="Properties of plugin elements"><link rel="next" href="pluginmapelements.html" title="Elements for use in .pluginmap files"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Embeddable plugins shipped with the official <span class="application">RKWard</span> release</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="elementproperties.html">Prev</a></td><td align="center" class="navCenter" width="34%">Reference</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="pluginmapelements.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="standard_embeddable_plugins"></a>Embeddable plugins shipped with the official <span class="application">RKWard</span> release</h2></div></div></div><p>A number of embeddable plugins is shipped with <span class="application">RKWard</span>, and can be used in your own plugins. Detailed documentation is currently available
+ only in these plugins source or help files. However, here is a list to give you a quick overview of what is available:</p><div class="table"><a name="idm3422"></a><p class="title"><b>Table A.1. Standard embeddable plugins</b></p><div class="table-contents"><table class="table" summary="Standard embeddable plugins" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>ID</th><th>Pluginmap</th><th>Description</th><th>Example usage</th></tr></thead><tbody><tr><td>rkward::plot_options</td><td>embedded.pluginmap</td><td>Provides a wide range of options for plots. Most plotting plugins utilize this.</td><td>Plots->Barplot, most other plotting plugins</td></tr><tr><td>rkward::color_chooser</td><td>embedded.pluginmap</td><td>Very simple plugin for specifying a color. Current implementation provides a list of color names. Future implementations may provide
+ more elaborate color picking.</td><td>Plots->Histogram</td></tr><tr><td>rkward::plot_stepfun_options</td><td>embedded.pluginmap</td><td>Step function plot options</td><td>Plots->ECDF plot</td></tr><tr><td>rkward::histogram_options</td><td>embedded.pluginmap</td><td>Histogram (plot) options</td><td>Plots->Histogram</td></tr><tr><td>rkward::barplot_embed</td><td>embedded.pluginmap</td><td>Barplot options</td><td>Plots->Barplot</td></tr><tr><td>rkward::one_var_tabulation</td><td>embedded.pluginmap</td><td>Provides tabulation on a single variable.</td><td>Plots->Barplot</td></tr><tr><td>rkward::limit_vector_length</td><td>embedded.pluginmap</td><td>Limit the length of a vector (to the n largest or smallest elements).</td><td>Plots->Barplot</td></tr><tr><td>rkward::level_select</td><td>embedded.pluginmap</td><td>Provides a <valueselector> filled with the levels (or unique values) of a vector.</td><td>Data->Recode Categorical data</td></tr><tr><td>rkward::multi_input</td><td>embedded.pluginmap</td><td>Combines spinbox, input and radio controls to provide input for character, numeric, logical data.</td><td>Data->Recode Categorical data</td></tr></tbody></table></div></div><br class="table-break"></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="elementproperties.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="pluginmapelements.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Properties of plugin elements </td><td width="34%" align="center" class="navCenter"><a href="reference.html">Up</a></td><td width="33%" align="right" class="navRight"> Elements for use in <code class="literal">.pluginmap</code> files</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/structure_of_a_plugin_package.html b/doc/rkwardplugins/structure_of_a_plugin_package.html
new file mode 100644
index 0000000..5fdeef1
--- /dev/null
+++ b/doc/rkwardplugins/structure_of_a_plugin_package.html
@@ -0,0 +1,68 @@
+<html><head><title>Structure of a plugin package</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="external_plugins.html" title="Chapter 14. Share your work with others"><link rel="prev" href="why_external_plugins.html" title="Why external plugins?"><link rel="next" href="building_the_plugin_package.html" title="Building the plugin package"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Structure of a plugin package</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="why_external_plugins.html">Prev</a></td><td align="center" class="navCenter" width="34%">Share your work with others</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="building_the_plugin_package.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="structure_of_a_plugin_package"></a>Structure of a plugin package</h2></div></div></div><p>For external plugins to install and work properly, they must follow some structural guidelines regarding their file hierarchy. </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="file_hierarchy"></a>File hierarchy</h3></div></div></div><p>
+ Let's have a look at the prototypic file hierarchy of an elaborate plugin archive. You don’t have to include all of these directories and/or files for a plugin to work (read on to learn what’s absolutely necessary), consider this a <span class="quote">“<span class="quote">best practice</span>”</span> example:
+ </p><pre class="programlisting">
+ plugin_name/
+ inst/
+ rkward/
+ plugins/
+ plugin_name.xml
+ plugin_name.js
+ plugin_name.rkh
+ ...
+ po/
+ ll/
+ LC_MESSAGES/
+ rkward__plugin_name_rkward.mo
+ rkward__plugin_name_rkward.ll.po
+ rkward__plugin_name_rkward.pot
+ tests/
+ testsuite_name/
+ RKTestStandards.sometest_name.rkcommands.R
+ RKTestStandards.sometest_name.rkout
+ ...
+ testsuite.R
+ plugin_name.pluginmap
+ ...
+ ChangeLog
+ README
+ AUTHORS
+ LICENSE
+ DESCRIPTION
+ </pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+ In this example, all occasions of <span class="token">plugin_name</span>, <span class="token">testsuite_name</span> and <span class="token">sometest_name</span> are to be replaced with their correct names, accordingly. Also, <span class="token">ll</span> is a placeholder for a language abbreviation (<abbr class="abbrev">e.g.</abbr>, <span class="quote">“<span class="quote">de</span>”</span>, <span class="quote">“<span class="quote">en</span>”</span> or <span class="quote">“<span class="quote">es</span>”</span>).
+ </p></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+ You do not have to create this file hierarchy by hand. If you use the function <code class="function">rk.plugin.skeleton()</code> from the <a class="link" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><span class="application">rkwarddev</span> package</a>, it will automatically create all necessary files and directories for you, except the <code class="filename">po</code> directory which is created and managed by the <a class="link" href="i18n_workflow.html" title="Translation maintainance">translation script</a>.
+ </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="basic_plugin_components"></a>Basic plugin components</h4></div></div></div><p>
+ It is mandatory to include at least three files: a <a class="link" href="pluginmap.html" title="Chapter 3. Creating menu entries"><code class="literal">.pluginmap</code></a>, a plugin <a class="link" href="mainxml.html" title="Chapter 4. Defining the GUI">.xml</a> description and a plugin <a class="link" href="jstemplate.html" title="Chapter 5. Generating R code from GUI settings">.js</a> 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 <a class="link" href="pluginmap.html" title="Chapter 3. Creating menu entries"><code class="literal">.pluginmap</code></a>, respectively. It is also possible to even include several <code class="literal">.pluginmap</code> files, if it fits your needs, but you should include them all in <span class="quote">“<span class="quote">plugin_name.pluginmap</span>”</span> then.
+ </p><p>
+ Each <span class="application">R</span> package must have a valid <code class="filename">DESCRIPTION</code> file, which is also crucial for <span class="application">RKWard</span> recognizing it as a plugin provider. Most of the information it carries is also needed in the plugin <a class="link" href="chapter_about_information.html" title="Chapter 13. Author, license and version information">Meta-information</a> and possibly <a class="link" href="chapter_dependencies.html" title="Chapter 11. Handling dependencies and compatibility issues">dependencies</a>, but in a different format (the <span class="application">R</span> documentation explains <a class="ulink" href="http://cran.r-project.org/doc/manuals/R-exts.html#The-DESCRIPTION-file" target="_top">the <code class="filename">DESCRIPTION</code> file in detail</a>).
+ </p><p>
+ In addition to the general contents of a <code class="filename">DESCRIPTION</code> file, make sure to also include the line <span class="quote">“<span class="quote">Enhances: rkward</span>”</span>. This will cause <span class="application">RKWard</span> to automatically scan the package for plugins if it is installed. An example <code class="filename">DESCRIPTION</code> file looks like this:
+ </p><pre class="programlisting">
+ Package: SquaretheCircle
+ Type: Package
+ Title: Square the circle
+ Version: 0.1-3
+ Date: 2011-09-19
+ Author: E.A. Dölle <doelle at eternalwondermaths.example.org>
+ Maintainer: A. Assistant <alterego at eternalwondermaths.example.org>
+ Enhances: rkward
+ Description: Squares the circle using Heisenberg compensation.
+ License: GPL
+ LazyLoad: yes
+ URL: http://eternalwondermaths.example.org/23/stc.html
+ Authors at R: c(person(given="E.A.", family="Dölle", role="aut",
+ email="doelle at eternalwondermaths.example.org"),
+ person(given="A.", family="Assistant", role=c("cre",
+ "ctb"), email="alterego at eternalwondermaths.example.org"))
+ </pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+ You do not have to write this file by hand. If you use the function <code class="function">rk.plugin.skeleton()</code> from the <a class="link" href="rkwarddev.html" title="Chapter 15. Plugin development with the rkwarddev package"><span class="application">rkwarddev</span> package</a> and provide all necessary information via the <span class="quote">“<span class="quote">about</span>”</span> option, it will automatically create a working <code class="filename">DESCRIPTION</code> file for you.
+ </p></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="additional_information"></a>Additional information (optional)</h4></div></div></div><p>
+ <code class="filename">ChangeLog</code>, <code class="filename">README</code>, <code class="filename">AUTHORS</code>, <code class="filename">LICENSE</code> should be self-explaining and are entirely optional. Actually, they won’t be interpreted by <span class="application">RKWard</span>, so they are rather meant to carry additional information that might be relevant <abbr class="abbrev">e.g.</abbr> for distributors. Most of their relevant content (author credits, licence terms <abbr class="abbrev">etc.</abbr>) will be included in the actual plugin files anyway, though (see the <a class="link" href="chapter_about_information.html" title="Chapter 13. Author, license and version information">section on meta-information</a>). 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.
+ </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="automated_plugin_testing"></a>Automated plugin testing (optional)</h4></div></div></div><p>
+ Another optional directory is "tests", which is meant to provide files needed for <a class="ulink" href="http://sourceforge.net/apps/mediawiki/rkward/index.php?title=Automated_Plugin_Testing" target="_top">automated plugin testing</a>. These tests are helpful to quickly check if your plugins still work with new versions of <span class="application">R</span> or <span class="application">RKWard</span>. 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 <code class="filename">tests</code>, which includes a file <code class="filename">testsuite.R</code> 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 <code class="filename">testsuite.R</code> file, you can split them in <abbr class="abbrev">e.g.</abbr> one file for each test suite and create one <code class="filename">testsuite.R</code> with <code class="function">source()</code> calls for each suite file. In either case, create separate subdirectories with test
+standards for each defined suite.
+ </p><p>
+ The benefits of upholding to this structure is that plugin tests can be run simply by calling <code class="function">rktests.makplugintests()</code> from the <a class="ulink" href="rkward://rhelp/rkwardtests" target="_top">rkwardtests</a> package without additional arguments. Have a look at the online documentation on <a class="ulink" href="http://sourceforge.net/apps/mediawiki/rkward/index.php?title=Automated_Plugin_Testing" target="_top">Automated Plugin Testing</a> for further details.
+ </p></div></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="why_external_plugins.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="building_the_plugin_package.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Why external plugins? </td><td width="34%" align="center" class="navCenter"><a href="external_plugins.html">Up</a></td><td width="33%" align="right" class="navRight"> Building the plugin package</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/troubleshooting.html b/doc/rkwardplugins/troubleshooting.html
new file mode 100644
index 0000000..c23ce6c
--- /dev/null
+++ b/doc/rkwardplugins/troubleshooting.html
@@ -0,0 +1,10 @@
+<html><head><title>Appendix B. Troubleshooting during plugin development</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="guilogic_functions.html" title="Functions available for GUI logic scripting"><link rel="next" href="license.html" title="Appendix C. License"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Troubleshooting during plugin development</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="guilogic_functions.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="license.html">Next</a></td></tr></tbody></table><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a name="troubleshooting"></a>Appendix B. Troubleshooting during plugin development</h1></div></div></div><p>
+ So you have read all the documentation, did everything right, and still cannot get it to work? Do not worry, we will work it out. First thing to do is: Activate <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guilabel"><span class="application">RKWard</span> Debug Messages</span></span> - window (available from the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">Windows</span></span> - menu, or right click on one of the tool bars), and then start your plugin, again. As a general rule of thumb, you should not see any output in the messages window when your plugin gets invoked, or at any other time. If there is one, it is likely related to your plugin. See if it helps you.
+</p><p>
+ If everything seems fine on the console, try to increase the debug-level (from the command line, using <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong>rkward --debug-level 3</strong></span></span>, or by setting debug level to 3 in <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">Settings</span></span> → <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Configure <span class="application">RKWard</span></span></span> → <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Debug</span></span>). Not all messages shown at higher debug levels necessarily indicate a problem, but chance are, your problem shows up somewhere between the messages.
+</p><p>
+If you still cannot find out what is wrong, do not despair. We know this is complicated stuff, and - after all - possibly you have also come across a bug in <span class="application">RKWard</span>, and <span class="application">RKWard</span> needs to be fixed. Just write to the development mailing list, and tell us about the problem. We will be happy to help you.
+</p><p>
+Finally, even if you found out how to do it on your own, but found the documentation to be not-so-helpful or even wrong in some respects, please tell us on the mailing list as well, so we can fix/improve the documentation.
+</p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="guilogic_functions.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="license.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Functions available for <acronym class="acronym">GUI</acronym> logic scripting </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> License</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/whatareplugins.html b/doc/rkwardplugins/whatareplugins.html
new file mode 100644
index 0000000..ae5b59b
--- /dev/null
+++ b/doc/rkwardplugins/whatareplugins.html
@@ -0,0 +1,10 @@
+<html><head><title>Chapter 2. Preliminaries: What are plugins in RKWard? How do they work?</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="prev" href="introduction.html" title="Chapter 1. Introduction"><link rel="next" href="pluginmap.html" title="Chapter 3. Creating menu entries"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Preliminaries: What are plugins in <span class="application">RKWard</span>? How do they work?</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="introduction.html">Prev</a></td><td align="center" class="navCenter" width="34%"> </td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="pluginmap.html">Next</a></td></tr></tbody></table><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="whatareplugins"></a>Chapter 2. Preliminaries: What are plugins in <span class="application">RKWard</span>? How do they work?</h1></div></div></div><p>
+ Of course the first question you might have is: what portions of <span class="application">RKWard</span> functionality is realized using plugins? Or: what can plugins do?
+ </p><p>
+ One way to answer this is: deselect all <code class="literal">.pluginmap</code> files under <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenu">Settings</span></span> → <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Configure <span class="application">RKWard</span></span></span> → <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guimenuitem">Plugins</span></span>, and see what is missing. A slightly more helpful answer: most actual statistics functions accessible via the <acronym class="acronym">GUI</acronym> are realized using plugins. Also, you can create fairly flexible <acronym class="acronym">GUI</acronym>s for all kinds of operations using plugins.
+ </p><p>
+ The basic paradigm behind <span class="application">RKWard</span> plugins is the one we will walk you through in this document: an <acronym class="acronym">XML</acronym> file describes what the <acronym class="acronym">GUI</acronym> looks like. An additional JavaScript file is used to generate <span class="application">R</span> syntax from the <acronym class="acronym">GUI</acronym> settings. That is, plugins do not really have to perform any statistical calculations. Rather plugins generate the <span class="application">R</span> syntax needed to run those calculations. The <span class="application">R</span> syntax is then sent to the <span class="application">R</span> backend for evaluation, and typically a result is shown in the output window.
+ </p><p>
+ Read on in the next chapters to see how this is done.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="introduction.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="pluginmap.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Introduction </td><td width="34%" align="center" class="navCenter"><a href="index.html">Up</a></td><td width="33%" align="right" class="navRight"> Creating menu entries</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/why_external_plugins.html b/doc/rkwardplugins/why_external_plugins.html
new file mode 100644
index 0000000..cb49128
--- /dev/null
+++ b/doc/rkwardplugins/why_external_plugins.html
@@ -0,0 +1,6 @@
+<html><head><title>Why external plugins?</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="external_plugins.html" title="Chapter 14. Share your work with others"><link rel="prev" href="external_plugins.html" title="Chapter 14. Share your work with others"><link rel="next" href="structure_of_a_plugin_package.html" title="Structure of a plugin package"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Why external plugins?</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="external_plugins.html">Prev</a></td><td align="center" class="navCenter" width="34%">Share your work with others</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="structure_of_a_plugin_package.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="why_external_plugins"></a>Why external plugins?</h2></div></div></div><p>
+ The number of packages to extend the functionality of <span class="application">R</span> 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 <span class="application">RKWard</span> quite modular as well. The <span class="application">RKWard</span> team maintains its own public package repository at <a class="ulink" href="https://files.kde.org/rkward/R/" target="_top">https://files.kde.org/rkward/R/</a>, designated to host your external plugins.
+ </p><p>
+ As a rule of thumb, plugins that seem to serve a widely used purpose (<abbr class="abbrev">e.g.</abbr> 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.
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="external_plugins.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="structure_of_a_plugin_package.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Share your work with others </td><td width="34%" align="center" class="navCenter"><a href="external_plugins.html">Up</a></td><td width="33%" align="right" class="navRight"> Structure of a plugin package</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/wizard_interface.html b/doc/rkwardplugins/wizard_interface.html
new file mode 100644
index 0000000..054a859
--- /dev/null
+++ b/doc/rkwardplugins/wizard_interface.html
@@ -0,0 +1,33 @@
+<html><head><title>Adding a wizard interface</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="mainxml.html" title="Chapter 4. Defining the GUI"><link rel="prev" href="mainxml.html" title="Chapter 4. Defining the GUI"><link rel="next" href="mainxmltips.html" title="Some considerations on GUI design"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Adding a wizard interface</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="mainxml.html">Prev</a></td><td align="center" class="navCenter" width="34%">Defining the <acronym class="acronym">GUI</acronym></td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="mainxmltips.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="wizard_interface"></a>Adding a wizard interface</h2></div></div></div><p>
+ Actually we do not have to define an additional <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><wizard></strong></span></span> interface, but here is how that would be done. To add a wizard interface, you will add a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><wizard></strong></span></span> tag at the same level as the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dialog></strong></span></span> tag:
+ </p><pre class="programlisting">
+ <wizard label="Two Variable t-Test">
+ <page id="firstpage">
+ <text>As a first step, select the two variables you want to compare against
+ each other. And specify, which one you theorize to be greater. Select two-sided,
+ if your theory does not tell you, which variable is greater.</text>
+ <copy id="main_settings_row"/>
+ </page>
+ </pre><p>
+ Some of this is pretty self explanatory: We add a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><wizard></strong></span></span> tag with a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span> for the wizard. Since a wizard can hold several pages that are shown one after another, we next define the first <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><page></strong></span></span>, and put an explanatory <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><text></strong></span></span> note in there. Then we use a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><copy></strong></span></span> tag. What this does, is really it saves us having to define yet again, what we already wrote for the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dialog></strong></span></span>: The copy tag looks for another tag with the same <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> earlier in the <acronym class="acronym">XML</acronym>. This happens to be defined in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dialog></strong></span></span> section, and is a <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><row></strong></span></span> in which there are the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varselector></strong></span></span>, <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><varslots></strong></span></span> and the <span class="quote">“<span class="quote">hypothesis</span>”</span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span> control. All of this is copied 1:1 and inserted right at the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><copy></strong></span></span> element.
+ </p><p>
+ Now to the second page:
+ </p><pre class="programlisting">
+ <page id="secondpage">
+ <text>Below are some advanced options. It is generally safe not to assume the
+ variables have equal variances. An appropriate correction will be applied then.
+ Choosing "assume equal variances" may increase test-strength, however.</text>
+ <copy id="varequal"/>
+ <text>Sometimes it is helpful to get an estimate of the confidence interval of
+ the difference in means. Below you can specify whether one should be shown, and
+ which confidence-level should be applied (95% corresponds to a 5% level of
+ significance).</text>
+ <copy id="frame_conf_int"/>
+ </page>
+ </wizard>
+ </pre><p>
+ Much of the same thing here. We add some texts, and in between that <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><copy></strong></span></span> further sections from the dialog interface.
+ </p><p>
+ You may of course make the wizard interface look very different to the plain dialog, and not use the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><copy></strong></span></span> tag at all. Be sure, however, to assign corresponding elements the same <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> 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 <span class="application">RKWard</span>), but also simplifies writing your code template (see below).
+ </p></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="mainxml.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="mainxmltips.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">Defining the <acronym class="acronym">GUI</acronym> </td><td width="34%" align="center" class="navCenter"><a href="mainxml.html">Up</a></td><td width="33%" align="right" class="navRight"> Some considerations on <acronym class="acronym">GUI</acronym> design</td></tr></table></body></html>
\ No newline at end of file
diff --git a/doc/rkwardplugins/xmlelements.html b/doc/rkwardplugins/xmlelements.html
new file mode 100644
index 0000000..8d16f56
--- /dev/null
+++ b/doc/rkwardplugins/xmlelements.html
@@ -0,0 +1,48 @@
+<html><head><title>Elements to be used in the XML description of the plugin</title><link rel="stylesheet" type="text/css" href="../common/kde-default.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="KDE, R, rkward, plugins"><link rel="home" href="index.html" title="Introduction to Writing Plugins for RKWard"><link rel="up" href="reference.html" title="Appendix A. Reference"><link rel="prev" href="globalxmlelements.html" title="General purpose elements to be used in any XML file (.xml, .rkh, .pluginmap)"><link rel="next" href="elementproperties.html" title="Properties of plugin elements"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr class="header"><td colspan="2"> </td></tr><tr id="logo"><td valign="top"><img src="../common/part_of_the_kde_family_horizontal_190.png" alt="Part of the KDE family" width="190" height="68" border="0"></td><td valign="middle" align="center" id="location"><h1>Elements to be used in the <acronym class="acronym">XML</acronym> description of the plugin</h1></td></tr></table><table width="100%" class="header"><tbody><tr><td align="left" class="navLeft" width="33%"><a accesskey="p" href="globalxmlelements.html">Prev</a></td><td align="center" class="navCenter" width="34%">Reference</td><td align="right" class="navRight" width="33%">
+ <a accesskey="n" href="elementproperties.html">Next</a></td></tr></tbody></table><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="xmlelements"></a>Elements to be used in the <acronym class="acronym">XML</acronym> description of the plugin</h2></div></div></div><p>Properties held by the elements are listed in a <a class="link" href="elementproperties.html" title="Properties of plugin elements">separate section</a>.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="generalelements"></a>General elements</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><document></span></dt><dd><p>Needs to be present in each description.xml-file as the root-node. No special function. No attributes</p></dd><dt><span class="term"><about></span></dt><dd><p>Information about this plugin (author, licence, <abbr class="abbrev">etc.</abbr>). This element is allowed in both an individual plugin's <code class="literal">.xml</code> file, and in <code class="literal">.pluginmap</code> files. Refer to the <a class="link" href="pluginmapelements.html" title="Elements for use in .pluginmap files"><code class="literal">.pluginmap</code> file reference</a> for reference details, <a class="link" href="chapter_about_information.html" title="Chapter 13. Author, license and version information">the chapter on 'about' information</a> for an introduction.</p></dd><dt><span class="term"><code></span></dt><dd><p>Defines where to look for the JS template to the plugin. Use only once per file, as a direct child of the document-tag. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>file</code></em></span></span></dt><dd><p>Filename of the JS template, relative to the directory the plugin-xml is in</p></dd></dl></div></dd><dt><span class="term"><help></span></dt><dd><p>Defines where to look for the help file for the plugin. Use only once per file, as a direct child of the document-tag. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>file</code></em></span></span></dt><dd><p>Filename of the help file, relative to the directory the plugin-xml is in</p></dd></dl></div></dd><dt><span class="term"><copy></span></dt><dd><p>Can be used as a child (direct or indirect) of the main layout elements, <abbr class="abbrev">i.e.</abbr> <dialog> and <wizard>. This is used to copy an entire block a <acronym class="acronym">XML</acronym> elements 1:1. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span></span></dt><dd><p>The ID to look for. The <copy> tag will look for a previous <acronym class="acronym">XML</acronym> element that has been given the same ID, and copy it including all descendant elements.</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>copy_element_tag_name</code></em></span></span></dt><dd><p>In some few cases, you will want an almost literal copy, but change the tag-name of the element to copy. The most important example of this is, when you want to copy an entire <tab> from a dialog interface to the <page> of a wizard interface. In this case, you would set copy_element_tag_name="page" to do this conversion automatically.</p></dd></dl></div></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="interfaceelements"></a>Interface definitions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><dialog></span></dt><dd><p>Defines a dialog-type interface. Place the <acronym class="acronym">GUI</acronym> definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Caption for the dialog</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>recommended</code></em></span></span></dt><dd><p>Should the dialog be used as the "recommended" interface (<abbr class="abbrev">i.e.</abbr> the interface that will be shown by default, unless the user has configured <span class="application">RKWard</span> to default to a specific interface)? This attribute does not currently have an effect, as it is implicitly "true", unless the wizard is recommended.</p></dd></dl></div></dd><dt><span class="term"><wizard></span></dt><dd><p>Defines a wizard-type interface. Place the <acronym class="acronym">GUI</acronym> definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Accepts only <page> or <embed>-tags as direct children. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Caption for the wizard</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>recommended</code></em></span></span></dt><dd><p>Should the wizard be used as the "recommended" interface (<abbr class="abbrev">i.e.</abbr> the interface that will be shown by default, unless the user has configured <span class="application">RKWard</span> to default to a specific interface)? Optional, defaults to "false".</p></dd></dl></div></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="layoutelements"></a>Layout elements</h3></div></div></div><p>All elements in this section accept an attribute id="identifierstring". This attribute is optional for all elements. It can be used, for example, to hide/disable the entire layout element and all the elements contained therein (see <a class="link" href="logic.html" title="Chapter 7. Logic interactions between GUI elements">chapter <acronym class="acronym">GUI</acronym> logic</a>). The id-string may not contain "." (dot) or ";" (semicolon), and should generally be limited to alphanumeric characters and the underscore ("_"). Only the additional attributes are listed.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><page></span></dt><dd><p>Defines a new page inside a wizard. Only allowed as a direct child of a <wizard> element.</p></dd><dt><span class="term"><row></span></dt><dd><p>All direct children of a "row" tag will be placed left-to-right.</p></dd><dt><span class="term"><column></span></dt><dd><p>All direct children of a "column" tag will be placed top-to-bottom.</p></dd><dt><span class="term"><stretch></span></dt><dd><p>By default, elements in the <acronym class="acronym">GUI</acronym> take up all the space that is available. For instance, if you have two columns side by side, the left one is packed with elements, but the right one only contains a lonely <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span>, the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span> control will expand vertically, even though it does not really need the available space, and it will look ugly. In this case you really want to add a "blank" below the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><radio></strong></span></span>. For this, use the <stretch> element. It will simply use up some space. Do not overuse this element, usually it is a good idea for <acronym class="acronym">GUI</acronym> elements to get all the available space, only sometimes will the layout become spaced out. The <stretch> element does not take any arguments, not even an "id". Also you can place no children inside the <stretch> element (in other words, you will only ever use it as "<stretch/>")</p></dd><dt><span class="term"><frame></span></dt><dd><p>Draws a frame/box around its direct children. Can be used to visually group related options. Layout inside a frame is top-to-bottom, unless you place a <row> inside. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Caption for the frame (optional)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>checkable</code></em></span></span></dt><dd><p>Frames can be made checkable. In this case, all contained elements will be disabled when the frame is unchecked, and enabled, when it is checked. (optional, defaults to "false")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>checked</code></em></span></span></dt><dd><p>For checkable frames only: Should the frame be checked by default? Defaults to "true". Not interpreted for non-checkable frames.</p></dd></dl></div></dd><dt><span class="term"><tabbook></span></dt><dd><p>Organizes elements in a tabbook. Accepts only <tab>-tags as direct children.</p></dd><dt><span class="term"><tab></span></dt><dd><p>Defines a page in a tabbook. Place the <acronym class="acronym">GUI</acronym> definition for the tab inside this tag. May be used only as a direct child of a <tabbook> tag. A <tabbook> should have at least two defined tabs. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Caption for the tab page (required)</p></dd></dl></div></dd><dt><span class="term"><text></span></dt><dd><p>Shows the text enclosed in this tag in the <acronym class="acronym">GUI</acronym>. Some simple <acronym class="acronym">HTML</acronym> style markup is supported (notably <span class="markup"><b></span>, <span class="markup"><i></span>, <span class="markup"><p></span>, and <span class="markup"><br/></span>). Please keep formatting to a minimum, however. Inserting a completely empty line adds a hard line break. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>type</code></em></span></span></dt><dd><p>Type of the text. One of "normal", "warning" or "error". This influences the look of the text (optional, defaults to normal)</p></dd></dl></div></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="activeelements"></a>Active elements</h3></div></div></div><p>All elements in this section accept an attribute id="identifierstring". This attribute is required for all elements. Only the additional attributes are listed. The id-string may not contain "." (dots).</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><varselector></span></dt><dd><p>Provides a list of available objects from which the user can select one or more. Requires one or more <varslot>s as a counterpart to be useful. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the varselector (optional, defaults to "Select variable(s)")</p></dd></dl></div></dd><dt><span class="term"><varslot></span></dt><dd><p>Used in conjunction with a "varselector" to allow the user to select one or more variables. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the varslot (recommended, defaults to "Variable:")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>source</code></em></span></span></dt><dd><p>The varselector to fetch the selection from (required, unless you connect manually or using source_property)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>source_property</code></em></span></span></dt><dd><p>An arbitrary property to copy values from, when the select button is clicked. If specified, this overrides the "source"-attribute.</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>required</code></em></span></span></dt><dd><p>Whether - for submitting the code - it is required that this varslot holds a valid value. See <a class="link" href="elementproperties.html" title="Properties of plugin elements">required-property</a> (optional, defaults to false)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>multi</code></em></span></span></dt><dd><p>Whether the varslot holds only one (default, "false"), or several objects</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>allow_duplicates</code></em></span></span></dt><dd><p>Whether the varslot may accept only unique objects (default, "false"), or if the same object may be added several times.</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min_vars</code></em></span></span></dt><dd><p>Only meaningful if multi="true": Minimum number of vars to be selected for the selection to be considered valid (optional, defaults to "1")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min_vars_if_any</code></em></span></span></dt><dd><p>Only meaningful if multi="true": Some varslots may be considered valid, if, for instance, the varslot is either empty, or holds at least two values. This specifies how many variables have to be selected if any at all (2 in the example). (optional, defaults to "1")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>max_vars</code></em></span></span></dt><dd><p>Only meaningful if multi="true": Maximum number of variables to select (optional, defaults to "0", which means no maximum)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>classes</code></em></span></span></dt><dd><p>If you specify one or more <span class="application">R</span> classnames (separated by spaces (" ")), here, the varslot will only accept objects belonging to those classes (optional, <span class="emphasis"><em>use with great care</em></span>, the user should not be prevented from making valid choices, and <span class="application">R</span> has <span class="emphasis"><em>a lot</em></span> of different classes)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>types</code></em></span></span></dt><dd><p>If you specify one or more variables types (separated by spaces (" ")), here, the varslot will only accept objects of those types. Valid types are "unknown", "number", "string", "factor", "invalid". (Optional, <span class="emphasis"><em>use with great care</em></span>, the user should not be prevented from making valid choices, and <span class="application">RKWard</span> does not always know the type of a variable)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>num_dimensions</code></em></span></span></dt><dd><p>The number of dimensions, an object needs to have. "0" (the default) means, any number of dimensions is acceptable. (optional, defaults to "0")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min_length</code></em></span></span></dt><dd><p>The minimum length, an object needs to have in order to be acceptable. (optional, defaults to "0")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>max_length</code></em></span></span></dt><dd><p>The maximum length, an object needs to have in order to be acceptable. (optional, defaults to the largest integer number representable on the system)</p></dd></dl></div></dd><dt><span class="term"><valueselector></span></dt><dd><p>Provides a list of available strings (not <span class="application">R</span> objects) to be selected in one or more accompanying <valueslot>s. String options can be defined using <option>-tags as direct children (see below), or set using dynamic <a class="link" href="elementproperties.html" title="Properties of plugin elements">properties</a>. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the valueselector (optional, defaults to no label)</p></dd></dl></div></dd><dt><span class="term"><valueslot></span></dt><dd><p>Used in conjunction with a <valueselector> to allow the user to select one or more string items. This element is mostly identical to <varslot>, and shares the same attributes, except for those which refer to properties of the acceptable items (<abbr class="abbrev">i.e.</abbr> classes, types, num_dimensions, min_length, max_length).</p></dd><dt><span class="term"><radio></span></dt><dd><p>Defines a group of radio-exclusive buttons (only one can be selected at a time). Requires at least two <option>-tags as direct children. No other tags are allowed as children. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the radio control (recommended, defaults to "Select one:")</p></dd></dl></div></dd><dt><span class="term"><dropdown></span></dt><dd><p>Defines a group of options of which one and only one can be selected at the same time, using a dropdown list. This is functionally equivalent to a <radio>, but looks different. Requires at least two <option>-tags as direct children. No other tags are allowed as children. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the dropdown list (recommended, defaults to "Select one:")</p></dd></dl></div></dd><dt><span class="term"><select></span></dt><dd><p>Provides a list of available strings from which the user can select an arbitrary number. String options can be defined using <option>-tags as direct children (see below), or set using dynamic <a class="link" href="elementproperties.html" title="Properties of plugin elements">properties</a>. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the <select> (optional, defaults to no label)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>single</code></em></span></span></dt><dd><p>If set to true, only a single value will be selectable, instead of multiple values at once (boolean, defaults to false)</p></dd></dl></div></dd><dt><span class="term"><option></span></dt><dd><p>Can only be used as a direct child of a <radio>, <dropdown>, <valueselector> or <select> element. Represents one selectable option in a radio control or dropdown list. As <option> elements are always part of one of the selection elements, they do not normally
+have an "id" of their own, but see below. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the option (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>value</code></em></span></span></dt><dd><p>The string value the parent element will return if this option is checked/selected (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>checked</code></em></span></span></dt><dd><p>Whether the option should be checked/selected by default "true" or "false". In a <radio> or <dropdown>, only one option may be set to <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>checked=</code></em></span><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>"true"</code></em></span>, and if no option is set to checked, the first option in the parent element will be checked/selected automatically. In a <select>, any number of options may be set to checked. (optional, default to "false")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span></span></dt><dd><p>Specifying the "id" parameter for the <option> elements is optional (and in fact it is recommended, not to set an "id", unless you really need one). However, specifying an "id" will allow you to enable/disable <option>s, dynamically, by connecting to the boolean property <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>id_of_radio.id_of_optionX.enabled</code></em></span>. Currently this works for options inside <radio> or <dropdown>
+ elements, only; <valueselector> and <select> options do not currently support ids.</p></dd></dl></div></dd><dt><span class="term"><checkbox></span></dt><dd><p>Defines a check box, <abbr class="abbrev">i.e.</abbr> a single option that can either be set to on or off. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the check box (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>value</code></em></span></span></dt><dd><p>The value the check box will return if checked (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>value_unchecked</code></em></span></span></dt><dd><p>The value that will be returned if the check box is not checked (optional, defaults to "", <abbr class="abbrev">i.e.</abbr> an empty string)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>checked</code></em></span></span></dt><dd><p>Whether the option should be checked by default "true" or "false" (optional, default to "false")</p></dd></dl></div></dd><dt><span class="term"><frame></span></dt><dd><p>The frame element is generally used as a pure layout element, and is listed in the section on <a class="link" href="xmlelements.html#layoutelements" title="Layout elements">layout elements</a>. However, it can also be
+made checkable, thus acting like a simple check box at the same time.
+</p></dd><dt><span class="term"><input></span></dt><dd><p>Defines a free text input field. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the input field (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>initial</code></em></span></span></dt><dd><p>Initial text of the text field (optional, defaults to "", <abbr class="abbrev">i.e.</abbr> an empty string)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>size</code></em></span></span></dt><dd><p>One of "small", "medium", or "large". "large" defines a multi-line input field, "small", and "medium" are single line fields (optional, defaults to "medium")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>required</code></em></span></span></dt><dd><p>Whether - for submitting the code - it is required that this input is not empty. See <a class="link" href="elementproperties.html" title="Properties of plugin elements">required-property</a> (optional, defaults to false)</p></dd></dl></div></dd><dt><span class="term"><matrix></span></dt><dd><p>A table for entering matrix data (or vectors) in the <acronym class="acronym">GUI</acronym>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This input element is <span class="emphasis"><em>not</em></span> optimized for entering/editing large amounts of data. While there is no strict limit on the size of a <matrix>, in general it should not exceed around ten rows / columns. If you expect larger data, allow users to select it as an <span class="application">R</span> object (which may be a good idea as an alternative option, in almost <span class="emphasis"><em>every</em></span> instance where you use a matrix element).</p></div><p>Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the table (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>mode</code></em></span></span></dt><dd><p>One of "integer", "real", or "string". The type of data that will be accepted in the table (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min</code></em></span></span></dt><dd><p>Minimum acceptable value (for matrices of type "integer" or "real") (optional, defaults to the smallest representable value)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>max</code></em></span></span></dt><dd><p>Maximum acceptable value (for matrices of type "integer" or "real") (optional, defaults to the largest representable value)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>allow_missings</code></em></span></span></dt><dd><p>Whether missing (empty) values are allowed in the matrix. This is implied for matrices or mode "string" (optional, defaults to false).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>allow_user_resize_columns</code></em></span></span></dt><dd><p>When set to true, the user can add columns by typing on the rightmost (inactive) cells (optional, defaults to true).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>allow_user_resize_rows</code></em></span></span></dt><dd><p>When set to true, the user can add rows by typing on the bottommost (inactive) cells (optional, defaults to true).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>rows</code></em></span></span></dt><dd><p>Number of rows in the matrix. Has no effect for allow_user_resize_rows="true". </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This can also be controlled by setting the "rows" property.</p></div><p> (optional, defaults to 2).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>columns</code></em></span></span></dt><dd><p>Number of columns in the matrix. Has no effect for allow_user_resize_columns="true". </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This can also be controlled by setting the "columns" property.</p></div><p> (optional, defaults to 2).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min_rows</code></em></span></span></dt><dd><p>Minimum number of rows in the matrix. The matrix will refuse shrink below this size. (optional, defaults to 0; see also: <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>allow_missings</code></em></span>.).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min_columns</code></em></span></span></dt><dd><p>Minimum number of columns in the matrix. The matrix will refuse shrink below this size. (optional, defaults to 0; see also: <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>allow_missings</code></em></span>.).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>fixed_height</code></em></span></span></dt><dd><p>Force the <acronym class="acronym">GUI</acronym> element to stay at its initial height. Do not use in combination with matrices, where the number of rows may change in any way. Useful, esp. when creating a vector input element (columns="1"). With this option set to true, no horizontal scroll bar will be shown, even in the matrix exceeds the available width (as this would affect the height). (optional, defaults to false).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>fixed_width</code></em></span></span></dt><dd><p>Slightly misnamed: Assume the column count will not change. The last (or typically only) column will be stretched to take up the available width. Do not use in combination with matrices, where the number of columns may change in any way. Useful, esp. when creating a vector input element (rows="1"). (optional, defaults to false).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>horiz_headers</code></em></span></span></dt><dd><p>Strings to use for the horizontal header, separated by ";". The header will be hidden, if set to "". (optional, defaults to column number).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>vert_headers</code></em></span></span></dt><dd><p>Strings to use for the vertical header, separated by ";". The header will be hidden, if set to "". (optional, defaults to row number).</p></dd></dl></div></dd><dt><span class="term"><optionset></span></dt><dd><p>A UI for repeating a set of options for an arbitrary number of items (<a class="link" href="optionset.html" title="Repeating (a set of) options">introduction to optionsets</a>). Attributes:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min_rows</code></em></span></span></dt><dd><p>If specified, the set will be marked invalid, unless it has at least this number of rows (optional, integer).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min_rows_if_any</code></em></span></span></dt><dd><p>Like min_rows, but will only be tested, if there is at least one row (optional, integer).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>max_rows</code></em></span></span></dt><dd><p>If specified, the set will be marked invalid, unless it has at most this number of rows (optional, integer).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>keycolumn</code></em></span></span></dt><dd><p>Id of the column to act as keycolumn. An optionset with a (valid) keycolumn will act as a "driven" optionset. An optionset with no keycolumn will allow manual insertion / removal of items. The keycolumn must be marked as external. (optional, defaults to no keycolumn).</p></dd></dl></div><p>Child-elements:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><optioncolumn></span></dt><dd><p>Declares one optioncolumn of the set. For each value that you want to fetch from the optionset, you must declare a separate <optioncolumn>. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span></span></dt><dd><p>The id of the optioncolumn (required, string).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>external</code></em></span></span></dt><dd><p>Set to true, if the optioncolumn is controlled from outside the optionset (optional, boolean, defaults to false).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>If given, the optioncolumn will be displayed in a column by that label (optional, string, defaults to not displayed).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>connect</code></em></span></span></dt><dd><p>The property to connect this optioncolumn to, given as id inside the <content>-area. For external <optioncolumn>s, the corresponding value will be set to the externally set value. For regular (non-external) <optioncolumn>s,
+ the corresponding row of the <optioncolumn>-property, will be set when the property changes inside the content-area. (optional, string, defaults to not connected).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>default</code></em></span></span></dt><dd><p>Only for external columns: The value to assume for this column, if no value is known for an entry. Rarely useful. (Optional, defaults to empty string)</p></dd></dl></div><p>
+ </p></dd><dt><span class="term"><content></span></dt><dd><p>Declare the content / UI of the set. No attributes. All usual active, passive, and layout elements are allowed as childname elements. In addition, in earlier versions of <span class="application">RKWard</span> (up to 0.6.3), the special child-element <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><optiondisplay></strong></span></span> was allowed. This is obsolete in <span class="application">RKWard</span> 0.6.4, and should simply be removed from existing plugins.
+ </p></dd><dt><span class="term"><logic></span></dt><dd><p>Optional specification of UI logic to apply <span class="emphasis"><em>inside</em></span> the contents region the optionset. See <a class="link" href="xmlelements.html#logicelements" title="Logic section">the reference on <logic></a>
+ </p></dd></dl></div></dd><dt><span class="term"><browser></span></dt><dd><p>An element designed to select a single filename (or directory name). Note that this field will take any string, even though it is meant to be used for files, only:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the browser (optional, defaults to "Enter filename")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>initial</code></em></span></span></dt><dd><p>Initial text of the browser (optional, defaults to "", <abbr class="abbrev">i.e.</abbr> an empty string)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>type</code></em></span></span></dt><dd><p>One of "file", "dir", or "savefile". To select an existing file, existing directory, or non-existing file, respectively (optional, defaults to "file")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>allow_urls</code></em></span></span></dt><dd><p>Whether (non-local) <acronym class="acronym">URL</acronym>s can be selected (optional, defaults to "false")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>filter</code></em></span></span></dt><dd><p>File type filter, <abbr class="abbrev">e.g.</abbr> ("*.txt *.csv" for .txt and .csv files). A separate entry for "All files" is added, automatically (optional, defaults to "", <abbr class="abbrev">i.e.</abbr> All files)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>required</code></em></span></span></dt><dd><p>Whether - for submitting the code - it is required that the field is not empty. Note that this does not necessarily mean that the selected filename is valid. See <a class="link" href="elementproperties.html" title="Properties of plugin elements">required-property</a> (optional, defaults to true)</p></dd></dl></div></dd><dt><span class="term"><saveobject></span></dt><dd><p>An element designed to select the name of an <span class="application">R</span> object to save to (<abbr class="abbrev">i.e.</abbr> generally not already existing, in contrast to a varslot):
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the input (optional, defaults to "Save to:")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>initial</code></em></span></span></dt><dd><p>Initial text of the input (optional, defaults to "my.data")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>required</code></em></span></span></dt><dd><p>Whether - for submitting the code - it is required that the field holds a permissible object name. See <a class="link" href="elementproperties.html" title="Properties of plugin elements">required-property</a> (optional, defaults to true)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>checkable</code></em></span></span></dt><dd><p>In many use cases, saving to an <span class="application">R</span> object is optional. In these cases, a check box can be integrated into the saveobject-element using this attribute. When set to true, the saveobject will be activated / deactivated by the check box. See the <a class="link" href="elementproperties.html" title="Properties of plugin elements">active-property</a> of saveobject (optional, defaults to false)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>checked</code></em></span></span></dt><dd><p>For checkable saveobject-elements, only: Whether the control is checked/enabled by default (optional, defaults to false)</p></dd></dl></div></dd><dt><span class="term"><spinbox></span></dt><dd><p>A spinbox in which the user can select a numeric value, using either direct keyboard input or small up/down arrows. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label for the spinbox (recommend, default to "Enter value:")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min</code></em></span></span></dt><dd><p>The lowest value the user is allowed to enter in the spinbox (optional, defaults to the lowest value technically representable in the spinbox)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>max</code></em></span></span></dt><dd><p>The largest value the user is allowed to enter in the spinbox (optional, defaults to the highest value technically representable in the spinbox)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>initial</code></em></span></span></dt><dd><p>The initial value shown in the spinbox (optional, defaults to "0")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>type</code></em></span></span></dt><dd><p>One of "real" or "integer". Whether the spinbox will accept real numbers or only integers (optional, defaults to "real")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>default_precision</code></em></span></span></dt><dd><p>Only meaningful if the spinbox is of type="real". Specifies the default number of decimal places shown in the spinbox (only this many trailing zeros will be shown). When the user presses the up/down arrows, this decimal place will be changed. The user may still be able to enter values with a higher precision, however (see below) (optional, defaults to "2")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>max_precision</code></em></span></span></dt><dd><p>The maximum number of digits that can be meaningfully represented (optional, defaults to "8")</p></dd></dl></div></dd><dt><span class="term"><formula></span></dt><dd><p>This advanced element allows the user to select a formula/set of interactions from selected variables. For instance for a GLM, this element can be used to allow the user to specify the interaction-terms in the model. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>fixed_factors</code></em></span></span></dt><dd><p>The ID of the varslot holding the selected fixed factors (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>dependent</code></em></span></span></dt><dd><p>The ID of the varslot holding the selected dependent variable (required)</p></dd></dl></div></dd><dt><span class="term"><embed></span></dt><dd><p>Embed a different plugin into this one (see <a class="link" href="embedding.html" title="Chapter 8. Embedding Plugins into Plugins">chapter on embedding</a>). Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>component</code></em></span></span></dt><dd><p>The registered name of the component to embed (see <a class="link" href="pluginmap.html" title="Chapter 3. Creating menu entries">chapter on registering components</a>) (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>as_button</code></em></span></span></dt><dd><p>If set to "true", only a pushbutton will be placed in the embedding <acronym class="acronym">GUI</acronym>, the embedded <acronym class="acronym">GUI</acronym> will only be shown (in a separate window) when the pushbutton is pressed (optional, default is "false")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Only meaningful if as_button="true": The label of the button (recommend, default is "Options")</p></dd></dl></div></dd><dt><span class="term"><preview></span></dt><dd><p>Checkbox to toggle preview functionality. Note that starting with version 0.6.5 of <span class="application">RKWard</span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><preview></strong></span></span> preview elements are special-
+ cased in plugin dialogs (not wizards): They will be placed in the button-column, irrespective of where exactly they are defined in the UI. It is still a good idea to
+ define them at a sensible place in the layout, for backwards compatibility. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>Label of the box (optional, default is "Preview")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>mode</code></em></span></span></dt><dd><p>Type of preview. Supported types are "plot" (see <a class="link" href="specialized_plugins.html#preview_plots" title="Adding preview functionality">chapter on graph previews</a>), "output" (see <a class="link" href="ch10s02.html#preview_output" title="Previews of (HTML) output">chapter on (<acronym class="acronym">HTML</acronym>) output previews</a>), "data" (see <a class="link" href="ch10s02.html#preview_data" title="Previews of (imported) data">data previews</a>), and "custom" (see <a class="link" href="ch10s02.html#preview_custom" title="Custom previews">custom previews</a>). (optional, default is "plot")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>placement</code></em></span></span></dt><dd><p>Placement of the preview: "attached" (to the main workplace), "detached" (standalone window), "docked" (attached to the plugin dialog) and "default" (currently this is the same as "docked", but might become user-configurable at some point). In general, it is recommended to leave this as the default setting for best UI-consistency (optional, default is "default")</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>active</code></em></span></span></dt><dd><p>Whether the preview is active by default. In general, only docked previews should be made active by default, and even for these, there is a reason why the default is in-active previews (optional, default is "false")</p></dd></dl></div></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="logicelements"></a>Logic section</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><logic></span></dt><dd><p>The containing element for the logic section. All elements below are allowed only inside the <logic> element. The <logic> element is allowed only as a direct child of the <document> element (at most once per document), or of <optionset> elements (at most once per optionset). The document's logic section applies to both <dialog> and <wizard> GUIs in the same way.</p></dd><dt><span class="term"><external></span></dt><dd><p>Creates a new (string) property that is supposed to be connected to an outside property if the plugin gets embedded. See <a class="link" href="embedding_incomplete.html" title="Embedding/defining incomplete plugins">section on "incomplete" plugins</a>. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span></span></dt><dd><p>The ID of the new property (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>default</code></em></span></span></dt><dd><p>The default string value of the new property, <abbr class="abbrev">i.e.</abbr> the value used, if the property is not connected to an outside property (optional, defaults to an empty string)</p></dd></dl></div></dd><dt><span class="term"><i18n></span></dt><dd><p>Creates a new (string) property that is supposed to be provide an i18n'ed label. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span></span></dt><dd><p>The ID of the new property (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>label</code></em></span></span></dt><dd><p>The label. This will be translated. (required)</p></dd></dl></div></dd><dt><span class="term"><set></span></dt><dd><p>Set a property to a fixed value (of course, if you additionally connect the property to some other property, the value does not remain fixed). For instance, if you embed a plugin, but want to hide some of its elements, you might set the visibility property of those elements to false. Useful esp. for embedded/embedding plugins. Note: If there are several <set> elements
+for a single <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span>, the latest one to be defined takes precedence. This will sometimes be useful to rely on when using <include>d parts.
+Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span></span></dt><dd><p>The ID of the property to set (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>to</code></em></span></span></dt><dd><p>The string value to set the property to (required). Note: For boolean properties such as visibility, enabledness, you will typically set the to attribute to either to="true" or to="false".</p></dd></dl></div></dd><dt><span class="term"><convert></span></dt><dd><p>Create a new boolean properties that depends on the state of one or more different properties. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span></span></dt><dd><p>The ID of the new property (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>sources</code></em></span></span></dt><dd><p>The ids of the properties this property will depend on. One or more properties may be specified, separated by ";" (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>mode</code></em></span></span></dt><dd><p>The mode of conversion/operation. One of "equals", "notequals", "range", "and", "or". If in mode equals, the property will only be true, if the value of all of its sources equals the attribute standard (see below). If in at mode notequals, the property will only be true, if the value of all of its sources are different from the attribute standard (see below). If in mode range, the sources have to be numeric (integer or real). The property will only be true, if all sources are in the range specified by the attributes min and max (see below). If in mode and, the sources have to be boolean properties. The property will only be true, if all the sources are true simultaneously. If in mode or, the sources have to be boolean properties. The property will only be true, if at least one of the sources is true. (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>standard</code></em></span></span></dt><dd><p>Only meaningful in modes equals or notequals: the string value to compare against (required if in one of these modes)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>min</code></em></span></span></dt><dd><p>Only meaningful in mode range: the minimum value to compare against (optional, defaults to the lowest floating point number representable on the machine)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>max</code></em></span></span></dt><dd><p>Only meaningful in mode range: the maximum value to compare against (optional, defaults to the largest floating point number representable on the machine)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>require_true</code></em></span></span></dt><dd><p>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 <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="guiitem"><span class="guibutton">Submit</span></span> button (optional, defaults to "false").
+ </p><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p>If you use this, make sure the user can easily detect what is wrong, such as by showing an explanatory <text>.</p></div></dd></dl></div></dd><dt><span class="term"><switch></span></dt><dd><p>Create a new property that will relay to different target properties (or fixed strings) based on the value of a condition property. This allows to create logic similar to <code class="function">if()</code> or <code class="function">switch()</code> constructs. Attributes:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span></span></dt><dd><p>The ID of the new property (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>condition</code></em></span></span></dt><dd><p>The id of the condition property (required)</p></dd></dl></div><p>Child elements:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><true></span></dt><dd><p>If the condition property is boolean, you can specify the two child elements <true> and <false> (and only these). (Required, if <false> is also given)</p></dd><dt><span class="term"><false></span></dt><dd><p>If the condition property is boolean, you can specify the two child elements <true> and <false> (and only these). (Required, if <true> is also given)</p></dd><dt><span class="term"><case></span></dt><dd><p>If the condition property is not boolean, you can supply an arbitrary number of <case>-elements, one for each
+ value of the condition property that you want to match (at least one such element is required, if the condition property is not boolean)</p></dd><dt><span class="term"><default></span></dt><dd><p>If the condition property is not boolean, the optional <default>-element, allows to specify the behavior, if no
+ <case> element is matches the value of the condition property (optional, allowed only once, in combination with one or more <case> elements).</p></dd></dl></div><p>Child elements <true>, <false>, <case>, and <default> take the following attributes:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>standard</code></em></span></span></dt><dd><p>Only for <case>-elements: The value to match the condition property against (required, string).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>fixed_value</code></em></span></span></dt><dd><p>A fixed string that should be supplied as the value of the <switch> property, if the current condition matches (required, if dynamic_value is not supplied).</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>dynamic_value</code></em></span></span></dt><dd><p>The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>id</code></em></span> of the target property that should be supplied as the value of the <switch> property, if the current condition matches (required, if fixed_value is not supplied).</p></dd></dl></div></dd><dt><span class="term"><connect></span></dt><dd><p>Connects two properties. The client property will be changed whenever the governor property changes (but not the other way around). Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>client</code></em></span></span></dt><dd><p>The ID of the client property, <abbr class="abbrev">i.e.</abbr> the property that will be adjusted (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>governor</code></em></span></span></dt><dd><p>The ID of the governor property, <abbr class="abbrev">i.e.</abbr> the property that will adjusts the client property. This may include a modifier (required)</p></dd><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>reconcile</code></em></span></span></dt><dd><p>If "true", the client property will make adjust the governor property on connection in such a way that the governor property will only accept values that are also acceptable by the client (<abbr class="abbrev">e.g.</abbr> suppose the governor is a numeric property with min value "0", and the client is a numeric property with min value "100". The min of both properties will be adjusted to 100, if reconcile="true"). Generally works only for properties of the same basic type (optional, default to "false")</p></dd></dl></div></dd><dt><span class="term"><dependency_check></span></dt><dd><p>Creates a boolean property that is true, if the specified dependencies are met, false otherwise. The <acronym class="acronym">XML</acronym> syntax of the element is the same as that of the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><dependencies></strong></span></span> element, described in the <a class="link" href="pluginmapelements.html" title="Elements for use in .pluginmap files"><code class="literal">.pluginmap</code> reference</a>. As of <span class="application">RKWard</span> 0.6.1, only the <span class="application">RKWard</span> and <span class="application">R</span> version specifications are taken into account, not dependencies on packages or pluginmaps.</p></dd><dt><span class="term"><script></span></dt><dd><p>Define script code to control UI logic. See <a class="link" href="logic_scripted.html" title="Scripted GUI logic">the section on scripted GUJI logic</a> for details. The script code to run can be given either using the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>"file"</code></em></span> attribute, or as a (commented) text of the element. The <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><script></strong></span></span> element is not allowed in the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span class="command"><strong><logic></strong></span></span> section of an optionset. Attributes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="parameter"><em class="parameter"><code>file</code></em></span></span></dt><dd><p>File name of the script file. (required)</p></dd></dl></div></dd></dl></div></div></div><table width="100%" class="bottom-nav"><tr><td width="33%" align="left" valign="top" class="navLeft"><a href="globalxmlelements.html">Prev</a></td><td width="34%" align="center" valign="top" class="navCenter"><a href="index.html">Contents</a></td><td width="33%" align="right" valign="top" class="navRight"><a href="elementproperties.html">Next</a></td></tr><tr><td width="33%" align="left" class="navLeft">General purpose elements to be used in any <acronym class="acronym">XML</acronym> file (<code class="literal">.xml</code>, <code class="literal">.rkh</code>, <code class="literal">.pluginmap</code>) </td><td width="34%" align="center" class="navCenter"><a href="reference.html">Up</a></td><td width="33%" align="right" class="navRight"> Properties of plugin elements</td></tr></table></body></html>
\ No newline at end of file
More information about the rkward-tracker
mailing list