better documentation as to what the variables are about in this config

file.

webtools/tinderbox2/src/lib/TreeData.pm

@@ -4,7 +4,7 @@
 # repository data.  Only TinderDB::VC and VCDisplay know the
 # datastructure contained in this file.  Other modules can only check
 # if a string is a valid tree name or can get the list of all valid
-# trees through funtional interfaces.  Also this file store the list
+# trees through functional interfaces.  Also this file store the list
 # of valid tree states.  The TreeState is used as an informational
 # message only it does not directly effect the operation of the
 # version control system. The TreeState is manipulated via the
@@ -14,10 +14,10 @@
 # do not support that. The format of this data depends on the version
 # control system in use and abstraction prevents treeadmin.cgi from
 # knowing those details.  I may code a TreeData specific admin-CGI
-# script in the future but I do not have time now and the benifits are
+# script in the future but I do not have time now and the benefits are
 # not so clear.  For bonsai users it would be best if the DB stored
-# the tree data.  The tinderbox server could download the data from a
-# central place when it first starts up, and this download could
+# the tree data.  The tinderbox server could down load the data from a
+# central place when it first starts up, and this down load could
 # trigger a registration for email updates of changes to any trees
 # which this tinderbox server is monitoring. As long as the data is
 # stored in a file, it is safer to have this data stored in VC in its
@@ -29,8 +29,8 @@
 # issue to work out.
 
 
-# $Revision: 1.2 $ 
-# $Date: 2000/08/11 00:35:25 $ 
+# $Revision: 1.3 $ 
+# $Date: 2000/08/24 15:04:33 $ 
 # $Author: kestes%staff.mail.com $ 
 # $Source: /home/hwine/cvs_conversion/cvsroot/mozilla/webtools/tinderbox2/src/lib/Attic/TreeData.pm,v $ 
 # $Name:  $ 
@@ -67,12 +67,13 @@ $VERSION = '#tinder_version#';
 
 # Each tree is a map from a name to all the information necessary to
 # do a checkout of the sources (in this case cvs repository to
-# checkout, module, branch needed).  Tree names are used as parts of
+# checkout, module, branch needed) and to create a URL to display the
+# page (if such a means exists).  Tree names are used as parts of
 # filenames so should not contain ' ' or '/' or unprintable
 # characters.  You may need to change this datastructure if you do not
 # use CVS.
 
-# Who uses tree data?  
+# Who uses tree data?
 
 # Only the VCDisplay and TinderDB::VC know what the internal structure
 # of the tree hash is.  All other modules only need to use the name of
@@ -81,10 +82,52 @@ $VERSION = '#tinder_version#';
 # Also the client side build script needs to know how to checkout a
 # tree.
 
-# dir_pattern is a hack to get arround the fact that CVS does not
-# always understand the module structure.  If we can discribe what is
-# in the module using a perl pattern we can implement lost
-# CVS functionality in perl.
+
+#------------------------------------------------------------------
+
+
+# This section describes some functionality issues when using
+# VC_CVS.pm and is not applicable to Bonsai users.
+
+
+# The 'cvs history' command does not give correct info about
+# modifications to the repository (types= 'ARM') when passed a module
+# name, it was only designed to work on individual files.  If you use
+# the -m option you will not find any info about checkins. We leave
+# off the module name and take the info for the whole repository
+# instead. If this becomes a bother we can reject information about
+# updates which do not match a pattern.  In this respect the pattern
+# becomes a proxy for the module.  The pattern is stored in
+# $TreeData::VC_TREE{$tree}{'dir_pattern'}.  
+
+# There is nothing I can think of to get information about which
+# branch the changes were checked in on.  The history command also has
+# no notion of branches, but that is a common problem with the way CVS
+# does branching anyway.
+
+# What we really want it the checkin comments but history does not
+# give us that information and it would be too expensive to run cvs
+# again for each file.  The file name is good enough but other VC
+# implementations should use the checkin comments if available.
+
+# dir_pattern: Reject all CVS update file names which do not match
+# this pattern. This is only used by VC_CVS.pm and not by Bonsai.
+# This is a hack to get around the fact that CVS does not always
+# understand the module structure, and 'cvs history' will report all
+# updates to a repository even for modules not of interest to us.  So
+# if you use VC_CVS.pm the module value will not be passed to CVS. If
+# the user can describe what is in the module using a perl pattern
+# then VC_CVS.pm can implement lost CVS module functionality in the
+# perl code.
+
+# module: Although VC_CVS ignores this variable you should still set
+# it because it is clearer (a tree is supposed to map to a module) and
+# for practical reasons (the VC_Display may use it an CVS may allow
+# proper use in the future).
+
+
+#------------------------------------------------------------------
+
 
 # It may interest you to know we are currently using this format to
 # build sets of locally developed libraries.  Each tree is really a