Added chapters Overview of SGPEM and Starting with SGPEM

git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@521 3ecf2c5c-341e-0410-92b4-d18e462d057c

doc/sgpem2uman.texi

@@ -65,12 +65,14 @@ Free Documentation License''.
 
 * History::       The history of changes to this document.
 
-* What is SGPEM:: Description and objectives of SGPEM v2.
+* Overview of SGPEM:: Description and objectives of SGPEM v2.
 
 * Installation::  Here we explain how to install SGPEM v2,
 		  as well as providing some advice for 
                   believed-to-be useful compilation options.
 
+* Starting with SGPEM:: Insructions on how to use SGPEM. 
+
 * License:: A full copy of the GNU Free Documentation License 
             this manual is licensed into.
 
@@ -80,11 +82,13 @@ Free Documentation License''.
 
 @c % --------------------------------------------------
 
-@node       History, What is SGPEM, Top, Top
+@node       History, Overview of SGPEM, Top, Top
 @unnumbered History
 
 @table @strong
 
+@item 2006, March 9th @r{--- Djina Verbanac}
+Add chapters Overview of SGPEM and Starting with SGPEM.
 @item 2006, January 26th @r{--- Matteo Settenvini}
 Add subsection about how to generate code documentation
 via Doxygen.
@@ -100,17 +104,20 @@ First draft of this document.
 
 @c % --------------------------------------------------
 
-@node    What is SGPEM, Installation, History, Top
+@node    Overview of  SGPEM, Installation, History, Top
-@chapter What is SGPEM
+@chapter Overview of  SGPEM
+
 
 @menu
 * Description and aims::
+* How to read this manual?::
+* Reporting Bugs::
 * Features::
 @end menu
 
 @c % --------------------------------------------------
 
-@node    Description and aims, Features, What is SGPEM, What is SGPEM
+@node    Description and aims, How to read this manual?, Overview of SGPEM, Overview of SGPEM
 @section Description and aims
 @cindex  SGPEM
 @cindex  description
@@ -119,27 +126,78 @@ SGPEM is an Italian acronym, standing for ``@emph{Simulatore della Gestione dei
 in un Elaboratore Multiprogrammato}'' (in English, ``@emph{Multitasking Computer Process 
 Management Simulator}'').
 It was initially developed for use inside the ``Operating Systems'' teaching,
-part of the Computer Science course of the University of Padova, Italy.
+part of the Computer Science course of the University of Padova, Italy. 
+
+SGPEMv2 is a didactic software, so the main product users are professors and students interested in the simulation of processes.
 
-SGPEMv2 is a didactic software aiming...
 
 @c % --------------------------------------------------
 
-@node    Features, (none), Description and aims, What is SGPEM
+@node    How to read this manual?, Reporting Bugs, Description and aims, Overview of SGPEM
+@section How to read this manual?
+@cindex  manual
+
+We recommend that you read the manual following the the structure that we imposed for it. 
+You will be guided trough the Installation, Configuration and Usage process of SGPEM v2.
+If you find yourself in trouble reading the manual, please don't hesitate to contact us at
+@email{swe@@thgnet.it}. 
+
+@c % --------------------------------------------------
+
+@node    Reporting Bugs,Features, How to read this manual?, Overview of SGPEM
+@section Reporting Bugs
+@cindex  bugs
+@cindex reporting
+
+We welcome bug reports and suggestions for any aspect of the SGPEM v2 system, program in general,
+documentation, installation, anything.Please email us at @email{swe@@thgnet.it}.
+For bug reporters, include enough information for us to reproduce the problem. In general:
+@itemize
+@item
+version and number of SGPEM v2.
+@item
+hardware and operating system name and version.
+@item
+the content of any file neccesary to reproduce the bug.
+@item
+description of the problem and any erroneous output.
+@item
+any unusual option you gave to configure.
+@item
+anything else you think might be helpful.
+@end itemize
+If you are ambitious you can try to fix the problem yourself, but we warmly recommend that you read the
+Developer Manual first.
+
+
+@c % --------------------------------------------------
+
+
+@node    Features, (none), Reporting Bugs, Overview of SGPEM
 @section Features
 @cindex  features
 
 Main features are:
