source: trunk/doc/readme.txt @ 524

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

adding text on how to configure parsing codons - fixes ticket:283

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