X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=cgi-auth-flexible.git;a=blobdiff_plain;f=caf.pod;h=4277923aa9603f782c7a643aaa358d3d9cccdbe6;hp=40ee9cd6fc2c283ac542c3152e9a31245f8d24b9;hb=52e25ce84bfd2d237e5a51dd4637da51104fa26c;hpb=6e2f63056e51f6e0e788d25f338834bfb0497af1

diff --git a/caf.pod b/caf.pod
index 40ee9cd..4277923 100644
--- a/caf.pod
+++ b/caf.pod
@@ -618,8 +618,8 @@ any tags.
 
 =item C<CookieSecret>
 
-The secret cookie which should be set along with whatever response is
-sent to the client.  The value in the hash is the actual secret value
+The login cookie which should be set along with whatever response is
+sent to the client.  The value in the hash is the actual value
 of the cookie as a string.  C<undef> means no cookie setting header
 should be sent; C<''> means the cookie should be cleared.
 
@@ -752,7 +752,7 @@ path settings are relative values.
 
 Must be an absolute filename.
 
-=item C<assocdb_dbh>
+=item C<db_dbh>
 
 CGI::Auth::Flexible needs a database for recording users' login
 session.  This database needs to be shared across all instances of the
@@ -766,26 +766,26 @@ particular, there is no need for transactional integrity across
 changes made by CAF and your own application.)
 
 By default, CAF uses a sqlite3 database stored on local disk in the
-file named by C<assocdb_path>.  This will be suitable for all
+file named by C<db_path>.  This will be suitable for all
 applications which run on a single host.
 
 This value, if supplied, should be a DBI handle for the database.
 
-=item C<assocdb_dsn>
+=item C<db_dsn>
 
 This is the DSN to pass to C<< DBI->connect >>.  Used only if
-C<assocdb_dbh> is not supplied.
+C<db_dbh> is not supplied.
 
-=item C<assocdb_path>
+=item C<db_path>
 
 Path to the sqlite3 database used for CAF's session storage.  The
-default is currently C<caf-assocs.db> but will change in the future.
+default is C<caf.db>.
 
-Used only if neither C<assocdb_dbh> or C<assocdb_dsn> are supplied.
+Used only if neither C<db_dbh> or C<db_dsn> are supplied.
 
 If this is a relative path, it is in C<dir>.
 
-=item C<assocdb_table>
+=item C<db_prefix>
 
 Prefix for the SQL tables and indices to use (and to create, if
 necessary).
@@ -1172,15 +1172,20 @@ been done and should be skipped; otherwise the hash entry should be set.
 C<\&outfn> is a coderef which C<srcdump_process_item> should call each
 time it wants to generate a file which should be included as part of
 the source code.  It should be called using one of these patterns:
-   $outfn->("message for log");
-   $outfile = $outfn->("message for log", "extension");
-The former simply logs this message (along with the associated
-C<$item>, so there is no need to mention that).  The latter logs the
-message but also generates and returns a filename which should then
+   $outfn->("message for manifest");
+   $outfile = $outfn->("message for manifest", "extension");
+The former simply prints the message into the manifest in the form
+  none: message for manifest
+The latter generates and returns a filename which should then
 be created and filled with some appropriate data.  C<"extension">
 should be a string for the file extension, eg C<"txt">.  The output
 can be written directly to the named file: there is no need to
-write to a temporary file and rename.
+write to a temporary file and rename.  C<$outfn> writes the filename
+and the message to the manifest, in the form
+  filename leaf: message
+In neither case is the actual name of C<$dir> on the system
+disclosed per se although of course some of the contents of some of
+the files in the source code dump may mention it.
 
 The default implementation is the module function
 C<srcdump_process_item>.
@@ -1306,12 +1311,27 @@ your application runs on multiple frontend hosts with a shared
 database, you may need to create for yourself the tables and indices
 used by CGI::Auth::Flexible.
 
+By default, every time CAF starts up, it attempts to execute certain
+fixed database statements to create the tables and indices it needs.
+These are run with C<$dbh->{PrintError}> set to 0.  The effect with
+sqlite (the default database) is that the tables and indices are
+created iff they do not already exist, and that no spurious errors are
+reported anywhere.
+
+If you use a different database, or just prefer to do things
+differently, you can set up the tables yourself and/or disable or
+modify the default setup statements, via the C<db_setup_stmts>
+setting.
+
+The tables needed are:
+
+
 xxx document _db_setup_do
 xxx make _db_setup_do explicitly overrideable
 
 
 xxx remaining settings
- assocdb_password
+ db_password
  username_password_error
  login_ok
  get_cookie_domain
@@ -1319,15 +1339,13 @@ xxx remaining settings
  print
  debug
 
-xxx $message argument to $outfn->() is not for log, it's for manifest
-xxx document syntax of $message argument to $outfn->()
+xxx document cookie usage
+xxx document construct_cookie fn
 
-xxx html generators
-xxx document cookie
+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-assocs.db
 xxx rename caf_assocsecret default cookie name
 xxx mention relationship between login_timeout and cookies