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.
 
-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.
 
@@ -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
-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() >>
-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.
 
-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
@@ -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.
 
-=item C<< $authreq->disconnect() >>
+=item C<< $verifier->disconnect() >>
 
-Disconnects from the 
+Discards the resources (open files, etc.) in the verifier object.
 
 =back