Work on documentation.

doc/additionalDoc/dgshell_doc.h

+/**
+\page dgshell_doc dg-shell executable
+Dynamic-graph shell program "dg-shell" allows access to the dynamic-graph library's
+Interpreter class, which can execute commands and scripts from the command line.
+It can be found in the installlation prefix's bin/ directory.
+
+There is also a linux shell script available, dg-shell-plugin, that runs
+dg-shell with a default script, which in turns loads useful plugins as
+shell-functions and shell-procedure.
+**/

doc/additionalDoc/package.h

 /*
  * Copyright 2010,
  * François Bleibel,
+ * Thomas Moulard,
  * Olivier Stasse,
  *
  * CNRS/AIST
@@ -28,7 +29,61 @@ together using a graph system, akin to what Simulink does. With the building
 blocks this package provides, you can easily create a full computation graph
 for a given problem. It is the basis for the stack of tasks operation.
 
+\image html pictures/entity.png
+Functionality:
+\li Built-in scripting language* for fast prototyping and testing
+\li Support for extensions and modules using dynamic link libraries
+\li Template-based signal definition, independant
+\li Type-safe connection of input and output signals
+\li On-demand signal computation as well as a caching system for signal values allow fast
+computation of signal values, which is a critical point for real-time systems\n
+* See \ref scriptingabout
+
 \section overview Code overview
+
+\section entities List of entities in this package
+Since most of the functionality in projects using the dynamic-graph framework
+is exposed from entities, here is a short description of all the entities contained in
+this package. Note that most entities are contained in a binary file that closely matches
+the entities' names in the scripts; loading this file with the plugin loader will
+enable creation of this entity through the factory.
+\li \ref tracerdoc
+\li \ref tracerrealtimedoc
+\li ShellProcedure
+\li \ref shellfunctions_doc
+
+The entities will be placed in ${PREFIX}/lib/plugin (since this may change, it is advised to
+check the install log or the CMakeLists.txt file to check the installation path).
+\section sigintro About signals
+
+Entities can output different types of signals. All signals are templated by a Time
+tick type parameter (which is used in the caching of signals) - usually \c int. Signals
+are also templated after the type of data they accept or provide. For example:
+(example)
+For a more detailed programmer-oriented description of signals, please see \ref signals
+
+\section scriptingabout Note about the scripting language
+The scripting language allows entities to define their own commands, and
+provides a basic framework for working with the dynamic-graph.
+
+A couple of functions are built-in in the interpreter and provides low-level features such as file sourcing or
+plug-in loading.\n
+These functions are:\n
+\code plug <obj1.sig1> <obj2.sig2> \endcode plugs the signal sig1 of obj1 to the signal sig2 of obj2. sig1 and sig2
+have to be of the same type. sig1 has to be an output signal and sig2 an input signal.
+\code new <class> <object> \endcode instantiates an object object of class class. object has to be a free identifier and
+class an existing entity.
+\code destroy <object> \endcode deletes an instance previously created.
+\code run <script.txt> \endcode sources (i.e. read and interpret) an external file.
+\code loadPlugin <file.so> <directory> \endcode loads a plugin called file.so and located in the directory directory.
+\code unloadPlugin <path/file.so> \endcode unloads a plugin.
+\code help \endcode lists available functions.
+\code set <obj.signal> <value> \endcode defines an input signal to a specific, constant, value.
+\code get <obj.signal> <value> \endcode
+\code compute <obj.sig> <time> \endcode computes an output signal and sets the associated time to time.
+
+\section usecase How to use this package
+1) Programmatically
 This code implements the factory design pattern, making creation of entities
 available to packages depending on the dynamic-graph API.
 
@@ -59,34 +114,22 @@ corresponding headers in this module are:
 \li g_pool: dynamicgraph::PoolStorage
 \li g_shell: dynamicgraph::Interpreter
 
-\section entities List of entities in this package
-Since most of the functionality in projects using the dynamic-graph framework
-is exposed from entities, here is a short description of all the entities contained in
-this package. Note that most entities are contained in a binary file that closely matches
-the entities' names in the scripts; loading this file with the plugin loader will
-enable creation of this entity through the factory.
-\li \ref tracerdoc
-\li \ref tracerrealtimedoc
-\li ShellProcedure
-\li \ref shellfunctions_doc
-\li \link dynamicgraph::Contiifstream Contiifstream \endlink
-
-The entities will be placed in ${PREFIX}/lib/plugin (since this may change, it is advised to
-check the install log or the CMakeLists.txt file to check the installation path).
-\section sigintro About signals
+For an example of a program creating entities programmatically, see the unit test
+test_pool.cpp (in your package source directory/unitTesting).
 
-Entities can output different types of signals. All signals are templated by a Time
-tick type parameter (which is used in the caching of signals) - usually \c int. Signals
-are also templated after the type of data they accept or provide. For example:
-(example)
-For a more detailed programmer-oriented description of signals, please see \ref signals
+2) Through scripts
+The program \ref dgshell_doc can be used to have scripting access to the dynamic-graph
+library, where you can execute scripts and commands, load plugins, create entities and connect signals.
 
-\section scriptingabout About the scripting language
-(...)
+Here is a typical use case for programmers:
+\image html figures/use-case.svg
 
-\section usecase Programmers use case
+\section References
+\anchor Mansard2007
 
-\image html pictures/use-case.svg
+<b>"Task sequencing for sensor-based control"</b>,
+<em>N. Mansard, F. Chaumette,</em>
+IEEE Trans. on Robotics, 23(1):60-72, February 2007
 
 
 \defgroup dgraph Core classes and objects

doc/figures/use-case.svg

+<svg xmlns:x="http://ns.adobe.com/Extensibility/1.0/" xmlns:i="http://ns.adobe.com/AdobeIllustrator/10.0/" xmlns:graph="http://ns.adobe.com/Graphs/1.0/" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/"  xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="721" height="735"><defs></defs><rect stroke="#000000" stroke-width="0" fill="#ffffff" x="0" y="0" width="720" height="734"/><g transform='translate(21.0,40.0)'><line x1='0.0' y1='0.0' x2='601.0' y2='0.0' stroke-dasharray='23, 0' stroke='#333333' stroke-width='1' /><g transform='translate(290.5,0.0)'></g></g><g transform='translate(26.5,-9.5) rotate(0 175.0 33.5)'><g  transform='translate(0.0,41.5)'><text x='2' style='text-anchor: start' y='-3.0'><tspan xml:space='preserve' font-size='18' font-family='Arial' fill='#000000' >Typical plugin loading and usage process</tspan></text></g></g><g transform='translate(56.0,55.5) rotate(0 70.0 37.5)'><g transform='translate(0.0,0.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='21.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g transform='translate(0.0,21.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='20.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g transform='translate(0.0,41.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='34.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g  transform='translate(0.0,15.5)'><text x='70.0' style='text-anchor: middle' y='-2.0'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' font-weight='bold' text-decoration='underline' >:PluginLoader</tspan></text></g><g ></g><g ></g></g><g transform='translate(91.26515179773804,214.89454904672732) rotate(0 37.734848202261965 30.10545095327268)'><rect x='0.0' y='4.493350888548161' width='67.65211829090791' height='55.41799429209398'  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><polygon points='0.0,4.493350888548161 7.516902032323101,0.0 75.16902032323101,0.0 67.65211829090791,4.493350888548161 '  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><polygon points='75.16902032323101,0.0 75.16902032323101,55.41799429209398 67.65211829090791,59.911345180642144 67.65211829090791,4.493350888548161 '  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><g  transform='translate(0.0,35.10545095327268)'><text x='37.734848202261965' style='text-anchor: middle' y='-2.0'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' font-style='italic' >plugin.so</tspan></text></g></g><g transform='translate(361.0,245.5) rotate(0 70.0 37.5)'><g transform='translate(0.0,0.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='21.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g transform='translate(0.0,21.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='20.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g transform='translate(0.0,41.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='34.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g  transform='translate(0.0,15.5)'><text x='70.0' style='text-anchor: middle' y='-2.0'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' font-weight='bold' text-decoration='underline' >factory:Factory</tspan></text></g><g ></g><g ></g></g><g transform='translate(361.0,395.5) rotate(0 70.0 37.5)'><g transform='translate(0.0,0.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='21.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g transform='translate(0.0,21.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='20.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g transform='translate(0.0,41.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='34.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g  transform='translate(0.0,15.5)'><text x='70.0' style='text-anchor: middle' y='-2.0'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' font-weight='bold' text-decoration='underline' >pool:Pool</tspan></text></g><g ></g><g ></g></g><g transform='translate(361.0,542.0) rotate(0 70.0 45.0)'><g transform='translate(0.0,0.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='36.0'  stroke="#000000" stroke-width="2.0" fill="#ffffff"/></g><g transform='translate(0.0,36.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='34.0'  stroke="#000000" stroke-width="2.0" fill="#ffffff"/></g><g transform='translate(0.0,70.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='20.0'  stroke="#000000" stroke-width="2.0" fill="#ffffff"/></g><g  transform='translate(0.0,15.0)'><text x='70.0' style='text-anchor: middle' y='-2.0'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' font-weight='bold' text-decoration='underline' >myEntityInstance</tspan></text><text x='70.0' style='text-anchor: middle' y='14.2'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' font-weight='bold' text-decoration='underline' >:Entity</tspan></text></g><g  transform='translate(0.0,54.0)'><text x='2' style='text-anchor: start' y='-2.0'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' >+</tspan><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' >commandLine(input</tspan></text><text x='2' style='text-anchor: start' y='14.2'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' >stream, output stream)</tspan></text></g><g ></g></g><g transform='translate(130.0,214.0)'><line x1='-0.017762440882695196' y1='-0.49968439608805953' x2='-3.0' y2='-84.39454904672732' stroke-dasharray='23, 0' stroke='#000000' stroke-width='1' /><g transform='translate(0.0,0.0) rotate(267.9641458400894)'><polygon points='2.0,0 8.0,-3.0 8.0,3.0' fill='#000000' stroke='#000000' stroke-width='1.0' /></g><g transform='translate(-1.5031560391194043,-37.19727452336366)'><rect fill='#ffffff' x='-20.5' y='-9.0' width='41.0' height='15'/><text x='0.0' style='text-anchor: middle' y='2.0'><tspan font-size='13px' font-family='Arial' fill='#000000' >loads</tspan></text></g></g><g transform='translate(360.0,128.5) rotate(0 70.0 37.5)'><g transform='translate(0.0,0.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='21.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g transform='translate(0.0,21.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='20.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g transform='translate(0.0,41.0)'><rect x='0.0' y='0.0' width='139.4422310756972' height='34.0'  stroke="#000000" stroke-width="2.0" fill="#ffcc33"/></g><g  transform='translate(0.0,15.5)'><text x='70.0' style='text-anchor: middle' y='-2.0'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' font-weight='bold' >Shell:Interpreter</tspan></text></g><g ></g><g ></g></g><g transform='translate(536.2421099913893,64.97396996134887) rotate(0 29.75789000861068 48.026030038651136)'><circle cx='29.56081788934836' cy='9.566938254711381' r='9.85360596311612'  fill='#FFFFFF'  stroke="#000000" stroke-width="1.0"/><line x1='29.56081788934836' y1='19.133876509422763' x2='29.56081788934836' y2='57.40162952826829'  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><line x1='29.56081788934836' y1='57.40162952826829' x2='19.70721192623224' y2='95.66938254711381'  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><line x1='29.56081788934836' y1='57.40162952826829' x2='39.41442385246448' y2='95.66938254711381'  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><line x1='29.56081788934836' y1='57.40162952826829' x2='39.41442385246448' y2='95.66938254711381'  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><line x1='0.0' y1='28.700814764134144' x2='59.12163577869672' y2='28.700814764134144'  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><g  transform='translate(0.0,114.05206007730227)'><text x='29.75789000861068' style='text-anchor: middle' y='-2.0'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' >user</tspan></text></g></g><g transform='translate(431.0,321.0)'><line x1='0.006666074153073843' y1='0.4999555614806037' x2='1.0' y2='75.0' stroke-dasharray='23, 0' stroke='#000000' stroke-width='1' /><g transform='translate(0.0,0.0) rotate(89.23610153907002)'><polygon points='2.0,0 8.0,-3.0 8.0,3.0' fill='#000000' stroke='#000000' stroke-width='1.0' /></g><g transform='translate(0.49955561480603716,42.5)'><rect fill='#ffffff' x='-53.0' y='-9.0' width='106.0' height='15'/><text x='0.0' style='text-anchor: middle' y='2.0'><tspan font-size='13px' font-family='Arial' fill='#000000' >calls newEntity()</tspan></text></g></g><g transform='translate(501.0,580.0)'><path d='M1.0,0.0 L94.75789000861073,0.0 Q104.75789000861073,0.0 104.75789000861073,-10.0 L104.75789000861073,-457.0 Q104.75789000861073,-467.0 94.75789000861073,-467.0 L93.75789000861073,-467.0 ' stroke-dasharray='23, 0' fill='none' stroke='#000000' stroke-width='1' /><g transform='translate(0.0,0.0) rotate(0.0)'><polygon points='2.0,0 8.0,-3.0 8.0,3.0' fill='#000000' stroke='#000000' stroke-width='1.0' /></g><g transform='translate(104.75789000861073,-166.62105499569464)'><rect fill='#ffffff' x='-98.5' y='-17.0' width='197.0' height='15'/><text x='0.0' style='text-anchor: middle' y='-6.0'><tspan font-size='13px' font-family='Arial' fill='#000000' >requests new instance creation</tspan></text><rect fill='#ffffff' x='-98.5' y='1.1999999999999993' width='197.0' height='15'/><text x='0.0' style='text-anchor: middle' y='12.2'><tspan font-size='13px' font-family='Arial' fill='#000000' >(either through code or the shell)</tspan></text></g></g><g transform='translate(196.0,93.0)'><line x1='0.49913841090379535' y1='0.029340190190827932' x2='340.24210999138927' y2='20.0' stroke-dasharray='23, 0' stroke='#000000' stroke-width='1' /><g transform='translate(0.0,0.0) rotate(3.364070655892468)'><polygon points='2.0,0 8.0,-3.0 8.0,3.0' fill='#000000' stroke='#000000' stroke-width='1.0' /></g><g transform='translate(160.13828677761873,10.0)'><rect fill='#ffffff' x='-98.5' y='-17.0' width='197.0' height='15'/><text x='0.0' style='text-anchor: middle' y='-6.0'><tspan font-size='13px' font-family='Arial' fill='#000000' >requests plugin load</tspan></text><rect fill='#ffffff' x='-98.5' y='1.1999999999999993' width='197.0' height='15'/><text x='0.0' style='text-anchor: middle' y='12.2'><tspan font-size='13px' font-family='Arial' fill='#000000' >(either through code or the shell)</tspan></text></g></g><g transform='translate(167.0,245.0)'><path d='M0.0,0.0 Q96.5,0.0 96.5,-39.5 Q96.5,-79.0 189.0,-78.98193899898531 ' stroke-dasharray='23, 0' fill='none' stroke='#000000' stroke-width='1' /><g transform='translate(193.0,-79.0) rotate(539.0)'><polygon points='2.0,0 8.0,-3.0 8.0,3.0' fill='#000000' stroke='#000000' stroke-width='1.0' /></g><g transform='translate(102.0,-37.5)'><rect fill='#ffffff' x='-90.0' y='-9.0' width='180.0' height='15'/><text x='0.0' style='text-anchor: middle' y='2.0'><tspan font-size='13px' font-family='Arial' fill='#000000' >(auto-)registers functions with</tspan></text></g></g><g transform='translate(361.0,283.0)'><path d='M-4.0,-0.008528940762130819 Q-97.13257589886902,0.0 -97.13257589886902,-19.0 Q-97.13257589886902,-38.0 -194.26515179773804,-38.0 ' stroke-dasharray='23, 0' fill='none' stroke='#000000' stroke-width='1' /><g transform='translate(0.0,0.0) rotate(180.0)'><polygon points='2.0,0 8.0,-3.0 8.0,3.0' fill='#000000' stroke='#000000' stroke-width='1.0' /></g><g transform='translate(-92.0,-16.5)'><rect fill='#ffffff' x='-85.0' y='-9.0' width='170.0' height='15'/><text x='0.0' style='text-anchor: middle' y='2.0'><tspan font-size='13px' font-family='Arial' fill='#000000' >(auto-)registers entities with</tspan></text></g></g><g transform='translate(431.0,471.0)'><line x1='0.0' y1='0.5' x2='0.0' y2='64.0' stroke-dasharray='23, 0' stroke='#000000' stroke-width='1' /><g transform='translate(0.0,0.0) rotate(90.0)'><polygon points='2.0,0 8.0,-3.0 8.0,3.0' fill='#000000' stroke='#000000' stroke-width='1.0' /></g><g transform='translate(0.0,37.0)'><rect fill='#ffffff' x='-74.0' y='-9.0' width='148.0' height='15'/><text x='0.0' style='text-anchor: middle' y='2.0'><tspan font-size='13px' font-family='Arial' fill='#000000' >(auto-)registers entity to</tspan></text></g></g><g transform='translate(361.0,587.0)'><line x1='0.0' y1='0.0' x2='-131.5' y2='-6.123233995736766E-17' stroke-dasharray='23, 0' stroke='#000000' stroke-width='1' /><g transform='translate(-132.0,0.0) rotate(360.0)'><polygon points='2.0,0 8.0,-3.0 8.0,3.0' fill='#000000' stroke='#000000' stroke-width='1.0' /></g><g transform='translate(-76.0,0.0)'></g></g><g transform='translate(81.5,555.0) rotate(0 72.5 40.0)'><polygon points='0.0,0.0 124.203187250996,0.0 144.42231075697208,18.543046357615896 144.42231075697208,79.47019867549669 0.0,79.47019867549669 '  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><line x1='124.203187250996' y1='0.0' x2='124.203187250996' y2='18.543046357615896'  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><line x1='124.203187250996' y1='18.543046357615896' x2='144.42231075697208' y2='18.543046357615896'  stroke="#000000" stroke-width="1.0" fill="#ffffff"/><g  transform='translate(0.0,21.0)'><text x='72.5' style='text-anchor: middle' y='-2.0'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' >Can respond to</tspan></text><text x='72.5' style='text-anchor: middle' y='14.2'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' >commands e.g. (in the</tspan></text><text x='72.5' style='text-anchor: middle' y='30.4'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' >shell) myEntity.help,</tspan></text><text x='72.5' style='text-anchor: middle' y='46.599999999999994'><tspan xml:space='preserve' font-size='13' font-family='Arial' fill='#000000' >etc.</tspan></text></g></g></svg>
\ No newline at end of file