docs: wip

diff --git a/cgi-auth-flexible.pm b/cgi-auth-flexible.pm
index a4b8f561c5adf35231217289f1c7e289a31f3868..500c9e498e63995bac51867ddca34dba2e9e63be 100644 (file)
--- a/cgi-auth-flexible.pm
+++ b/cgi-auth-flexible.pm
@@ -1398,10 +1398,10 @@ special secret hidden form parameter for the benefit of
 CGI::Auth::Generic.  This form parameter will be checked by
 C<check_ok>/C<check_divert> and should be ignored by your application.
 
 CGI::Auth::Generic.  This form parameter will be checked by
 C<check_ok>/C<check_divert> and should be ignored by your application.
 

-By default its name is C<caf_assochash>.  After calling C<check_ok> or
-C<check_divert> the value to put in your form can be obtained from
-C<secret_hidden_val>; C<secret_hidden_html> will generate the whole
-HTML C<< <input...> >> element.
+By default the hidden parameter is called C<caf_assochash>.  After
+calling C<check_ok> or C<check_divert> the value to put in your form
+can be obtained from C<secret_hidden_val>; C<secret_hidden_html> will
+generate the whole HTML C<< <input...> >> element.

 
 Do not put the secret value in URLs for C<GET> requests.
 
 
 Do not put the secret value in URLs for C<GET> requests.
 


@@ -1409,31 +1409,31 @@ Do not put the secret value in URLs for C<GET> requests.
 
 By default CGI::Auth::Flexible does not permit external links into
 your site.  All GET requests give a "click to continue" page which
 
 By default CGI::Auth::Flexible does not permit external links into
 your site.  All GET requests give a "click to continue" page which

-submits a form.  In this configuration all your application's forms
-and AJAX requests should use C<POST>.
-
-This is because the alternative (for complicated reasons relating to
-the web security architecture) is to require your application to make
-a special and different check when the incoming request is going to do
-some kind of action (such as modifying the user's setup, purchasing
-goods, or whatever) rather than just display HTML pages.
-
-To support external links, and C<GET> requests, pass C<<
-promise_check_mutate => 1 >> in I<settings>, and then call C<<
-$authreq->check_mutate() >> before taking any actions.  If the
+submits a form which loads your app's main page.  In this
+configuration all your application's forms and AJAX requests should
+use C<POST>.  This restriction arises from complicated deficiencies
+in the web's security architecture.  
+
+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
+modifying the user's setup, purchasing goods, or whatever) rather than
+just display HTML pages.  Then non-mutating pages can be linked to
+from other, untrustworthy, websites.
+
+To support external links, and C<GET> requests, pass
+C<< promise_check_mutate => 1 >> in I<settings>, and then call
+C<< $authreq->check_mutate() >> before taking any actions.  If the

 incoming request is not suitable then C<< $authreq->check_mutate() >>
 incoming request is not suitable then C<< $authreq->check_mutate() >>

-will call C<die>.  If you do this you must make sure that you have no
-mutating C<GET> requests in your application - but you shouldn't have
-any of those anyway.
+will call C<die>.
+
+You must make sure that you have no mutating C<GET> requests in your
+application - but you shouldn't have any of those anyway.

 
 =head2 DATA STORAGE
 
 CGI::Auth::Flexible needs to store various information in plain files;
 it does this in the directory specified by the C<dir> parameter.
 
 
 =head2 DATA STORAGE
 
 CGI::Auth::Flexible needs to store various information in plain files;
 it does this in the directory specified by the C<dir> parameter.
 

-It also needs to record state relating to user sessions in a database.
-There is no particular reason for this 
-

 =head1 SOURCE CODE DOWNLOAD
 
 By default, CGI::Auth::Flexible provides a facility for users to
 =head1 SOURCE CODE DOWNLOAD
 
 By default, CGI::Auth::Flexible provides a facility for users to


@@ -1539,8 +1539,8 @@ Otherwise it handles the request itself, generating any appropriate
 redirect, login form, or continuation page.  It then returns false and
 the application should not process the request further.
 
 redirect, login form, or continuation page.  It then returns false and
 the application should not process the request further.
 

-=item C<< $authreq->disconnect() >>
+=item C<< $verifier->disconnect() >>

 
 

-Disconnects from the 
+Discards the resources (open files, etc.) in the verifier object.

 
 =back
 
 =back