docs: more work

diff --git a/caf.pod b/caf.pod
index 5dd2f07fb56ebe9ddecf6dc4955489022f74190e..922f7f8c0eb79fefeb56393e0525ffb95cda3ee4 100644 (file)
--- a/caf.pod
+++ b/caf.pod
@@ -111,7 +111,14 @@ The resulting verifier object can be used to process individual
 requests, in each case with
 C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>.
 
-=head2 RESPONSES - SIMPLE APPLICATIONS
+=head2 CHECKING AND RESPONSE GENERATION
+
+If the user is logged in, your application is to handle the request.
+Otherwise, the user needs to be presented with a login form or error
+message, as appropriate.  CGI::Auth::Flexible provides two alternative
+interfaces for this:
+
+=head3 Simple applications
 
 The simplist usage is to call C<< $request->check_ok() >> which will
 check the user's authentication.  If the user is not logged in it will
@@ -126,7 +133,7 @@ After C<check_ok> returns true you should go ahead and process the
 request; you can use C<< $request->get_username >> to find out which
 user the request came from.
 
-=head2 RESPONSES - SOPHISTICATED APPLICATIONS
+=head2 Sophisticated applications
 
 If you want to handle the control flow and to generate login forms,
 redirections, etc., yourself, you can say
@@ -134,7 +141,11 @@ C<< $divert = $request->check_divert >>.  This returns undef if
 the user is logged in, or I<divert spec> if some kind of login
 page or diversion should be generated.
 
-=head2 MUTATING OPERATIONS AND EXTERNAL LINKS - MUTATION-IGNORANT APPLICATIONS
+xxx see below
+
+=head2 MUTATING OPERATIONS AND EXTERNAL LINKS
+
+=head3 Mutation-ignorant applications
 
 By default CGI::Auth::Flexible does not permit external links into
 your site.  All GET requests give a "click to continue" page which
@@ -146,7 +157,7 @@ in the web's security architecture.
 Such applications are also not able to provide user-specific CSS
 stylesheets, javascript, favicons, etc.
 
-=head2 MUTATING OPERATIONS AND EXTERNAL LINKS - MUTATION-AWARE APPLICATIONS
+=head3 Mutation-aware applications
 
 The alternative is for your application to always make a special check
 when the incoming request is going to do some kind of action (such as
@@ -368,10 +379,9 @@ parameter in a single request; normally each arrayref would be a
 singleton.)
 
 The request path will be the path to the application.  If a parameter
-with name C<< '' >> is supplied, it is taken as the PATH_INFO to
-supply - its value will be appended to the application path.  (It
-should normally start with C<< / >>, and only one value should be
-supplied.)
+with name C<< '' >> is supplied, it is taken as the PATH_INFO - its
+value will be appended to the application path.  (It should normally
+start with C<< / >>, and only one value should be supplied.)
 
 =item C<< $authreq->chain_params() >>