X-Git-Url: https://git.creatis.insa-lyon.fr/pubgit/?a=blobdiff_plain;f=kernel%2Fdoc%2FbbtkUsersGuide%2FbbtkUsersGuide.tex;h=62590e0bba7bf6b3f776371087a8eb40e1dd4f75;hb=400f5daf4374267b93b347affb285943f60803f2;hp=fb6e13161236760470746ba57c7ba194b4a66e70;hpb=e04a3f7bc34fada6a357adcf8bcf2021f54d8ff8;p=bbtk.git diff --git a/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex b/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex index fb6e131..62590e0 100644 --- a/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex +++ b/kernel/doc/bbtkUsersGuide/bbtkUsersGuide.tex @@ -34,6 +34,14 @@ 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''}. +I would add something very important to this definition : +not only the inputs and outputs are of interest but also +\emph{what the box does} ! +Hence, I would say that a black box is any \emph{\bf documented} +component of a system, letting know the user +\emph{\bf what} the box is supposed to do and +\emph{\bf how to use it} +but not \emph{\bf how it does it}. \BBTK provides a systematic framework to encapsulate (or ``wrap'') any @@ -46,7 +54,7 @@ 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 +\item{\bf symbolic} means that 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 @@ -82,13 +90,13 @@ 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. +\bbi. \end{itemize} Finally, these different components allow {\bf efficient}: \begin{itemize} -\item {\bf capitalization and reuse} of existing processings, +\item {\bf capitalization and reuse} of existing processing units, including {\bf documentation} \item {\bf testing, prototyping} in a very simple script language \item {\bf inter-operability} between atomic processings which @@ -119,10 +127,11 @@ processing chains by connecting various black boxes of the already loaded packag \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. +%\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 allows to create the basic file architecture +to start the development of a new black box package. \end{itemize} \end{itemize} @@ -208,14 +217,26 @@ Use it as a reference. 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} +You get a window which looks like the one in figure +\ref{bbi-fig-bbi-gui} +(the exact appearance of \bbi is system and \bbtk version dependent) +\footnote{If you compiled \bbtk without \wx then \bbi does not have a +graphical interface but a simple prompt}. + +\begin{figure}[!ht] +\caption{\label{bbi-fig-bbi-gui}The black box interpreter interface} +\begin{center} +\includegraphics[width=0.7\textwidth]{bbi-gui.png} +\end{center} +\end{figure} + +The 'Command' tab is subdivided into two parts : +one single line zone at the bottom in which you can enter your commands and +one multiple line zone in which \bbi prints out the result of your commands. -If you type: + +Try typing in the input zone (in this manual, +the commands entered by the user will be preceded by a prompt '>') : \begin{verbatim} > help \end{verbatim} @@ -224,21 +245,25 @@ you get the list of the commands of the interpreter: \begin{verbatim} Available commands: author + category config connect define delete description endefine + endpackage exec graph help include + index input load message new output + package print quit reset @@ -313,6 +338,7 @@ If you type \texttt{'help workspace'}, you get: Complex Black Box User's workspace By: bbi (internal) + Category(s) : complex box; * No inputs * No outputs * No boxes @@ -333,7 +359,7 @@ which contains basic useful black boxes. To load it, type: \begin{verbatim} -> load std +> include std \end{verbatim} Then if you type: @@ -364,13 +390,16 @@ You get: \begin{verbatim} Black Box Adds its inputs - By: laurent.guigues@creatis.insa-lyon.fr + By: laurent.guigues at creatis.insa-lyon.fr + Categories : atomic box;math; * Inputs: - 'In1' : First number to add - 'In2' : Second number to add - 'ProcessMode' : Set the process mode of the box (0=Pipeline | 1=Always | 2=Reactive) - * Outputs: - 'Out' : Result + 'BoxExecute' : Any signal received by this input executes the box + 'BoxProcessMode' : Sets the processing mode of the box (Pipeline | Always | Reactive) + 'In1' : First number to add + 'In2' : Second number to add + * Outputs : + 'BoxChange' : Signal modifications of the box + 'Out' : Result'In1' : First number to add \end{verbatim} Like previously, @@ -379,11 +408,12 @@ 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)). +the author(s) of the box (usually e-mail adress(es)) and +the categories to which the box belong. 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{}) +its \emph{type} (between \texttt{<>}, e.g. \texttt{}) and a description. Remark that the box \texttt{Add} is not a 'complex' black box but an 'atomic' box, hence its help does not @@ -418,6 +448,7 @@ you get: Complex Black Box User's workspace By: bbi (internal) + Category(s) : complex box; * No inputs * No outputs * Boxes: @@ -465,11 +496,11 @@ To process this special substrings, \bbi does: 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. +\item the input \texttt{'BoxProcessMode'} of the box is set to +\texttt{'Always'}, which forces box reprocessing. \end{itemize} -Note that all boxes have the input \texttt{'ProcessMode'}. +Note that all boxes have the input \texttt{'BoxProcessMode'}. Another way to process the box \texttt{a} is to issue the command: \begin{verbatim} @@ -494,7 +525,7 @@ Good bye ! \paragraph{Summary} %\hrule \begin{itemize} -\item The \texttt{load} command allows to load a package. +\item The \texttt{include} command allows to load a package. \item \texttt{help} gives help on: \begin{itemize} \item Available commands if you just type \texttt{help}. @@ -521,6 +552,8 @@ The same syntax holds for outputs. \label{bbi-connecting-black-boxes} % ========================================== +LG : THE GUIDE IS UP TO DATE UNTIL HERE + \BBTK allows to create and execute processing chains, also called \emph{pipelines}, @@ -531,9 +564,7 @@ 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 +> include std \end{verbatim} Assume you want to compute $1+2+3$. You can do it by