source: trunk/doc/readme.txt @ 348

Last change on this file since 348 was 348, checked in by Peter Johansson, 15 years ago

added section on copyright update

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
  • Property svn:mime-type set to text/x-trac-wiki
File size: 6.0 KB
RevLine 
[3]1$Id: readme.txt 348 2007-05-20 09:18:48Z peter $
2
[341]3= About svndigest =
[84]4
[341]5Svndigest traverses a directory structure (controlled by subversion)
[149]6and calculates developer statistics for all subversion controlled
[187]7entries. The result is written to a sub-directory of a user
[188]8specifiable target directory (default is the current working
[185]9directory).
[3]10
[341]11== Statistics ==
12
[149]13To understand what statistics is calculated by svndigest this
14definition is needed: The developer who made the latest change to a
[185]15line still in use in the latest revision, is considered as the
16contributor of that line regardless of who actually originally created
17that line.
[3]18
[188]19For each developer svndigest calculates the number of contributed
[189]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
[341]23still are in use.
[3]24
[341]25== Different linetypes ==
[188]26
[341]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:
[188]39
[341]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''
[188]65
[342]66There is one exception to these rules. If the files name ends with
67`.in`, the trailing `.in` is ignored and the file name rules above are
68applied on the remaining part of the file name. An example is
69`test/test_repo.sh.in` that is parsed using the shell-mode rules.
70
[341]71== Different file types ==
[188]72
[46]73There are many different types of files and for many file types it
[3]74does not make sense to define lines. Source code, documentation, and
[185]75other human readable files can be treated in single line basis whereas
76symbolic links and binary files cannot. svndigest treats binary files
77as zero-line files, whereas symbolic links are treated as one-line
[188]78files. There is a possibility to exclude files from the statistics, the
[185]79use of the property svndigest:ignore.
[3]80
[189]81Sometimes large test files and XML files are added to the repository
[185]82that should not really be counted in the statistics. This is solved
83with the svndigest:ignore property. Files with this property are
[187]84excluded from statistics. Setting the svndigest:ignore property to a
[185]85directory will exclude all siblings to that directory from svndigest
86treatment.
[3]87
[348]88== Copyright update ==
89
90Using the option `--copyright` svndigest will try to update the
91copyright statement in each of the parsed files. The copyright
92statement is detected as the first line containing `Copyright
93(C)`. The copyright statement block is defined to start at this line
94and ends with the first following line containing no alphanumerical
95characters (i.e. line is treated as `other` in statistics). This
96copyright statement block is replaced with a new copyright block
97generated from analyzing `svn log`. An author is considered to has
98copyright of the file if (s)he has modified the file and thereby
99occurs in the log. For an example of the format of the generated
100copyright statement, please have a look at any file in the svndigest
101project.
102
[341]103== Prerequisites ==
[3]104
[341]105Svndigest runs against a working copy (WC), i.e., svndigest will not
106run directly against a repository. Svndigest requires that the WC is
107pristine before running the analysis, i.e., no files are allowed to be
108modified. We also recommend that the WC is in synch with the
109repository. Issue `svn update` before running svndigest.
[185]110
[341]111== Flow of the program ==
[3]112The current flow of the program is.
113
[341]114  * Check that we are working with a WC in subversion control.
[3]115
[341]116  * Build the requested directory structure ignoring not subversion
117    controlled items. During the directory structure creation a check
118    is made that the WC is up to date with the repository.
[3]119
[341]120  * Walk through the directory structure and calculate statistics for
121    each entry.
[3]122
[341]123  * Create the plots and HTML presentation.
124
125----------------------------------------------------------------------
126{{{
127Copyright (C) 2005 Jari Häkkinen
128Copyright (C) 2006 Jari Häkkinen, Peter Johansson
129Copyright (C) 2007 Peter Johansson
130
131This file is part of svndigest, http://lev.thep.lu.se/trac/svndigest
132
133svndigest is free software; you can redistribute it and/or modify it
134under the terms of the GNU General Public License as published by the
135Free Software Foundation; either version 2 of the License, or (at your
136option) any later version.
137
138svndigest is distributed in the hope that it will be useful, but
139WITHOUT ANY WARRANTY; without even the implied warranty of
140MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
141General Public License for more details.
142
143You should have received a copy of the GNU General Public License
144along with this program; if not, write to the Free Software
145Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
146USA.
147}}}
148
149
Note: See TracBrowser for help on using the repository browser.