Changeset 341 for trunk

Timestamp:

May 19, 2007, 1:29:24 PM (16 years ago)

Author:

Peter Johansson

Message:

wiki wiki wiki

File:

• trunk/doc/readme.txt (modified) (2 diffs, 1 prop)

trunk/doc/readme.txt

@@ -1 +1 @@
 $Id$
 
-======================================================================
+= About svndigest =
+
+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 of a user
+specifiable target directory (default is the current working
+directory).
+
+== Statistics ==
+
+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 revision, is considered as the
+contributor of that line regardless of who actually originally created
+that line.
+
+For each developer svndigest calculates the number of contributed
+lines in the latest (checked out) revision. Svndigest calculates for
+each revision, by checking when each line was last changed, how many
+lines each developer had contributed at that specific revision and
+still are in use. 
+
+== Different linetypes ==
+
+Svndigest parses each file to detect whether lines are `code`,
+`comment`, or `other`. Depending on the file name, different
+parsing modes are used, which means different sets of rules what is
+`code` or `comment` are employed. Common for all modes is that
+comment blocks are identified by a start code (e.g. '/*' in a C file)
+and a stop code (e.g. '*/' in a C file). If a line contains
+alphanumeric characters being outside comment blocks, the line is
+considered to be ''code''. Otherwise, if the line contains
+alphanumeric characters inside a comment block, the line is considered
+to be a line of ''comment''. Otherwise the line is considered to be
+`other`. At the time being the following comment identifiers are
+used:
+
+ * cc-mode
+   * files: *.c, *.cc, *.cpp, *.cxx, *.h, *.hh, *.hpp, and *.java
+   * identifier: /* <comment> */
+   * identifier: // <comment> end-of-line
+ * m4-mode
+   * files: *.ac *.am *.m4
+   * identifier: dnl <comment> end-of-line
+   * identifier: # <comment> end-of-line
+ * shell-mode
+   * files: *.sh *.pl *.pm *config bootstrap Makefile
+   * identifier: # <comment> end-of-line
+ * tex-mode
+   * files: *.tex *.m
+   * identifier: % <comment> end-of-line
+ * jsp-mode
+   * files: *.jsp
+   * identifier: <!-- <comment> -->
+   * identifier: <%-- <comment> --%>
+ * sgml-mode
+   * files: *.sgml, *.html, *.shtml, *.xml, *.xsl, *.xsd, *.css, and *.rss
+   * identifier: <!-- <comment> -->
+ * text-mode
+   * files: all files not matching any other mode
+   * identifier: not applicable. All text is considered comments,
+     i.e., lines are either ''comments'' or ''other''
+
+== Different file types ==
+
+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 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 possibility to exclude files from the statistics, the
+use of the property svndigest:ignore.
+
+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 property to a
+directory will exclude all siblings to that directory from svndigest
+treatment.
+
+== Prerequisites ==
+
+Svndigest runs against a working copy (WC), i.e., svndigest will not
+run directly against a repository. Svndigest requires that the WC is
+pristine before running the analysis, i.e., no files are allowed to be
+modified. We also recommend that the WC is in synch with the
+repository. Issue `svn update` before running svndigest.
+
+== Flow of the program ==
+The current flow of the program is.
+
+  * Check that we are working with a WC in subversion control.
+
+  * 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.
+
+  * Walk through the directory structure and calculate statistics for
+    each entry.
+
+  * Create the plots and HTML presentation.
+
+----------------------------------------------------------------------
+{{{
 Copyright (C) 2005 Jari Häkkinen
 Copyright (C) 2006 Jari Häkkinen, Peter Johansson
+Copyright (C) 2007 Peter Johansson
 
 This file is part of svndigest, http://lev.thep.lu.se/trac/svndigest
@@ -21 +125 @@
 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 of a user
-specifiable target directory (default 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 revision, is considered as the
-contributor of that line regardless of who actually originally created
-that line.
-
-For each developer svndigest calculates the number of contributed
-lines in the latest (checked out) revision. Svndigest calculates for
-each revision, by checking when each line was last changed, how many
-lines each developer had contributed at that specific revision and
-still are in use. svndigest separates between different types of
-lines: line of code, line of comment, and empty lines.
-
-The separation between types of lines is designed to support C++ style
-line comments like
-
-// blah blah
-
-with two or more slashes in front of them, and C style block comments like
-
-/*
- * blah blah
- */
-
-with zero or more stars at the beginning of every line. A line is
-consider to be a line of code, if it contains non-whitespace
-characters being neither inside a C style block nor after a C++ style
-line comment start ('//'). In case the line is not a line of code, it
-is considered as a line of comment if it contains alphanumeric
-characters (see isalnum). Remaining lines are consider empty, in other
-words, lines like: '////////////' or '/*' are considered as empty.
-
-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 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 possibility to exclude files from the statistics, the
-use of the property svndigest:ignore.
-
-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 property to a
-directory will exclude all siblings to that directory from svndigest
-treatment.
-
-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) Check that we are working with a WC in subversion control.
-
-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) Create the plots and HTML presentation.