# [rkward-cvs] SF.net SVN: rkward:[3921] trunk/rkward/packages/rkwarddev

m-eik at users.sourceforge.net m-eik at users.sourceforge.net
Mon Oct 10 21:11:35 UTC 2011

Revision: 3921
http://rkward.svn.sourceforge.net/rkward/?rev=3921&view=rev
Author:   m-eik
Date:     2011-10-10 21:11:35 +0000 (Mon, 10 Oct 2011)
Log Message:
-----------
rkwarddev: began to write vignette

Modified Paths:
--------------
trunk/rkward/packages/rkwarddev/ChangeLog
trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.Rnw

-----------
trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.pdf
trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.tex

Modified: trunk/rkward/packages/rkwarddev/ChangeLog
===================================================================
--- trunk/rkward/packages/rkwarddev/ChangeLog	2011-10-10 15:21:12 UTC (rev 3920)
+++ trunk/rkward/packages/rkwarddev/ChangeLog	2011-10-10 21:11:35 UTC (rev 3921)
@@ -8,6 +8,7 @@
files need to be generated
- cleaned up rk.XML.pluginmap() and rk.XML.plugin() hint code
- changed "nodes" option to "..." also in rk.XML.menu()
+  - added beginnings of a vignette (to be continued...)

## 0.03-3 (2011-10-09)
- replaced most of the "nodes" and "children" options with "..." in functions rk.rkh.related(), rk.rkh.settings(),

Modified: trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.Rnw
===================================================================
--- trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.Rnw	2011-10-10 15:21:12 UTC (rev 3920)
+++ trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.Rnw	2011-10-10 21:11:35 UTC (rev 3921)
@@ -3,7 +3,7 @@
\usepackage{apacite}

%opening
-\title{RKWard plugin development with the \code{rkwarddev} package}
+\title{RKWard plugin development with the \texttt{rkwarddev} package}
%\VignetteIndexEntry{RKWard plugin development with the rkwarddev package}
\author{m.eik michalke}

@@ -11,11 +11,77 @@

\maketitle

-%  \begin{abstract}
-%  \end{abstract}
+\begin{abstract}
+Writing plugins for \verb at RKWard@ means writing at least two XML files (a GUI description and a plugin map),
+one JavaScript file (to create the \verb at R@ code), maybe a help file (again in XML), and for plugins who
+should be distributed, a DESCRIPTION file. Furtermore, all of these files need to be in a certain directory
+structure.

-%  \section{}
+The \verb at rkwarddev@ package aims to simplify this, by enabling you to fulfill all the listed tasks in just
+one \verb at R@ script.
+\end{abstract}

