[rkward-cvs] rkward/doc/en writing_plugins_introduction.docbook,1.2,1.3

[Thomas Friedrichsmeier]

Update of /cvsroot/rkward/rkward/doc/en
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv30705

Modified Files:
	writing_plugins_introduction.docbook 
Log Message:
Fix problem with wrong quotes

Index: writing_plugins_introduction.docbook
===================================================================
RCS file: /cvsroot/rkward/rkward/doc/en/writing_plugins_introduction.docbook,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** writing_plugins_introduction.docbook	22 Mar 2006 17:10:38 -0000	1.2
--- writing_plugins_introduction.docbook	22 Mar 2006 17:27:55 -0000	1.3
***************
*** 119,123 ****
  </programlisting>
  <para>
! The doctype is not really interpreted, but set it to “rkpluginmap” anyway.
  </para>
  <programlisting>
--- 119,123 ----
  </programlisting>
  <para>
! The doctype is not really interpreted, but set it to "rkpluginmap" anyway.
  </para>
  <programlisting>
***************
*** 125,129 ****
  </programlisting>
  <para>
! The “base_prefix”-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. As you will see below, all plugins get a unique identifier. The “namespace” is a way to organized those ids, and make it less likely to create a duplicate identifier accidentally. Internally, basically the namespace and then a “::” gets prepended to all the identifiers you specify below.
  </para>
  <programlisting>
--- 125,129 ----
  </programlisting>
  <para>
! The "base_prefix"-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. As you will see below, all plugins get a unique identifier. The "namespace" is a way to organized those ids, and make it less likely to create a duplicate identifier accidentally. Internally, basically the namespace and then a "::" gets prepended to all the identifiers you specify below.
  </para>
  <programlisting>
***************
*** 137,141 ****
  </programlisting>
  <para>
! First the “type”-attribute: Leave this to “standard” for now. Further types are not yet implemented. The “id” I've already hinted at. Each component has to be given a unique (in its namespace) identifier. Pick one that is easily recognizable. Avoid spaces and any special characters. Those are not banned, so far, but might have special meanings. With the “file” attribute, you specify where the <link linkend="mainxml">description of the actual plugin itself</link> is located. This is relative to the directory the .pluginmap-file is in, and the “base_prefix” above. Finally, give the component a label. This label will be shown whereever the plugin is placed in the menu (or in the future perhaps in other places as well).
  </para>
  <para>
--- 137,141 ----
  </programlisting>
  <para>
! First the "type"-attribute: Leave this to "standard" for now. Further types are not yet implemented. The "id" I've already hinted at. Each component has to be given a unique (in its namespace) identifier. Pick one that is easily recognizable. Avoid spaces and any special characters. Those are not banned, so far, but might have special meanings. With the "file" attribute, you specify where the <link linkend="mainxml">description of the actual plugin itself</link> is located. This is relative to the directory the .pluginmap-file is in, and the "base_prefix" above. Finally, give the component a label. This label will be shown whereever the plugin is placed in the menu (or in the future perhaps in other places as well).
  </para>
  <para>
***************
*** 158,163 ****
  </programlisting>
  <para>
! Right below the <hierarchy>-tag, you start describing, in which menu, your plugins should go. With the above line, you basically say, that your plugin should be in the “Analysis” menu (not necessarily directly there, but in a submenu). The “Analysis” menu is standard in &kapp;, so it does not acutally have to be created from scratch. However, if it did not exist yet, using the “label”-attribute you'd give it its name. The “index” attribute says, that the menu (if newly created) should be placed at the fourth position in the menubar.
! Finally, the “id” once again identifies this menu. This is needed, so several .pluginmap-files can place their plugins in the same menus. They do this by looking for a menu with the given “id”. If the id does not yet exist, a new menu will be created. Otherwise the entries will be added to the existing menu.
  </para>
  <programlisting>
--- 158,163 ----
  </programlisting>
  <para>
