Changeset 185 for trunk/doc

Timestamp:

Sep 6, 2006, 4:39:18 AM (15 years ago)

Author:

Jari Häkkinen

Message:

Fixes #65 and #60. Added support for svndigest:ignore. Uppdated documentation. Reworked binary file treatment.

File:

• trunk/doc/readme.txt (modified) (4 diffs)

trunk/doc/readme.txt

@@ -1 +1 @@
 $Id$
 
+======================================================================
 Copyright (C) 2005, 2006 Jari Häkkinen
 
@@ -12 +13 @@
 svndigest is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 General Public License for more details.
 
@@ -19 +20 @@
 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
 USA.
-
+======================================================================
 
 
 svndigest traverses a directory structure (controlled by subversion)
 and calculates developer statistics for all subversion controlled
-entries. The result is written to a sub-directory that will be created
-in the current working directory.
+entries. The result is written to a sub-directory of an user
+specifiable target directory (defualt is the current working
+directory).
 
 To understand what statistics is calculated by svndigest this
 definition is needed: The developer who made the latest change to a
-line still in use in the latest (checked out) revision, is considered
-as the contributor of that line regardless of who actually originally
-created that line.
+line still in use in the latest revision, is considered as the
+contributor of that line regardless of who actually originally created
+that line.
 
 The statistics calculated is the number of lines contributed from each
@@ -39 +41 @@
 There are many different types of files and for many file types it
 does not make sense to define lines. Source code, documentation, and
-other human readable files can be treated on line basis whereas
-symbolic links and binary files cannot. svndigest treats non-line based
-files as one-line files, i.e. the developer that made the last change
-to this type of files gets a one-line credit for it.
+other human readable files can be treated in single line basis whereas
+symbolic links and binary files cannot. svndigest treats binary files
+as zero-line files, whereas symbolic links are treated as one-line
+files. There is a possiblity to exclude files from the statistics, the
+use of the property svndigest:ignore.
 
-How should we exclude un-reasonable credit for large line based files?
-We could add a property to that file, tagging it as a file that should
-be treated as an non-line base file.
+Sometimes large test files and xml files are added to the repository
+that should not really be counted in the statistics. This is solved
+with the svndigest:ignore property. Files with this property are
+excluded from statistics. Setting the svndigest:ignore propertu to a
+directory will exclude all siblings to that directory from svndigest
+treatment.
 
-The current design assumes that the subversion repository to be
-analysed is checked out, maybe one would want to run the analysis
-agains a subversion repositoy directly.
+svndigest requires the subversion repository to be checked out before
+analysis, i.e., svndigest will not run directly against a repository,
+and up to date with the repository.
+
 
 The current flow of the program is.
 
-i) Extract the directory structure starting from the directory given
-   at the command line.
+i) Check that we are working with a WC in subversion control.
 
-ii) Parse the directory structure, removing files and direcotries that
-   is not in subversion control. After this step, only valid
-   subversion entries will be allowed in the tree. Beware, 'svn blame'
-   chokes on directories, and the directories are still a part of the
-   tree.
+ii) Build the requested directory structure ignoring not subversion
+   controlled items. During the directory structure creation a check
+   is made that the WC is up to date with the repository.
 
 iii) Walk through the directory structure and calculate statistics for
    each entry.
 
-iv) Compile statistics as discussed. This step may be intermingled
-   with step iii).
-
-v) Create the html presentation as discussed.
+iv) Create the plots and html presentation.