[Commit] nickle/doc/tutorial/advanced concurrency.sgml,1.1,1.2 continuations.sgml,1.1,1.2 exceptions.sgml,1.1,1.2 namespaces.sgml,1.1,1.2

[commit at keithp.com]

Committed by: p186

Update of /local/src/CVS/nickle/doc/tutorial/advanced
In directory home.keithp.com:/tmp/cvs-serv11636/doc/tutorial/advanced

Modified Files:
	concurrency.sgml continuations.sgml exceptions.sgml 
	namespaces.sgml 
Log Message:
Changed lists to synopses.  Tour subsection removed.  Got repository up-to-date.



Index: concurrency.sgml
===================================================================
RCS file: /local/src/CVS/nickle/doc/tutorial/advanced/concurrency.sgml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- concurrency.sgml	23 May 2003 23:48:59 -0000	1.1
+++ concurrency.sgml	6 Jun 2003 22:26:23 -0000	1.2
@@ -5,9 +5,9 @@
 Threads provide concurrent processing of calculations.
 They are created with the <literal>fork</literal> operator, which spawns a child thread to evaluate its argument and returns it as a variable of the first-class type <literal>thread</literal>:
 </para>
-<itemizedlist>
-<listitem><para>fork <literal>expr</literal></para></listitem>
-</itemizedlist>
+<synopsis>
+fork <literal>expr</literal>
+</synopsis>
 <para>
 The thread it returns is typically stored like this:
 <informalexample><screen>
@@ -30,18 +30,18 @@
 </para>
 
 <sect3><title>Kill</title>
-<itemizedlist>
-<listitem><para>int kill ( thread t, ... )</para></listitem>
-</itemizedlist>
+<synopsis>
+int kill ( thread t, ... )
+</synopsis>
 <para>
 Kills the threads it takes as arguments, regardless of whether or not they are finished, and returns the number of threads successfully killed. 
 </para>
 </sect3>
 
 <sect3><title>Join</title>
-<itemizedlist>
-<listitem><para>poly join ( thread t )</para></listitem>
-</itemizedlist>
+<synopsis>
+poly join ( thread t )
+</synopsis>
 <para>
 Waits for thread <literal>t</literal> to finish and returns the value of its expression.
 This is how to get the value back out of a thread.
@@ -59,19 +59,21 @@
 </sect3>
 
 <sect3><title>Current</title>
-<itemizedlist>
-<listitem><para>thread current ( )</para></listitem>
-</itemizedlist>
+<synopsis>
+thread current ( )
+</synopsis>
 <para>
 Returns the currently running thread. Note that things such as <literal>kill(current())</literal> and <literal>join(current())</literal> are allowed, although the former merely exits and the latter hangs forever; watch out for these errors.
 </para>
 </sect3>
 
 <sect3><title>Priorities</title>
-<itemizedlist>
-<listitem><para>int set_priority ( thread t, int i )</para></listitem>
-<listitem><para>int get_priority ( thread t )</para></listitem>
-</itemizedlist>
+<synopsis>
+int set_priority ( thread t, int i )
+</synopsis>
+<synopsis>
+int get_priority ( thread t )
+</synopsis>
 <para>
 Priorities determine how runtime is divided among threads; a thread with higher priority will always run before one with a lower priority.
 <literal>set_priority</literal> sets the priority of <literal>t</literal> to <literal>i</literal> and returns the new priority.
@@ -115,18 +117,18 @@
 </para>
 
 <sect3><title>New</title>
-<itemizedlist>
-<listitem><para>mutex new ( )</para></listitem>
-</itemizedlist>
+<synopsis>
+mutex new ( )
+</synopsis>
 <para>
 Creates a new mutex and returns it.
 </para>
 </sect3>
 
 <sect3><title>Acquire</title>
