Man Patch
Jesse Jones
* The semantics of the command line options are (hopefully) clearer.
* The rules.xml section in the man page has been completely rewritten.
* Added an ignore-file section to the man page.
* The earlier commit for the gendarme.exe.config section wasn't
applied properly (the lines started with bogus '+' characters).
-- Jesse
Sebastien Pouliot
>
> Index: console/ConsoleRunner.cs
> ===================================================================
> --- console/ConsoleRunner.cs (revision 140725)
> +++ console/ConsoleRunner.cs (working copy)
> @@ -471,12 +471,12 @@
> {
> 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 rulesets. Default is 'rules.xml'.");
It's more than rule sets since it also contains the configurable
properties (and likely any future rules options). So I think
"configuration" was the right term.
> + Console.WriteLine (" --set ruleset\t\tSpecify a ruleset 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 @@
> 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 ();
> }
> Index: man/gendarme.1.in
> ===================================================================
> --- man/gendarme.1.in (revision 140725)
> +++ man/gendarme.1.in (working copy)
> @@ -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 rulesets. Default is 'rules.xml'.
Same as above. However we can be more explicit and say the file includes
both the rulesets and the rules' configuration.
> .TP
> .I "--set ruleset"
> -Specify the set of rules to verify. Default is '*'.
> +Specify a ruleset 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 @@
> 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.
For "FILES" the actual details (format) for them should be part of (a
new) gendarme(5) - i.e. man 5 gendarme. The names and
(short)descriptions are ok here.
> .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 (rulesets) and each ruleset 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
A "SEE ALSO" section should be added to let people know more information
is available about the data formats (5).
Thanks a lot!
Sebastien
Jesse Jones
Well, I was trying to avoid "configuration" because it's such a
generic term that it doesn't mean a lot. And, this might be just me,
but when I see "configuration file" I think of .NET configuration
files ("gendarme.exe.config") which makes the original language rather
confusing.
I'd rather be poked in the eye with a sharp stick than grapple any
more with groff and automake.
-- Jesse
Sebastien Pouliot
It's already named --config so I guess it won't stop all possible
confusion. In that case we better be more (than less) precise, so what
about "Specify the rules sets and configuration file." ?
Well if that can save you an eye I'll do the split and autofu
adjustments after your commit ;-)
Sebastien
Jesse Jones
I really don't like "configuration file". What about, "Specify the
rule sets and rule settings."?
>
>
>>> For "FILES" the actual details (format) for them should be part of
>>> (a
>>> new) gendarme(5) - i.e. man 5 gendarme. The names and
>>> (short)descriptions are ok here.
>>
>> I'd rather be poked in the eye with a sharp stick than grapple any
>> more with groff and automake.
>
> Well if that can save you an eye I'll do the split and autofu
> adjustments after your commit ;-)
Sorry about that Sebastien, but I have a real aversion to the
autotools...
-- Jesse
Sebastien Pouliot
sounds good
> >
> >
> >>> For "FILES" the actual details (format) for them should be part of
> >>> (a
> >>> new) gendarme(5) - i.e. man 5 gendarme. The names and
> >>> (short)descriptions are ok here.
> >>
> >> I'd rather be poked in the eye with a sharp stick than grapple any
> >> more with groff and automake.
> >
> > Well if that can save you an eye I'll do the split and autofu
> > adjustments after your commit ;-)
>
> Sorry about that Sebastien, but I have a real aversion to the
> autotools...
np, as far as I'm concerned it's in my necessary-evil list ;-)
Sebastien
Sebastien Pouliot
>
> Here's a new patch. It includes the above change and I changed
> instances of "ruleset" in the prose to "rule set".
Looks great, please commit!
Sebastien
Jesse Jones
r141621
"Andrés G. Aragoneses"
>
>>> (...)
>> Well if that can save you an eye I'll do the split and autofu
>> adjustments after your commit ;-)
>
> Sorry about that Sebastien, but I have a real aversion to the
> autotools...
I have a very similar feeling. How about migrating to xbuild?
Andres
PS: I'm not proposing that others work on this, just checking if
"patches would be welcome" in this case ;)
--
Sebastien Pouliot
> Jesse Jones wrote:
> >
> >>> (...)
> >> Well if that can save you an eye I'll do the split and autofu
> >> adjustments after your commit ;-)
> >
> > Sorry about that Sebastien, but I have a real aversion to the
> > autotools...
>
>
> I have a very similar feeling.
I don't like it either but it's (kind of) a necessary evil.
> How about migrating to xbuild?
AFAIK (but never tried) the gendarme[-win32].sln should be usable by
[ms|x]build without additional work.
The real limits to the solutions are (right now):
a) no "make self-test"
b) auto-generated files (versions, man pages)
> Andres
>
>
> PS: I'm not proposing that others work on this, just checking if
> "patches would be welcome" in this case ;)
I'm open to patches :) but keep in mind that this requires Gendarme to
*stay* fully build-able, dist-able and package-able from mono-tools - so
doing this will involve quite a bit of autofu (if only elsewhere)
changes
Sebastien