From 7fdd9d11419684606beb08a8a7bc673955eb08af Mon Sep 17 00:00:00 2001
From: mquinson <mquinson@48e7efb5-ca39-0410-a469-dd3cf9ba447f>
Date: Sun, 16 Jul 2006 18:47:18 +0000
Subject: [PATCH] placeholders for lessons 8 and 9, plus add tocs all over the
 place to ease the navigation

git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@2595 48e7efb5-ca39-0410-a469-dd3cf9ba447f
---
 doc/Doxyfile.in                |  2 ++
 doc/gtut-main.doc              |  1 +
 doc/gtut-tour-1-bones.doc      | 12 ++++++-
 doc/gtut-tour-2-simple.doc     | 10 +++++-
 doc/gtut-tour-3-args.doc       |  9 ++++-
 doc/gtut-tour-4-callback.doc   | 10 +++++-
 doc/gtut-tour-5-globals.doc    | 14 +++++++-
 doc/gtut-tour-6-logs.doc       | 12 +++++--
 doc/gtut-tour-7-timers.doc     |  9 ++++-
 doc/gtut-tour-8-exceptions.doc | 26 ++++++++++++++
 doc/gtut-tour-9-rpc.doc        | 26 ++++++++++++++
 doc/gtut-tour.doc              | 63 ++++++++++++++++++++++++++++------
 12 files changed, 175 insertions(+), 19 deletions(-)
 create mode 100644 doc/gtut-tour-8-exceptions.doc
 create mode 100644 doc/gtut-tour-9-rpc.doc

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 8edce6fb1e..d950258291 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -416,6 +416,8 @@ INPUT                  = @srcdir@/index.doc \
 				@srcdir@/gtut-tour-5-globals.doc \
 				@srcdir@/gtut-tour-6-logs.doc \
 				@srcdir@/gtut-tour-7-timers.doc \
+				@srcdir@/gtut-tour-8-exceptions.doc \
+				@srcdir@/gtut-tour-9-rpc.doc \
 			 \
                          ./logcategories.doc \
 			 \
diff --git a/doc/gtut-main.doc b/doc/gtut-main.doc
index cf49a72b89..4801e9ec0e 100644
--- a/doc/gtut-main.doc
+++ b/doc/gtut-main.doc
@@ -24,6 +24,7 @@ This section constitutes a tutorial to the GRAS programming environment.
    - \ref GRAS_tut_tour_logs
    - \ref GRAS_tut_tour_timers
    - \ref GRAS_tut_tour_exceptions
+   - \ref GRAS_tut_tour_rpc
 
     \htmlonly <!-- 
       DOXYGEN_NAVBAR_LABEL="Tutorial"
diff --git a/doc/gtut-tour-1-bones.doc b/doc/gtut-tour-1-bones.doc
index cd8a02b4d1..642b37d702 100644
--- a/doc/gtut-tour-1-bones.doc
+++ b/doc/gtut-tour-1-bones.doc
@@ -2,6 +2,16 @@
 /** 
 @page GRAS_tut_tour_setup Lesson 1: Setting up your own project
 
+\section GRAS_tut_tour_setup_toc Table of Contents
+ - \ref GRAS_tut_tour_setup_C
+ - \ref GRAS_tut_tour_setup_plat
+ - \ref GRAS_tut_tour_setup_deploy
+ - \ref GRAS_tut_tour_setup_glue
+ - \ref GRAS_tut_tour_setup_make
+ - \ref GRAS_tut_tour_setup_start
+
+<hr>      
+
 Any GRAS project should be constituted of at least 3 files, and possibly
 much more.
 
@@ -179,6 +189,6 @@ That's it. You are done with this lesson and can now write, build and
 execute GRAS applications as long as they don't do anything ;) Move
 to the next lessons to add some flesh on these bones.
 
-\ref GRAS_tut_tour_simpleexchange
+Go to \ref GRAS_tut_tour_simpleexchange
 
 */
diff --git a/doc/gtut-tour-2-simple.doc b/doc/gtut-tour-2-simple.doc
index b7bb396226..3fcfab6751 100644
--- a/doc/gtut-tour-2-simple.doc
+++ b/doc/gtut-tour-2-simple.doc
@@ -2,6 +2,14 @@
 /** 
 @page GRAS_tut_tour_simpleexchange Lesson 2: Exchanging simple messages
 
+\section GRAS_tut_tour_simpleexchange_toc Table of Contents
+ - \ref GRAS_tut_tour_simpleexchange_msgtype
+ - \ref GRAS_tut_tour_simpleexchange_socks
+ - \ref GRAS_tut_tour_simpleexchange_exchange
+ - \ref GRAS_tut_tour_simpleexchange_recaping
+    
+<hr>      
+
 \section GRAS_tut_tour_simpleexchange_msgtype Declaring the messages to be exchanged
 
 We will now see how to exchange messages between hosts. As explained in
@@ -112,6 +120,6 @@ Here we are, you now know how to exchange messages between peers. There is
 still a large room for improvement, such as adding payload to messages. But
 there some little things you should know before we speak of payloads.
 
-\ref GRAS_tut_tour_args
+Go to \ref GRAS_tut_tour_args
 
 */
