Changeset 341 for trunk/doc


Ignore:
Timestamp:
May 19, 2007, 1:29:24 PM (14 years ago)
Author:
Peter Johansson
Message:

wiki wiki wiki

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/readme.txt

    • Property svn:mime-type set to text/x-trac-wiki
    r189 r341  
    11$Id$
    22
    3 ======================================================================
     3= About svndigest =
     4
     5Svndigest traverses a directory structure (controlled by subversion)
     6and calculates developer statistics for all subversion controlled
     7entries. The result is written to a sub-directory of a user
     8specifiable target directory (default is the current working
     9directory).
     10
     11== Statistics ==
     12
     13To understand what statistics is calculated by svndigest this
     14definition is needed: The developer who made the latest change to a
     15line still in use in the latest revision, is considered as the
     16contributor of that line regardless of who actually originally created
     17that line.
     18
     19For each developer svndigest calculates the number of contributed
     20lines in the latest (checked out) revision. Svndigest calculates for
     21each revision, by checking when each line was last changed, how many
     22lines each developer had contributed at that specific revision and
     23still are in use.
     24
     25== Different linetypes ==
     26
     27Svndigest parses each file to detect whether lines are `code`,
     28`comment`, or `other`. Depending on the file name, different
     29parsing modes are used, which means different sets of rules what is
     30`code` or `comment` are employed. Common for all modes is that
     31comment blocks are identified by a start code (e.g. '/*' in a C file)
     32and a stop code (e.g. '*/' in a C file). If a line contains
     33alphanumeric characters being outside comment blocks, the line is
     34considered to be ''code''. Otherwise, if the line contains
     35alphanumeric characters inside a comment block, the line is considered
     36to be a line of ''comment''. Otherwise the line is considered to be
     37`other`. At the time being the following comment identifiers are
     38used:
     39
     40 * cc-mode
     41   * files: *.c, *.cc, *.cpp, *.cxx, *.h, *.hh, *.hpp, and *.java
     42   * identifier: /* <comment> */
     43   * identifier: // <comment> end-of-line
     44 * m4-mode
     45   * files: *.ac *.am *.m4
     46   * identifier: dnl <comment> end-of-line
     47   * identifier: # <comment> end-of-line
     48 * shell-mode
     49   * files: *.sh *.pl *.pm *config bootstrap Makefile
     50   * identifier: # <comment> end-of-line
     51 * tex-mode
     52   * files: *.tex *.m
     53   * identifier: % <comment> end-of-line
     54 * jsp-mode
     55   * files: *.jsp
     56   * identifier: <!-- <comment> -->
     57   * identifier: <%-- <comment> --%>
     58 * sgml-mode
     59   * files: *.sgml, *.html, *.shtml, *.xml, *.xsl, *.xsd, *.css, and *.rss
     60   * identifier: <!-- <comment> -->
     61 * text-mode
     62   * files: all files not matching any other mode
     63   * identifier: not applicable. All text is considered comments,
     64     i.e., lines are either ''comments'' or ''other''
     65
     66== Different file types ==
     67
     68There are many different types of files and for many file types it
     69does not make sense to define lines. Source code, documentation, and
     70other human readable files can be treated in single line basis whereas
     71symbolic links and binary files cannot. svndigest treats binary files
     72as zero-line files, whereas symbolic links are treated as one-line
     73files. There is a possibility to exclude files from the statistics, the
     74use of the property svndigest:ignore.
     75
     76Sometimes large test files and XML files are added to the repository
     77that should not really be counted in the statistics. This is solved
     78with the svndigest:ignore property. Files with this property are
     79excluded from statistics. Setting the svndigest:ignore property to a
     80directory will exclude all siblings to that directory from svndigest
     81treatment.
     82
     83== Prerequisites ==
     84
     85Svndigest runs against a working copy (WC), i.e., svndigest will not
     86run directly against a repository. Svndigest requires that the WC is
     87pristine before running the analysis, i.e., no files are allowed to be
     88modified. We also recommend that the WC is in synch with the
     89repository. Issue `svn update` before running svndigest.
     90
     91== Flow of the program ==
     92The current flow of the program is.
     93
     94  * Check that we are working with a WC in subversion control.
     95
     96  * Build the requested directory structure ignoring not subversion
     97    controlled items. During the directory structure creation a check
     98    is made that the WC is up to date with the repository.
     99
     100  * Walk through the directory structure and calculate statistics for
     101    each entry.
     102
     103  * Create the plots and HTML presentation.
     104
     105----------------------------------------------------------------------
     106{{{
    4107Copyright (C) 2005 Jari Häkkinen
    5108Copyright (C) 2006 Jari Häkkinen, Peter Johansson
     109Copyright (C) 2007 Peter Johansson
    6110
    7111This file is part of svndigest, http://lev.thep.lu.se/trac/svndigest
     
    21125Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
    22126USA.
    23 ======================================================================
     127}}}
    24128
    25129
    26 svndigest traverses a directory structure (controlled by subversion)
    27 and calculates developer statistics for all subversion controlled
    28 entries. The result is written to a sub-directory of a user
    29 specifiable target directory (default is the current working
    30 directory).
    31 
    32 To understand what statistics is calculated by svndigest this
    33 definition is needed: The developer who made the latest change to a
    34 line still in use in the latest revision, is considered as the
    35 contributor of that line regardless of who actually originally created
    36 that line.
    37 
    38 For each developer svndigest calculates the number of contributed
    39 lines in the latest (checked out) revision. Svndigest calculates for
    40 each revision, by checking when each line was last changed, how many
    41 lines each developer had contributed at that specific revision and
    42 still are in use. svndigest separates between different types of
    43 lines: line of code, line of comment, and empty lines.
    44 
    45 The separation between types of lines is designed to support C++ style
    46 line comments like
    47 
    48 // blah blah
    49 
    50 with two or more slashes in front of them, and C style block comments like
    51 
    52 /*
    53  * blah blah
    54  */
    55 
    56 with zero or more stars at the beginning of every line. A line is
    57 consider to be a line of code, if it contains non-whitespace
    58 characters being neither inside a C style block nor after a C++ style
    59 line comment start ('//'). In case the line is not a line of code, it
    60 is considered as a line of comment if it contains alphanumeric
    61 characters (see isalnum). Remaining lines are consider empty, in other
    62 words, lines like: '////////////' or '/*' are considered as empty.
    63 
    64 There are many different types of files and for many file types it
    65 does not make sense to define lines. Source code, documentation, and
    66 other human readable files can be treated in single line basis whereas
    67 symbolic links and binary files cannot. svndigest treats binary files
    68 as zero-line files, whereas symbolic links are treated as one-line
    69 files. There is a possibility to exclude files from the statistics, the
    70 use of the property svndigest:ignore.
    71 
    72 Sometimes large test files and XML files are added to the repository
    73 that should not really be counted in the statistics. This is solved
    74 with the svndigest:ignore property. Files with this property are
    75 excluded from statistics. Setting the svndigest:ignore property to a
    76 directory will exclude all siblings to that directory from svndigest
    77 treatment.
    78 
    79 svndigest requires the subversion repository to be checked out before
    80 analysis, i.e., svndigest will not run directly against a repository,
    81 and up to date with the repository.
    82 
    83 
    84 The current flow of the program is.
    85 
    86 i) Check that we are working with a WC in subversion control.
    87 
    88 ii) Build the requested directory structure ignoring not subversion
    89    controlled items. During the directory structure creation a check
    90    is made that the WC is up to date with the repository.
    91 
    92 iii) Walk through the directory structure and calculate statistics for
    93    each entry.
    94 
    95 iv) Create the plots and HTML presentation.
Note: See TracChangeset for help on using the changeset viewer.