-
+@itemize
-@itemize 
 @item
-Graphical display of simulated processes...
+For now you can use only prompt commands to start the simulation and change some parameters.
-
+For more information see @ref{SGPEM Commands}. 
+@item
+You can use the program from your own shell, or if you prefer you can use the minimal GUI that SGPEM offers, at this moment.
+@item
+The output of the simulation is textual, and you can see it on the main GUI window or on your Terminal window.
+@item
+The policy in use if First Come First Served.
+@item
+You can write your own policies.
+For more information see @ref{Writing new policies}.
 @end itemize
 
+
+
 @c % --------------------------------------------------
 
-@node    Installation, License, What is SGPEM, Top
+@node    Installation, Starting with SGPEM, Overview of SGPEM, Top
 @chapter Installation
 @cindex  installation
 
@@ -296,8 +354,84 @@ install @command{dot}, part of the @emph{Graphviz} package.
 
 @c % --------------------------------------------------
 
+
+
+@node Starting with SGPEM, License, Installation, Top
+@chapter Starting with SGPEM
+@cindex starting
+
+@menu
+
+* SGPEM Commands:: Here you find a set of commands available 
+                        from the command line
+* SGPEM Output:: Interpretation of the output 
+* Writing new policies:: Steps that must be followed to insert a new policy
+
+@end menu
+
+@c % -------------------------------------------------
+@node SGPEM Commands, SGPEM Output, Starting with SGPEM, Starting with SGPEM
+@section SGPEM Commands
+@cindex commands
+
+
+@table @strong
+
+@item help @command{<string>}
+If <string> is a valid command, it prints the usage instructions for that specific command
+@item @command{run}
+ Advances the simulation by one or more steps, depending on the actual state and on the value sett ed with setmode
+@item @command{pause}
+ It is useful only when the advancement mode is continue. Calling again run will cause the simulation to start from the current simulation step.
+@item @command{stop}
+ Stops the simulation.
+@item @command{setmode <bool>}
+ This methods allows to change the way the simulation progresses. If the input value is 0 (false), the simulation will advance a single time step for each call to run. If the 
+ input value is 1 (true), the simulation will advance contiuosly, waiting the time defined with settimer between each step, until all processes terminate, 
+ or some error occurs. 
+@item @command{getmode}
+ Prints the simulation advancement mode: 0 if step-to-step, 1 if continue.
+@item @command{settimer <int>}
+ This command is used to define how a single time unit is to be interpreted when the simulation advancement mode is continue. 
+ The input value is in milliseconds, and it must be in range [0, 10000]. 
+@item @command{gettimer}
+ Prints the value of the current timer
+@item @command{reset}
+ Resets the simulation.Erases the state of the simulation, and takes care of removing any residual or temporary data to ensure the simulation has reached 
+ a clean and stable state. 
+@item @command{jumpto <int>}
+ Causes the simulation to jump to a given time unit.
+@item @command{getpolicy}
+ Prints the current policy.
+@item @command{getpolicyattributes}
+ Prints the name and the value of the policy's attributes
+ 
+@end table
+
+@c % -------------------------------------------------
+
+@node SGPEM Output, Writing new policies, SGPEM Commands,Starting with SGPEM
+@section SGPEM Output
+@cindex output
+
+You can seg the textual output of the simulation in your console window or on the GUI window provided with SGPEM v2.
+The output of RUN is one or more rows each of which represents the state of the schedulable entities. 
+It can be RUNNING, READY, BLOCKED, FUTURE or TERMINATED.
+The row begins with the number of the instant described by the following lists of states. 
+The instant 0 represents the INITIAL STATE during which no process is running. 
+The scheduler activity begins at instant 1. Each schedulable entity is represented by its 
+name followed by its priority enclosed between round parenthesis.
+
+@c % ------------------------------------------------
+
+@node Writing new policies, (none), SGPEM Output, Starting with SGPEM
+@section Writing new policies
+@cindex policies
+
+
+@c % -------------------------------------------------
 @c include license text
-@node License, Concept index, Installation, Top
+@node License, Concept index, Starting with SGPEM, Top
 @include fdl.texi
 
 @c % --------------------------------------------------