diff --git a/doc/gtut-tour-3-args.doc b/doc/gtut-tour-3-args.doc
index 9ea00566f4..b8a69dbbe0 100644
--- a/doc/gtut-tour-3-args.doc
+++ b/doc/gtut-tour-3-args.doc
@@ -2,6 +2,13 @@
 /** 
 @page GRAS_tut_tour_args Lesson 3: Passing arguments to the processes (in SG)
 
+\section GRAS_tut_tour_args_toc Table of Contents
+ - \ref GRAS_tut_tour_args_use
+ - \ref GRAS_tut_tour_args_sg
+ - \ref GRAS_tut_tour_args_recap
+   
+<hr>
+
 The most problematic issue with the code of previous lesson is that it does
 not work in RL since we hardcoded the server hostname in the client code. We
 will thus learn you how to pass arguments to your processes to overcome this
@@ -37,6 +44,6 @@ The whole program now reads:
 And here is the output:
 \include 3-args.output
 
-\ref GRAS_tut_tour_callbacks
+Go to \ref GRAS_tut_tour_callbacks
 
 */
diff --git a/doc/gtut-tour-4-callback.doc b/doc/gtut-tour-4-callback.doc
index 82ff58790e..5cf803f236 100644
--- a/doc/gtut-tour-4-callback.doc
+++ b/doc/gtut-tour-4-callback.doc
@@ -2,6 +2,14 @@
 /** 
 @page GRAS_tut_tour_callbacks Lesson 4: Attaching callbacks to messages
 
+\section GRAS_tut_tour_callbacks_toc Table of Contents
+ - \ref GRAS_tut_tour_callbacks_declare
+ - \ref GRAS_tut_tour_callbacks_attach
+ - \ref GRAS_tut_tour_callbacks_handle
+ - \ref GRAS_tut_tour_callback_recap
+    
+<hr>
+
 Our program is well and good, but if we had to write a longer program,
 explicitely waiting for messages of a given type would not be really
 practical. To add some more dynamism, what we want to do is to attach
@@ -72,5 +80,5 @@ lastly attached first, and if the return value is 0, it will pass it also to
 the next one, and so on. I'm not sure there is any sensible use of this
 feature, but it's possible ;)
 
-\ref GRAS_tut_tour_globals
+Go to \ref GRAS_tut_tour_globals
 */
diff --git a/doc/gtut-tour-5-globals.doc b/doc/gtut-tour-5-globals.doc
index f08d0e0898..b14acd8c5d 100644
--- a/doc/gtut-tour-5-globals.doc
+++ b/doc/gtut-tour-5-globals.doc
@@ -1,6 +1,16 @@
 /**
 @page GRAS_tut_tour_globals Lesson 5: Using globals in processes
 
+\section GRAS_tut_tour_globals_toc Table of Contents
+ - \ref GRAS_tut_tour_globals_intro
+ - \ref GRAS_tut_tour_globals_use
+ - \ref GRAS_tut_tour_callback_pitfall
+ - \ref GRAS_tut_tour_callback_recap
+    
+<hr>
+
+\section GRAS_tut_tour_globals_intro Introduction
+
 Callbacks are great to express your processes as state machines, but they
 pose another problem: callbacks don't have acces to the variable declared
 within the scope of the process' main function (of course). You should
@@ -13,6 +23,8 @@ the several instances of your process, leading to bad problems.
 Instead, you you have to put all globals in a structure, and let GRAS handle
 it with the gras_userdata_* functions (there is only 3 of them ;). 
 
+\section GRAS_tut_tour_globals_use Putting globals into action
+
 We will now modify the example to add a "kill" message, and let the server
 loop on incoming messages until it gets such a message. We only need a
 boolean, so the structure is quite simple: 
@@ -77,6 +89,6 @@ That's it, we're done. We have a server able to handle any number of
 messages, which the client can stop remotely properly. That's already
 something, hu?
 
-\ref GRAS_tut_tour_logs
+Go to \ref GRAS_tut_tour_logs
 
 */
