source: trunk/doc/readme.txt @ 505

Last change on this file since 505 was 505, checked in by Peter Johansson, 14 years ago

Fixes #270 - Changing the rule of what is code. Rather than requiring a line of code to contain a alhanumerical character, a line of code is required to contain a visible character (outside comment blocks).

  • 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: 7.8 KB
RevLine 
[3]1$Id: readme.txt 505 2007-12-06 02:57:39Z 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
[495]25see also: http://trac.thep.lu.se/trac/svndigest/wiki/StatsType
26
[341]27== Different linetypes ==
[188]28
[341]29Svndigest parses each file to detect whether lines are `code`,
30`comment`, or `other`. Depending on the file name, different
31parsing modes are used, which means different sets of rules what is
32`code` or `comment` are employed. Common for all modes is that
33comment blocks are identified by a start code (e.g. '/*' in a C file)
34and a stop code (e.g. '*/' in a C file). If a line contains
[505]35visible characters being outside comment blocks, the line is
[341]36considered to be ''code''. Otherwise, if the line contains
37alphanumeric characters inside a comment block, the line is considered
38to be a line of ''comment''. Otherwise the line is considered to be
[505]39''other''. At the time being the following comment identifiers are
[341]40used:
[188]41
[341]42 * cc-mode
43   * files: *.c, *.cc, *.cpp, *.cxx, *.h, *.hh, *.hpp, and *.java
44   * identifier: /* <comment> */
45   * identifier: // <comment> end-of-line
46 * m4-mode
47   * files: *.ac *.am *.m4
48   * identifier: dnl <comment> end-of-line
49   * identifier: # <comment> end-of-line
50 * shell-mode
51   * files: *.sh *.pl *.pm *config bootstrap Makefile
52   * identifier: # <comment> end-of-line
53 * tex-mode
54   * files: *.tex *.m
55   * identifier: % <comment> end-of-line
56 * jsp-mode
57   * files: *.jsp
58   * identifier: <!-- <comment> -->
59   * identifier: <%-- <comment> --%>
60 * sgml-mode
61   * files: *.sgml, *.html, *.shtml, *.xml, *.xsl, *.xsd, *.css, and *.rss
62   * identifier: <!-- <comment> -->
63 * text-mode
64   * files: all files not matching any other mode
65   * identifier: not applicable. All text is considered comments,
66     i.e., lines are either ''comments'' or ''other''
[188]67
[342]68There is one exception to these rules. If the files name ends with
69`.in`, the trailing `.in` is ignored and the file name rules above are
70applied on the remaining part of the file name. An example is
71`test/test_repo.sh.in` that is parsed using the shell-mode rules.
72
[341]73== Different file types ==
[188]74
[46]75There are many different types of files and for many file types it
[3]76does not make sense to define lines. Source code, documentation, and
[185]77other human readable files can be treated in single line basis whereas
78symbolic links and binary files cannot. svndigest treats binary files
[361]79and symbolic links as zero-line files. There is a possibility to
80exclude files from the statistics, the use of the property
81svndigest:ignore.
[3]82
[189]83Sometimes large test files and XML files are added to the repository
[185]84that should not really be counted in the statistics. This is solved
85with the svndigest:ignore property. Files with this property are
[187]86excluded from statistics. Setting the svndigest:ignore property to a
[185]87directory will exclude all siblings to that directory from svndigest
88treatment.
[3]89
[351]90== Configuration ==
91
[439]92The configuration file may be used to define various behaviors for
[351]93svndigest. By default svndigest looks for a config file named `config`
94in directory `<root-dir>/.svndigest` (<root-dir> is directory set by
95option `--root`). If no such file is found, svndigest behaves as
96default. Which file to be used as config file may also be set with
97option `--config-file`. To update an old config file you can use the
98option `--generate-config`. With this option set the used
99configuration will be written to standard output. If new variables has
100been added to configuration of svndigest, these variables will be
101written with default values. Note: if you have added a comment (e.g. a
[353]102subversion keyword) to your old config file, this will not be
[351]103inherited to the new config file. To preserve such a comment you must
104merge the new config file with the old config file manually.
105
[348]106== Copyright update ==
107
108Using the option `--copyright` svndigest will try to update the
109copyright statement in each of the parsed files. The copyright
110statement is detected as the first line containing `Copyright
111(C)`. The copyright statement block is defined to start at this line
112and ends with the first following line containing no alphanumerical
[444]113characters (excluding `prefix` string preceeding `Copyright (C)`). This
[349]114copyright statement block is replaced with a new copyright statement
115generated from analyzing `svn log`. An author is considered to have
[348]116copyright of the file if (s)he has modified the file and thereby
117occurs in the log. For an example of the format of the generated
[351]118copyright statement, please have a look at the bottom of this file. By
119default the `svn user name` of the author is printed in the copyright
120statement. This may be overridden by setting a `copyright-alias` in
121the config file. In svndigest, e.g., user name `jari` is set to
122copyright-alias ''Jari Häkkinen'' and user name `peter` is set to
123copyright-alias ''Peter Johansson''. If two (or several) authors are
124given the same copyright-alias they are considered as one person in
125the copyright statement (i.e. their alias is not repeated). This may
126be useful if you want to give copyright to an organization rather than
127to individual developers.
[348]128
[352]129== TracLinks ==
130
131From svndigest 0.6 there is support for TracLinks. The root trac
132location may be set in the configuration, in which case various links
133to the trac site will be included in the resulting report. This
134includes links from revision number to the corresponding revision at
135the trac site, and various kinds of links are detected in the messages
136in `Recent Log`.
137
[341]138== Prerequisites ==
[3]139
[341]140Svndigest runs against a working copy (WC), i.e., svndigest will not
141run directly against a repository. Svndigest requires that the WC is
142pristine before running the analysis, i.e., no files are allowed to be
143modified. We also recommend that the WC is in synch with the
144repository. Issue `svn update` before running svndigest.
[185]145
[341]146== Flow of the program ==
[3]147The current flow of the program is.
148
[341]149  * Check that we are working with a WC in subversion control.
[3]150
[341]151  * Build the requested directory structure ignoring not subversion
152    controlled items. During the directory structure creation a check
153    is made that the WC is up to date with the repository.
[3]154
[341]155  * Walk through the directory structure and calculate statistics for
156    each entry.
[3]157
[341]158  * Create the plots and HTML presentation.
159
160----------------------------------------------------------------------
161{{{
162Copyright (C) 2005 Jari Häkkinen
163Copyright (C) 2006 Jari Häkkinen, Peter Johansson
164Copyright (C) 2007 Peter Johansson
165
[440]166This file is part of svndigest, http://trac.thep.lu.se/trac/svndigest
[341]167
168svndigest is free software; you can redistribute it and/or modify it
169under the terms of the GNU General Public License as published by the
170Free Software Foundation; either version 2 of the License, or (at your
171option) any later version.
172
173svndigest is distributed in the hope that it will be useful, but
174WITHOUT ANY WARRANTY; without even the implied warranty of
175MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
176General Public License for more details.
177
178You should have received a copy of the GNU General Public License
179along with this program; if not, write to the Free Software
180Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
181USA.
182}}}
183
184
Note: See TracBrowser for help on using the repository browser.