[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
Added Paths:
-----------
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}
+\section{About the package}
+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
+RKWard},\footnote{\url{http://rkward.sourceforge.net/documents/devel/plugins/index.html}} please do so before
+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}
Added: trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.pdf
===================================================================
(Binary files differ)
Property changes on: trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.pdf
___________________________________________________________________
Added: svn:mime-type
+ application/octet-stream
Added: trunk/rkward/packages/rkwarddev/inst/doc/rkwarddev_vignette.tex
===================================================================
--- 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}
+
+\section{About the package}
+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
+RKWard},\footnote{\url{http://rkward.sourceforge.net/documents/devel/plugins/index.html}} please do so before
+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}
+% \addcontentsline{toc}{chapter}{\bibname}
+% \bibliography{rkwarddev_lit}
+
+\end{document}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the rkward-tracker
mailing list