diff --git a/doc/gtut-tour-6-logs.doc b/doc/gtut-tour-6-logs.doc
index 41fb1abdfb..56f9da0949 100644
--- a/doc/gtut-tour-6-logs.doc
+++ b/doc/gtut-tour-6-logs.doc
@@ -1,6 +1,14 @@
 /**
 @page GRAS_tut_tour_logs Lesson 6: Logging informations properly
 
+\section GRAS_tut_tour_logs_toc Table of Contents
+ - \ref GRAS_tut_tour_logs_intro
+ - \ref GRAS_tut_tour_logs_practice
+ - \ref GRAS_tut_tour_logs_recap
+ - \ref GRAS_tut_tour_logs_config
+    
+<hr>
+
 \section GRAS_tut_tour_logs_intro Introduction
 
 Let's have another look at the output of the program we came up with in
@@ -50,7 +58,7 @@ That is all you really need to know about the logs before diving into
 practice. If you want more information on that topic, refer to the \ref
 XBT_log section, which contains much more information than this page.
 
-\section GRAS_tut_tour_logs_practice Putting logs in practice in a program
+\section GRAS_tut_tour_logs_practice Putting logs into action
 
 Enough with theory, let's change our example so that it uses proper
 loggings. The first thing to do is to add a new channel in the existing
@@ -106,5 +114,5 @@ Again, you should refer to the \ref XBT_log section for more information on
 how to configure the logs. Or you can proceed with the next lesson, of
 course.
 
-\ref GRAS_tut_tour_timers
+Go to \ref GRAS_tut_tour_timers
 */
diff --git a/doc/gtut-tour-7-timers.doc b/doc/gtut-tour-7-timers.doc
index 0d568be119..3994597199 100644
--- a/doc/gtut-tour-7-timers.doc
+++ b/doc/gtut-tour-7-timers.doc
@@ -1,6 +1,13 @@
 /**
 @page GRAS_tut_tour_timers Lesson 7: Using internal timers
 
+\section GRAS_tut_tour_timers_toc Table of Contents
+ - \ref GRAS_tut_tour_timers_intro
+ - \ref GRAS_tut_tour_timers_use
+ - \ref GRAS_tut_tour_timers_recap
+   
+<hr>
+
 \section GRAS_tut_tour_timers_intro Introduction
 
 The messaging primitives we saw until now allow the processes to react to
@@ -87,6 +94,6 @@ The program now reads:
 Which produces the expected output:
 \include 7-timers.output
 
-\ref GRAS_tut_tour_exceptions
+Go to \ref GRAS_tut_tour_exceptions
 
 */
diff --git a/doc/gtut-tour-8-exceptions.doc b/doc/gtut-tour-8-exceptions.doc
new file mode 100644
index 0000000000..118ef2616d
--- /dev/null
+++ b/doc/gtut-tour-8-exceptions.doc
@@ -0,0 +1,26 @@
+/**
+@page GRAS_tut_tour_exceptions Lesson 8: Handling errors through exceptions (TODO)
+
+\section GRAS_tut_tour_exceptions_toc Table of Contents
+ - \ref GRAS_tut_tour_exceptions_intro
+ - \ref GRAS_tut_tour_exceptions_use
+ - \ref GRAS_tut_tour_exceptions_recap
+   
+<hr>
+
+\section GRAS_tut_tour_exceptions_intro Introduction
+
+\section GRAS_tut_tour_exceptions_use Putting exceptions into action
+
+
+\section GRAS_tut_tour_exceptions_recap Recapping everything together
+
+The program now reads:
+\include 8-exceptions.c
+
+Which produces the expected output:
+\include 8-exceptions.output
+
+Go to \ref GRAS_tut_tour_rpc
+
+*/
diff --git a/doc/gtut-tour-9-rpc.doc b/doc/gtut-tour-9-rpc.doc
new file mode 100644
index 0000000000..0c6d86e150
--- /dev/null
+++ b/doc/gtut-tour-9-rpc.doc
@@ -0,0 +1,26 @@
+/**
+@page GRAS_tut_tour_rpc Lesson 9: Remote Procedure Calling (RPCing) (TODO)
+
+\section GRAS_tut_tour_rpc_toc Table of Contents
+ - \ref GRAS_tut_tour_rpc_intro
+ - \ref GRAS_tut_tour_rpc_use
+ - \ref GRAS_tut_tour_rpc_recap
+   
+<hr>
+
+\section GRAS_tut_tour_rpc_intro Introduction
+
+
+\section GRAS_tut_tour_rpc_use Putting rpc into action
+
+
+\section GRAS_tut_tour_rpc_recap Recapping everything together
+
+The program now reads:
+\include 9-rpc.c
+
+Which produces the expected output:
+\include 9-rpc.output
+
+
+*/
diff --git a/doc/gtut-tour.doc b/doc/gtut-tour.doc
index e8a159a417..9d6db8f782 100644
--- a/doc/gtut-tour.doc
+++ b/doc/gtut-tour.doc
@@ -15,16 +15,61 @@ all features available in GRAS.
       DOXYGEN_NAVBAR_CHILD "5: Globals"=GRAS_tut_tour_globals.html
       DOXYGEN_NAVBAR_CHILD "6: Logs"=GRAS_tut_tour_logs.html
       DOXYGEN_NAVBAR_CHILD "7: Timers"=GRAS_tut_tour_timers.html
