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

tfry at users.sourceforge.net tfry at users.sourceforge.net
Thu Dec 16 17:57:12 UTC 2010

Revision: 3254
http://rkward.svn.sourceforge.net/rkward/?rev=3254&view=rev
Author:   tfry
Date:     2010-12-16 17:57:12 +0000 (Thu, 16 Dec 2010)

Log Message:
-----------
Fix some references

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

Modified: branches/jss_dec_10/FINAL_JSS_TEX/background.tex
===================================================================
--- branches/jss_dec_10/FINAL_JSS_TEX/background.tex	2010-12-16 16:07:50 UTC (rev 3253)
+++ branches/jss_dec_10/FINAL_JSS_TEX/background.tex	2010-12-16 17:57:12 UTC (rev 3254)
@@ -1,14 +1,15 @@
-\section[Background and motivation]{Background and motivation}
+\section{Background and motivation}
+\label{background}
In mid 1993 Ihaka and Gentleman published initial efforts on the computing
language and programming environment \proglang{R} on the s-news mailing list. Ambitions for
this project aimed to develop an \proglang{S}-like language but without inheriting memory
and performance issues. The source code of R was finally released in 1995 and
development has since evolved under the umbrella of the R Development Core Team
since mid 1997 \citep{RDCT2001, RDCT2010, Ihaka_Gentlemen_1993}.
-\proglang{R} does not include an advanced cross-platform GUI (Graphical User Interface) as known from other
+\proglang{R} does not include an advanced cross-platform GUI (graphical user interface) as known from other
statistical software packages. However, \proglang{R} includes tools for building GUIs
mainly based on Tlc/Tk \citep{Dalgaard2001, Dalgaard2002}. Since then a
-plethora of R GUIs have emerged (see \url{http://www.sciviews.org/_rgui/} for a
+plethora of \proglang{R} GUIs have emerged (see \url{http://www.sciviews.org/_rgui/} for a
comprehensive list). In 2005 John Fox released version 1.0 of R Commander which
can be considered a milestone in \proglang{R} GUI development; this was the first GUI
implementation which was able to deliver the experience of statistical tests,
@@ -25,14 +26,14 @@
immediately, without having to learn anything about the \proglang{R} programming language,
first. At the same time RKWard tries to support users who want to learn and
exploit the full flexibility of the \proglang{R} language for automating or customizing
-analyses. At the other end of the learning curve, RKWard provides advanced IDE (Integrated Development Environment)
+analyses. At the other end of the learning curve, RKWard provides advanced IDE (integrated development environment)
features to \proglang{R} experts to assist in the development of \proglang{R} scripts. Yet, the idea
is that \proglang{R} experts, too will benefit from the availability task-oriented GUI
dialogs from time to time, such as when exploring an unfamiliar type of analysis
or by allowing to implement routinely performed tasks as a GUI element. In
addition, many features, such as the integrated data editor, or the plot preview
feature will be useful to \proglang{R} novices and \proglang{R} experts alike in their everyday work
-(see section \ref{Default Graphical User Interface Elements}).
+(see section \ref{sec:usage}).

%% TODO: TF: I have edited this section (and the following) a bit more. Please take a look.
RKWard provides a high level of transparency about the steps that are needed to
@@ -55,14 +56,14 @@
artificial limitations on how users can work with the application. For example,
the user is not limited to using only one \code{data.frame} or one model at a
time, in RKWard. RKWard is designed to allow users to create custom GUI dialogs
-easily (see sections \ref{technical_plugins} and \ref{example_plugins}).
+easily (see sections \ref{sec:technical_plugins} and \ref{sec:example_plugins}).

%% TODO: TF: I've removed the reference to Beta''-status. It's just an arbitrary estimate without a real definition, anyway.
-or later. However, due to its dependencies, RKWard binaries are effctively
-distributable only under the terms of the GPL v 2. Some documentation templates are
-GFDL (GNU Free Documentation License) licensed. While the project remains in constant development, a growing
+or later. However, due to its dependencies, RKWard binaries are effectively
+distributable only under the terms of the GPL Version 2. Parts of the documentation are
+GFDL (GNU free documentation license) licensed. While the project remains in constant development, a growing
number of users employs RKWard in productive scenarios. The source code,
selected binaries and documentation is hosted at SourceForge
(\url{http://sourceforge.net/}). Some key milestones of the development of RKWard are

Modified: branches/jss_dec_10/FINAL_JSS_TEX/technical.tex
===================================================================
--- branches/jss_dec_10/FINAL_JSS_TEX/technical.tex	2010-12-16 16:07:50 UTC (rev 3253)
+++ branches/jss_dec_10/FINAL_JSS_TEX/technical.tex	2010-12-16 17:57:12 UTC (rev 3254)
@@ -1,17 +1,19 @@
-\section[technical]{Technical Design}
+\section{Technical Design}
+\label{sec:technical}
In this section we will give a compact overview over key aspects of RKWards
technical design. We will give slightly more attention to the details of the
plugin framework used in RKWard, since this is central to the extensibility of
RKWard.

-\subsection[technical_asynchronous]{Asynchronous command execution}
+\subsection{Asynchronous command execution}
+\label{sec:technical_asynchronous}
One central design decision in the implementation of RKWard is that the
interface to the \proglang{R} engine operates asynchronous. The intention is to
remain the application usable to a high degree, even during the computation of
time-consuming analyses. For instance while waiting for the estimation of a
complex model to complete, the user should be able to continue to use the GUI to
prepare the next analysis. Asynchronous command execution is also a prerequisite
-for a implementation of the plot-preview feature (see Section~\ref{usage_plotpreview}). Commands
+for a implementation of the plot-preview feature (see Section~\ref{sec:usage_plotpreview}). Commands
generated from plugins or user actions are placed in queue and are evaluated in
a separate thread in the order they were submitted\footnote{
It is possible, and in some cases necessary to enforce a different order of command execution in
@@ -21,11 +23,11 @@
}. The asynchronous design implies that RKWard avoids to rely on the
\proglang{R} engine during interactive use. This is one of several reasons for
the use of \proglang{ECMAScript} in plugins, instead of scripting using
-\proglang{R} (see Sections~\ref{technical_toolkit} and \ref{technical_plugins}).
+\proglang{R} (see Sections~\ref{sec:technical_toolkit} and \ref{sec:technical_plugins}).
A further implication is that RKWard avoids quering information about the
existence and properties of objects in \proglang{R}, interactively. Rather
RKWard keeps a representation of \proglang{R} objects and their basic properties
-(e.g. class and dimensions), which is used for the workspace browser (Section~\ref{usage_browser}),
+(e.g. class and dimensions), which is used for the workspace browser (Section~\ref{sec:usage_browser}),
object name completion, function argument hinting and
other occasions. The object representation includes objects in all environments
on the search path, and any objects contained within these environments in a
@@ -44,7 +46,10 @@
of \proglang{R} commands has even been moved into a separate process. In the somewhat longer term it could even
be possible to run GUI and \proglang{R} engine on different computers.

-\subsection[technical_omd]{Object modification detection}
+%% TODO: Add figure (and reference it)
+
+\subsection{Object modification detection}
+\label{sec:technical_omd}
RKWard allows the user to run arbitrary commands in \proglang{R} at any time, even while
editing a \code{data.frame} or while selecting objects for analysis in a GUI dialog. Any user
command could potentially add, modify, or remove objects in \proglang{R}. RKWard tries to
@@ -52,7 +57,7 @@
workspace browser, object selection lists, and object views. Beyond that,
detecting any changes is particularly important with respect to objects which
are currently opened for editing in the data editor (which provides an illusion
-of in-place editing, see Section~\ref{usage_dataeditor}). Here, it is necessary to synchronize
+of in-place editing, see Section~\ref{sec:usage_dataeditor}). Here, it is necessary to synchronize
the data between \proglang{R} and the GUI in both directions.

For simplicity and performance, object modification detection is only
@@ -98,7 +103,8 @@
and performance overhead. Special handling will be needed for environments and
active bindings.

-\subsection[technical_toolkit]{Choice of toolkit and implementation languages}
+\subsection{Choice of toolkit and implementation languages}
+\label{sec:technical_toolkit}
In addition to \proglang{R}, RKWard is based on the \proglang{KDE} libraries, which are in turn based
on \proglang{Qt}, and implemented mostly in \proglang{C++}. Compared to many competing libraries,
this constitutes a rather heavy dependency. Moreover, the \proglang{KDE} libraries are
@@ -122,7 +128,7 @@
the various components of RKWard.

Plugins in RKWard rely on \proglang{XML} (Extensible Markup Language)\footnote{\url{http://www.w3.org/XML/}}
-and \proglang{ECMAScript}\footnote{\url{http://www.ecmascript.org/}} (see Section~\ref{technical_plugins}). \proglang{XML} is not
+and \proglang{ECMAScript}\footnote{\url{http://www.ecmascript.org/}} (see Section~\ref{sec:technical_plugins}). \proglang{XML} is not
only well suited to describe the layout of the GUI of plugins, but simple
functional logic can also be represented \citep{Visne2009}. \proglang{ECMAScript} was
chosen for the generation of \proglang{R} commands within plugins in particular due to its
@@ -134,7 +140,8 @@
strings with the \code{+}-operator, as available in \proglang{ECMAScript}, allows for a much
more readable way to perform such text concatenation.

-\subsection[technical_graphics]{Onscreen graphics windows}
+\subsection{Onscreen graphics windows}
+\label{sec:technical_graphics}
Contrary to the approach used in \pkg{JGR} \citep{HelbigTheus2005}, RKWard does
not technically provide a custom on-screen graphics device. RKWard detects when
new graphics windows are created via calls to \code{X11()} or \code{windows()}. These windows
@@ -174,7 +181,8 @@
for non-sequential browsing (see Figure~\ref{fig:plot_history}) providing a very intuitive browsing
interface unlike the implementation for windows or quartz devices.

-\subsection[technical_plugins]{Plugin infrastructure}
+\subsection{Plugin infrastructure}
+\label{sec:technical_plugins}
One of the earliest features of RKWard was the extensibility by plugins.
Basically, plugins in RKWard provide complete GUI-dialogs, or re-useable
GUI-components, which accept user settings, and translate those user settings
@@ -190,8 +198,9 @@
especially for Item response theory (IRT), distributions and descriptive
statistical analysis.

-\subsubsection[technical_plugins_defining]{Defining a plugin}
-Plugins consist of four parts \citep[see Section~\ref{example_plugin} for an example; for a complete
+\subsubsection{Defining a plugin}
+\label{sec:technical_plugins_defining}
+Plugins consist of four parts \citep[see Section~\ref{sec:example_plugin} for an example; for a complete
manual, see][]{Friedrichsmeier2010}:

%% TODO: Make these bullets!
@@ -237,7 +246,8 @@

Basically the source code of these elements can be changed without a requirement to recompile.

-\subsubsection[technical_plugins_embedding]{Embedding and reuse of plugins}
+\subsubsection{Embedding and reuse of plugins}
+\label{sec:technical_plugins_embedding}
RKWard supports several mechanisms for modularization and re-use of
functionality in plugins. File inclusion is one very simple but effective
mechanism, which can be used in the \proglang{ECMAScript} files but is also supported in
@@ -254,7 +264,8 @@
code. Other examples of embedded plugins are options for histograms, barplots,
and ECDF plots (which in turn embed the generic plot options plugin).

-\subsubsection[technical_plugins_consistency]{Enforcing a consistent interface}
+\subsubsection{Enforcing a consistent interface}
+\label{sec:technical_plugins_consistency}
RKWard tries to make it easy to create a consistent interface in all plugins.
GUI-wise this is supported by providing high-level GUI elements, and embeddable
clients. Also, the standard-elements of each dialog (Submit'', and
@@ -271,7 +282,7 @@
\code{HTML()}-function of the \pkg{R2HTML}-package \citep{Lecoutre2003} in the current
implementation. The use of custom formatting with \proglang{HTML} is possible, but
discouraged. Standard elements such as a horizontal separator, and the run-again
-link (see Section~\ref{usage_output}) are inserted automatically, without the need to define
+link (see Section~\ref{sec:usage_output}) are inserted automatically, without the need to define
them for each plugin.

Regarding the style of the generated \proglang{R} code, enforcing consistency is harder,
@@ -289,7 +300,8 @@
those computations, transparently.
\end{itemize}

-\subsubsection[technical_plugins_dependencies]{Handling of \proglang{R} package dependencies}
+\subsubsection{Handling of R package dependencies}
+\label{sec:technical_plugins_dependencies}
A wide range of plugins for diverse functionality is present in RKWard,
including plots (e.g. boxplot) or standard tests (e.g. Student's t-Test)\footnote{
At the time of this writing, there are 164 user-accessible plugins in RKWard.
@@ -298,7 +310,7 @@
of the plugins depend on \proglang{R} packages other than the recommended \proglang{R} base packages.
Examples herein are the calculation of kurtosis, skewness or the exact Wilcoxon
test. Installation of additional packages is handled automatically by RKWard
-(see Section~\ref{usage_packages}).
+(see Section~\ref{sec:usage_packages}).

plugins which depend on certain package simply include an appropriate call to
@@ -309,8 +321,9 @@

Dependencies between (embedded) plugins are handled using the \code{<require>}-tag in the plugin map.

-\subsection[technical_processes]{Development process}
-\subsubsection[technical_processes_plugins]{RKWard core and external plugins}
+\subsection{Development process}
+\subsubsection{RKWard core and external plugins}
+\label{sec:technical_processes_plugins}
Newly developed plugins are placed in a dedicated plugin map called
under\_development.pluginmap. Plugins in this map are not visible to the user by
default, but need to be enabled manually. Once the author(s) of a plugin
@@ -324,7 +337,8 @@
plugins from the Internet, which are not officially included or supported by the
RKWard developers.

-\subsubsection[technical_processes_automatedtesting]{Automated testing}
+\subsubsection{Automated testing}
+\label{sec:technical_processes_automatedtesting}
A second requirement for new plugins is that each plugin must be accompanied by
at least one automated test. The automated testing framework in RKWard consists
of a set of \proglang{R} scripts which allow to run a plugin with specific GUI settings,
@@ -339,7 +353,8 @@
application which are not implemented as plugins, but this is currently limited
to very few basic tests.

-\subsection[technical_internationalization]{Internationalization}
+\subsection{Internationalization}
+\label{sec:technical_internationalization}
Currently strings in the main application are translated to varying extents in
Czech (cs), Catalan (ca), Spanish (es), German (de), Chinese (zh\_CN), Turkish
(tr), Polish (pl), Italian (it), French (fr), Greek (el), and Danish (da).

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