! Right below the <hierarchy>-tag, you start describing, in which menu, your plugins should go. With the above line, you basically say, that your plugin should be in the "Analysis" menu (not necessarily directly there, but in a submenu). The "Analysis" menu is standard in &kapp;, so it does not acutally have to be created from scratch. However, if it did not exist yet, using the "label"-attribute you'd give it its name. The "index" attribute says, that the menu (if newly created) should be placed at the fourth position in the menubar.
! Finally, the "id" once again identifies this menu. This is needed, so several .pluginmap-files can place their plugins in the same menus. They do this by looking for a menu with the given "id". If the id does not yet exist, a new menu will be created. Otherwise the entries will be added to the existing menu.
  </para>
  <programlisting>
***************
*** 165,169 ****
  </programlisting>
  <para>
! Basically the same thing here: Now we define a submenu to the “Analysis”-menu. It is to be called “Means”.
  </para>
  <programlisting>
--- 165,169 ----
  </programlisting>
  <para>
! Basically the same thing here: Now we define a submenu to the "Analysis"-menu. It is to be called "Means".
  </para>
  <programlisting>
***************
*** 171,175 ****
  </programlisting>
  <para>
! And a final level in the menu-hierarchy: A sub-menu of the sub-menu “Means”. Note, that if you omit the “index” parameter, the new entry will be placed below any already existing ones.
  </para>
  <programlisting>
--- 171,175 ----
  </programlisting>
  <para>
! And a final level in the menu-hierarchy: A sub-menu of the sub-menu "Means". Note, that if you omit the "index" parameter, the new entry will be placed below any already existing ones.
  </para>
  <programlisting>
***************
*** 177,181 ****
  </programlisting>
  <para>
! Now, finally, this is the menu, we want to place the plugin in. The <entry>-tag signals, this actually is the real thing, instead of another submenu. The “component”-attribute refers to the “id” you gave the plugin/component above.
  </para>
  <programlisting>
--- 177,181 ----
  </programlisting>
  <para>
! Now, finally, this is the menu, we want to place the plugin in. The <entry>-tag signals, this actually is the real thing, instead of another submenu. The "component"-attribute refers to the "id" you gave the plugin/component above.
  </para>
  <programlisting>
***************
*** 184,191 ****
  				<entry component="fictional_t_test" />
  			</menu>
! 			<menu id=”frequency” label=”Frequency” index=”2”/>
  </programlisting>
  <para>
! In case you have lost track: This is another submenu to the “Analysis” menu. See the screenshot below. We'll skip some of what's not visible, marked with [...].
  </para>
  <programlisting>
--- 184,191 ----
  				<entry component="fictional_t_test" />
  			</menu>
! 			<menu id="frequency" label="Frequency" index="2"/>
  </programlisting>
  <para>
! In case you have lost track: This is another submenu to the "Analysis" menu. See the screenshot below. We'll skip some of what's not visible, marked with [...].
  </para>
  <programlisting>
***************
*** 198,202 ****
  </programlisting>
  <para>
! These are the final entries visible in the screenshots below. Note, that you don't need to define the entries in the order they should have in the menu. Use the “index”-attribute instead.
  </para>
  <programlisting>
--- 198,202 ----
  </programlisting>
  <para>
! These are the final entries visible in the screenshots below. Note, that you don't need to define the entries in the order they should have in the menu. Use the "index"-attribute instead.
  </para>
  <programlisting>
***************
*** 206,210 ****
  </programlisting>
  <para>
! Of course you can also place your plugins in menus other than “Analysis”.
  </para>
  <programlisting>
--- 206,210 ----
  </programlisting>
  <para>
! Of course you can also place your plugins in menus other than "Analysis".
  </para>
  <programlisting>
***************
*** 214,218 ****
  </programlisting>
  <para>
! Even in standard-menus such as “File”. All you need is the correct “id”.
  </para>
  <programlisting>
