Index: ossp-pkg/ex/ex.pod
RCS File: /v/ossp/cvs/ossp-pkg/ex/ex.pod,v
rcsdiff -q -kk '-r1.10' '-r1.11' -u '/v/ossp/cvs/ossp-pkg/ex/ex.pod,v' 2>/dev/null
--- ex.pod	2002/01/30 10:33:36	1.10
+++ ex.pod	2002/01/30 11:11:09	1.11
@@ -36,13 +36,13 @@
 
 B<ex_t> I<variable>;
 
-B<ex_try> {...} [B<ex_cleanup> {...}] B<ex_catch> (I<variable>) {...}
+B<ex_try> I<BLOCK1> [B<ex_cleanup> I<BLOCK2>] B<ex_catch> (I<variable>) I<BLOCK3>
 
 B<ex_throw>(I<class>, I<object>, I<value>);
 
 B<ex_rethrow>;
 
-B<ex_shield> {...};
+B<ex_shield> I<BLOCK>
 
 if (B<ex_catching>) ...
 
@@ -50,30 +50,31 @@
 
 =head1 DESCRIPTION
 
-B<OSSP ex> is a small ISO-C++ style exception handling library for use
-in the ISO-C language. It allows you to use the paradigm of throwing
-and catching exceptions in order to reduce the amount of error handling
-code without making your program less robust. This is achieved
+B<OSSP ex> is a small B<ISO-C++> style exception handling library for
+use in the B<ISO-C> language. It allows you to use the paradigm of
+throwing and catching exceptions in order to reduce the amount of error
+handling code without making your program less robust. This is achieved
 by directly transferring exceptional return codes (and the program
-control flow) from the location where it was raised (throw point) to
-the location where it is handled (catch point) - usually from a deeply
-nested sub-routine to a parent routine. All intermediate routines
-no longer have to make sure that the exceptional return codes from
-sub-routines are correctly passed back to the parent.
+control flow) from the location where the exception is raised (throw
+point) to the location where it is handled (catch point) -- usually
+from a deeply nested sub-routine to a parent routine. All intermediate
+routines no longer have to make sure that the exceptional return codes
+from sub-routines are correctly passed back to the parent.
 
 =head2 EXCEPTIONS
 
 An exception is a triple E<lt>I<class>,I<object>,I<value>E<gt> where
 I<class> identifies the class of the exception thrower, I<object>
 identifies the particular class instance of the exception thrower, and
-I<value> is the exceptional return code the thrower wants to send to the
-catcher. All three parts are of type C<void *> internally, but every
-value can be used which can be (automatically) casted to a C<void *>.
-Exceptions are created on-the-fly by the B<ex_throw> command.
+I<value> is the exceptional return code value the thrower wants to send
+to the catcher. All three parts are of type "C<void *>" internally,
+but every value can be used which can be (automatically) casted to the
+B<ISO-C> type "C<void *>". Exceptions are created on-the-fly by the
+B<ex_throw> command.
 
 =head2 APPLICATION PROGRAMMER INTERFACE (API)
 
-The B<OSSP ex> API consists of four different elements:
+The B<OSSP ex> API consists of the following elements:
 
 =over 4
 
@@ -133,38 +134,45 @@
 
 =back
 
-=item B<ex_try> {...} [B<ex_cleanup> {...}] B<ex_catch> (I<variable>) {...}
+=item B<ex_try> I<BLOCK1> [B<ex_cleanup> I<BLOCK2>] B<ex_catch> (I<variable>) I<BLOCK3>
 
 This is the main construct provided by B<OSSP ex>. It is modeled after
-the ISO-C++ C<try>-C<catch> construct which in turn is very similar to
-an ISO-C C<if>-C<else> construct. It consists of an B<ex_try> block
-which forms the dynamic scope of the exception handling (i.e. exceptions
-directly thrown there or thrown from subroutines are catched), an
-optional B<ex_cleanup> block for performing cleanup sequences and a
-B<ex_catch> block where the caught exceptions are handled.
-
-# CONTROL FLOW FIXME!
-
+the B<ISO-C++> C<try>-C<catch> clause which in turn is very similar to
+an B<ISO-C> C<if>-C<else> clause. It consists of an B<ex_try> block
+I<BLOCK1> which forms the dynamic scope of the exception handling (i.e.
+exceptions directly thrown there or thrown from its sub-routines are
+catched), an optional B<ex_cleanup> block I<BLOCK2> for performing
+cleanup operations and an B<ex_catch> block I<BLOCK3> where the caught
+exceptions are handled.
+
+The control flow in case no exception is thrown is simply I<BLOCK1>,
+optionally followed by I<BLOCK2>. I<BLOCK3> is skipped. The control flow
+in case an exception is thrown is: I<BLOCK1> (up to the statement where
+the exception is thrown), optionally followed by I<BLOCK2>, followed by
+I<BLOCK3>.
+    
 The B<ex_try>, B<ex_cleanup> and B<ex_catch> cannot be used seperately,
