chiark / gitweb /
Docs: Various fixes and minor clarifications
authorIan Jackson <ian.jackson@eu.citrix.com>
Wed, 28 Oct 2015 16:19:28 +0000 (16:19 +0000)
committerIan Jackson <Ian.Jackson@eu.citrix.com>
Wed, 28 Oct 2015 16:19:28 +0000 (16:19 +0000)
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
caf.pod

diff --git a/caf.pod b/caf.pod
index fcb0615..ab45ac0 100644 (file)
--- a/caf.pod
+++ b/caf.pod
@@ -133,10 +133,10 @@ interfaces for this:
 
 =head3 Simple applications
 
-The simplist usage is to call C<< $request->check_ok() >> which will
+The simplest usage is to call C<< $request->check_ok() >> which will
 check the user's authentication.  If the user is not logged in it will
 generate a login form (or redirection or other appropriate page) and
-return false; your application should not then processing that request
+return false; your application should not then process that request
 any further.  If the user is logged in it will return true.
 
 Various hooks are provided to customise the responses generated by
@@ -145,13 +145,15 @@ C<check_ok>.
 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.
+You may also need to call C<check_mutate> and/or C<check_nonpage>
+- see below.
 
-=head2 Sophisticated applications
+=head3 Sophisticated applications
 
 If you want to handle the control flow and to generate login forms,
 redirections, etc., yourself, you can say
 C<< $divert = $request->check_divert >>.  This returns undef if
-the user is logged in, or I<divert spec> if some kind of login
+the user is logged in, or I<divert spec> if some kind of login
 page or diversion should be generated.  See L</DIVERT SPEC> below for
 details of how to deal with the return value.
 
@@ -159,16 +161,19 @@ details of how to deal with the return value.
 
 =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
+By default CGI::Auth::Flexible does not permit external deep links
+into your site.
+All GET requests give a "click to continue" page which
 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.
+use C<POST>.
 
 Such applications are also not able to provide user-specific CSS
 stylesheets, javascript, favicons, etc.
 
+This restriction arises from complicated deficiencies
+in the web's security architecture.
+
 =head3 Mutation-aware applications
 
 The alternative is for your application to always make a special check
@@ -198,7 +203,7 @@ include a 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 the hidden parameter is called C<caf_assochash>.
+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>
@@ -373,6 +378,8 @@ All of these are only valid after C<check_divert> or C<check_ok> has
 been called.  (In the case of C<check_ok> it won't normally be sensible
 to call these functions unless C<check_ok> returned true.)
 
+=over
+
 =item C<< $authreq->get_divert() >>
 
 Returns the value previously returned by C<check_divert>.
@@ -413,8 +420,12 @@ C<check_nonpage> will either return successfully, indicating that all
 is well and the request should proceed, or it will die, like
 C<check_mutate>.
 
+=back
+
 =head1 RESPONSE-RELATED FUNCTIONS AND METHODS
 
+=over
+
 =item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
 
 Convenience function which returns a url for a GET request to this
@@ -462,7 +473,7 @@ Returns the value of the secret cookie.  CGI::Auth::Flexible sets this
 cookie in the forms generated by C<check_ok>.  You may also set it
 yourself (and indeed you must do so if you use C<check_divert>).
 
-item C<< $authreq->_chain_params() >>
+=item C<< $authreq->_chain_params() >>
 
 Returns a hash of the "relevant" parameters to this request, in a form
 suitable for C<url_with_query_params>.  This is all of the query
@@ -490,7 +501,7 @@ parameter.
 
 I<$reqtype> is the request type (the value which will be passed to
 C<check_nonpage> and C<need_add_hidden>.  If you are supporting a new
-I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstrea,
+I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstream,
 or other users, to assign a unique request type name.
 
 This method may be called on an authreq or a verifier, in which case
@@ -603,7 +614,7 @@ confidential for the user.)
 C<< XMLHttpRequest >> returning data of some other kind.  (Possibly
 confidential for the user.)
 
-=back.
+=back
 
 =head1 DIVERT SPEC
 
@@ -633,6 +644,10 @@ should be sent; C<''> means the cookie should be cleared.
 
 =item C<Params>
 
+Provided with diversion kinds which involve
+generating a redirection or indirection,
+perhaps via a login form.
+
 The extra hidden form parameters (and the C<PATH_INFO>) which should
 be set when the subsequent request bounces back from the client, in
 the form used by C<url_with_query_params>.
@@ -722,6 +737,8 @@ submits our own main page without any parameters.
 (Applications which set C<promise_check_mutate> do not see this divert
 kind.)
 
+=back
+
 =head1 SETTINGS
 
 C<new_verifier> and C<new_request> each take a list of settings, as
@@ -748,10 +765,10 @@ When a hook's default implementation is mentioned and named, that
 function won't also be described in the section on the module's
 functions.
 
-=over
-
 =head2 GENERAL SETTINGS
 
+=over
+
 =item C<dir>
 
 The directory CGI::Auth::Generic should use for its data storage.
@@ -881,7 +898,7 @@ Used by the default C<is_logout> hook.
 
 If you want users to be able to explicitly log out, you need to
 provide a logout button, something like
-C<< <input type="submit" name="caf_logout" ...>>
+C<< <input type="submit" name="caf_logout" ... >>
 
 The default is C<['caf_logout']>
 
@@ -914,8 +931,6 @@ only flag on its cookie.
 
 The default is 1.
 
-=back
-
 =item C<< get_url($cgi,$authreq) >>
 
 Hook which returns the URL of this web application.  By default, we
@@ -974,8 +989,6 @@ value of the cookie.
 Returns the HTTP method as a string.  The default is to call
 C<< $cgi->request_method() >>.
 
-=back
-
 =item C<< is_https($cgi,$authreq) >>
 
 Returns a boolean indicating whether the request was over an encrypted
@@ -1087,6 +1100,8 @@ Size of generated text entry fields.  Default is 60.
 Some of CAF's HTML-generating functions need to invent form parameter
 names.  They will all start with this string.  Default: C<caf__>.
 
+=back
+
 =head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY
 
 =over
@@ -1353,7 +1368,11 @@ xxx document construct_cookie fn
 xxx document @default_db_setup_statements
 
 xxx bugs wrong default random on Linux
+
 xxx bugs wrong default random on *BSD
+
 xxx bugs keys not shared should be in db
+
 xxx rename caf_assocsecret default cookie name
+
 xxx mention relationship between login_timeout and cookies