Edited the help and man page prose. Added sections to the man file about ignore and rules files.

svn path=/trunk/mono-tools/; revision=141621

4 files changed, 82 insertions, 32 deletions

diff --git a/gendarme/console/ChangeLog b/gendarme/console/ChangeLog
index cabffee9..48fc65b9 100644
--- a/gendarme/console/ChangeLog
+++ b/gendarme/console/ChangeLog
@@ -1,3 +1,7 @@
+2009-08-09  Jesse Jones  <jesjones@mindspring.com>
+
+	* ConsoleRunner.cs: Edited the --help text.
+
 2009-07-09  Jesse Jones  <jesjones@mindspring.com>
 
 	* ResultWriter.cs, TextResultWriter.cs, XmlResultWriter.cs, HtmlResultWriter.cs:
diff --git a/gendarme/console/ConsoleRunner.cs b/gendarme/console/ConsoleRunner.cs
index a663f876..3b6c1b7d 100644
--- a/gendarme/console/ConsoleRunner.cs
+++ b/gendarme/console/ConsoleRunner.cs
@@ -471,12 +471,12 @@ namespace Gendarme {
 		{
 			Console.WriteLine ("Usage: gendarme [--config file] [--set ruleset] [--{log|xml|html} file] assemblies");
 			Console.WriteLine ("Where");
-			Console.WriteLine ("  --config file\t\tSpecify the configuration file. Default is 'rules.xml'.");
-			Console.WriteLine ("  --set ruleset\t\tSpecify the set of rules to verify. Default is '*'.");
-			Console.WriteLine ("  --log file\t\tSave the text output to the specified file.");
-			Console.WriteLine ("  --xml file\t\tSave the output, as XML, to the specified file.");
-			Console.WriteLine ("  --html file\t\tSave the output, as HTML, to the specified file.");
-			Console.WriteLine ("  --ignore file\t\tDo not report defects specified inside the file.");
+			Console.WriteLine ("  --config file\t\tSpecify the rule sets and rule settings. Default is 'rules.xml'.");
+			Console.WriteLine ("  --set ruleset\t\tSpecify a rule set from configfile. Default is 'default'.");
+			Console.WriteLine ("  --log file\t\tSave the report to the specified file.");
+			Console.WriteLine ("  --xml file\t\tSave the report, as XML, to the specified file.");
+			Console.WriteLine ("  --html file\t\tSave the report, as HTML, to the specified file.");
+			Console.WriteLine ("  --ignore file\t\tDo not report defects listed in the specified file.");
 			Console.WriteLine ("  --limit N\t\tStop reporting after N defects are found.");
 			Console.WriteLine ("  --severity [all | [[audit | low | medium | high | critical][+|-]]],...");
 			Console.WriteLine ("\t\t\tFilter defects for the specified severity levels.");
@@ -484,8 +484,8 @@ namespace Gendarme {
 			Console.WriteLine ("  --confidence [all | [[low | normal | high | total][+|-]],...");
 			Console.WriteLine ("\t\t\tFilter defects for the specified confidence levels.");
 			Console.WriteLine ("\t\t\tDefault is 'normal+'");
-			Console.WriteLine ("  --quiet\t\tDisplay minimal output (results) from the runner.");
-			Console.WriteLine ("  --v\t\t\tEnable debugging output (can be used multiple times).");
+			Console.WriteLine ("  --quiet\t\tUsed to disable progress and other information which is normally written to stdout.");
+			Console.WriteLine ("  --v\t\t\tWhen present additional progress information is written to stdout (can be used multiple times).");
 			Console.WriteLine ("  assemblies\t\tSpecify the assemblies to verify.");
 			Console.WriteLine ();
 		}
diff --git a/gendarme/man/ChangeLog b/gendarme/man/ChangeLog
index e4f84500..1e290225 100644
--- a/gendarme/man/ChangeLog
+++ b/gendarme/man/ChangeLog
@@ -1,3 +1,7 @@
+2008-08-09  Jesse Jones  <jesjones@mindspring.com>
+
+	* gendarme.1.in: Edited. Added sections for ignore and rules files.
+
 2009-01-27  Jonathan Pryor  <jpryor@novell.com>
 
 	* . (svn:ignore): Ignore generated files.
diff --git a/gendarme/man/gendarme.1.in b/gendarme/man/gendarme.1.in
index bfd2f414..994407f0 100644
--- a/gendarme/man/gendarme.1.in
+++ b/gendarme/man/gendarme.1.in
@@ -13,35 +13,36 @@
 ..
 .TH Gendarme "Gendarme @GENDARME_VERSION@"
 .SH NAME
-Gendarme \- Rule-based code analysis for Mono::
+Gendarme \- Rule-based code analysis for Mono.
 .SH SYNOPSIS
 .PP
 .B gendarme [--config configfile] [--set ruleset] [--log file | --xml file | --html file] [options] assemblies ...
 .SH DESCRIPTION
-\fIGendarme\fP is a extensible rule-based tool to find problems in .NET 
+\fIGendarme\fP is a extensible rule-based tool used to find problems in .NET 
 applications and libraries. Gendarme inspects programs and libraries that
 contain code in ECMA CIL format (Mono and .NET) and looks for common 
-problems with the code, problems that compiler do not typically check or
-have not historically checked.
+problems with the code, problems that compilers do not typically check or
+have historically not checked.
 .SH OPTIONS
 .TP
 .I "--config configfile"
-Specify the configuration file. Default is 'rules.xml'.
+Specify the rule sets and rule settings. Default is 'rules.xml'.
 .TP
 .I "--set ruleset"
-Specify the set of rules to verify. Default is '*'.
+Specify a rule set from configfile. Defaults to 'default'.
 .TP
 .I "--log file"
-Save the text output to the specified file.
+Save the report to the specified file. If none of --log, --xml, or --html are used
+then the report is written to stdout.
 .TP
 .I "--xml file"
-Save the output, formatted as XML, to the specified file.
+Save the report, formatted as XML, to the specified file.
 .TP
 .I "--html file"
-Save the output, formatted as HTML, to the specified file.
+Save the report, formatted as HTML, to the specified file.
 .TP
 .I "--ignore ignore-file"
-Do not report the known defects that are part of the specified file.
+Do not report defects listed in the specified file.
 .TP
 .I "--limit N"
 Stop reporting after N defects are found.
@@ -55,31 +56,72 @@ Filter the reported defects to include the specified confidence levels.
 Default is 'normal+' (i.e. low level is ignored).
 .TP
 .I "--quiet"
-Display minimal output (results) from the runner.
+Used to disable progress and other information which is normally written to stdout.
 .TP
 .I "--v|verbose"
-Enable debugging output. You can supply several -v to augment debugging verbosity.
+When present additional progress information is written to stdout. May be used
+more than once to write even more info. 
 .TP
 .I "--version"
-Display Gendarme's version number. This number match the Mono release
-where it was released.
+Display Gendarme's version number. This will match the Mono version number
+that this copy of Gendarme was released with.
 .TP
 .I "assemblies ..."
 Specify the assemblies to verify. You can specify multiple filenames, 
-including masks (? and *). You can also provide a file that list several
-assemblies (one by line) by prefixing the filename with @ on the command 
+including masks (? and *). You can also provide a file that lists several
+assemblies (one per line) by prefixing the filename with @ on the command 
 line.
 .SH FILES
 .TP
+.I ignore-file
+This file is used to filter out defects from gendarme reports. It uses a line oriented
+file format where the first characters of the line control the interpretation of the line:
+.RS
+# - means that the line is a comment.
+.RE
+.RS
+R: - if the full name of a rule to be filtered.
+.RE
+.RS
+A: - is used to filter out an assembly (the extension can be omitted).
+.RE
+.RS
+T: - is used to filter out a namespace qualified type name.
+.RE
+.RS
+M: - is used to filter out a method. It must contain the full method name as it appears in the report.
+.RE
+
+.TP
 .I rules.xml
-This files contains a list of all the rulesets available to Gendarme. Each 
-ruleset includes a list of assemblies in which some, or all, rules can be
-verified (include) or not (exclude).
-+.TP
-+.I gendarme.exe.config
-+Used by debug versions of Gendarme to enable logging for rules. A config
-+file will be generated automatically by the make file. To enable logging
-+for a rule add a switch using the rule's name and set the value to 1.
+This file is used in conjunction with the --set option to control and configure the rules
+used by Gendarme. It contains a set of named rules (rule sets) and each rule set contains 
+a list of rules. Rules have required from and include attributes, optional exclude and
+applyTo attributes, and optional parameter child elements.
+
+The from attribute is the path of a dll to load ("Gendarme.Rules.BadPractice.dll").
+Relative paths are relative to the gendarme executable.
+
+The include attribute may be "*" to match every rule in the dll or a list of rule names
+separated by '|' ("WhizBangRule | MyRule").
+
+The exclude attribute is a list of rule names separated by '|' ("IckyRule").
+These will override any rules matched by the include attribute.
+
+The applyTo attribute may be "all", "visible", or "nonvisible". If it is all (the default) then
+all types in the assemblies are checked, if it is visible then only the externally visible
+types are checked, if it is nonvisible then only the internally visible types are checked.
+
+The parameter child element is used to customize the behavior of a rule within a dll.
+It has three required attributes: rule, property, and value. rule is the name of the
+applicable rule ("AvoidSmallNamespaceRule"), property is the name of a public
+property in the rule ("Minimum"), value is the value to assign to the property ("10").
+.TP
+.I gendarme.exe.config
+Used by debug versions of Gendarme to enable logging for rules. A config
+file will be generated automatically by the make file. To enable logging
+for a rule edit the config file, add a switch using the rule's name, and set the 
+value to 1.
 .SH ENVIRONMENT VARIABLES
 .TP
 .I GENDARME_COLOR