[rkward] doc/rkwardplugins: updated plugin docs

[m.eik michalke]

Git commit 6986de60220abc576f719550ac39eebbe64bed03 by m.eik michalke.
Committed on 13/11/2015 at 14:14.
Pushed by meikm into branch 'master'.

updated plugin docs

  - added info on i18n and help pages with rkwarddev

M  +67   -1    doc/rkwardplugins/index.docbook

http://commits.kde.org/rkward/6986de60220abc576f719550ac39eebbe64bed03

diff --git a/doc/rkwardplugins/index.docbook b/doc/rkwardplugins/index.docbook
index 5a95499..59186b5 100644
--- a/doc/rkwardplugins/index.docbook
+++ b/doc/rkwardplugins/index.docbook
@@ -2409,7 +2409,7 @@ JS.calc <- rk.paste.JS(
 JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
 		</programlisting>
 		<para>As you can see, <application>rkwarddev</application> also provides an &r; implementation of the <function>echo()</function> function. It returns exactly one character string with a valid JS version of itself. You might also notice that all of the &r; objects here are the ones we created earlier. They will automatically be replaced with their variable names, so this should be quite intuitive. Whenever you need just this replacement, the function <function>id()</function> can be used, which also will return exactly one character string from all the objects it was given (you could say it behaves like <function>paste()</function> with a very specific object substitution).</para>
-		<para>The function name <function>ite()</function> is an abbreviation for <quote>if, then, else</quote>, and these three conditional statements are exactly what its three optional arguments are for -- although our example only uses two, so we're dealing with three <quote>if, then</quote> conditions here. Maybe it's best to just look at the above <quote>JS.calc</quote> object, which now contains a character string with this content:</para>
+    <para>The <function>js()</function> function is a wrapper that allows you to use &r;'s <command>if(){...} else {...}</command> conditions like you are used to. They will be translated directly into JS code. It also preserves some operators like <command><</command>, <command>>=</command> or <command>||</command>, so you can logically compare your &r; objects without the need for quoting most of the time. Let's have a look at the resulting <quote>JS.calc</quote> object, which now contains a character string with this content:</para>
 		<programlisting>
 	echo("res <- t.test (x=" + vrslCompare + ", y=" + vrslAgainst + ", hypothesis=\"" + radUsngtsth + "\"");
 	if(chcPardsmpl) {
@@ -2423,6 +2423,11 @@ JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
 	} else {}
 	echo(")\n");
 		</programlisting>
+    <note>
+      <para>
+        Alternatively for <function>if()</function> conditions nested in <function>js()</function>, you can use the <function>ite()</function> function, which behaves similar to &r;'s <function>ifelse()</function>. However, conditional statements constructed using <function>ite()</function> are usually harder to read and should be replaced by <function>js()</function> whenever possible.
+      </para>
+    </note>
 		</sect2>
 
 		<sect2 id="rkdev_pluginmap"><title>Plugin map</title>
@@ -2546,7 +2551,68 @@ local({
 		</programlisting>
 		</sect2>
 
+  </sect1>
+  <sect1 id="i18n_rkwarddev"><title>Adding help pages</title>
+    <para>
+      If you want to write a help page for your plugin, the most straight forward way to do so is to add the particular instructions directly to the definitions of the XML elements they belong to:
+    </para>
+    <programlisting>
+variables <- rk.XML.varselector(
+  id.name="vars",
+  help="Select the data object you would like to analyse.",
+  component="Data"
+)
+    </programlisting>
+    <para>
+      The text given to the <parameter>help</parameter> parameter can then be fetched by <function>rk.rkh.scan()</function> and written to the help page of this plugin component. For this to work technically, however, <function>rk.rkh.scan()</function> must know which &r; objects belong to one plugin component. This is why you must also provide the <parameter>component</parameter> parameter and make sure it is identical for all objects belonging together.
+    </para>
+    <para>
+      Since you will usually combine many objects into one dialog and might also like to be able to re-use objects like the <command><varslot></command> in multiple components of your plugins, it is possible to globally define a component with the <function>rk.set.comp()</function>. If set, it is assumend that all the following objects used in your script belong to that particular component, until <function>rk.set.comp()</function> is being called again with a different component name. You can then omit the <parameter>component</parameter> parameter:
+    </para>
+    <programlisting>
+rk.set.comp("Data")
+variables <- rk.XML.varselector(
+  id.name="vars",
+  help="Select the data object you would like to analyse."
+)
+    </programlisting>
+    <para>
+      To add global sections like <command><summary></command> or <command><usage></command> to the help page, you use functions like <function>rk.rkh.summary()</function> or <function>rk.rkh.usage()</function> accordingly. Their results are then used to set the list elements like <parameter>summary</parameter> or <parameter>usage</parameter> in the <parameter>rkh</parameter> parameter of <function>rk.plugin.component()</function>/<function>rk.plugin.skeleton()</function>.
+    <para>
 	</sect1>
+  <sect1 id="i18n_rkwarddev"><title>Translating plugins</title>
+    <para>
+      The <application>rkwarddev</application> 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 <replaceable>i18n_context</replaceable> or <replaceable>noi18n_label</replaceable>:
+    </para>
+    <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)
+    </programlisting>
+    <para>The above examples produce output like this:</para>
+    <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" />
+    </programlisting>
+    <para>
+      There's also support for translatable JS code. In fact, the package tries add <function>i18n()</function> calls by default in places where this is usually helpful. The <function>rk.JS.header()</function> function is a good example:
+    </para>
+    <programlisting>
+jsHeader <- rk.JS.header("Test results")
+    </programlisting>
+    <para>This produces the following JS code:</para>
+    <programlisting>
+new Header(i18n("Test results")).print();
+    </programlisting>
+    <para>But you can also manually mark strings in your JS code as translatable, by using the <function>i18n()</function> function just like you would if you wrote the JS file directly.</para>
+  </sect1>
 </chapter>
 
 <appendix id="reference">