+You might ask why you should write R scripts to generate plugins, if you could just directly write the XML
+and JavaScript files. First of all, you don't have to use this package at all, it's totally fine to code your
+plugins however you like. The main reason why I wrote this package is that I like to really concentrate on
+what I'm doing, so this is my attempt to avoid the need to switch between three different languages all the
+time. I wanted to be able to constantly ''think in \verb at R@ while working on a plugin. As a side effect, a
+lot of useful automation was implemented, and using this package will definitely save you quite some amount of
+typing.
+
+\section{Before we start}
+It is important to undertsand that while \verb at rkwarddev@ can help you to make designing new plugins
+much easier, you still need to know how the generated XML and JavaScript files work and interact. That is, if
+you didn't yet read the \textit{Introduction to Writing Plugins for
+you start working with this package. Once you're sure you understand how plugins in \verb at RKWard@ actually
+work, just come back here.
+
+\section{Ingredients}
+If you look at the contents of the package, you might feel a little lost because of the number of functions.
+So let's first see that there's actually some order in the chaos.
+
+Most functions start with the prefix \verb at rk.@ to indicate that they somehow belong to \verb at RKWard@
+(we'll get to the exceptions later). After that, many names have another abbreviation by which they can
+roughly be classified into their specific ''area of plugin development:
+
+\begin{itemize}
+	\item \verb at rk.XML.*()@: XML code for GUI description (and plugin maps)
+	\item \verb at rk.JS.*()@: JavaScript code
+	\item \verb at rk.rkh.*()@: XML code for help pages
+\end{itemize}
+
+In short, you should find a \verb at rk.XML.*()@ equivalent to every XML tag explained in the
+\textit{Introduction to Writing Plugins for
+RKWard},\footnote{\url{http://rkward.sourceforge.net/documents/devel/plugins/index.html}}
+e.\,g. \verb at rk.XML.dropdown()@ to generate a \verb@<dropdown>@ menu node. There are a few functions for
+JavaScript generation which fall out of this scheme. That is because firstly they should be intuitively to use
+just like their JavaScript equivalent (like \verb at echo()@), and secondly they are likely to be used very often
+in a script, so short names seemed to be a blessing here (like \verb at id()@ or \verb at qp()@).
+
+Adding to that, there are some special functions, which will all be explained later, but here's the list,
+roughly ordered by the development stage they're used for:
+
+\begin{itemize}
+	\item \verb at rk.paste.JS()@: Paste JavaScript code from \verb at R@ objects
+	\item \verb at rk.XML.plugin()@: Combine XML objects into one plugin GUI object
+	\item \verb at rk.JS.scan()@: Scan a GUI XML file (or \verb at R@ object) and generate JavaScript code
+		(define all relevant variables)
+	\item \verb at rk.JS.saveobj()@: Scan a GUI XML file (or \verb at R@ object) and generate JavaScript code
+		(save result objects)
+	\item \verb at rk.JS.doc()@: Combine JavaScript parts into one plugin JavaScript file object
+	\item \verb at rk.rkh.scan()@: Scan a GUI XML file (or \verb at R@ object) and generate a help page skeleton
+	\item \verb at rk.rkh.doc()@: Combine XML objects into one help page object
+	\item \verb at rk.testsuite.doc()@: Paste a testsuite skeleton
+	\item \verb at rk.XML.pluginmap()@: Combine XML objects into one plugin map object
+	\item \verb at rk.plugin.skeleton()@: Generate actual plugin files from the plugin GUI, JavaScript, help page,
+		testsuite and plugin map objects (i.\,e., put all of the above together)
+	\item \verb at rk.build.plugin()@: Compress the generated files into an installable \verb at R@ package for
+		distribution
+\end{itemize}
+
+
%  \begin{Schunk}
%  	\begin{Sinput}
%  	\end{Sinput}

===================================================================
(Binary files differ)

Property changes on: trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.pdf
___________________________________________________________________
+ application/octet-stream

===================================================================
--- trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.tex	                        (rev 0)
+++ trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.tex	2011-10-10 21:11:35 UTC (rev 3921)
@@ -0,0 +1,97 @@
+\documentclass[a4paper,10pt]{scrartcl}
+\usepackage[utf8x]{inputenc}
+\usepackage{apacite}
+
+%opening
+\title{RKWard plugin development with the \texttt{rkwarddev} package}
+%\VignetteIndexEntry{RKWard plugin development with the rkwarddev package}
+\author{m.eik michalke}
+
+\usepackage{Sweave}
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+Writing plugins for \verb at RKWard@ means writing at least two XML files (a GUI description and a plugin map),
+one JavaScript file (to create the \verb at R@ code), maybe a help file (again in XML), and for plugins who
+should be distributed, a DESCRIPTION file. Furtermore, all of these files need to be in a certain directory
+structure.
+
+The \verb at rkwarddev@ package aims to simplify this, by enabling you to fulfill all the listed tasks in just
+one \verb at R@ script.
+\end{abstract}
+
+You might ask why you should write R scripts to generate plugins, if you could just directly write the XML
+and JavaScript files. First of all, you don't have to use this package at all, it's totally fine to code your
+plugins however you like. The main reason why I wrote this package is that I like to really concentrate on
+what I'm doing, so this is my attempt to avoid the need to switch between three different languages all the
+time. I wanted to be able to constantly ''think in \verb at R@ while working on a plugin. As a side effect, a
+lot of useful automation was implemented, and using this package will definitely save you quite some amount of
+typing.
+
+\section{Before we start}
+It is important to undertsand that while \verb at rkwarddev@ can help you to make designing new plugins
+much easier, you still need to know how the generated XML and JavaScript files work and interact. That is, if
+you didn't yet read the \textit{Introduction to Writing Plugins for
+you start working with this package. Once you're sure you understand how plugins in \verb at RKWard@ actually
+work, just come back here.
+
+\section{Ingredients}
+If you look at the contents of the package, you might feel a little lost because of the number of functions.
+So let's first see that there's actually some order in the chaos.
+
+Most functions start with the prefix \verb at rk.@ to indicate that they somehow belong to \verb at RKWard@
+(we'll get to the exceptions later). After that, many names have another abbreviation by which they can
+roughly be classified into their specific ''area of plugin development:
+
+\begin{itemize}
+	\item \verb at rk.XML.*()@: XML code for GUI description (and plugin maps)
+	\item \verb at rk.JS.*()@: JavaScript code
+	\item \verb at rk.rkh.*()@: XML code for help pages
+\end{itemize}
+
+In short, you should find a \verb at rk.XML.*()@ equivalent to every XML tag explained in the
+\textit{Introduction to Writing Plugins for
+RKWard},\footnote{\url{http://rkward.sourceforge.net/documents/devel/plugins/index.html}}
+e.\,g. \verb at rk.XML.dropdown()@ to generate a \verb@<dropdown>@ menu node. There are a few functions for
+JavaScript generation which fall out of this scheme. That is because firstly they should be intuitively to use
+just like their JavaScript equivalent (like \verb at echo()@), and secondly they are likely to be used very often
+in a script, so short names seemed to be a blessing here (like \verb at id()@ or \verb at qp()@).
+
+Adding to that, there are some special functions, which will all be explained later, but here's the list,
+roughly ordered by the development stage they're used for:
+
+\begin{itemize}
+	\item \verb at rk.paste.JS()@: Paste JavaScript code from \verb at R@ objects
+	\item \verb at rk.XML.plugin()@: Combine XML objects into one plugin GUI object
+	\item \verb at rk.JS.scan()@: Scan a GUI XML file (or \verb at R@ object) and generate JavaScript code
+		(define all relevant variables)
+	\item \verb at rk.JS.saveobj()@: Scan a GUI XML file (or \verb at R@ object) and generate JavaScript code
+		(save result objects)
+	\item \verb at rk.JS.doc()@: Combine JavaScript parts into one plugin JavaScript file object
+	\item \verb at rk.rkh.scan()@: Scan a GUI XML file (or \verb at R@ object) and generate a help page skeleton
+	\item \verb at rk.rkh.doc()@: Combine XML objects into one help page object
+	\item \verb at rk.testsuite.doc()@: Paste a testsuite skeleton
+	\item \verb at rk.XML.pluginmap()@: Combine XML objects into one plugin map object
+	\item \verb at rk.plugin.skeleton()@: Generate actual plugin files from the plugin GUI, JavaScript, help page,
+		testsuite and plugin map objects (i.\,e., put all of the above together)
+	\item \verb at rk.build.plugin()@: Compress the generated files into an installable \verb at R@ package for
+		distribution
+\end{itemize}
+
+
+%  \begin{Schunk}
+%  	\begin{Sinput}
+%  	\end{Sinput}
+%  	\begin{Soutput}
+%  	\end{Soutput}
+%  \end{Schunk}
+
+%  \bibliographystyle{apacite}