-they work only in combination. In contrast to ISO-C++ there is only
-one B<ex_catch> block and not multiple ones (all B<OSSP ex> exceptions
-are of the same ISO-C type B<ex_t>). If an exception is caught, it
-is stored in I<variable> for inspection (or re-throwing) inside the
-B<ex_catch> block. Although declared outside, the I<variable> is only
-valid within the B<ex_catch> block. But it can be re-used in following
-B<ex_try>/B<ex_catch> constructs, of course.
-
-The B<ex_try> block is a regular ISO-C language block, but it is not
-allowed to jump into it via C<goto> or C<longjmp>(3) or out of it via
-C<return>, C<goto> or C<longjmp>(3) because there is some hidden setup
-and cleanup that needs to be done by B<OSSP ex> regardless of whether an
-exception is caught. Jumping into an B<ex_try> clause would avoid doing
-the setup, and jumping out of it would avoid doing the cleanup. In both
-cases the result is a broken exception facility. Nevertheless you are
-allowed to nest B<ex_try> clauses.
-
-The B<ex_catch> block is a regular ISO-C language block without any
-restrictions.
+they work only in combination. And in contrast to B<ISO-C++> there
+is only one B<ex_catch> block and not multiple ones (all B<OSSP ex>
+exceptions are of the same B<ISO-C> type B<ex_t>). If an exception is
+caught, it is stored in I<variable> for inspection (or re-throwing)
+inside the B<ex_catch> block. Although declared outside, the I<variable>
+is only valid within the B<ex_catch> block. But it can be re-used in
+following B<ex_try>/B<ex_catch> constructs, of course.
+
+The B<ex_try> block is a regular B<ISO-C> language block of
+statement(s), but it is not allowed to jump into it via C<goto> or
+C<longjmp>(3) or out of it via C<return>, C<goto> or C<longjmp>(3)
+because there is some hidden setup and cleanup that needs to be done by
+B<OSSP ex> regardless of whether an exception is caught. Jumping into
+an B<ex_try> clause would avoid doing the setup, and jumping out of it
+would avoid doing the cleanup. In both cases the result is a broken
+exception facility. Nevertheless you are allowed to nest B<ex_try>
+clauses.
+
+The B<ex_cleanup> and B<ex_catch> blocks are regular B<ISO-C> language
+block of statement(s) without any restrictions. You are even allowed to
+throw (and in the B<ex_catch> block to re-throw) an exception.
 
 =item B<ex_throw>(I<class>, I<object>, I<value>);
 
@@ -185,11 +193,11 @@
 I<variable>.ex_value) but with the difference that the C<ex_file>,
 C<ex_line> and C<ex_func> elements of the thrown exception are kept.
 
-=item B<ex_shield> {...}
+=item B<ex_shield> I<BLOCK>
 
-This directive executes its block while shielding against the throwing
-of exceptions, i.e., in the dynamic scope of B<ex_shield> any
-B<ex_throw> operation is ignored. 
+This directive executes I<BLOCK> while shielding it against the throwing
+of exceptions, i.e., inside the dynamic scope of B<ex_shield> all
+B<ex_throw> operations are ignored.
 
 =item B<ex_catching>
 
@@ -246,7 +254,7 @@
 =back
 
 The default implementation (define C<__EX_MCTX_USE_SJLJ__> or as long
-C<__EX_MCTX_USE_CUSTOM__> is not defined) uses B<ISO C> jmp_buf(3):
+C<__EX_MCTX_USE_CUSTOM__> is not defined) uses B<ISO-C> jmp_buf(3):
 
  #define __ex_mctx_struct         jmp_buf jb;
  #define __ex_mctx_save(mctx)     (setjmp((mctx)->jb) == 0)
@@ -295,7 +303,7 @@
 B<ex_> prefix for the API macros B<ex_try>, B<ex_catch>, B<ex_throw>,
 B<ex_rethrow> and B<ex_shield> sometimes have a unpleasant optical
 appearance. Especially because B<OSSP rc> is modeled after the exception
-facility in ISO C++ where there is no such prefix on the directives.
+facility in B<ISO-C++> where there is no such prefix on the directives.
 
 For this B<OSSP ex> optionally provides the ability to provide
 additional namespace mappings for those API macros. By default (define