Menu
▾
▴
[rkward-cvs] [rkward] doc: Fix typos and EBN issues
|
From: Yuri C. <yu...@uk...> - 2015-02-04 19:56:33
|
Git commit 6b71b510f89becda9fc917fb675c79cd770a71ea by Yuri Chornoivan. Committed on 04/02/2015 at 19:55. Pushed by yurchor into branch 'master'. Fix typos and EBN issues M +1 -1 doc/rkward/index.docbook M +115 -112 doc/rkwardplugins/index.docbook http://commits.kde.org/rkward/6b71b510f89becda9fc917fb675c79cd770a71ea diff --git a/doc/rkward/index.docbook b/doc/rkward/index.docbook index 0fee126..cf6a6be 100644 --- a/doc/rkward/index.docbook +++ b/doc/rkward/index.docbook @@ -42,7 +42,7 @@ thanks ;-). <title>The RKWard Handbook</title> <authorgroup> -<!-- New authors, add youselves here! --> +<!-- New authors, add yourselves here! --> <author> <firstname>Thomas</firstname> <surname>Friedrichsmeier</surname> diff --git a/doc/rkwardplugins/index.docbook b/doc/rkwardplugins/index.docbook index 2c298c6..8c8bdd3 100644 --- a/doc/rkwardplugins/index.docbook +++ b/doc/rkwardplugins/index.docbook @@ -37,9 +37,11 @@ as Authors, publish date, the abstract, and Keywords --> </affiliation> </author> <!-- Additional authors go here --> -</authorgroup> <!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + + <copyright> <year>2006</year> @@ -347,7 +349,7 @@ This is a guide to writing plugins for &rkward;. <dialog label="Two Variable t-Test"> </programlisting> <para> - As you know, plugins may have either a dialog or a wizard interface or both. Here we start definining a dialog interface. the <parameter>label</parameter> attribute specifies the caption of the dialog. + As you know, plugins may have either a dialog or a wizard interface or both. Here we start defining a dialog interface. the <parameter>label</parameter> attribute specifies the caption of the dialog. </para> <programlisting> <tabbook> @@ -377,7 +379,7 @@ This is a guide to writing plugins for &rkward;. <column> </programlisting> <para> - Next, we nest a <command><column></command> inside the row. I.e. the following elements will be place above each other (top-to-bottom), and all will be to the right of the <command><varselector></command>. + Next, we nest a <command><column></command> 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 <command><varselector></command>. </para> <programlisting> <varslot types="number" id="x" source="vars" required="true" label="compare"/> @@ -420,14 +422,14 @@ This is a guide to writing plugins for &rkward;. </mediaobject> </screenshot> <para> - Note that we have not specified the <guibutton>Submit</guibutton>, <guibutton>Close</guibutton>, etc. buttons or the code view. Those elements get generated automatically. But of course we still have to define the second page of the <command><tabbook></command>: + Note that we have not specified the <guibutton>Submit</guibutton>, <guibutton>Close</guibutton>, &etc; buttons or the code view. Those elements get generated automatically. But of course we still have to define the second page of the <command><tabbook></command>: </para> <programlisting> <tab label="Options"> - <checkbox id="varequal" label="assume equal variances" value=", var.equal=TRUE"/> + <check box id="varequal" label="assume equal variances" value=", var.equal=TRUE"/> </programlisting> <para> - By default elements will be placed top-to-bottom like in a <command><column></command>. Since that is what we want here, we don't have to explicitly state a <command><row></command> or <command><column></command> layout. The first element we define is a checkbox. Just like the <command><radio></command><command><option></command>s, the checkbox has a <parameter>label</parameter> and a <parameter>value</parameter>. The <parameter>value</parameter> is what gets returned, if the checkbox is checked. Of course the checkbox also needs an <parameter>id</parameter>. + By default elements will be placed top-to-bottom like in a <command><column></command>. Since that is what we want here, we don't have to explicitly state a <command><row></command> or <command><column></command> layout. The first element we define is a check box. Just like the <command><radio></command><command><option></command>s, the check box has a <parameter>label</parameter> and a <parameter>value</parameter>. The <parameter>value</parameter> is what gets returned, if the check box is checked. Of course the check box also needs an <parameter>id</parameter>. </para> <programlisting> <frame label="Confidence Interval" id="frame_conf_int"> @@ -436,15 +438,15 @@ This is a guide to writing plugins for &rkward;. Here's yet another layout element: In order to signal that the two elements below belong together, we draw a <command><frame></command> (box). That frame may have a <parameter>label</parameter> (caption). Since the frame is just a passive layout element, it does not need an <parameter>id</parameter>, we still define one here, as we'll refer to it later, when defining an additional wizard interface. </para> <programlisting> - <checkbox id="confint" label="print confidence interval" value="1" checked="true"/> + <check box 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> </programlisting> <para> - Inside the <command><frame></command> we place another <command><checkbox></command> (using <parameter>checked=</parameter><replaceable>"true"</replaceable>, we signal that checkbox should be checked by default), and a <command><spinbox></command>. The spinbox allows the user to select a value between <replaceable>"min"</replaceable> and <replaceable>"max"</replaceable> with the default/initial value <replaceable>"0.95"</replaceable>. Setting the <parameter>type</parameter> to <replaceable>"real"</replaceable> signals that real numbers are accepted as opposed to <parameter>type=</parameter><replaceable>"integer"</replaceable> which would accept integers only. + Inside the <command><frame></command> we place another <command><check box></command> (using <parameter>checked=</parameter><replaceable>"true"</replaceable>, we signal that check box should be checked by default), and a <command><spinbox></command>. The spinbox allows the user to select a value between <replaceable>"min"</replaceable> and <replaceable>"max"</replaceable> with the default/initial value <replaceable>"0.95"</replaceable>. Setting the <parameter>type</parameter> to <replaceable>"real"</replaceable> signals that real numbers are accepted as opposed to <parameter>type=</parameter><replaceable>"integer"</replaceable> which would accept integers only. </para> <note><para> - It is also possible, and often preferable, to make the <command><frame></command> itself checkable, instead of adding a <command><checkbox></command> inside. See the reference for details. This is not done here, for illustrational purposes. + It is also possible, and often preferable, to make the <command><frame></command> itself checkable, instead of adding a <command><check box></command> inside. See the reference for details. This is not done here, for illustrational purposes. </para></note> <programlisting> </tab> @@ -511,12 +513,12 @@ This is a guide to writing plugins for &rkward;. </para> <sect2 id="radio_vs_checkbox_vs_dropdown"> - <title><radio> vs. <checkbox> vs. <dropdown></title> + <title><radio> vs. <check box> vs. <dropdown></title> <para> - The three elements <command><radio></command>, <command><checkbox></command>, <command><dropdown></command>, all serve a similar function: To select one out of several options. Obviously, a checkbox only allows to chose between two options: checked or not checked, so you can't use it, if there are more than two options to chose from. But when to use which of the elements? Some rules of thumb: + The three elements <command><radio></command>, <command><check box></command>, <command><dropdown></command>, all serve a similar function: To select one out of several options. Obviously, a check box only allows to chose between two options: checked or not checked, so you cannot use it, if there are more than two options to chose from. But when to use which of the elements? Some rules of thumb: </para> <para> - If you find yourself creating a <command><radio></command> or <command><dropdown></command> with only two options, ask yourself, whether the question is essentially a yes / no type of question. E.g. a choice between <quote>adjust results</quote> and <quote>do not adjust results</quote>, or between <quote>remove missing values</quote> and <quote>keep missing values</quote>. In this case a <command><checkbox></command> is the best choice: It uses little space, will have the least words of labels, and is easiest to read for the user. There are very few situations where you should chose a <command><radio></command> over a <command><checkbox></command>, when there are only two options. An example of that might be: <quote>Method of calculation: 'pearson'/'spearman'</quote>. Here, more methods might be thinkable, and they don't really form a pair of opposites. + If you find yourself creating a <command><radio></command> or <command><dropdown></command> with only two options, ask yourself, whether the question is essentially a yes / no type of question. E.g. a choice between <quote>adjust results</quote> and <quote>do not adjust results</quote>, or between <quote>remove missing values</quote> and <quote>keep missing values</quote>. In this case a <command><check box></command> is the best choice: It uses little space, will have the least words of labels, and is easiest to read for the user. There are very few situations where you should chose a <command><radio></command> over a <command><check box></command>, when there are only two options. An example of that might be: <quote>Method of calculation: 'pearson'/'spearman'</quote>. Here, more methods might be thinkable, and they don't really form a pair of opposites. </para> <para> Chosing between a <command><radio></command> and a <command><dropdown></command> is mostly a question of space. The <command><dropdown></command> has the advantage of using little space, even if there are a lot of options to chose from. On the other hand, a <command><radio></command> has the advantage of making all possible choices visible to the user at once, without clicking on the dropdown arrow. Generally, if there are six or more options to chose from, a <command><dropdown></command> is preferable. If there are five or less options, a <command><radio></command> is the better choice. @@ -529,7 +531,7 @@ This is a guide to writing plugins for &rkward;. <title>Generating R code from GUI settings</title> <sect1 id="sect_generating_R_code"><title>Using JavaScript in RKWard plugins</title> <para> - Now we have a GUI defined, but we still need to generate some &r; code from that. For that, we need another text file, <filename>code.js</filename>, located in the same directory as the <link linkend="mainxml"><filename>description.xml</filename></link>. You may or may not be familiar with JavaScript (or, to be technically precise: ECMA-script). Documentation on JS can be found in abundance, both in printed form, and on the internet (e.g.: <ulink url="https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide">https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide</ulink>). But for most purposes you will not need to know much about JS at all, as we'll only use some very basic features. + Now we have a GUI defined, but we still need to generate some &r; code from that. For that, we need another text file, <filename>code.js</filename>, located in the same directory as the <link linkend="mainxml"><filename>description.xml</filename></link>. You may or may not be familiar with JavaScript (or, to be technically precise: ECMA-script). Documentation on JS can be found in abundance, both in printed form, and on the Internet (⪚: <ulink url="https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide">https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide</ulink>). But for most purposes you will not need to know much about JS at all, as we'll only use some very basic features. </para> <tip> <para> @@ -569,7 +571,7 @@ function calculate () { res <- t.test ( </screen> <para> - as plain text. Next we need to fill in the value, the user selected as the first variable. We fetch this using <function>getString ("x")</function>, and append it to the string to be <quote>echoed</quote>. This prints out the value of the GUI-element with <parameter>id=</parameter><replaceable>"x"</replaceable>: our first <command><checkbox></command>. Next, we append a ', ', and do the same to fetch the value of the element <replaceable>"y"</replaceable> - the second <command><checkbox></command>. For the hypothesis (the <command><radio></command> group), and the equal variances <command><checkbox></command>, the procedure is very similar. + as plain text. Next we need to fill in the value, the user selected as the first variable. We fetch this using <function>getString ("x")</function>, and append it to the string to be <quote>echoed</quote>. This prints out the value of the GUI-element with <parameter>id=</parameter><replaceable>"x"</replaceable>: our first <command><check box></command>. Next, we append a ', ', and do the same to fetch the value of the element <replaceable>"y"</replaceable> - the second <command><check box></command>. For the hypothesis (the <command><radio></command> group), and the equal variances <command><check box></command>, the procedure is very similar. </para> <para> Note that instead of concatenating the output snippets with <quote>+</quote>, you can also use several <function>echo()</function> statments. Everything is printed on a single line. To produce a line break in the generated code, insert a <replaceable>"\n"</replaceable> in the echoed string. In theory, you can even produce many lines with a single echo-statement, but please keep it to one line (or less) of generated code per <function>echo()</function>. @@ -593,7 +595,7 @@ function printout () { <para> And this was all there is to the printout function in most cases. <function>rk.header()</function> prints a standard headline for the results. Note that in the .js files, you have to mark up all translatable strings by hand, using <command>i18n()</command>, or some alternative commands. More on this in the <link linkend="i18n_js">chapter on internationaliation</link>. - You can also add some more information to this, if you like, e.g.: + You can also add some more information to this, if you like, ⪚: </para> <programlisting> function printout () { @@ -609,7 +611,7 @@ echo ('rk.print (res)\n'); <function>rk.print()</function> utilizes the R2HTML package to provide HTML formatted output. Another helpful function is <function>rk.results()</function>, which can also output different kinds of result tables. If in doubt, however, just use <function>rk.print()</function>, and be done with. The JS class <function>Header</function> is a JS level helper to generate a call to <function>rk.header()</function> (just take a look at the generated &r; code). In some cases you may want to call <function>echo ('rk.header (...)')</function> directly to print a header for your output. </para> <para> - Note that internally, the output is just a plain HTML document at this point of time. Therefore you might be tempted to add custom HTML using <function>rk.cat.output()</function>. While this will work, please don't do this. The output format may change (e.g. to ODF) in the future, so it's best not to introduce HTML specific code. Rather keep things simple with <function>rk.header()</function>, <function>rk.print()</function>, <function>rk.results()</function>, and -- if needed -- <function>rk.print.literal()</function>. If those don't seem to satisfy your formatting needs, contact us on the mailing list for help. + Note that internally, the output is just a plain HTML document at this point of time. Therefore you might be tempted to add custom HTML using <function>rk.cat.output()</function>. While this will work, please don't do this. The output format may change (⪚ to ODF) in the future, so it's best not to introduce HTML specific code. Rather keep things simple with <function>rk.header()</function>, <function>rk.print()</function>, <function>rk.results()</function>, and -- if needed -- <function>rk.print.literal()</function>. If those don't seem to satisfy your formatting needs, contact us on the mailing list for help. </para> <para> Congratulations! You created your first plugin. Read on in the next chapters for more advanced concepts. @@ -632,7 +634,7 @@ echo ('rk.print (res)\n'); If the user explicitly asks for a variable to be saved, you will need to assign to that object using <function>.GlobalEnv$objectname <- value</function>. In general, do not use the <function><<-</function> operator. It will not necessarily assign in .GlobalEnv. </para> <para> - One important pitfall is using <function>eval()</function>. Here, you need to note that eval will by default use the current environment for evaluation, i.e. the local one. This will work well most of the times, but but not always. Thus, if you need to use <function>eval()</function>, you will probably want to specify the <parameter>envir</parameter> parameter: <function>eval(..., envir=globalenv()</function>). + One important pitfall is using <function>eval()</function>. Here, you need to note that eval will by default use the current environment for evaluation, &ie; the local one. This will work well most of the times, but but not always. Thus, if you need to use <function>eval()</function>, you will probably want to specify the <parameter>envir</parameter> parameter: <function>eval(..., envir=globalenv()</function>). </para> </sect2> @@ -673,7 +675,7 @@ if (my.rotation > wobble.rotation.limit (x)) { <sect2 id="policysimplicity"> <title>Dealing with complex options</title> <para> - Many plugins can do more than one thing. For instance, the <quote>Descriptive Statistics</quote> plugin can compute mean, range, sum, product, median, length, etc. However, typically the user will only chose 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): + Many plugins can do more than one thing. For instance, the <quote>Descriptive Statistics</quote> plugin can compute mean, range, sum, product, median, length, &etc; However, typically the user will only chose 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 <check box> elements): </para> <programlisting> function calculate () { @@ -779,7 +781,7 @@ 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.: +(in this case, rkward is assumed as the standard namespace, ⪚: <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 <link linkend="pluginmap">&pluginmap;</link>. @@ -971,7 +973,7 @@ R code. </dialog> </programlisting> <para> - What happens here, is that the entire GUI or the plot options plugin (except of course for the standard elements like <guibutton>Submit</guibutton> button, etc.) is embedded right into your plugin (try it!). + What happens here, is that the entire GUI or the plot options plugin (except of course for the standard elements like <guibutton>Submit</guibutton> button, &etc;) is embedded right into your plugin (try it!). </para> <para> As you can see the syntax of the <command><embed></command>-tag is fairly simple. It takes an <parameter>id</parameter> as most elements. The parameter component specifies which plugin to embed, as defined in the &pluginmap; file (<replaceable>"rkward::plot_options"</replaceable> is the result of concatenating the namespace <quote>rkward</quote>, a separator <quote>::</quote>, and the name of the component <quote>plot_options</quote>). @@ -1318,7 +1320,7 @@ This chapter contains information on some topics that are useful only to certain <title>Drawing a plot to the output window</title> <para> In order to draw a plot to the output window, use <function>rk.graph.on()</function> directly before creating the plot, and - <function>rk.graph.off()</function>, directly afterwards. This is similar to e.g. callling <function>postscript()</function> and + <function>rk.graph.off()</function>, directly afterwards. This is similar to ⪚ callling <function>postscript()</function> and <function>dev.off()</function> in a regular R session. </para> <para> @@ -1330,10 +1332,10 @@ This chapter contains information on some topics that are useful only to certain <sect2 id="preview_plots"> <title>Adding preview functionality</title> <para> - A very useful feature for all plugins generating a plot/graph is to provide an automatically updating preview. To do so, you will need two things: Adding a <command><preview></command> checkbox to your <link linkend="mainxml">GUI definition</link>, and adjusting the <link linkend="jstemplate">generated code</link> for the preview. + A very useful feature for all plugins generating a plot/graph is to provide an automatically updating preview. To do so, you will need two things: Adding a <command><preview></command> check box to your <link linkend="mainxml">GUI definition</link>, and adjusting the <link linkend="jstemplate">generated code</link> for the preview. </para> <para> - Adding a <command><preview></command> checkbox is simple. Just place the following somewhere in your GUI. It will take care of all the behind-the-scenes magic of creating a preview device, updaing the preview whenever the setting have changed, etc. Example: + Adding a <command><preview></command> check box is simple. Just place the following somewhere in your GUI. It will take care of all the behind-the-scenes magic of creating a preview device, updaing the preview whenever the setting have changed, &etc; Example: </para> <programlisting> <document> @@ -1350,13 +1352,13 @@ This chapter contains information on some topics that are useful only to certain And that's it for the GUI definition. </para> <para> - Adjusting the JS template is a little more work. You will have to create a new function called <function>preview()</function> in addition to the <function>preprocess()</function>, <function>calculate()</function>, etc. functions. This function should generate the code needed to produce the plot, and only that. Esp. no printing of headers, <function>rk.graphics.on()</function>, or similar calls. See the <link linkend="plot_plugin_example">example</link>, below for the typical pattern that you will use. + Adjusting the JS template is a little more work. You will have to create a new function called <function>preview()</function> in addition to the <function>preprocess()</function>, <function>calculate()</function>, &etc; functions. This function should generate the code needed to produce the plot, and only that. Esp. no printing of headers, <function>rk.graphics.on()</function>, or similar calls. See the <link linkend="plot_plugin_example">example</link>, below for the typical pattern that you will use. </para> </sect2> <sect2 id="plot_options"> <title>Generic plot options</title> <para> - You will have noticed that most plotting plugins in RKWard provide a wide range of generic options e.g. for customizing axis titles or figure margins. Adding these options to your plugin is easy. They are provided by an <link linkend="embedding">embeddable</link> plugin called <command>rkward::plot_options</command>. Embed this in your plugin UI like this: + You will have noticed that most plotting plugins in RKWard provide a wide range of generic options ⪚ for customizing axis titles or figure margins. Adding these options to your plugin is easy. They are provided by an <link linkend="embedding">embeddable</link> plugin called <command>rkward::plot_options</command>. Embed this in your plugin UI like this: </para> <programlisting> <document> @@ -1393,7 +1395,7 @@ This chapter contains information on some topics that are useful only to certain <programlisting> function preprocess () { // the "somepackage" is needed to create the plot - ecoh ("require (somepackage)\n"); + echo ("require (somepackage)\n"); } function printout () { @@ -1454,7 +1456,7 @@ This chapter contains information on some topics that are useful only to certain <sect2 id="context_x11"> <title>X11 device context</title> <para> - To use a plugin in the context of an x11 device - that is place it in the menu bar of the window you get when you call <function>x11()</function> in the console, first declare it as usual in the <link linkend="pluginmap">&pluginmap; file</link>: + 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 <function>x11()</function> in the console, first declare it as usual in the <link linkend="pluginmap">&pluginmap; file</link>: </para> <programlisting> <document [...]> @@ -1564,15 +1566,15 @@ This chapter contains information on some topics that are useful only to certain } ]]></script> </programlisting> - <para>Here, <parameter>variable</parameter> is a property holding an object name (e.g. inside a <command><varslot></command>). Whenever that changes, you will want to update the display + <para>Here, <parameter>variable</parameter> is a property holding an object name (⪚ inside a <command><varslot></command>). Whenever that changes, you will want to update the display of levels inside the <command><valueselector></command>, named <parameter>selector</parameter>. The key function here is <command>doRCommand()</command>, 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 <command><valueselector></command> remains disabled, while it does not contain up-to-date information. Another thing is that you could potentially have queued more than one command, before you get the first results. This is why every command is given an "id", and we store that in <parameter>last_command_id</parameter> for later reference.</para> <para>When the command is done, the specified callback is called (<parameter>commandFinished</parameter>, in this case) with two parameters: The result itself, and the id of the correspoding - command. The result will be of a type resembling the representation in R, i.e. a numeric Array, if the result is numeric, etc. It can even be an R <command>list()</command>, but in this case + command. The result will be of a type resembling the representation in R, &ie; a numeric Array, if the result is numeric, &etc; It can even be an R <command>list()</command>, but in this case it will be represented as a JS <command>Array()</command> whithout names.</para> - <para>Note that even this example is somewhat simplified. In reality you should take additional precautions, e.g. to avoid putting an extreme amount of levels into the selector. The good news + <para>Note that even this example is somewhat simplified. In reality you should take additional precautions, ⪚ to avoid putting an extreme amount of levels into the selector. The good news is that probably you do not have to do all this yourself. The above example is taken from the <command>rkward::level_select</command> plugin, for instance, which you can simply <link linkend="embedding">embed</link> in your own plugin. This even allows you to specify a different expression to run in place of <command>levels()</command>.</para> </sect1> @@ -1590,7 +1592,7 @@ This chapter contains information on some topics that are useful only to certain <sect1 id="optionset"> <title>Repeating (a set of) options</title> <para> - 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 <command><varslot></command> with <parameter>multi="true"</parameter>. But if you want to extend this, e.g. 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, etc. for each line), or specifying a mapping for recoding from a set of old values to new values. + 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 <command><varslot></command> with <parameter>multi="true"</parameter>. But if you want to extend this, ⪚ 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, &etc; for each line), or specifying a mapping for recoding from a set of old values to new values. </para> <para> Enter the <command><optionset></command>. Let's look at a simple example, first: @@ -1621,8 +1623,8 @@ This chapter contains information on some topics that are useful only to certain </dialog> </programlisting> <para> - Here, we created a UI for specifying a number of persons (e.g. authors). The UI requires at least one entry (<parameter>min_rows="1"</parameter>). Inside the <command><optionset></command>-element, we begin by specifying the - <command><content></command>, i.e. those elements that belong to the option set. You will be familiar with most elements + Here, we created a UI for specifying a number of persons (⪚ authors). The UI requires at least one entry (<parameter>min_rows="1"</parameter>). Inside the <command><optionset></command>-element, we begin by specifying the + <command><content></command>, &ie; those elements that belong to the option set. You will be familiar with most elements inside the <command><content></command>. The <command><optiondisplay></command> is a special element for use in option sets. It lists the current items, allows the user to switch between items, to add or to remove entries. <parameter>index="true"</parameter> means that we want an extra column in the list, showing an index (number) of each item. </para><para> 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 @@ -1652,14 +1654,14 @@ This chapter contains information on some topics that are useful only to certain </dialog> </programlisting> <para> - Of course you can also use <link linkend="logic">UI logic</link> inside an optionset. There are two options for doing this: You can do so by making connection (or scripting) in the main <command><logic></command> section of your plugin, as usual. However, you will access the UI elements in the contents region as (e.g.) "set.contents.firstname.XYZ". Note the prefix "set" (the <parameter>id</parameter> you have assigned to the set and "contents". Alternatively, you can add a separate <command><logic></command> section as a child element of your <command><optionset></command>. In this case, <parameter>id</parameter>s will be addressed relative to the contents region, e.g. "firstname.XYZ". Only the <command><script></command>-element is not allowed in the logic section of an optionset. If you want to use scripting, + Of course you can also use <link linkend="logic">UI logic</link> inside an optionset. There are two options for doing this: You can do so by making connection (or scripting) in the main <command><logic></command> section of your plugin, as usual. However, you will access the UI elements in the contents region as (⪚) "set.contents.firstname.XYZ". Note the prefix "set" (the <parameter>id</parameter> you have assigned to the set and "contents". Alternatively, you can add a separate <command><logic></command> section as a child element of your <command><optionset></command>. In this case, <parameter>id</parameter>s will be addressed relative to the contents region, ⪚ "firstname.XYZ". Only the <command><script></command>-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 <command><logic></command> section. </para> <note> <para> When scripting logic in an optionset, all you can do is access the <emphasis>current</emphasis> content region. Thus, typically, it is only meaningful to connect elements inside the contents region to each other. Connecting a property outside the <command><optionset></command> to a property inside the content region, may be useful for initialization. However, - modifying the contents region after initialzation will <emphasis>not</emphasis> apply to items that the user has already + modifying the contents region after initialization will <emphasis>not</emphasis> apply to items that the user has already defined. Only to the currently selected item in the set. </para> </note> @@ -1707,7 +1709,7 @@ This chapter contains information on some topics that are useful only to certain objects). The purpose of the "vars"-optioncolumn is to serve as the "key" column, as specified by <command><optionset keycolumn="vars"...></command>. 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 <command><varslot></command>. I.e. for each object that is selected there, the <command><optionset></command> will allow to specify line color. + selected objects in the <command><varslot></command>. That is for each object that is selected there, the <command><optionset></command> will allow to specify line color. </para> <note> <para> @@ -1815,7 +1817,7 @@ x </components ...> /> </dependencies> </programlisting> -<para>Currently will neither load, nor install, nor even warn about missing &pluginmap;s, but at least information on dependencies (and where to obtain them) will be shown on the plugin's help page. You do not have to (and you should not) declare dependencies on &pluginmap;s that are shipped with the offical &rkward; distribution, or on &pluginmap;s that are inside your own package. Further, if a required &pluginmap; is <link linkend="external_plugins">distributed as an &r; package</link>, declare a dependency of the package (as shown in the previous section), rather than on the map.</para> +<para>Currently will neither load, nor install, nor even warn about missing &pluginmap;s, but at least information on dependencies (and where to obtain them) will be shown on the plugin's help page. You do not have to (and you should not) declare dependencies on &pluginmap;s that are shipped with the official &rkward; distribution, or on &pluginmap;s that are inside your own package. Further, if a required &pluginmap; is <link linkend="external_plugins">distributed as an &r; package</link>, declare a dependency of the package (as shown in the previous section), rather than on the map.</para> <para>To make sure that required &pluginmap;s are actually loaded, use the <command><require></command>-tag (refer to the <link linkend="pluginmapelements">reference</link> for details).</para> </sect1> <sect1 id="sect_dependencies_example"><title>An example</title> @@ -1874,7 +1876,7 @@ x </components ...> </sect1> <sect1 id="i18n_xml"><title>i18n in &rkward;'s xml files</title> <para> - For &rkward;'s xml files, i18n will mostly just work. If you are writing your own <command>.pluginmap</command> (e.g. for an <link linkend="external_plugins">external plugin</link>), + For &rkward;'s xml files, i18n will mostly just work. If you are writing your own <command>.pluginmap</command> (⪚ for an <link linkend="external_plugins">external plugin</link>), you will have to specify a <replaceable>po_id</replaceable> next to the pluginmap's <replaceable>id</replaceable>. This defines the "message catalog" to use. In general this should be set identical to the <replaceable>id</replaceable> of your <command>.pluginmap</command>, but if you provide several <command>.pluginmap</command>s and want to control, how message catalogs are divided up, this allows you to do so. The <replaceable>po_id</replaceable> is inherited by any <command>.pluginmap</command> you include, unless that declares @@ -1886,13 +1888,13 @@ x </components ...> an <replaceable>i18n_context</replaceable> like this: </para> <programlisting> -<checkbox id="scale" label="Scale" i18n_context="Show the scale"/> -<checkbox id="scale" label="Scale" i18n_context="Scale the plot"/> +<check box id="scale" label="Scale" i18n_context="Show the scale"/> +<check box id="scale" label="Scale" i18n_context="Scale the plot"/> </programlisting> <para> Providing <replaceable>i18n_context</replaceable> 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 <replaceable>i18n_context</replaceable>-attribute is supported on all elements that can have translatable strings, somewhere, including elements that - contain text inside them (e.g. <command><text></command>-elements). + contain text inside them (⪚ <command><text></command>-elements). </para> <para> 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. @@ -1936,7 +1938,7 @@ user (selection from a list of values shown next to this element) --> <variablelist> <varlistentry> <term><command>i18n (msgid, [...])</command></term> - <listitem><para>The most important function. Marks the string for translation. The string (whether translated or not) is returned quoted using double quotes ('"'). An aribtrary + <listitem><para>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.:</para> <programlisting> i18n ("Compare objects %1 and %2", getString ('x'), getString ('y')); @@ -1989,7 +1991,7 @@ user (selection from a list of values shown next to this element) --> </para> <para> That said, it is generally not a good idea to make bits like function names or variable names translatable. For one thing, R, the programming language, is inherently in English, - and there is no internationalization of the lanuage itself. Code comments are a different beast, but you should use the <command>comment()</command>-function for those. Secondly, + and there is no internationalization of the language itself. Code comments are a different beast, but you should use the <command>comment()</command>-function for those. Secondly, making syntactically relevant parts of the generated code translatable means that translations could actually break your plugin. E.g. if an unsuspecting translator translates a string meant as a variable name in two distinct words with a space in between. </para> @@ -2010,7 +2012,7 @@ user (selection from a list of values shown next to this element) --> // js-function "comment" was not defined before 0.6.3 if (typeof (comment) == 'undefined) { // define function i18n(), and any others you may need. Note that your implementation could actually be simpler than - // shown, here, e.g. if you do not make use of placeholders. + // shown, here, ⪚ if you do not make use of placeholders. i18n = function (msgid) { var ret = msgid; for (var i = 1; i < arguments.length; i++) { @@ -2028,7 +2030,7 @@ user (selection from a list of values shown next to this element) --> </sect1> <sect1 id="i18n_workflow"><title>Translation maintainance</title> <para> - Now that you have made your plugin translatable, how do you actually get it translated? In general you only need to worry about this, when develoing an <link linkend="external_plugins"> + Now that you have made your plugin translatable, how do you actually get it translated? In general you only need to worry about this, when developing an <link linkend="external_plugins"> external plugin</link>. For plugins in &rkward;'s main repository, all the magic is done for you. Here's the basic workflow. Note that you need the "gettext" tools, installed: </para> <itemizedlist> @@ -2046,7 +2048,7 @@ user (selection from a list of values shown next to this element) --> <replaceable>--extract-only</replaceable>, this time). This will merge the translation with any interim string changes, compile the translation, and install it into <command><replaceable>DIR_OF_PLUGINMAP</replaceable>/po/<replaceable>xx</replaceable>/LC_MESSAGES/rkward__<replaceable>POID</replaceable>.mo</command> (where <replaceable>xx</replaceable> is the language code, again).</para></listitem> - <listitem><para>You should also include the non-compiled translation (i.e. <command>rkward__<replaceable>POID</replaceable>.<replaceable>xx</replaceable>.po</command>) in + <listitem><para>You should also include the non-compiled translation (&ie; <command>rkward__<replaceable>POID</replaceable>.<replaceable>xx</replaceable>.po</command>) in your distribution, in the "po" subdirectory.</para></listitem> <listitem><para>For any update of your plugin, run <command>python scripts/extract_plugin_messages.py /path/to/my.pluginmap</command> to update the .pot file, but also the existing .po-files, and the compiled message catalogs.</para></listitem> @@ -2116,8 +2118,8 @@ user (selection from a list of values shown next to this element) --> </programlisting> <para>Most of this should explain itself, so we’ll not discuss each and every tag element. But let’s look at some details that probably need some commentary for easier understanding. </para> <para>The <parameter>category</parameter> element in <command><about></command> can be defined rather freely, but should be meaningful, as it’s thought to be used to order plugins into groups. All other attributes in this opening tag are mandatory and must be filled with reasonable content. </para> -<para>At least one <command><author></command> with a valid e-mail address and the role <quote>aut</quote> (<quote>author</quote>) must also be given. In case your plugin causes problems or someone would like to share its gratitude with you, it should be easy to contact someone who’s involved. For further information on other valid roles, like <quote>ctb</quote> for code contributors or <quote>cre</quote> for package maintenance, please refer to the <ulink url="http://stat.ethz.ch/R-manual/R-patched/library/utils/html/person.html">R documentation on <function>person()</function></ulink>. </para> -<note><para>Remember that you can use <command><include></command> and / or <command><insert></command> to repeat information across several .xml files (e.g. information on an author who was involved with several plugins). <link linkend="sect_similar_plugins">More information</link>.</para></note> +<para>At least one <command><author></command> with a valid email address and the role <quote>aut</quote> (<quote>author</quote>) must also be given. In case your plugin causes problems or someone would like to share its gratitude with you, it should be easy to contact someone who’s involved. For further information on other valid roles, like <quote>ctb</quote> for code contributors or <quote>cre</quote> for package maintenance, please refer to the <ulink url="http://stat.ethz.ch/R-manual/R-patched/library/utils/html/person.html">R documentation on <function>person()</function></ulink>. </para> +<note><para>Remember that you can use <command><include></command> and / or <command><insert></command> to repeat information across several .xml files (⪚ information on an author who was involved with several plugins). <link linkend="sect_similar_plugins">More information</link>.</para></note> <tip><para>You don't have to write this XML code by hand. If you use the function <function>rk.plugin.skeleton()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> and provide all necessary information via the <parameter>about</parameter> option, it will automatically create a &pluginmap; file with a working <about> section for you.</para></tip> </chapter> @@ -2145,7 +2147,7 @@ user (selection from a list of values shown next to this element) --> The number of packages to extend the functionality of &r; is immense already, and climbing. On one hand, we want to encourage you to write plugins for even the most specialised tasks you need solved. On the other hand, the average user should not get lost in huge menu trees full of unknown statistical terms. Therefore it seemed reasonable to keep the plugin handling in &rkward; quite modular as well. The &rkward; team maintains its own public package repository at <ulink url="http://files.kde.org/rkward/R">http://files.kde.org/rkward/R</ulink>, designated to host your external plugins. </para> <para> - As a rule of thumb, plugins that seem to serve a widely used purpose (e.g. t-Tests) should become part of the core package, while those who serve a rather limited group of people with special interests should be provided as an optional package. For you as a plugin author it’s best practice to just start with an external plugin. + As a rule of thumb, plugins that seem to serve a widely used purpose (⪚ t-Tests) should become part of the core package, while those who serve a rather limited group of people with special interests should be provided as an optional package. For you as a plugin author it’s best practice to just start with an external plugin. </para> </sect1> @@ -2228,13 +2230,13 @@ user (selection from a list of values shown next to this element) --> <sect3 id="additional_information"> <title>Additional information (optional)</title> <para> - <filename>ChangeLog</filename>, <filename>README</filename>, <filename>AUTHORS</filename>, <filename>LICENSE</filename> should be self-explaining and are entirely optional. Actually, they won’t be interpreted by &rkward;, so they are rather meant to carry additional information that might be relevant e.g. for distributors. Most of their relevant content (author credits, licence terms etc.) will be included in the actual plugin files anyway, though (see the <link linkend="chapter_about_information">section on meta-information</link>). Note that all of these files could also be placed somewhere in the "inst" directory, if you want them not only to be present in the source archive but the installed package as well. + <filename>ChangeLog</filename>, <filename>README</filename>, <filename>AUTHORS</filename>, <filename>LICENSE</filename> should be self-explaining and are entirely optional. Actually, they won’t be interpreted by &rkward;, so they are rather meant to carry additional information that might be relevant ⪚ for distributors. Most of their relevant content (author credits, licence terms &etc;) will be included in the actual plugin files anyway, though (see the <link linkend="chapter_about_information">section on meta-information</link>). Note that all of these files could also be placed somewhere in the "inst" directory, if you want them not only to be present in the source archive but the installed package as well. </para> </sect3> <sect3 id="automated_plugin_testing"> <title>Automated plugin testing (optional)</title> <para> - Another optional directory is "tests", which is meant to provide files needed for <ulink url="http://sourceforge.net/apps/mediawiki/rkward/index.php?title=Automated_Plugin_Testing">automated plugin testing</ulink>. These tests are helpful to quickly check if your plugins still work with new versions of &r; or &rkward;. If you want to include tests, you should really restrain yourself to the naming scheme and hierarchy shown here. That is, tests should reside in a directory called <filename>tests</filename>, which includes a file <filename>testsuite.R</filename> and a folder with tests standards named after the appropriate test suite. You can, however, provide more than one test suite; in that case, if you don’t want to append them all in the one <filename>testsuite.R</filename> file, you can split them in e.g. one file for each test suite and create one <filename>testsuite.R</filename> with <function>source()</function> calls for each suite file. In either case, create separate subdirectories with test + Another optional directory is "tests", which is meant to provide files needed for <ulink url="http://sourceforge.net/apps/mediawiki/rkward/index.php?title=Automated_Plugin_Testing">automated plugin testing</ulink>. These tests are helpful to quickly check if your plugins still work with new versions of &r; or &rkward;. If you want to include tests, you should really restrain yourself to the naming scheme and hierarchy shown here. That is, tests should reside in a directory called <filename>tests</filename>, which includes a file <filename>testsuite.R</filename> and a folder with tests standards named after the appropriate test suite. You can, however, provide more than one test suite; in that case, if you don’t want to append them all in the one <filename>testsuite.R</filename> file, you can split them in ⪚ one file for each test suite and create one <filename>testsuite.R</filename> with <function>source()</function> calls for each suite file. In either case, create separate subdirectories with test standards for each defined suite. </para> <para> @@ -2261,7 +2263,7 @@ standards for each defined suite. <chapter id="rkwarddev"> <title>Plugin development with the <application>rkwarddev</application> package</title> <sect1 id="rkdev_overview"><title>Overview</title> - <para>Writing external plugins involves writing files in three languages (XML, JavaScript and R) and the creation of a standardized hierarchy of directories. To make this a lot easier for willing plugin developers, we're providing the <application>rkwarddev</application> package. It provides a number of simple &r; functions to create the XML code for all dialog elements like tabbooks, checkboxes, dropdownlists or filebrowsers, as well as functions to create JavaScript code and &rkward; help files to start with. The function <function>rk.plugin.skeleton()</function> creates the expected directory tree and all necessary files where they are supposed to be.</para> + <para>Writing external plugins involves writing files in three languages (XML, JavaScript and R) and the creation of a standardized hierarchy of directories. To make this a lot easier for willing plugin developers, we're providing the <application>rkwarddev</application> package. It provides a number of simple &r; functions to create the XML code for all dialog elements like tabbooks, check boxes, dropdownlists or filebrowsers, as well as functions to create JavaScript code and &rkward; help files to start with. The function <function>rk.plugin.skeleton()</function> creates the expected directory tree and all necessary files where they are supposed to be.</para> <para>This package is not installed by default, but has to be installed manually from <ulink url="http://files.kde.org/rkward/R/">&rkward;'s own repository</ulink>. You can either do that by using the GUI interface (<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure packages</guimenuitem></menuchoice>), or from any running &r; session:</para> <programlisting> install.packages("rkwarddev", repos="http://files.kde.org/rkward/R") @@ -2277,7 +2279,7 @@ standards for each defined suite. <tip><para>The package will add a new GUI dialog to &rkward; under <menuchoice><guimenu>File</guimenu><guimenuitem>Export</guimenuitem><guimenuitem>Create &rkward; plugin skeleton</guimenuitem></menuchoice>. Like the name suggests, you can create plugin skeletons for further editing with it. This dialog itself was in turn generated by an <application>rkwarddev</application> script which you can find in the <quote>demo</quote> directory of the installed package and package sources, as an additional example. You can also run it by calling <function>demo("skeleton_dialog")</function></para></tip> <sect2 id="rkdev_gui"><title>GUI description</title> - <para>You will imediately notice that the workflow is considerably different: Contrary to writing the XML code directly, you do not begin with the <command><document></command> definition, but directly with the plugin elements you'd like to have in the dialog. You can assign each interface element -- be it checkboxes, dropdown menus, variable slots or anything else -- to individual &r; objects, and then combine these objects to the actual GUI. The package has functions for <link linkend="interfaceelements">each XML tag</link> that can be used to define the plugin GUI, and most of them even have the same name, only with the prefix <function>rk.XML.*</function>. For example, defining a <command><varselector></command> and two <command><varslot></command> elements for the <replaceable>"x"</replaceable> and <replaceable>"y"</replaceable> variable of the t-test example can be done by:</para> + <para>You will immediately notice that the workflow is considerably different: Contrary to writing the XML code directly, you do not begin with the <command><document></command> definition, but directly with the plugin elements you'd like to have in the dialog. You can assign each interface element -- be it check boxes, dropdown menus, variable slots or anything else -- to individual &r; objects, and then combine these objects to the actual GUI. The package has functions for <link linkend="interfaceelements">each XML tag</link> that can be used to define the plugin GUI, and most of them even have the same name, only with the prefix <function>rk.XML.*</function>. For example, defining a <command><varselector></command> and two <command><varslot></command> elements for the <replaceable>"x"</replaceable> and <replaceable>"y"</replaceable> variable of the t-test example can be done by:</para> <programlisting> variables <- rk.XML.varselector(id.name="vars") var.x <- rk.XML.varslot("compare", source=variables, types="number", required=TRUE, id.name="x") @@ -2312,7 +2314,7 @@ test.hypothesis <- rk.XML.radio("using test hypothesis", <option label="Second is greater" value="less" /> </radio> </programlisting> - <para>All that's missing from the elements of the <quote>Basic settings</quote> tab is the checkbox for paired samples, and the structuring of all of these elements in rows and columns:</para> + <para>All that's missing from the elements of the <quote>Basic settings</quote> tab is the check box for paired samples, and the structuring of all of these elements in rows and columns:</para> <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)) @@ -2329,7 +2331,7 @@ basic.settings <- rk.XML.row(variables, rk.XML.col(var.x, var.y, test.hypothe <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" /> + <check box id="chc_Pardsmpl" label="Paired sample" value="1" value_unchecked="0" /> </column> </row> </programlisting> @@ -2373,9 +2375,9 @@ full.wizard <- rk.XML.wizard( <sect2 id="rkdev_jscode"><title>JavaScript code</title> <para>Until now, using the <application>rkwarddev</application> package might not seem to have helped so much. This is going to change right now.</para> <para>First of all, just like we didn't have to care about IDs for elements when defining the GUI layout, we don't have to care about JavaScript variable names in the next step. If you want more control, you can write plain JavaScript code and have it pasted to the generated file. But it's probably much more efficient to do it the <application>rkwarddev</application> way.</para> - <para>Most notably you don't have to define any variable yourself, as <function>rk.plugin.skeleton()</function> can scan your XML code and automatically define all variables you will probably need -- for instance, you wouldn't bother to include a checkbox if you don't use its value or state afterwards. So we can start writing the actual &r; code generating JS immediately.</para> + <para>Most notably you don't have to define any variable yourself, as <function>rk.plugin.skeleton()</function> can scan your XML code and automatically define all variables you will probably need -- for instance, you wouldn't bother to include a check box if you don't use its value or state afterwards. So we can start writing the actual &r; code generating JS immediately.</para> <tip><para>The function <function>rk.JS.scan()</function> can also scan existing XML files for variables.</para></tip> - <para>The package has some functions for JS code constructs that are commonly used in &rkward; plugins, like the <function>echo()</function> function or <function>if() {...} else {...}</function> conditions. There are some differences between JS and R, e.g., for <function>paste()</function> in &r; you use the comma to concatenate character strings, whereas for <function>echo()</function> in JS... [truncated message content] |