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

---
 caf.pod | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 55 insertions(+), 6 deletions(-)

diff --git a/caf.pod b/caf.pod
index 7fefd16..1308700 100644
--- a/caf.pod
+++ b/caf.pod
@@ -999,7 +999,11 @@ 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
+C<srcdump_process_item>.
+
+It skips directories for which C<srcdump_system_dir> returns true.
+
+It then 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>).
@@ -1055,16 +1059,61 @@ of C<srcdump_novcs>.  The default value is C<['*~','*.bak','*.tmp','#*#']>.
 
 Entries must not contain C<'> or C<\>.
 
+=item C<srcdump_listitems($cgi,$verifier)>
 
-xxx conditions on listitems implied by srcdump_dirscan_prepare
-xxx listitems enoent behaviour
-The de
+Returns an array of directories which might contain source code of the
+web application and which should be therefore be considered for
+including in the source code delivery.
 
-xxx syntax of srcdump_excludes
+Used by the default implementation of C<srcdump_prepare>.
 
+Entries must be directories, plain files, or nonexistent; they may
+also be symlinks which resolve to one of those.
 
-=back
+If C<.> is included it may be treated specially - see
+C<srcdump_filter_cwd>.
+
+The default implementation returns 
+C<(@INC, $ENV{'SCRIPT_FILENAME'}, $0)>.
+
+=item C<srcdump_system_dir($cgi,$verifier,$dir)>
+
+Determines whether C<$dir> is a "system directory", in which any
+source code used by the application should nevertheless not be
+included in the source code dump.
+
+Used by the default implementation of C<srcdump_item>.
+
+The default implementation is as follows: Things in C</etc/> are
+system directories.  Things in C</usr/> are too, unless they are in
+C</usr/local/> or C</usr/lib/cgi*>.
+
+=item C<srcdump_filter_cwd>
 
+Boolean which controls the handling of C<.> if it appears in the
+return value from C<srcdump_listitems>.  Used only by the default
+implementation of C<srcdump_prepare>.
+
+If set to false, C<.> is treated normally and no special action is
+taken.
+
+However often the current directory may be C</>, or a data directory,
+or some other directory containing data which is confidential, or
+should not be included in the public source code distribution for
+other reasons.  And for historical reasons Perl has C<@INC> containing
+C<.> by default (which is arguably dangerous and wrong).
+
+So the default this setting is true, which has the following effects:
+
+C<.> is not searched for source code even if it appears in C<@INC>.
+C<.> is removed from C<@INC> and C<%INC> is checked to see if any
+modules appear to have already been loaded by virtue of C<.> appearing
+in C<@INC> and if they have it is treated as a fatal error.
+
+Only the literal string C<.> is affected.  If the cwd is included by
+any other name it is not treated specially regardless of this setting.
+
+=back
 
 =head1 DATABASE TABLES
 
-- 
2.30.2