-<itemizedlist>
-<listitem><para>bool acquire ( mutex m )</para></listitem>
-</itemizedlist>
+<synopsis>
+bool acquire ( mutex m )
+</synopsis>
 <para>
 <literal>acquire</literal> blocks until <literal>m</literal> is free, then locks it and returns true.
 At the top of the conflicting code, each thread should acquire the mutex; since only one at a time can have it, they will take turns executing.
@@ -135,18 +137,18 @@
 </sect3>
 
 <sect3><title>Release</title>
-<itemizedlist>
-<listitem><para>void release ( mutex m )</para></listitem>
-</itemizedlist>
+<synopsis>
+void release ( mutex m )
+</synopsis>
 <para>
 When the thread which owns a mutex leaves the conflicting section of code, it should call release to free it for the next thread to acquire it.
 </para>
 </sect3>
 
 <sect3><title>Owner</title>
-<itemizedlist>
-<listitem><para>mutex_owner owner ( mutex m )</para></listitem>
-</itemizedlist>
+<synopsis>
+mutex_owner owner ( mutex m )
+</synopsis>
 <para>
 Returns the owner of <literal>m</literal>: either the thread which currently owns it or null if it is free.
 </para>
@@ -201,19 +203,21 @@
 <para>
 Semaphores are created with <literal>new</literal>, which is unlike <literal>Mutex::new</literal> in that it takes an argument: the number of threads it will run simultaneously.
 </para>
-<itemizedlist>
-<listitem><para>semaphore new ( int c )</para></listitem>
-</itemizedlist>
+<synopsis>
+semaphore new ( int c )
+</synopsis>
 </sect3>
 
 <sect3><title>Wait and Signal</title>
 <para>
 Just as Mutexes are <literal>acquire</literal>d and <literal>release</literal>d, threads <literal>wait</literal> on semaphores and <literal>signal</literal> them when finished.
 </para>
-<itemizedlist>
-<listitem><para>void wait ( semaphore s )</para></listitem>
-<listitem><para>void signal ( semaphore s )</para></listitem>
-</itemizedlist>
+<synopsis>
+void wait ( semaphore s )
+</synopsis>
+<synopsis>
+void signal ( semaphore s )
+</synopsis>
 <para>
 <literal>wait</literal> merely decrements the count of <literal>s</literal>, which starts with the initial value specified by <literal>new</literal>.
 If the count, after the decrement, is positive, the thread continues to run; if it is negative, it blocks until the count becomes positive again.

Index: continuations.sgml
===================================================================
RCS file: /local/src/CVS/nickle/doc/tutorial/advanced/continuations.sgml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- continuations.sgml	23 May 2003 23:48:59 -0000	1.1
+++ continuations.sgml	6 Jun 2003 22:26:23 -0000	1.2
@@ -3,10 +3,12 @@
 Arbitrary flow control is accomplished in Nickle with first-class continuations and the functions <literal>setjmp</literal> and <literal>longjmp</literal>.
 These are similar to those in C, but without restrictions on the target.
 </para>
-<itemizedlist>
-<listitem><para>poly setjmp ( continuation *c, poly retval )</para></listitem>
-<listitem><para>void lomgjmp ( continuation c, poly retval )</para></listitem>
-</itemizedlist>
+<synopsis>
+poly setjmp ( continuation *c, poly retval )
+</synopsis>
+<synopsis>
+void lomgjmp ( continuation c, poly retval )
+</synopsis>
 <para>
 Setjmp saves the state of the program, including program counter and names in scope, in <literal>c</literal> and returns <literal>retval</literal>.
 </para>
@@ -48,7 +50,7 @@
 		search ( t, 2, &c );
 	else
 		printf ( "value = %g\n", p );
-	}
+}
 ]]></screen></informalexample>
 </para>
 <para>

Index: exceptions.sgml
===================================================================
RCS file: /local/src/CVS/nickle/doc/tutorial/advanced/exceptions.sgml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- exceptions.sgml	23 May 2003 23:48:59 -0000	1.1
+++ exceptions.sgml	6 Jun 2003 22:26:23 -0000	1.2
@@ -16,9 +16,9 @@
 <para>
 The following syntax may be used to declare a new exception:
 </para>
