Written documentation for section "The Schedulables/Requests tree"

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

doc/sgpem2uman.texi

@@ -89,6 +89,8 @@ Free Documentation License''.
 @unnumbered History
 
 @table @strong
+@item 2006, September 9th @r{--- Luca Vezzaro} 
+Written documentation for section "The Schedulables/Requests tree"
 @item 2006, September 8th @r{--- Luca Vezzaro} 
 Written documentation for section "Overall view of the main window"
 @item 2006, September 8th @r{--- Matteo Settenvini}
@@ -564,9 +566,9 @@ Normally, the window is split into three sections.
 @itemize
 @item
 The top left section is briefly called 
-the "Schedulables tree", although this is not completely correct, since except from resources,
-every entity in the SGPEMv2 is shown and edited in this tree view.
-The interface of this widget is straightforward, but in case you need to know about it,
+the "Schedulables tree", every entity, except resources, in the SGPEMv2 is shown and 
+edited in this tree view.
+The interface of this widget is straightforward, but in case you need to know more about it,
 see @ref{The Schedulables/Requests tree}.
 
 @item
@@ -590,6 +592,49 @@ need it if you don't use resources and/or requests in your simulation. For more
 @subsection The Schedulables/Requests tree
 @cindex schedulables tree
 
+This widget is used to add/edit/remove processes, threads and requests. 
+To perform an operation on it, simply right-click, and a context-sensitive menu
+will popup.
+
+Each tree level is dedicated to a specific entity:
+@itemize
+@item The first level is for @strong{processes}
+@item The second level is for @strong{threads}
+@item The third level is for @strong{requests}
+@end itemize
+
+Right-clicking on any location over the tree will always allow you to add processes, while to
+add threads or requests you must select a process or a thread, respectively.
+To remove or edit an entity simply select it, and the popup menu will contain the remove
+or edit operation specific for that entity. 
+
+Anyway, these functionalities are only useful for a stopped simulation. While the simulation
+is not in a stopped state, a lot of dynamic information is displayed by the widget.
+
+Let's begin by describing what's the meaning of the colors used to highlight the entities' name:
+@itemize
+@item @strong{Light Grey} is used for "future" processes, threads, requests and subrequests. 
+"future" means an entity in the real world will still not exist, since it will "arrive" 
+at a time greater than the current instant
+@item @strong{Green} is used for running processes, threads and for allocated requests and subrequests
+@item @strong{Yellow} is used for ready processes, threads and for allocable requests and subrequests
+@item @strong{Red} is used for blocked processes, threads and for unallocable requests and subrequests 
+@item @strong{Dark Grey} is used for terminated processes, threads and for exhausted requests and subrequests
+@end itemize
+
+The dynamic display for processes and threads simply consists of their "elapsed time" (the time they've
+been given the processor) and "current priority", which is obviously their dynamic priority which may change
+if the scheduling policy decides to do so.
+
+Probably the format used to display requests is a bit less trivial (yes, I'm sarcastic), but since
+a request has no additional information other than its state, it makes sense to condense requests and
+its associated subrequests on a single line. @*
+So the color of the @strong{at <n>:} represents the state of the
+request, the <n> being the instant at which the request is raised.@*
+Then there are a series of subrequests, which are displayed as colored @strong{->} (arrows), followed by a 
+resource name and two numbers separated by a slash. The color of the arrow represents the state of the subrequest,
+and the numbers between parenthesis are its "elapsed time"/"required time".
+
 @c % -------------------------------------------------
 @node The Resources list, The Simulation widget, The Schedulables/Requests tree, From the GUI
 @subsection The Resources list