--- 214,218 ----
  </programlisting>
  <para>
! Even in standard-menus such as "File". All you need is the correct "id".
  </para>
  <programlisting>
***************
*** 255,259 ****
  <programlisting>
  <document>
! 	<code file=”code.php”/>
  </programlisting>
  <para>
--- 255,259 ----
  <programlisting>
  <document>
! 	<code file="code.php"/>
  </programlisting>
  <para>
***************
*** 261,265 ****
  </para>
  <programlisting>
! 	<dialog label=”Independent Samples T-Test”>
  </programlisting>
  <para>
--- 261,265 ----
  </para>
  <programlisting>
! 	<dialog label="Independent Samples T-Test">
  </programlisting>
  <para>
***************
*** 271,275 ****
  </programlisting>
  <para>
! GUI-elements can be organized using a tabbook. Here we define a tabbook as the first element in the dialog. Use <tabbook>[...]</tabbook> to define the tabbook and then for each page in the tabbook use <tab>[...]</tab>. The “label”-attribute in the <tab>-element allows you to specify a caption for that page of the tabbook.
  </para>
  <programlisting>
--- 271,275 ----
  </programlisting>
  <para>
! GUI-elements can be organized using a tabbook. Here we define a tabbook as the first element in the dialog. Use <tabbook>[...]</tabbook> to define the tabbook and then for each page in the tabbook use <tab>[...]</tab>. The "label"-attribute in the <tab>-element allows you to specify a caption for that page of the tabbook.
  </para>
  <programlisting>
***************
*** 283,287 ****
  </programlisting>
  <para>
! Using this simple tag you create a list from which the user can select variables. You have to specify an id for this element, so RKWard knows how to find it. Note that you may NOT use a dot (.) in the “id” string.
  </para>
  <programlisting>
--- 283,287 ----
  </programlisting>
  <para>
! Using this simple tag you create a list from which the user can select variables. You have to specify an id for this element, so RKWard knows how to find it. Note that you may NOT use a dot (.) in the "id" string.
  </para>
  <programlisting>
***************
*** 296,300 ****
  </programlisting>
  <para>
! These elements are the counterpart to the <varselector>. They represent “slots” into which the user can put variables. You will note that the “source” is set to the same value as the “id” of the <varselector>. This means, the <varslot>s will each take their variables from the varselector. The <varslot>s also have to be given an “id”. They may have a label, and they may be set to “required”. This means that the submit-button will not be enabled until the <varslot> holds a valid value. Finally the “type”-attribute is not interpreted, yet, but it will be used to take care that only the correct types of variables will be allowed in the <varslot>.
  </para>
  <programlisting>
--- 296,300 ----
  </programlisting>
  <para>
! These elements are the counterpart to the <varselector>. They represent "slots" into which the user can put variables. You will note that the "source" is set to the same value as the "id" of the <varselector>. This means, the <varslot>s will each take their variables from the varselector. The <varslot>s also have to be given an "id". They may have a label, and they may be set to "required". This means that the submit-button will not be enabled until the <varslot> holds a valid value. Finally the "type"-attribute is not interpreted, yet, but it will be used to take care that only the correct types of variables will be allowed in the <varslot>.
  </para>
  <programlisting>
***************
*** 306,310 ****
  </programlisting>
  <para>
! Here, you define a group of <radio>-exclusive buttons. The group has a “label” and an “id”. Each <option> (button) has a label and is assigned a value. This is the value the <radio>-element will return when the option is selected.
  </para>
  <programlisting>
--- 306,310 ----
  </programlisting>
  <para>
! Here, you define a group of <radio>-exclusive buttons. The group has a "label" and an "id". Each <option> (button) has a label and is assigned a value. This is the value the <radio>-element will return when the option is selected.
  </para>
  <programlisting>
***************
*** 328,332 ****
  </screenshot>
  <para>
