From 7e8ab990ac2f6fea415d5405b831fc7978e669a2 Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Thu, 28 Mar 2013 19:06:25 +0000
Subject: [PATCH] docs: more work

---
 caf.pod | 157 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 150 insertions(+), 7 deletions(-)

diff --git a/caf.pod b/caf.pod
index 32b7e4d..dad4736 100644
--- a/caf.pod
+++ b/caf.pod
@@ -508,7 +508,22 @@ class or due to previous requests on the same verifier.)
 
 See L</REQUEST TYPES>.
 
-=item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible->>>
+=item C<< CGI::Auth::Flexible::srcdump_dir_cpio($cgi,$verifier,$dumpdir,$dir,$outfn,$how,$script) >>
+
+Helper function for implementing the C<srcdump_process_item> hook.
+Generates a tarball using cpio and includes it in the prepared source
+code distribution.
+
+The arguments are mostly the same as for that hook.  C<$dir> is the
+root directory at which to start the archive.  C<$how> is a short text
+string which will be mentioned in the log.
+
+C<$script> is a shell script fragment which must output a
+nul-separated list of filenames (e.g. the output of C<find -print0>).
+
+xxx blah blah
+
+=item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible-> >>
 
 Hashes the supplied data using the hash function specified by the
 C<hash_algorithm> setting, and converts the result to a string of hex
@@ -538,6 +553,10 @@ legal syntax.  This should be read to mean that the
 %implicit_settings_hash{'some_hook'}($cgi,$authreq,@stuff)
 would be a legal call.  (However, the settings hash is not exposed.)
 
+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
@@ -810,7 +829,7 @@ C<< gettext(ucfirst $parameter_name) >>, a password field (with
 description C<gettext("Password")>, and a login submit button (with
 description C<gettext("Login")>.
 
-Default is available as the class function C<gen_plain_login_form>.
+Default is available as the module function C<gen_plain_login_form>.
 
 =item C<gen_login_link>($cgi,$authreq))
 
@@ -818,7 +837,7 @@ Default:
 
  <a href="http:...">gettext(Log in again to continue.)</a>
 
-Default is available as the class function C<gen_plain_login_link>.
+Default is available as the module function C<gen_plain_login_link>.
 
 =item C<gen_postmainpage_form>($cgi,$authreq,$params))
 
@@ -829,7 +848,7 @@ fields, and also:
 
  <input type="submit" ... value=getext('Continue')>
 
-Default is available as the class function C<gen_postmainpage_form>.
+Default is available as the module function C<gen_postmainpage_form>.
 
 =item C<gen_start_html>($cgi,$authreq,$title)
 
@@ -849,7 +868,7 @@ Default:
  [gen_source_link_html].
  </address>
 
-Default is available as the class function C<gen_plain_footer_html>.
+Default is available as the module function C<gen_plain_footer_html>.
 
 =item C<gen_licence_link_html>($cgi,$authreq)>
 
@@ -857,7 +876,7 @@ Default: uses C<url_with_query_params> to generate a URL for
 downloading the licence, and returns:
   <a href="...">GNU Affero GPL</a>
 
-Default is available as the class function C<gen_plain_licence_link_html>.
+Default is available as the module function C<gen_plain_licence_link_html>.
 
 =item C<gen_source_link_html>($cgi,$authreq)>
 
@@ -865,7 +884,7 @@ Default: uses C<url_with_query_params> to generate a URL for
 downloading the source, and returns:
   <a href="...">Source available</a>
 
-Default is available as the class function C<gen_plain_source_link_html>.
+Default is available as the module function C<gen_plain_source_link_html>.
 
 =item C<form_entry_size>
 
@@ -897,6 +916,130 @@ Defaults to C<caf-srcdump>.
 
 If this is a relative path, it is in C<dir>.
 