+      DOXYGEN_NAVBAR_CHILD "8: Exceptions"=GRAS_tut_tour_exceptions.html
+      DOXYGEN_NAVBAR_CHILD "9: RPC"=GRAS_tut_tour_rpc.html
     --> \endhtmlonly
 
- - \ref GRAS_tut_tour_install
  - \ref GRAS_tut_tour_setup
+    - \ref GRAS_tut_tour_setup_C
+    - \ref GRAS_tut_tour_setup_plat
+    - \ref GRAS_tut_tour_setup_deploy
+    - \ref GRAS_tut_tour_setup_glue
+    - \ref GRAS_tut_tour_setup_make
+    - \ref GRAS_tut_tour_setup_start
+    
  - \ref GRAS_tut_tour_simpleexchange
+    - \ref GRAS_tut_tour_simpleexchange_msgtype
+    - \ref GRAS_tut_tour_simpleexchange_socks
+    - \ref GRAS_tut_tour_simpleexchange_exchange
+    - \ref GRAS_tut_tour_simpleexchange_recaping
+    
  - \ref GRAS_tut_tour_args
+    - \ref GRAS_tut_tour_args_use
+    - \ref GRAS_tut_tour_args_sg
+    - \ref GRAS_tut_tour_args_recap
+    
  - \ref GRAS_tut_tour_callbacks
+    - \ref GRAS_tut_tour_callbacks_declare
+    - \ref GRAS_tut_tour_callbacks_attach
+    - \ref GRAS_tut_tour_callbacks_handle
+    - \ref GRAS_tut_tour_callback_recap
+    
  - \ref GRAS_tut_tour_globals
+    - \ref GRAS_tut_tour_globals_intro
+    - \ref GRAS_tut_tour_globals_use
+    - \ref GRAS_tut_tour_callback_pitfall
+    - \ref GRAS_tut_tour_callback_recap
+    
  - \ref GRAS_tut_tour_logs
+    - \ref GRAS_tut_tour_logs_intro
+    - \ref GRAS_tut_tour_logs_practice
+    - \ref GRAS_tut_tour_logs_recap
+    - \ref GRAS_tut_tour_logs_config
+    
  - \ref GRAS_tut_tour_timers
+    - \ref GRAS_tut_tour_timers_intro
+    - \ref GRAS_tut_tour_timers_use
+    - \ref GRAS_tut_tour_timers_recap
+    
+ - \ref GRAS_tut_tour_exceptions
+    - \ref GRAS_tut_tour_exceptions_intro
+    - \ref GRAS_tut_tour_exceptions_use
+    - \ref GRAS_tut_tour_exceptions_recap
+    
+ - \ref GRAS_tut_tour_rpc
+    - \ref GRAS_tut_tour_rpc_intro
+    - \ref GRAS_tut_tour_rpc_use
+    - \ref GRAS_tut_tour_rpc_recap
  
 <hr>
 
@@ -34,19 +79,15 @@ all features available in GRAS.
 Unfortunately, the tour is not terminated yet, and here are some ideas of
 missing missi^W lessons:
 
-- Lesson 8: Timers
-- Lesson 7: Exceptions
+- Lesson 10: Exchanging simple data through ping-pong
+- Lesson 11: More complex data description (automatic parsing, manual
+   description) and example. May need more than one lesson.
 
-- Lesson 8: Exchanging simple data through ping-pong
-- Lesson 9: More complex data description (automatic parsing, manual description) and example
+- Lesson 12: Splitting in several files
 
-- Lesson 10: Splitting in several files
+- Lesson 13: Debuging GRAS programs
 
-- Lesson 11: RPC mecanism and dealing with exceptions
-
-- Lesson 12: Debuging GRAS programs
-
-- Lesson   : Doing proper modules
+- Lesson 14: Doing proper modules
 
 */
 
-- 
2.20.1