-<itemizedlist>
-<listitem><para>exception <replaceable>name</replaceable> ( <replaceable>type</replaceable> <replaceable>name</replaceable>, ... )</para></listitem>
-</itemizedlist>
+<synopsis>
+exception <replaceable>name</replaceable> ( <replaceable>type</replaceable> <replaceable>name</replaceable>, ... )
+</synopsis>
 <para>
 For example,
 <informalexample><screen>
@@ -27,9 +27,9 @@
 </para>
 
 <sect2><title>Raise</title>
-<itemizedlist>
-<listitem><para>raise <replaceable>name</replaceable> ( <replaceable>value</replaceable>, ... )</para></listitem>
-</itemizedlist>
+<synopsis>
+raise <replaceable>name</replaceable> ( <replaceable>value</replaceable>, ... )
+</synopsis>
 <para>
 Raises the named exception with the given arguments, e.g.
 <informalexample><screen>
@@ -49,10 +49,12 @@
 </sect2>
 
 <sect2><title>Try - catch</title>
-<itemizedlist>
-<listitem><para>try <replaceable>statement</replaceable></para></listitem>
-<listitem><para>catch <replaceable>name</replaceable> ( <replaceable>type</replaceable> <replaceable>name</replaceable>, ... ) { <replaceable>statement-list</replaceable> }</para></listitem>
-</itemizedlist>
+<synopsis>
+try <replaceable>statement</replaceable>
+</synopsis>
+<synopsis>
+catch <replaceable>name</replaceable> ( <replaceable>type</replaceable> <replaceable>name</replaceable>, ... ) { <replaceable>statement-list</replaceable> }
+</synopsis>
 <para>
 <literal>try</literal> executes <replaceable>statement</replaceable>; if it raises an exception whose name matches that of a succeeding <literal>catch</literal> block, the arguments are placed in the names specified and the associated <replaceable>statement-list</replaceable> is executed.
 Control continues after the catch without continuing up the stack; if further propagation is desired, <replaceable>statement-list</replaceable> should re-raise the exception.

Index: namespaces.sgml
===================================================================
RCS file: /local/src/CVS/nickle/doc/tutorial/advanced/namespaces.sgml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- namespaces.sgml	23 May 2003 23:48:59 -0000	1.1
+++ namespaces.sgml	6 Jun 2003 22:26:23 -0000	1.2
@@ -45,10 +45,9 @@
 </para>
 
 <sect2><title>Extend</title>
-<itemizedlist>
-<listitem><para>extend namespace <replaceable>name</replaceable> {
-<replaceable>statement-list</replaceable> }</para></listitem>
-</itemizedlist>
+<synopsis>
+extend namespace <replaceable>name</replaceable> { <replaceable>statement-list</replaceable> }
+</synopsis>
 <para>
 Names may be added to a namespace after it is initially defined with the <literal>extend</literal> command.
 The namespace <literal>name</literal> is reopened and the new <literal>statement-list</literal> is added to the previous ones.
@@ -65,10 +64,12 @@
 </sect2>
 
 <sect2><title>Peering inside</title>
-<itemizedlist>
-<listitem><para><replaceable>namespace</replaceable>::<replaceable>name</replaceable></para></listitem>
-<listitem><para>import <replaceable>namespace</replaceable></para></listitem>
-</itemizedlist>
+<synopsis>
+<replaceable>namespace</replaceable>::<replaceable>name</replaceable>
+</synopsis>
+<synopsis>
+import <replaceable>namespace</replaceable>
+</synopsis>
 <para>
 The <literal>::</literal> operator refers to a <replaceable>name</replaceable>, which is in <replaceable>namespace</replaceable>, analogously to a structure dereference.
 If <replaceable>name</replaceable> also refers to a namespace, its names too are visible this way.