+% ==========================================
+\documentclass[11pt,final,a4paper]{article}
+\input{config.tex}
+\begin{document}
+\title{The Black Box Toolkit\\User's Guide}
+\date{\today}
+\author{Laurent Guigues}
+\maketitle
+% ==========================================
+\tableofcontents
+% ==========================================
+
+
+% ==========================================
+%\section*{Abstract}
+% ==========================================
+\newpage
+% ==========================================
+\hrule
+\section{What is {\bf bbtk} ?}
+% ==========================================
+\BBTK(\bbtkns) is a set of tools
+(\CPP libraries and executables)
+providing a \CPP framework for the definition
+of elementary processing \emph{units}, called {\bf black boxes},
+and the definition and execution of processing \emph{chains}
+made up of these black boxes.
+
+% ==========================================
+\subsection{The black box philosophy}
+% ==========================================
+\href{http://en.wikipedia.org/wiki/Black_box_\%28disambiguation\%29}{Wikipedia}
+defines a {\bf black box} as
+\emph{``any component in a system in which only the input and output
+characteristics are of interest, without regard to its internal mechanism
+or structure''}.
+
+\BBTK provides a systematic framework
+to encapsulate (or ``wrap'') any
+existing \texttt{C} or \CPP processing code into an object
+(a black box) having a {\bf generic symbolic interface}, where
+
+\begin{itemize}
+\item{\bf generic} means that the interface is \emph{the same}
+for all boxes. Hence one does not need to know which particular
+method allows, say, to set a particular input or
+get a particular output of the box.
+One can use a black box in a purely abstract way.
+\item{\bf symbolic} means a particular
+input or output is referenced by a 'name', that is by a symbol
+which identifies the input or output.
+It also means that symbolic information (text!) is
+attached to a box: description of the box, author,
+description of its inputs and outputs, etc.
+\end{itemize}
+
+(in fact, genericity is achieved because the interface is symbolic.
+I let you think about this\dots)
+
+Of course, symbolic data attached to box can be
+{\bf queried}: what are the inputs/outputs of the box ?
+what are their type ? description ? etc.
+This allows {\bf automatic documentation} of boxes.
+
+The abstract definition of black boxes is the most basic
+aspect of \BBTK architecture.
+Another key aspect is the groupement of black boxes into
+so called {\bf packages},
+which are \emph{dynamic libraries} which can also
+be queried, in particular about the boxes they provide.
+The package structure then offers a mechanism which
+is like a \emph{'plug-in'} mechanism.
+\BBTK provides the methods to load a package at run-time,
+and create instances of the boxes it contains.
+
+These two mechanisms (black boxes and packages)
+then gives the way to:
+
+\begin{itemize}
+\item The definition of an {\bf interpreted language},
+which allows to manipulate packages and boxes very easily in symbolic way.
+\BBTK provides one: \bbi (the Black Box Interpreter).
+\item {\bf Automatic documentation} of existing packages.
+\texttt{html} documentation of packages is proposed by
+the \bbdoc application.
+\end{itemize}
+
+Finally, these different components allow {\bf efficient}:
+
+\begin{itemize}
+\item {\bf capitalization and reuse} of existing processings,
+including {\bf documentation}
+\item {\bf testing, prototyping} in a very simple script language
+\item {\bf inter-operability} between atomic processings which
+have been written by different persons, using different libraries, etc.
+\end{itemize}
+
+% ==========================================
+\subsection{\bbtk components}
+% ==========================================
+\BBTK includes:
+\begin{itemize}
+\item A \CPP {\bf\emph{library}} - called \bbtk - which defines a framework
+(abstract classes) to develop black boxes and to store them into
+dynamic libraries, called black box \emph{packages}.
+\item Different {\bf\emph{black box packages}}:
+\begin{itemize}
+\item {\bf\emph{std}}: the 'standard' package including basic useful boxes.
+\item {\bf\emph{wx}}: basic graphical interface elements (widgets: sliders, buttons, etc. based on the \texttt{wxWidgets} library).
+\item {\bf\emph{itk}}: the basic image processing package, based on the \texttt{itk} library.
+\item {\bf\emph{vtk}}: the basic image and surfaces processing package, based on the \texttt{vtk} library.
+\item {\bf\emph{wxvtk}}: widget boxes based on the \texttt{vtk} library.
+\item {\bf\emph{itkvtk}}: boxes to convert \texttt{itk} structures into \texttt{vtk} structures and conversally.
+\end{itemize}
+\item An {\bf\emph{interpreter}}, called \bbi, which allows to
+load black box packages and to define and execute
+processing chains by connecting various black boxes of the already loaded packages.
+\item {\bf\emph{Utilities}}:
+\begin{itemize}
+\item \bbfy generates the \CPP code of a black box from a
+description file written in \texttt{xml}.
+\item \bbdoc generates the html documentation of a black box package
+(author, description, description of its black boxes:
+author, description, inputs, outputs, and so on).
+\item \bbCreatePackage creates a directory on disk which contains the basic files to start the development of a new black box package.
+\end{itemize}
+\end{itemize}
+
+The general architecture of \BBTK
+is shown in figure \ref{bb-architecture}.
+
+\begin{figure}[!ht]
+\caption{\label{bb-architecture}\BBTK architecture}
+\begin{center}
+\includegraphics[width=0.6\textwidth]{bb-architecture.png}
+\end{center}
+\end{figure}
+
+% ==========================================
+\subsection{Structure of this guide}
+% ==========================================
+
+This guide is divided into two parts.
+
+The first part (\ref{bbi})
+is devoted to the use of the \emph{black box interpreter} \bbi.
+This is the highest level of use of the toolkit, which
+allows to create and execute processing chains by connecting
+black boxes of existing packages.
+
+The second part (\ref{cpp}) explains how to
+use the black box toolkit framework in \CPP code,
+typically to develop large applications which
+involve complex graphical interfaces.
+
+
+% ==========================================
+% ==========================================
+% ==========================================
+% ==========================================
+% ==========================================
+% ==========================================
+\vspace{0.5cm}\hrule
+\section{The black box interpreter (bbi)}
+\label{bbi}
+% ==========================================
+
+% ==========================================
+%\subsection{Structure of this part}
+% ==========================================
+
+Using the black box interpreter is very simple.
+Everything is done with only a few commands.
+The philosophy of this part is also very simple:
+it introduces the \bbi commands using examples,
+starting with the most simple commands.
+The first section of this part
+(\ref{bbi-getting-started})
+is designed like a tutorial,
+which progressively introduces all the concepts of \bbi.
+We suggest you run \bbi and follow the examples,
+to see how it works in practice.
+At the end of this section,
+you will be able to use \bbi and write
+own black box processing scripts.
+
+After this tutorial,
+the section \ref{bbi-more-on}
+(called \emph{more on...})
+goes deeper into various issues of \bbi.
+Read it at your convenience,
+either linearly to learn more about \bbi,
+or in random order to get an answer
+to a particular question.
+
+Finally, the section \ref{bbi-reference}
+summarizes all the commands of \bbi,
+their parameters and effect.
+Use it as a reference.
+
+% ==========================================
+\subsection{Getting started}
+\label{bbi-getting-started}
+% ==========================================
+\subsubsection{Creating and executing black boxes}
+% ==========================================
+
+To run the black box interpreter,
+open a console and type \texttt{bbi}
+or double click on the application icon.
+You get a message and a prompt:
+\begin{verbatim}
+$$ bbi
+BBI (Black Box Interpreter) - bbtk "1.0.0" - (c) Creatis 2007
+>
+\end{verbatim}
+
+If you type:
+\begin{verbatim}
+> help
+\end{verbatim}
+
+you get the list of the commands of the interpreter:
+\begin{verbatim}
+Available commands:
+ author
+ config
+ connect
+ define
+ delete
+ description
+ endefine
+ exec
+ graph
+ help
+ include
+ input
+ load
+ message
+ new
+ output
+ print
+ quit
+ reset
+ set
+ unload
+\end{verbatim}
+
+To get help on a particular command type \texttt{help <command-name>},
+for example:
+\begin{verbatim}
+> help quit
+\end{verbatim}
+
+gives:
+\begin{verbatim}
+ quit:
+ usage: quit
+ Quits the program (during script execution it stops the complete execution)
+\end{verbatim}
+
+The \texttt{help} command has multiple usages.
+It is used to get help on almost anything in \bbi !
+Type \texttt{'help help'} to get help on the \texttt{help} command itself:
+\begin{verbatim}
+> help help
+ usage:
+ (1) help
+ (2) help <command name>
+ (3) help packages [all]
+ (4) help <package name> [all]
+ (5) help <black box type>
+ (6) help <black box name>
+ Effect:
+ (1) Lists all available commands;
+ (2) Prints help on a particular command;
+ (3) Lists the packages loaded and their black boxes.
+ Add 'all' to list adaptors;
+ (4) Prints short help on the black boxes of a package.
+ Add 'all' to include adaptors;
+ (5) Prints full help on a black box type;
+ (6) Prints information on the inputs, outputs and connections of a black box instance.
+\end{verbatim}
+
+At start \bbi does not know any black box.
+If you type \texttt{'help packages'}, which is
+the third form of the \texttt{help} command, you get:
+\begin{verbatim}
+> help packages
+user
+ workspace
+\end{verbatim}
+
+which means that \bbi only knows one package
+(library of black boxes) called \texttt{user}
+and which contains a black box called \texttt{workspace}.
+The \texttt{user} package is an internal package to \bbi,
+which stores user-defined black box types.
+At start, it already contains
+one box, called \texttt{workspace}.
+\texttt{workspace} is a special type of black box,
+called complex black box, whose purpose is
+to store other black boxes.
+Any black box you create in \bbi is stored
+in \texttt{workspace}
+(this will be explained in details in sections
+\ref{bbi-writing-scripts} and
+\ref{bbi-more-on-complex-black-boxes}).
+
+If you type \texttt{'help workspace'}, you get:
+\begin{verbatim}
+> help workspace
+Complex Black Box <user::workspace>
+ User's workspace
+ By: bbi (internal)
+ * No inputs
+ * No outputs
+ * No boxes
+\end{verbatim}
+
+In the text displayed,
+the \texttt{user::} prepended to the name \texttt{workspace}
+means that the box \texttt{workspace}
+belongs to the \texttt{user} package.
+Then comes a description and three lines which
+tell that \texttt{workspace} does not have any input
+nor output nor boxes yet.
+
+In order to let \bbi know of some black boxes,
+you must load another package.
+The \texttt{std} package is the ``standard'' package,
+which contains basic useful black boxes.
+
+To load it, type:
+\begin{verbatim}
+> load std
+\end{verbatim}
+
+Then if you type:
+\begin{verbatim}
+> help packages
+\end{verbatim}
+
+you get something like:
+\begin{verbatim}
+std
+ Add
+ ...
+user
+ workspace
+>
+\end{verbatim}
+
+Now \bbi knows the package \texttt{std} and the black boxes it provides,
+such as the \texttt{'Add'} box. Remark that the
+content of \texttt{std} may vary from one version to another
+as new black boxes might be added to it.
+If you type:
+\begin{verbatim}
+> help Add
+\end{verbatim}
+
+You get:
+\begin{verbatim}
+Black Box <std::Add>
+ Adds its inputs
+ By: laurent.guigues@creatis.insa-lyon.fr
+ * Inputs:
+ 'In1' <double>: First number to add
+ 'In2' <double>: Second number to add
+ 'ProcessMode' <int> : Set the process mode of the box (0=Pipeline | 1=Always | 2=Reactive)
+ * Outputs:
+ 'Out' <double>: Result
+\end{verbatim}
+
+Like previously,
+the \texttt{std::} prepended to the name \texttt{Add}
+means that the box \texttt{Add}
+belongs to the \texttt{std} package.
+Then comes a description
+(the one which was provided by the author of the box),
+the author(s) of the box (usually e-mail adress(es)).
+Finally comes the lists of inputs and outputs of the box.
+For each input or output, \bbi provides
+its \emph{name} (between quotes, e.g. \texttt{'ProcessMode'}),
+its \emph{type} (between \texttt{<>}, e.g. \texttt{<int>})
+and a description.
+Remark that the box \texttt{Add} is not a 'complex' black box
+but an 'atomic' box, hence its help does not
+mention any information concerning possible internal boxes.
+
+You can create an \emph{instance} of an \texttt{Add} box by
+the command \texttt{new}:
+\begin{verbatim}
+> new Add a
+\end{verbatim}
+
+The \texttt{'a'} at the end is the \emph{name} of the instance,
+which will be used to reference it later.
+It is important to make the difference between box \emph{types}
+and \emph{instances} of box types.
+The \texttt{Add} box of the package \texttt{std} is in fact
+a \emph{type} of box, like \texttt{int} is a type of data
+in \texttt{C} langage. The \texttt{new} command allows to create
+an instance of a box type, exactly like \texttt{int i;} in
+a \texttt{C} code declares a variable of type \texttt{int} whose
+name is \texttt{i}.
+Of course, like in \texttt{C} Language, you can declare multiple boxes of the
+same type in \bbi.
+
+After the creation of the box \texttt{a}, type:
+\begin{verbatim}
+> help workspace
+\end{verbatim}
+
+you get:
+\begin{verbatim}
+Complex Black Box <user::workspace>
+ User's workspace
+ By: bbi (internal)
+ * No inputs
+ * No outputs
+ * Boxes:
+ 'a' <std::Add>
+\end{verbatim}
+
+which means that \bbi's workspace now contains a black box
+of type \texttt{std::Add} and name \texttt{a}.
+
+Now look back at the help on \texttt{Add} boxes:
+you can see that this type of box has two inputs,
+with name \texttt{In1} and \texttt{In2},
+and an output, with name \texttt{Out}.
+
+You can set the input \texttt{In1}
+of the \texttt{Add} box \texttt{a} to the value $1$
+by the command:
+\begin{verbatim}
+> set a.In1 1
+\end{verbatim}
+
+Similarly, setting the input \texttt{In2} of \texttt{a} to the value $2$
+is done with:
+\begin{verbatim}
+> set a.In2 2
+\end{verbatim}
+
+And you print the output \texttt{Out} of the box \texttt{a} with:
+\begin{verbatim}
+> print "result=$a.Out$"
+result=3
+\end{verbatim}
+
+In the string passed to the \texttt{print} command,
+each substring enclosed between a couple of \$ is considered
+as the name of an output of a box.
+To process this special substrings, \bbi does:
+\begin{enumerate}
+\item Processes the box if needed (see below)
+\item Converts the output of the box to a string if possible
+(see below)
+\item Substitutes the result in the string to print
+\end{enumerate}
+
+Box processing is needed if:
+\begin{itemize}
+\item at least input has changed since last processing or
+\item the input \texttt{'ProcessMode'} of the box is set to
+\texttt{1}, which forces box reprocessing.
+\end{itemize}
+
+Note that all boxes have the input \texttt{'ProcessMode'}.
+
+Another way to process the box \texttt{a} is to issue the command:
+\begin{verbatim}
+> exec a
+\end{verbatim}
+
+however this command does not display anything (except if the
+box itself displays something in its processing).
+It just processes the box if needed.
+This command is used to execute boxes that do not have any output,
+such as boxes that write something to a file or, display a
+graphical interface, and so on.
+
+To exit \bbi, type:
+\begin{verbatim}
+> quit
+Good bye !
+\end{verbatim}
+
+% ==========================================
+\hrule
+\paragraph{Summary}
+%\hrule
+\begin{itemize}
+\item The \texttt{load} command allows to load a package.
+\item \texttt{help} gives help on:
+\begin{itemize}
+\item Available commands if you just type \texttt{help}.
+\item A particular command if you type \texttt{help <command-name>}.
+\item All available packages and their boxes (without description) if you type \texttt{help packages}.
+\item A particular package and its boxes (with brief description) if you type \texttt{help <package-name>}.
+\item A particular black box type (with full description) if you type \texttt{help <box-type-name>}. In particular, \texttt{help workspace} displays information on the content of the \texttt{'workspace'} black box, which stores the boxes created by the user (by \texttt{new}).
+\end{itemize}
+%\item \texttt{list} displays the list of black box instances created so far (by \texttt{new}).
+\item \texttt{new} creates an instance of a black box.
+\item \texttt{set} sets the value of an input of a black box.
+\item In all \bbi, to reference the input called \texttt{i}
+of a black box called \texttt{b} you must type \texttt{'b.i'}.
+The same syntax holds for outputs.
+\item \texttt{print} prints a string, substituting each substring of the form \$b.o\$ by the value of the output \texttt{o} of the black box \texttt{b}.
+\item \texttt{exec} runs the process of a box if needed.
+\item \texttt{quit} quits \bbi.
+\end{itemize}
+\hrule
+% ==========================================
+
+% ==========================================
+\subsubsection{Connecting black boxes}
+\label{bbi-connecting-black-boxes}
+% ==========================================
+
+\BBTK allows to create
+and execute processing chains,
+also called \emph{pipelines},
+by connecting black boxes.
+This section explains how to do it with examples.
+Read section \ref{bbi-more-on-pipeline-processing} to get
+more information on pipeline processing.
+
+First start \bbi and load the package \texttt{std}:
+\begin{verbatim}
+$$ bbi
+BBI (Black Box Interpreter) - bbtk "1.0.0" - (c) Creatis 2007
+> load std
+\end{verbatim}
+
+Assume you want to compute $1+2+3$. You can do it by
+chaining two \texttt{Add} boxes, as shown in figure
+\ref{bbi-fig-connecting-black-boxes-1}.
+
+\begin{figure}[!ht]
+\caption{\label{bbi-fig-connecting-black-boxes-1}
+A simple pipeline which adds 3 numbers}
+\begin{center}
+\includegraphics[width=0.5\textwidth]{1plus2plus3.png}
+\end{center}
+\end{figure}
+
+The \bbi instructions to create and execute this pipeline are:
+\begin{verbatim}
+> new Add a
+> new Add b
+> connect a.Out b.In1
+> set a.In1 1
+> set a.In2 2
+> set b.In2 3
+> print $b.Out$
+6
+\end{verbatim}
+
+The first three commands build the pipeline,
+the next three set its inputs and the last one
+executes it and prints its output.
+
+The command \texttt{'connect a.Out b.In1'} ``plugs'' the output
+\texttt{Out} of the box \texttt{a} into the input \texttt{In1} of the
+box \texttt{b}.
+Once the boxes connected, the processing of the two boxes are chained:
+getting the output of \texttt{b} requires getting its inputs,
+hence getting the output of \texttt{a} which is connected to it.
+This pipeline mechanism can recurse into arbitrary long
+chains of boxes (see \ref{bbi-more-on-pipeline-processing}
+for details).
+
+Of course, to be able to connect two boxes,
+the output and the input must be compatibles.
+You can always connect an output to an input of the \emph{same} type,
+but you can do more, thanks to particular black boxes called {\bf adaptors}.
+
+An adaptor is a black box which has at least one input, called \texttt{In},
+and at least one ouput called \texttt{Out} and whose role is to convert
+a data of the type of \texttt{In}
+into a data of the type of \texttt{Out} (other inputs or outputs may serve
+to parameter the adaptor or retreive other usefull information).
+
+In \bbi, if you type:
+\begin{verbatim}
+> load std
+> help std all
+\end{verbatim}
+you get:
+\begin{verbatim}
+ Package std v1.0.0 - laurent.guigues@creatis.insa-lyon.fr
+ Basic useful black boxes
+ Black boxes:
+ Add : Adds its inputs
+ Cast<double,float> [DA] : Casts a double into a float
+ Cast<double,int> [DA] : Casts a double into a int
+ ...
+ Convert<unsigned int,string> [DA] : Converts a unsigned int into a s...
+ Convert<unsigned short,string> [DA] : Converts a unsigned short into a...
+ Print : Prints its input to standard out...
+>
+\end{verbatim}
+
+The \texttt{Cast<?,?>} and \texttt{Convert<?,?>} boxes are \emph{default adaptors}, which is signaled by the tag \texttt{[DA]} before their descriptions.
+
+Once you have loaded the package \texttt{std}, you can
+plug an output of type \texttt{char} into an input of type \texttt{double}.
+When \bbi encounters the \texttt{connect} command,
+it looks for an adequate \emph{adaptor} in the loaded packages.
+In our case, as the package \texttt{std} provides the
+\texttt{Cast<char,double>} adaptor, \bbi automatically creates an
+instance of this adaptor and place it \emph{between}
+the output and the input you want to connect
+(however this adaptor is hidden to you,
+it is embedded into the created connection and does not appear
+as an existing black box).
+When the pipeline is processed the
+adaptor converts the output data into the required input type,
+in a totally transparent way.
+In our example, the \texttt{Cast<char,double>} adaptor
+would simply cast the value of the \texttt{char} into a \texttt{double},
+however arbitrarily complex type conversion can be done.
+
+Question:
+if two adaptors with the same input and output types exist
+in the packages loaded,
+which one is chosen by \bbi at connection ?
+-> Role of default adaptors
+
+Note that the \texttt{set} and \texttt{print} commands of \bbi
+work with adaptors from \texttt{string} to the type of the input to set
+or from the type of the output to print to \texttt{string}.
+Hence in order to \texttt{set} or \texttt{print} values the adequate
+adaptors must be available in the packages currently loaded.
+
+% ==========================================
+\hrule
+\paragraph{Summary}
+%\hrule
+\begin{itemize}
+\item The \texttt{connect} command allows to connect two black boxes
+\item You can connect two black boxes if (and only if):
+\begin{itemize}
+\item The output and the input are of the same type, or
+\item There is an adaptor black box in the packages loaded which
+converts data of the output type into data of the input type
+\end{itemize}
+\item \texttt{help <package name>} does not display the adaptors of the package. To see them use: \texttt{help <package name> all}.
+including adaptors
+\end{itemize}
+\hrule
+% ==========================================
+
+% ==========================================
+\subsubsection{Creating complex black boxes}
+\label{bbi-complex-black-boxes}
+% ==========================================
+
+Remember the pipeline of figure
+\ref{bbi-fig-connecting-black-boxes-1}, which
+computed the sum of three doubles ?
+You can view it as a whole and define
+a new black box type, which will be a \emph{complex black box},
+having three inputs and one output,
+as shown in figure \ref{bbi-fig-complex-black-box-1}.
+
+\begin{figure}[!ht]
+\caption{\label{bbi-fig-complex-black-box-1}
+Creating the complex black box \texttt{Add3}}
+\begin{center}
+\includegraphics[width=0.5\textwidth]{Add3.png}
+\end{center}
+\end{figure}
+
+The \bbi commands to define this complex black box are
+the following:
+
+\begin{verbatim}
+> load std
+>
+> define Add3
+>
+> new Add a
+> new Add b
+> connect a.Out b.In1
+>
+> author "myself"
+> description "adds 3 doubles"
+> input x a.In1 "first double to add"
+> input y a.In2 "second double to add"
+> input z b.In2 "third double to add"
+> output result b.Out "output"
+>
+> endefine
+\end{verbatim}
+
+Explainations:
+
+As we will use \texttt{Add} boxes, we need to load the package \texttt{std}, which is done in first line.
+
+The command \texttt{define} then starts the definition
+of the complex box type, which will be called \texttt{Add3}.
+
+The next three lines define the pipeline,
+exactly in the same way than outside a complex box definition.
+
+The commands \texttt{author}, \texttt{description}, \texttt{input}
+and \texttt{output} are commands specific to complex boxes definition:
+
+\texttt{author} and \texttt{description} are used for the documentation
+of the new box. You can provide multiple \texttt{author} or
+\texttt{description} commands, the arguments of the commands will
+be concatenated to produce the final author and description strings.
+
+\texttt{input} and \texttt{output} are used to define the inputs and outputs
+of the new complex box.
+Their syntax is the same: for each new input/output you need to say
+to which internal input/output it corresponds and to provide
+a help string documenting the input/output.
+In our example, we define that the box \texttt{Add3} has
+three inputs: \texttt{x}, \texttt{y} and \texttt{z}.
+The input \texttt{x} corresponds to the input \texttt{In1} of the
+internal box \texttt{a}.
+In the same way, the external input \texttt{y}
+corresponds to the internal input \texttt{a.In2}, and
+the external input \texttt{In3} to \texttt{b.In2}.
+The only output of the new box is called \texttt{result}
+and corresponds to \texttt{b.Out}.
+The figure \ref{bbi-fig-complex-black-box-1}
+illustrates the external to internal
+input/output correspondence.
+
+Finally, the \texttt{endefine} command ends the definition of the
+new box type.
+
+After this definition, if you ask for help
+on packages, you get:
+\begin{verbatim}
+> help packages
+std
+ Add
+ ...
+user
+ Add3
+ workspace
+\end{verbatim}
+
+The \texttt{user} package now contains a new black box type, called
+\texttt{Add3}. If you ask for help on this type of box, you get:
+\begin{verbatim}
+> help Add3
+Complex Black Box <user::Add3>
+ adds 3 doubles
+ By: myself
+ * Inputs:
+ 'x' <double>: first double to add
+ 'y' <double>: second double to add
+ 'z' <double>: third double to add
+ * Outputs:
+ 'result' <double>: output
+ * Boxes:
+ 'a' <std::Add>
+ 'b' <std::Add>
+\end{verbatim}
+
+and you can use it like any other box, for example type:
+
+\begin{verbatim}
+> new Add3 a
+> set a.x 1
+> set a.y 2
+> set a.z 3
+> print $a.result$
+6
+\end{verbatim}
+
+
+% ==========================================
+\hrule
+\paragraph{Summary}
+%\hrule
+\begin{itemize}
+\item The \texttt{define/endefine} commands allows to define complex black box types, i.e. types of black boxes made up of other black boxes.
+Inside a \texttt{define/endefine} block:
+\begin{itemize}
+\item The \texttt{author} and \texttt{description} commands allow to document the new type of box
+\item The \texttt{input} and \texttt{output} commands allow to define the inputs and outputs of the new type of box, that is to which inputs and outputs
+of internal boxes they correspond.
+\end{itemize}
+\end{itemize}
+\hrule
+% ==========================================
+
+% ==========================================
+\subsubsection{Writing scripts}
+\label{bbi-writing-scripts}
+% ==========================================
+
+Once you have defined a new type of complex box, you
+may like to reuse it. To do this, you can simply
+write the \bbi commands defining the new box
+into a text file and afterwards include that file in \bbi.
+Doing this, you start writing \bbi scripts.
+The conventionnal extension for such scripts is \texttt{bbs}
+(black box script).
+
+For example, the \texttt{Add3} complex box we previously worked on
+can be defined in the \texttt{Add3.bbs} file:
+
+\begin{file}{Add3.bbs}
+\begin{verbatim}
+# Defines the Add3 black box which adds 3 doubles
+load std
+
+define Add3
+ # I am the author
+ author "myself"
+ description "adds 3 doubles"
+ # Pipeline creation
+ new Add a
+ new Add b
+ connect a.Out b.In1
+ # Inputs definition
+ input x a.In1 "first double to add
+ input y a.In2 "second double to add
+ input z b.In2 "third double to add"
+ # Output definition
+ output result b.Out "output"
+endefine
+\end{verbatim}
+\end{file}
+
+Lines starting with a \texttt{\#} character are ignored, they
+are considered as comments by \bbi.
+To use this file in \bbi, use the \texttt{include} command:
+
+\begin{verbatim}
+> include Add3.bbs
+> help Add3
+Complex Black Box <user::Add3>
+ adds 3 doubles
+ By: myself
+ * Inputs:
+ 'x' <double>: first double to add
+ 'y' <double>: second double to add
+ 'z' <double>: third double to add
+ * Outputs:
+ 'result' <double>: output
+ * Boxes:
+ 'a' <std::Add>
+ 'b' <std::Add>
+>
+and so on ...
+\end{verbatim}
+
+If the file has the \texttt{bbs} extension, you can ommit it and just type:
+\begin{verbatim}
+> include Add3
+\end{verbatim}
+
+Of course, you can include script files in other script files,
+like in the following example:
+
+\begin{file}{Add4.bbs}
+\begin{verbatim}
+# Defines the Add4 black box which adds 4 doubles
+include Add3
+
+define Add4
+ author "myself"
+ description "adds 4 doubles"
+ new Add3 a
+ new Add b
+ connect a.Out b.In1
+ input In1 a.In1 "first double to add
+ input In2 a.In2 "second double to add
+ input In3 a.In3 "third double to add"
+ input In4 b.In2 "fourth double to add"
+ output Out b.Out "output"
+endefine
+\end{verbatim}
+\end{file}
+
+TO DO:
+
+- naming conventions: one cbb per file with the same name
+- search paths
+
+% ==========================================
+\hrule
+\paragraph{Summary}
+%\hrule
+\begin{itemize}
+\item The \texttt{include} command allows to include a script file in \bbi.
+\item Lines starting with a \texttt{\#} are treated as comments in \bbi scripts.
+\end{itemize}
+\hrule
+% ==========================================
+
+% ==========================================
+\subsubsection{Creating command line applications}
+\label{bbi-command-line-app}
+% ==========================================
+
+Now that you now how to create complex black boxes
+(with \texttt{define/endefine}), think
+back to the \texttt{workspace} object.
+Remember that it is also
+a \texttt{complex black box}.
+In fact what you are doing when you type \bbi commands
+outside a \texttt{define/endefine} block
+is to progressively define the \texttt{workspace}
+complex black box.
+You can think of it like if at start
+\bbi was issuing a command \texttt{'define workspace'}
+and then letting you define the interior of the box
+\texttt{workspace}.
+
+Remember that the command \texttt{inputs}
+allows to define an input of a complex box.
+Now, if you use the command \texttt{input}
+outside a \texttt{define/endefine} block then
+it defines an input of the \texttt{workspace} box,
+that is an input of the \emph{main program}.
+This input will then be connected to the
+parameters that the user passes to the command line.
+
+For example, consider the script:
+
+\begin{file}{add.bbs}
+\begin{verbatim}
+load std
+new Add a
+input x a.In1 "first number to add"
+input y a.In2 "second number to add"
+print "x+y=$a.Out$"
+\end{verbatim}
+\end{file}
+
+The third and fourth lines define two inputs \texttt{x}
+and \texttt{y}. When you execute this script,
+you can pass these two arguments on the command line,
+like this:
+
+\begin{verbatim}
+> bbi add x=1 y=1
+x+y=2
+\end{verbatim}
+
+You can also invoke \bbi the option \texttt{-h},
+which gives help on the \texttt{workspace} box:
+
+\begin{verbatim}
+> bbi add -h
+ User's workspace
+ By: bbi (internal)
+ * Inputs:
+ 'x' <double>: first number to add
+ 'y' <double>: second number to add
+\end{verbatim}
+
+To get a better help, use the \texttt{description}
+and \texttt{author} commands:
+
+\begin{file}{add.bbs}
+\begin{verbatim}
+description "Adds two numbers"
+author "foo@bar.com"
+load std
+new Add a
+input x a.In1 "first number to add"
+input y a.In2 "second number to add"
+print "x+y=$a.Out$"
+\end{verbatim}
+\end{file}
+
+Now if you ask for help on the \texttt{add} script, you get:
+
+\begin{verbatim}
+> bbi add -h
+ Adds two numbers
+ By: foo@bar.com
+ * Inputs:
+ 'x' <double>: first number to add
+ 'y' <double>: second number to add
+\end{verbatim}
+
+Rather than getting the inputs of a script
+from the command line, you can ask \bbi to
+prompt the user for the values, using the \texttt{-t}
+commutator:
+
+\begin{verbatim}
+> bbi add -t
+x=[the program waits for user answer]2
+y=[the program waits for user answer]5
+x+y=7
+\end{verbatim}
+
+If \bbi is compiled in graphical mode (with \wx),
+you can also use the \texttt{-g} commutator.
+\bbi then prompts the user in graphical mode,
+displaying a dialog box for each input,
+like in fig. \ref{bb-input-dialog-box}.
+
+\begin{figure}[!ht]
+\caption{\label{bb-input-dialog-box}Input dialog box}
+\begin{center}
+\includegraphics[width=0.6\textwidth]{enter-the-value-of-x.png}
+\end{center}
+\end{figure}
+
+% ==========================================
+\hrule
+\paragraph{Summary}
+%\hrule
+\begin{itemize}
+\item The \texttt{input}, \texttt{description} and \texttt{author} commands,
+when they are used outside a \texttt{define/endefine} block allow
+to define the inputs, description and author of the main program.
+\item Inputs of the main program can be passed on the command line
+using the syntax \texttt{<input-name>=<value>}.
+No white space is allowed, if the value or the input name
+contains white spaces, enclose them
+between double quotes, e.g. \texttt{"parameter with white spaces = gnu's not unix"}.
+\item The \texttt{-h} option of \bbi prints help on the main program.
+\item The \texttt{-t} option of \bbi orders the program to prompt for its inputs in text mode.
+\item The \texttt{-g} option of \bbi orders the program to prompt for its inputs in graphical mode.
+\end{itemize}
+\hrule
+% ==========================================
+
+% ==========================================
+\subsubsection{Using graphical interface boxes (widget boxes)}
+\label{bbi-widget}
+% ==========================================
+
+If \bbi is compiled in graphical mode
+(option \texttt{BUILD\_bbi\_GRAPHICAL} of \cmake, requires \wx),
+then you can use special black boxes which are
+graphical interface components (widgets).
+Basic components are provided in the package \texttt{wx},
+such as buttons, sliders, file open/save dialogs, etc.
+
+As first example, type the following commands in \bbi:
+\begin{verbatim}
+> load wx
+> new TextCtrl t
+> print $t.Out$\n
+\end{verbatim}
+
+When you type \texttt{enter} after the last line,
+a window pops up in which you can entrer a text.
+When you close the window, the text you entered is printed by
+the \texttt{print} command.
+
+Type \texttt{help wx}, you get something like:
+\begin{verbatim}
+Package wx v1.0.0- eduardo.davila/laurent.guigues@creatis.insa-lyon.fr
+ Basic graphical interface elements (slider, button ...) based on wxWidgets
+ Black boxes:
+ Button : Button that gives a string
+ FileDialog : FileDialog widget (wxFileDialog)
+ RadioButton : RadioButton group widget (wxRadioButton) 0-9 entries
+ Sizer : Sizer widget (wxSizer)
+ Slider : Slider widget (wxSlider)
+ Split : Split widget (wxSplitterWindow)
+ StaticText : wxWidget Static text
+ TextCtrl : TextCtrl widget (wxTextCtrl)
+\end{verbatim}
+
+You can reproduce the same experiment as above using a
+\texttt{Slider} or a \texttt{FileDialog} rather than a \texttt{TextCtrl}.
+See the files \texttt{test*.bbs} in the \texttt{scripts/test} directory.
+
+There are two kind of widgets: ``terminal'' widgets and ``container'' widgets.
+The \texttt{TextCtrl}, \texttt{FileDialog} or \texttt{Slider} widgets
+are ``terminal'' widgets.
+``container'' widgets are of another kind: they are made to
+contain other widgets in order to build larger dialog boxes.
+For example, the \texttt{Split} widget is a container which
+``splits'' horizontally a window into two parts,
+each part including another widget.
+The size of the two parts can be adjusted by the user thanks
+to a ``handle''.
+
+The script \texttt{scripts/test/testSplit.bbs} demonstrate its use.
+Run it: it displays a window with two sliders.
+Move the sliders and close the window.
+The final positions of the sliders are printed out.
+Now edit the file to see how this is done:
+
+\begin{file}{scripts/test/testSplit.bbs}
+\begin{verbatim}
+load std
+load wx
+
+new Slider s1
+new Slider s2
+
+new Split s
+connect s.Child s1.Parent
+connect s.Child s2.Parent
+
+print s1=$s1.Out$\\n
+print s2=$s2.Out$\\n
+\end{verbatim}
+\end{file}
+
+First, the two sliders \texttt{s1} and \texttt{s2} are created.
+A \texttt{Split} box \texttt{s} is also created.
+The \texttt{connect} commands then ``includes'' the sliders in the
+split ``container''.
+The input \texttt{Parent} is common to all widget boxes:
+every widget can be inserted into another widget.
+The output \texttt{Child} is specific of \emph{container}
+widgets
+(in \bbi type \texttt{help Slider}:
+you will see the input \texttt{Parent};
+type \texttt{help Split}:
+you will see the input \texttt{Parent}
+and the output \texttt{Child}).
+When you connect the \texttt{Child} output of a container
+to the \texttt{Parent} input of a widget,
+you order to include the widget in the container.
+Of course, the order of connection is important.
+In our case, the slider \texttt{s1} is included first,
+then the slider \texttt{s2}: \texttt{s1} will be placed
+on top of \texttt{s2} (the \texttt{Split} box is
+implemented that way, but this is arbitrary choice).
+
+For the moment, there are only \emph{two} container widgets in the \texttt{wx} package:
+the \texttt{Split} widget we just described and the \texttt{Sizer}
+widget, which can have multiple children and
+divides its window into as much parts as children,
+each part of equal size.
+The orientation of the sizer can be changed by the input \texttt{Orientation}.
+See the example \texttt{test/testSizer.bbs}.
+With only those two containers you can already create
+complex dialog boxes (of course containers can be nested, which
+leads to tree-like structures of widgets).
+See the script \texttt{test/testSizerSplit.bbs} for an example.
+
+One word about a special widget in the package \texttt{wx}:
+the \texttt{Button}... to be continued.
+
+
+TO DO:
+\begin{enumerate}
+\item Make a tour of ``complex'' widgets of wxvtk
+\item Explain the role of ProcessMode to update widgets
+\item Explain the creation of complex widgets (containers, contained...)
+\item Explain the ``control'' mechanism in bbi (switch exec commands, e.g. Button)
+\end{enumerate}
+
+
+% ==========================================
+\subsection{More on ...}
+\label{bbi-more-on}
+% ==========================================
+
+% ==========================================
+\subsubsection{Black box packages}
+\label{bbi-more-on-packages}
+% ==========================================
+
+% ==========================================
+\subsubsection{Pipeline processing}
+\label{bbi-more-on-pipeline-processing}
+% ==========================================
+
+% ==========================================
+\subsubsection{Complex black boxes}
+\label{bbi-more-on-complex-black-boxes}
+
+%\subsubsection{Advanced issues}
+%\paragraph{Reducing the number of inputs of a box}
+
+% ==========================================
+\subsubsection{Errors}
+\label{bbi-more-on-errors}
+
+% ==========================================
+\subsubsection{\bbtk configuration file and search pathes}
+\label{bbi-more-on-configuration}
+
+At start, \bbi tries to open an \texttt{xml}
+configuration file named \texttt{bbtk\_config.xml}.
+The search order is
+\begin{enumerate}
+\item The current directory
+\item The subdir \texttt{.bbtk} of the user's home directory.
+\begin{itemize}
+\item On \texttt{Unix}, the home directory is the
+one stored by the environnement variable \texttt{HOME},
+typically \texttt{/home/username}.
+\item On \texttt{Windows}, the home directory is
+the user's profile directory stored by the environnement
+variable \texttt{USERPROFILE},
+typically \texttt{C:\\...}.
+\end{itemize}
+\item If none of these two pathes contains the file then it creates
+a new one in the \texttt{.bbtk} directory.
+\end{enumerate}
+
+Once created, you can edit the \texttt{bbtk\_config.xml} file located
+in your \texttt{.bbtk} directory. It contains:
+
+\begin{file}{bbtk\_config.xml}
+\begin{verbatim}
+<?xml version="1.0" encoding="iso-8859-1"?>
+<config>
+ <bbtk_url> http://www.creatis.insa-lyon.fr/software/bbtk </bbtk_url>
+ <bbs_path> </bbs_path>
+ <package_path> </package_path>
+ <data_path> </data_path>
+</config>
+\end{verbatim}
+\end{file}
+
+You can add pathes to
+\begin{itemize}
+\item A custom folder in which to search for \texttt{.bbs} scripts (\texttt{include} command of \bbi) by adding an \texttt{xml} tag:
+\texttt{<bbs\_path>complete\_path\_to\_folder<\/bbs\_path>}.
+\item A custom folder in which to search for packages (\texttt{load} command of \bbi) by adding an \texttt{xml} tag:
+\texttt{<package\_path>complete\_path\_to\_folder<\/package\_path>}.
+\end{itemize}
+
+% ==========================================
+\subsection{Language reference}
+\label{bbi-reference}
+% ==========================================
+
+
+
+
+
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{bbi-reference-box}
+\bbi pipeline creation and execution related commands.}
+\small
+\begin{tabular}{|lcm{6cm}|}
+\hline
+Command & Parameters & Effect \\ \hline
+
+\texttt{new} & \texttt{<boxtype>} \texttt{<box-name>}&
+Creates a box of type \texttt{boxtype} and name
+\texttt{box-name}.
+\\ \hline
+
+\texttt{delete} & \texttt{<box-name>} &
+Destroys the box named \texttt{box-name}.
+\\ \hline
+
+\texttt{connect} & \texttt{<box1.output>} \texttt{<box2.input>} &
+Connects the output
+\texttt{output} of the box named \texttt{box1}
+to the input \texttt{input} of the box named \texttt{box2} \\ \hline
+
+\texttt{set} & \texttt{<box.input>} \texttt{<value>} &
+Sets the input \texttt{input} of
+the box named \texttt{box} to the value \texttt{value}.
+There must exist an \texttt{adaptor}
+in the packages loaded which converts a \texttt{std::string}
+to the type of the input \texttt{input}.
+ \\ \hline
+
+\texttt{print} & \texttt{<string>} &
+Prints the string after substituting each token of the form \texttt{\$box.output\$} by the adaptation to string of the value of the
+output \texttt{output} of the box named \texttt{box}.
+There must exist an \texttt{adaptor}
+in the packages loaded which converts
+the type of the output \texttt{output}
+to a \texttt{std::string}.
+\\ \hline
+
+\texttt{exec} & \texttt{<box-name>} &
+Executes the box named \texttt{box-name}.
+If needed the boxes
+connected to its inputs
+are also processed recursively (pipeline processing).\\ \hline
+\end{tabular}
+\end{table}
+% ==========================================
+
+
+
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{bbi-reference-interpreter}\bbi intepreter related commands.}
+\small
+\begin{tabular}{|lcm{6cm}|}
+\hline
+Command & Parameters & Effect \\ \hline
+
+
+\texttt{help} & - &
+Prints help on available commands \\ \hline
+
+& \texttt{<command-name>} &
+Prints help on the command \texttt{command-name} \\ \hline
+
+& \texttt{packages} &
+Prints help on available packages and their box types
+(without description)\\ \hline
+
+& \texttt{<package-name>} &
+Prints help on the package \texttt{package-name} and its boxes
+(with brief description).
+The package must have been previously loaded
+\\ \hline
+
+& \texttt{<box-type>} &
+Prints help (with full description) on the type of box
+\texttt{box-type}.
+The box type must belong to a package which has been previously loaded
+\\ \hline
+
+\texttt{include} & \texttt{<file-name>} &
+Includes and executes the content of the file named \texttt{file-name}
+exactly like if you were typing its content at the place were the
+\texttt{include} command is.
+\\ \hline
+
+\texttt{load} & \texttt{<package-name>} &
+Loads the package \texttt{package-name}\\ \hline
+
+\texttt{unload} & \texttt{<package-name>}&
+Unloads the package \texttt{package-name}.
+The package must have been previously loaded.
+No box of a type defined in this package must still exist.
+\\ \hline
+
+\texttt{message} & \texttt{<category>} \texttt{<level>} &
+Sets the level of verbosity of \bbi for the category of messages
+\texttt{category} to \texttt{level}.
+%See \ref{verbosity}.
+\\ \hline
+
+\texttt{config} & - & Displays the Configuration parameters\\ \hline
+
+\texttt{reset} & - & Deletes all boxes and unloads all packages so
+that \bbi gets back to its initial state \\ \hline
+
+\texttt{quit} & - & Exits the interpreter\\ \hline
+
+\end{tabular}
+\end{table}
+% ==========================================
+
+
+
+
+
+% ==========================================
+\begin{table}[!ht]
+\caption{\label{bbi-reference-complex-box}
+\bbi complex black box definition related commands.}
+\small
+\begin{tabular}{|lcm{6cm}|}
+\hline
+Command & Parameters & Effect \\ \hline
+
+
+\texttt{define} & \texttt{<box-type>} &
+Starts the definition of a complex black box of type
+\texttt{box-type}\\ \hline
+
+\texttt{endefine} & - &
+Ends the definition of a complex black box type\\ \hline
+
+
+\texttt{author} & \texttt{<string>} &
+Sets the author(s) of the complex black box currently being defined \\ \hline
+
+\texttt{description} & \texttt{<string>} &
+Sets the description of the complex black box currently being defined
+\\ \hline
+
+
+\texttt{input} & \texttt{<name>} \texttt{<box.input>} \texttt{<help>} &
+Defines a new input for the current complex black box,
+named \texttt{name}.
+It is defined as corresponding to
+the input \texttt{input} of the box \texttt{box}.
+\texttt{<help>} is the help string for the new input.
+The box \texttt{box} must already have been created in the complex box
+and of course have an input named \texttt{input}.
+\\ \hline
+
+
+\texttt{output} & \texttt{<name>} \texttt{<box.output>} \texttt{<help>} &
+Defines a new output for the current complex black box,
+named \texttt{name}.
+It is defined as corresponding to
+the output \texttt{output} of the box \texttt{box}.
+\texttt{<help>} is the help string for the new output.
+The box \texttt{box} must already have been created in the complex box and of course have an output named \texttt{output}.
+\\ \hline
+
+
+\end{tabular}
+\end{table}
+% ==========================================
+
+
+
+
+% ==========================================
+\vspace{0.5cm}\hrule
+\section{Using black boxes in \CPP programs}
+\label{cpp}
+% ==========================================
+
+
+
+
+%\bibliography{all}
+
+
+
+%\section{Conclusion}
+\end{document}
+