+=item C<srcdump_dump($cgi,$authreq,$srcobj)>
+
+Dump the source code (C<$srcobj='source'> or licence data
+(C<$srcobj='licence'>).  The default implementation checks that
+C<$srcobj> has reasonable syntax and uses the files C<$srcobj.data>
+and C<$srcobj.ctype> with the C<dump> hook.
+
+=item C<dump($cgi,$authreq,$contenttype,$datafilehandle)>
+
+Responds to the request by sending the contents of $datafilehandle
+(which should just have been opened) and specifying a content type of
+$contenttype.
+
+The default implmentation uses the C<print> hook, and also calls
+C<$cgi->header('-type' => $contenttype>, and is available as the
+module function C<dump_plain>.
+
+=item C<srcdump_prepare($cgi,$verifier)>
+
+Prepares the source code for download when requested.  Invoked by
+C<new_verifier>, always, immediately before it returns the
+just-created verifier object.
+
+The default implementation is the module function
+C<srcdump_dirscan_prepare>, which prepares a manifest, licence file
+and source code tarball of tarballs, as follows:
+
+It processes each entry in the return value from C<srcdump_listitems>.
+These are the software's include directories and any other directories
+containing source code.  It handles C<.> specially (see
+C<srcdump_filter_cwd>).
+
+For each entry it looks, relative to that, for the licence as a file
+with a name mentioned in C<srcdump_licence_files>.  The first such
+file found is considered to be the licence.  It then calls the hook
+C<srcdump_process_item> for the entry.
+
+The licence, a manifest file, and all the outputs generated by the
+calls to C<srcdump_process_item>, are tarred up and compressed as a
+single source tarball.
+
+It uses the directory named by C<srcdump_path> as its directory for
+working and output files.  It uses the filename patterns
+C<generate.*>, C<licence.*>, C<s.[a-z][a-z][a-z].*>, C<manifest.*>,
+C<source.*> in that directory.
+
+=item C<srcdump_process_item>($cgi,$verifier,$dumpdir,$item,\&outfn,\$needlicence,\%dirsdone)>
+
+Processes a single include directory or software entry, so as to
+include the source code found there.  Called only by the default
+implementation of C<srcdump_prepare>.
+
+C<$dumpdir> is the directory for working and output files.  C<$item>
+is the real (no symlinks) absolute path to the item.
+
+C<\$needlicence> is a ref to a scalar: this scalar is undef if we have
+already found the licence file; otherwise it is the filename to which
+the licence should be copied.  If the referent is undef on entry,
+C<srcdump_process_item> needs to see if it finds the licence; if it
+does it should copy it to the named file and then set the scalar to
+undef.
+
+C<\%dirsdone> is a ref to the hash used by C<srcdump_prepare> to avoid
+including a single directory more than once.  If
+C<srcdump_process_item> decides to process a directory other than
+C<$item> it should check this hash with the real absolute path of the
+other directoy as a key: if the hash entry is true, it has already
+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
+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.
+
+The default implementation is the module function
+C<srcdump_process_item>.  It searches the item and its parent
+directories for a vcs metadata directory (one of the names in
+C<srcdump_vcs_dirs>); if found, it calls the C<srcdump_byvcs> hook
+(after checking and updaeing C<%dirsdone>).
+Otherwise it calls the C<srcdump_novcs> hook.
+
+=item C<srcdump_novcs($cgi,$verifier,$dumpdir,$item,$outfn)>
+
+Called by the default implementation of C<srcdump_process_item>, with
+the same arguments, if it doesn't find vcs metadata.
+
+The default implementation is the module function C<srcdump_novcs>.
+
+If C<$item> is a directory, it uses C<srcdump_dir_cpio> to prepare a
+tarball of all the files under C<$item> which have the world read bit
+set.  Directories are not included (and their permissions are
+disregarded).  The contents of C<srcdump_excludes> are excluded.
+
+If it's a plain file it uses C<srcdump_file> to include the file.
+
+=item C<srcdump_byvcs($cgi,$verifier,$dumpdir,$item,$outfn,$vcs)>
+
+Called by the default implementation of C<srcdump_process_item>, with
+the same arguments, if it finds vcs metadata.  The additional argument
+C<$vcs> is derived from the entry of C<srcump_vcs_dirs> which was
+used: it's the first sequence of word characters, lowercased.
+
+The default implementation is the module function C<srcdump_byvcs>.
+It simply calls C<srcdump_dir_cpio> with the script from the setting
+C<srcdump_vcsscript_$vcs>.
+
+
+ which is defined
+
+xxx conditions on listitems implied by srcdump_dirscan_prepare
+xxx listitems enoent behaviour
+The de
+
+xxx syntax of srcdump_excludes
+
+
 =back
 
 
-- 
2.30.2