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
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
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
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
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() >>