! Note that we have not specified the “Submit”, “Close”, etc. buttons or the code-view. Those elements get generated automatically. But of course we still have to define the second page of the <tabbook>:
  </para>
  <programlisting>
--- 328,332 ----
  </screenshot>
  <para>
! Note that we have not specified the "Submit", "Close", etc. buttons or the code-view. Those elements get generated automatically. But of course we still have to define the second page of the <tabbook>:
  </para>
  <programlisting>
***************
*** 335,339 ****
  </programlisting>
  <para>
! By default elements will be placed top-to-bottom like in a <column>. Since that is what we want here, we don't have to explicitly state a <row> or <column>-layout. The first element we define is a checkbox. Just like the <radio><option>s, the checkbox has a “label” and a “value”. The “value” is what gets returned, if the checkbox is checked. Of course the checkbox also needs an “id”.
  </para>
  <programlisting>
--- 335,339 ----
  </programlisting>
  <para>
! By default elements will be placed top-to-bottom like in a <column>. Since that is what we want here, we don't have to explicitly state a <row> or <column>-layout. The first element we define is a checkbox. Just like the <radio><option>s, the checkbox has a "label" and a "value". The "value" is what gets returned, if the checkbox is checked. Of course the checkbox also needs an "id".
  </para>
  <programlisting>
***************
*** 341,345 ****
  </programlisting>
  <para>
! Here's yet another layout-element: In order to signal that the two elements below  belong together, we draw a <frame> (box). That frame may have a caption. Since the frame is just a passive layout-element, it does not need an “id”.
  </para>
  <programlisting>
--- 341,345 ----
  </programlisting>
  <para>
! Here's yet another layout-element: In order to signal that the two elements below  belong together, we draw a <frame> (box). That frame may have a caption. Since the frame is just a passive layout-element, it does not need an "id".
  </para>
  <programlisting>
***************
*** 349,353 ****
  </programlisting>
  <para>
! Inside the <frame> we place another <checkbox> (using checked=”true”, we signal that checkbox should be checked by default), and a <spinbox>. The spinbox allows the user to select a value between “min” and “max” with the default/initial value “0.95”. Setting the “type” to “real” signals that real number are accepted as opposed to type=”integer” which would accept integers only.
  </para>
  <programlisting>
--- 349,353 ----
  </programlisting>
  <para>
! Inside the <frame> we place another <checkbox> (using checked="true", we signal that checkbox should be checked by default), and a <spinbox>. The spinbox allows the user to select a value between "min" and "max" with the default/initial value "0.95". Setting the "type" to "real" signals that real number are accepted as opposed to type="integer" which would accept integers only.
  </para>
  <programlisting>
***************
*** 360,364 ****
  </para>
  <programlisting>
! 	<wizard label=”Independent Samples 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>
--- 360,364 ----
  </para>
  <programlisting>
! 	<wizard label="Independent Samples 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>
***************
*** 403,407 ****
  <title>Generating R code from GUI settings</title>
  <para>
! Now we have a GUI defined, but we still need to generate some R-code from that. For that, we need another text-file, “code.php”, located in the same directory as the <link linkend="mainxml">description.xml</link>. You may or may not be familiar with PHP. Documentation on PHP can be found here: http://www.php.net. But for most purposes you will not need to know much about PHP at all, as we'll only use some very basic features..
  </para>
  <para>
--- 403,407 ----
  <title>Generating R code from GUI settings</title>
  <para>
! Now we have a GUI defined, but we still need to generate some R-code from that. For that, we need another text-file, "code.php", located in the same directory as the <link linkend="mainxml">description.xml</link>. You may or may not be familiar with PHP. Documentation on PHP can be found here: http://www.php.net. But for most purposes you will not need to know much about PHP at all, as we'll only use some very basic features..
  </para>
  <para>
