[rkward-cvs] SF.net SVN: rkward:[3370] branches/jss_dec_10/FINAL_JSS_TEX

[tfry at users.sourceforge.net]

Revision: 3370
          http://rkward.svn.sourceforge.net/rkward/?rev=3370&view=rev
Author:   tfry
Date:     2011-01-20 16:47:03 +0000 (Thu, 20 Jan 2011)

Log Message:
-----------
Move comments into the text

Modified Paths:
--------------
    branches/jss_dec_10/FINAL_JSS_TEX/example_plugin.tex
    branches/jss_dec_10/FINAL_JSS_TEX/technical.tex

Modified: branches/jss_dec_10/FINAL_JSS_TEX/example_plugin.tex
===================================================================
--- branches/jss_dec_10/FINAL_JSS_TEX/example_plugin.tex	2011-01-20 16:11:41 UTC (rev 3369)
+++ branches/jss_dec_10/FINAL_JSS_TEX/example_plugin.tex	2011-01-20 16:47:03 UTC (rev 3370)
@@ -11,8 +11,10 @@
 A so called ``.pluginmap'' file declares each plugin, and, if appropriate, defines where it should
 be placed in the menu hierarchy. Usually each .pluginmap file declares many plugins. In this example
 we only show one, namely, a two variable t-test (see Figure~\ref{fig:ttest-gui-example}). 
-The pluginmap (\code{<!DOCTYPE rkpluginmap>}) gives a unique identifier (``id"), the location of the GUI description (``file"), and the window title (``label''). The menu
-is defined in a hierarchical structure, as shown in the code example below\footnote{Long lines are broken at ``$\ldots~\ldots$''.}. Moreover, the position within the menu can be explicitly defined.
+The pluginmap (\code{<!DOCTYPE rkpluginmap>}) gives a unique identifier (``id''), the location of the
+GUI description (``file"), and the window title (``label''). The menu layout is defined in a hierarchical
+structure by nesting \code{<menu>} elements to form toplevel menus and submenus. Menus with the same ``id''
+are merged across .pluginmap files. Moreover, the position within the menu can be explicitly defined (attribute ``index'').
 This might be required if the menu entries are to be ordered non-alphabetically.
 
 \begin{footnotesize}
@@ -21,14 +23,11 @@
 
 <document base_prefix="" namespace="rkward">
   <components>
-    <component type="standard" id="t_test_two_vars" file="analysis/t_test_two_vars.xml" ...
-      ... label="Two Variable t-test" />
+    <component type="standard" id="t_test_two_vars"
+          file="analysis/t_test_two_vars.xml" label="Two Variable t-test" />
   </components>
 
   <hierarchy>
-    <!-- Menu hierarchy can be defined in XML, easily.
-    Menus with the same "id"-attribute will be merged, even if defined in
-    separate .pluginmap files. -->
     <menu id="analysis" label="Analysis" index="4">
       <menu id="means" label="Means" index="4">
         <menu id="ttests" label="t-Tests">
@@ -55,8 +54,9 @@
 The main \proglang{XML} file of each plugin defines the layout and behavior of the GUI, and references the
 \proglang{ECMAScript} file that is used for generating \proglang{R} code from UI settings and the help file (not included in this paper).
 
-GUI logic can be defined directly in the \proglang{XML} file. In this example, the ``Assume equal variances'' checkbox
-is only enabled for paired sample tests. Optionally, GUI behavior can also be scripted in \proglang{ECMAScript}.
+GUI logic can be defined directly in the \proglang{XML} file (the \code{<logic>} element).
+In this example, the ``Assume equal variances'' checkbox is only enabled for paired sample tests.
+Optionally, GUI behavior can also be scripted in \proglang{ECMAScript}.
 
 The \proglang{XML} file defines the t-test plugin (\code{<!DOCTYPE rkplugin>}) to be organized in two tabs (Figure~\ref{fig:t_test}A).
 On the first tab, two variables can be selected (\code{<varslot .../>}). These are set to be ``required'', i.\,e.,
@@ -71,7 +71,6 @@
   <help file="t_test_two_vars.rkh"/>
 
   <logic>
-    <!-- GUI behavior can also be scripted in ECMAScript. -->
     <connect client="varequal.enabled" governor="paired.not"/>
   </logic>
 

Modified: branches/jss_dec_10/FINAL_JSS_TEX/technical.tex
===================================================================
--- branches/jss_dec_10/FINAL_JSS_TEX/technical.tex	2011-01-20 16:11:41 UTC (rev 3369)
+++ branches/jss_dec_10/FINAL_JSS_TEX/technical.tex	2011-01-20 16:47:03 UTC (rev 3370)
@@ -85,25 +85,27 @@
 
 The use of active bindings has significant performance implications when
 objects are accessed very frequently. This is particularly notable where an
-object inside the global environment (i.\,e., an object wrapped into an active
-binding) is used as the index variable in a loop, as illustrated by the
-following example:
+object inside the global environment is used as the index variable in a loop,
+as illustrated by the following example. When control returns to the top level
+prompt, after the first assignment, \code{i} will become subject to object modification
+detection (i.\,e., it will be wrapped into an active
+binding). The subsequent \code{for} loop will then run slow.
 
 \begin{Code}
-# 'i', created below, will be subject to object modification detection
-# as soon as the user command returns
-i <- 1
+R> i <- 1
+R> for (i in 1:100000) i + i
+\end{Code}
 
-# this loop will run slow, since 'i' is stored as an active binding
-for (i in 1:100000) i + i
+In contrast, in the following example, \code{i} is a local object, and will not
+be replaced by an active binding. Therefore the loop will run approximately as fast
+as in a plain \proglang{R} session:
 
-f <- function () {
-    # this loop will run approximately as fast as in plain R
-    # 'i' is a local object in this function, and not subject
-    # to object modification detection
-    for (i in 1:100000) i + i
-}
-f ()
+\begin{Code}
+R> f <- function () {
+R+    i <- 1
+R+    for (i in 1:100000) i + i
+R+ }
+R> f ()
 \end{Code}
 
 Future versions of RKWard will try to avoid this performance problem. 


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.