***************
*** 423,427 ****
  <programlisting>
  	function calculate () {
! ?>rk.temp <- t.test (<? getRK ("x"); ?>, <? getRK ("y"); ?>, "<? getRK ("hypothesis"); ?>"<? getRK (“varequal”); if (($conflevel = getRK_val ("conflevel")) != "0.95") echo (", conf.level=" . $conflevel); ?>)
  <?
  	}
--- 423,427 ----
  <programlisting>
  	function calculate () {
! ?>rk.temp <- t.test (<? getRK ("x"); ?>, <? getRK ("y"); ?>, "<? getRK ("hypothesis"); ?>"<? getRK ("varequal"); if (($conflevel = getRK_val ("conflevel")) != "0.95") echo (", conf.level=" . $conflevel); ?>)
  <?
  	}
***************
*** 432,447 ****
  </para>
  <screen>
! “rk.temp <- t.test (“
  </screen>
  <para>
! as plain text. Next we need to fill in the value, the user selected as the first variable. Hence we enter PHP-mode again (<?) and call 'getRK (“x”);'. This prints out the value of the GUI-element with id “x”: our first <varslot>. Next we leave PHP-mode again, print a ', ', and do the same to fetch the value of the element “y” - the second <varslot>. For the hypothesis (the <radio>-group), and the equal variances-<checkbox>, the procedure is very similar.
  </para>
  <para>
! It gets a little more tricky for the confidence level. For reasons of aestethics, we don't want to explicitly specify the confidence level to use, if it corresponds to the default value. Hence, instead of printing the value with 'getRK', we fetch it silently using 'getRK_val' and assign it to a PHP-variable. We then check, whether that variable differs from “0.95” and if so print out an additional argument.
  Finally, we leave PHP-mode again, print a last ')', and that's it for the calculate-function.
  </para>
  <programlisting>
  	function printout () {
! <? rk.print (rk.temp); ?>
  	}
  </programlisting>
--- 432,448 ----
  </para>
  <screen>
! rk.temp <- t.test (
  </screen>
  <para>
! as plain text. Next we need to fill in the value, the user selected as the first variable. Hence we enter PHP-mode again (<?) and call 'getRK ("x");'. This prints out the value of the GUI-element with id "x": our first <varslot>. Next we leave PHP-mode again, print a ', ', and do the same to fetch the value of the element "y" - the second <varslot>. For the hypothesis (the <radio>-group), and the equal variances-<checkbox>, the procedure is very similar.
  </para>
  <para>
! It gets a little more tricky for the confidence level. For reasons of aestethics, we don't want to explicitly specify the confidence level to use, if it corresponds to the default value. Hence, instead of printing the value with 'getRK', we fetch it silently using 'getRK_val' and assign it to a PHP-variable. We then check, whether that variable differs from "0.95" and if so print out an additional argument.
  Finally, we leave PHP-mode again, print a last ')', and that's it for the calculate-function.
  </para>
  <programlisting>
  	function printout () {
! ?>rk.print (rk.temp);
! <?
  	}
  </programlisting>
***************
*** 460,464 ****
  </programlisting>
  <para>
! Finally, in the function cleanup we discard the temporary object(s) we left in the R-workspace. You should always clean up all objects created while running the plugin, except the user explicitely requested otherwise.
  </para>
  </chapter>
--- 461,468 ----
  </programlisting>
  <para>
! Finally, in the function cleanup we discard the temporary object(s) we left in the R-workspace. You should always clean up all objects created while running the plugin, except if the user explicitely requested otherwise.
! </para>
! <para>
! Congratulations! You created your first plugin. Read on in the next chapters for more advanced concepts
  </para>
  </chapter>
***************
*** 467,470 ****
--- 471,478 ----
  <title>GUI logic</title>
  <para>
+ All the basic concepts of creating a plugin for &kapp; have been described in the previous chapters. Those basic concepts should be sufficient for many - if not most - cases. However, sometimes you want more control over how your plugin's GUI behaves.
+ </para>
+ <para>
+ For instance
  </para>
  </chapter>