improved documentation

1 files changed, 73 insertions, 101 deletions

diff --git a/man/pylint.1 b/man/pylint.1
index 7c519be0d..c7459e6a6 100644
--- a/man/pylint.1
+++ b/man/pylint.1
@@ -35,17 +35,7 @@ show this help message and exit
 .SH MASTER
 .IP "--rcfile=<file>"
 Specify a configuration file.
-.IP "--disable-all"
-Disable all possible checkers. This option should precede enable-* options.
-.IP "--help-msg=<msg-id>"
-Display a help message for the given message id and exit. This option may be a comma separated list.
-.IP "--list-msgs"
-List and explain every available messages.
-.IP "--generate-rcfile"
-Generate a sample configuration file according to the current configuration. You can put other options before this one to use them in the configuration. This option causes the program to exit
-.IP "--generate-man"
-Generate a man page for pylint. This option causes the program to exit
-.IP "--debug-mode"
+.IP "--errors-only, -e"
 In debug mode, checkers without error messages are disabled and for others, only the ERROR messages are displayed, and no reports are done by default
 .IP "--profile=<y_or_n>"
 Profiled execution.
@@ -58,97 +48,49 @@ Set the cache size for astng objects.
 .IP "--load-plugins=<modules>"
 List of plugins (as comma separated values of python modules names) to load, usually to register additional checkers.
 
+.SH COMMANDS
+.IP "--help-msg=<msg-id>"
+Display a help message for the given message id and exit. The value may be a comma separated list of message ids.
+.IP "--list-msgs"
+Generate pylint's full documentation.
+.IP "--generate-rcfile"
+Generate a sample configuration file according to the current configuration. You can put other options before this one to get them in the generated configuration.
+.IP "--generate-man"
+Generate pylint's man page.
+
+.SH MESSAGES CONTROL
+.IP "--enable-checker=<checker ids>"
+Enable only checker(s) with the given id(s).                 This option conflict with the disable-checker option
+.IP "--disable-checker=<checker ids>"
+Enable all checker(s) except those with the                  given id(s).                 This option conflict with the disable-checker option
+.IP "--enable-msg-cat=<msg cats>"
+Enable all messages in the listed categories.
+.IP "--disable-msg-cat=<msg cats>"
+Disable all messages in the listed categories.
+.IP "--enable-msg=<msg ids>"
+Enable the message(s) with the given id(s).
+.IP "--disable-msg=<msg ids>"
+Disable the message(s) with the given id(s).
+
 .SH REPORTS
-.IP "--reports=<y_or_n>, -r<y_or_n>"
-Tells wether to display a full report or only the messages
-.IP "--html=<y_or_n>"
-Use HTML as output format instead of text
-.IP "--parseable=<y_or_n>, -p<y_or_n>"
-Use a parseable text output format, so your favorite text editor will be able to jump to the line corresponding to a message.
-.IP "--color=<y_or_n>"
-Colorizes text output using ansi escape codes
+.IP "--output-format=<format>, -f<format>"
+set the output format. Available formats are text,                 parseable, colorized and html
+.IP "--include-ids=<y_or_n>, -i<y_or_n>"
+Include message's id in output
 .IP "--files-output=<y_or_n>"
 Put messages in a separate file for each module / package specified on the command line instead of printing them on stdout. Reports (if any) will be written in a file name "pylint_global.[txt|html]".
+.IP "--reports=<y_or_n>, -r<y_or_n>"
+Tells wether to display a full report or only the messages
 .IP "--evaluation=<python_expression>"
 Python expression which should return a note less than 10 (10 is the highest note).You have access to the variables errors warning, statement which respectivly contain the number of errors / warnings messages and the total number of statements analyzed. This is used by the  global evaluation report (R0004).
 .IP "--comment=<y_or_n>"
 Add a comment according to your evaluation note. This is used by the global evaluation report (R0004).
-.IP "--include-ids=<y_or_n>, -i<y_or_n>"
-Include message's id in output
-.IP "--enable-msg-cat=<msg cats>"
-Enable all messages in the listed categories.
-.IP "--disable-msg-cat=<msg cats>"
-Disable all messages in the listed categories.
-.IP "--enable-msg=<msg ids>"
-Enable the message with the given id.
-.IP "--disable-msg=<msg ids>"
-Disable the message with the given id.
 .IP "--enable-report=<rpt ids>"
-Enable the report with the given id.
+Enable the report(s) with the given id(s).
 .IP "--disable-report=<rpt ids>"
-Disable the report with the given id.
-
-.SH EXCEPTIONS
-.IP "--enable-exceptions=<y_or_n>"
-Enable / disable this checker
-
-.SH VARIABLES
-.IP "--enable-variables=<y_or_n>"
-Enable / disable this checker
-.IP "--init-import=<y_or_n>"
-Tells wether we should check for unused import in __init__ files.
-.IP "--dummy-variables-rgx=<regexp>"
-A regular expression matching names used                  for dummy variables (i.e. not used).
-.IP "--additional-builtins=<comma separated list>"
-List of additional names supposed to be defined in builtins. Remember that you should avoid to define new builtins when possible.
-
-.SH CLASSES
-.IP "--enable-classes=<y_or_n>"
-Enable / disable this checker
-.IP "--ignore-iface-methods=<method names>"
-List of interface methods to ignore, separated by a comma. This is used for instance to not check methods defines in Zope's Interface base class.
-.IP "--defining-attr-methods=<method names>"
-List of method names used to declare (i.e. assign) instance attributes.
-
-.SH IMPORTS
-.IP "--enable-imports=<y_or_n>"
-Enable / disable this checker
-.IP "--deprecated-modules=<modules>"
-Deprecated modules which should not be used, separated by a comma
-.IP "--import-graph=<file.dot>"
-Create a graph of every (i.e. internal and external) dependencies in the given file (report R0402 must not be disabled)
-.IP "--ext-import-graph=<file.dot>"
-Create a graph of external dependencies in the given file (report R0402 must not be disabled)
-.IP "--int-import-graph=<file.dot>"
-Create a graph of internal dependencies in the given file (report R0402 must not be disabled)
-
-.SH TYPECHECK
-.IP "--enable-typecheck=<y_or_n>"
-Enable / disable this checker
-.IP "--ignore-mixin-members=<y_or_n>"
-Tells wether missing members accessed in mixin class should be ignored. A mixin class is detected if its name ends with "mixin" (case insensitive).
-.IP "--zope=<y_or_n>"
-When zope mode is activated, consider the acquired-members option to ignore access to some undefined attributes.
-.IP "--acquired-members=<members names>"
-List of members which are usually get through zope's acquisition mecanism and so shouldn't trigger E0201 when accessed (need zope=yes to be considered.
-
-.SH METRICS
-.IP "--enable-metrics=<y_or_n>"
-Enable / disable this checker
-
-.SH SIMILARITIES
-.IP "--enable-similarities=<y_or_n>"
-Enable / disable this checker
-.IP "--min-similarity-lines=<int>"
-Minimum lines number of a similarity.
-.IP "--ignore-comments=<y or n>"
-Ignore comments when computing similarities.
-.IP "--ignore-docstrings=<y or n>"
-Ignore docstrings when computing similarities.
+Disable the report(s) with the given id(s).
 
 .SH BASIC
-.IP "--enable-basic=<y_or_n>"
-Enable / disable this checker
 .IP "--required-attributes=<attributes>"
 Required attributes for module, separated by a comma
 .IP "--no-docstring-rgx=<regexp>"
@@ -178,13 +120,13 @@ Bad variable names which should always be refused, separated by a comma
 .IP "--bad-functions=<builtin function names>"
 List of builtins function names that should not be used, separated by a comma
 
-.SH NEWSTYLE
-.IP "--enable-newstyle=<y_or_n>"
-Enable / disable this checker
+.SH CLASSES
+.IP "--ignore-iface-methods=<method names>"
+List of interface methods to ignore, separated by a comma. This is used for instance to not check methods defines in Zope's Interface base class.
+.IP "--defining-attr-methods=<method names>"
+List of method names used to declare (i.e. assign) instance attributes.
 
 .SH DESIGN
-.IP "--enable-design=<y_or_n>"
-Enable / disable this checker
 .IP "--max-args=<int>"
 Maximum number of arguments for function / method
 .IP "--max-locals=<int>"
@@ -205,8 +147,6 @@ Minimum number of public methods for a class (see R0903).
 Maximum number of public methods for a class (see R0904).
 
 .SH FORMAT
-.IP "--enable-format=<y_or_n>"
-Enable / disable this checker
 .IP "--max-line-length=<int>"
 Maximum number of characters on a single line.
 .IP "--max-module-lines=<int>"
@@ -214,11 +154,43 @@ Maximum number of lines in a module
 .IP "--indent-string=<string>"
 String used as indentation unit. This is usually "    " (4 spaces) or "\t" (1 tab).
 
+.SH IMPORTS
+.IP "--deprecated-modules=<modules>"
+Deprecated modules which should not be used, separated by a comma
+.IP "--import-graph=<file.dot>"
+Create a graph of every (i.e. internal and external) dependencies in the given file (report R0402 must not be disabled)
+.IP "--ext-import-graph=<file.dot>"
+Create a graph of external dependencies in the given file (report R0402 must not be disabled)
+.IP "--int-import-graph=<file.dot>"
+Create a graph of internal dependencies in the given file (report R0402 must not be disabled)
+
 .SH MISCELLANEOUS
-.IP "--enable-miscellaneous=<y_or_n>"
-Enable / disable this checker
 .IP "--notes=<comma separated values>"
-List of note tags to take in consideration, separated by a comma. Default to FIXME, XXX, TODO
+List of note tags to take in consideration, separated by a comma.
+
+.SH SIMILARITIES
+.IP "--min-similarity-lines=<int>"
+Minimum lines number of a similarity.
+.IP "--ignore-comments=<y or n>"
+Ignore comments when computing similarities.
+.IP "--ignore-docstrings=<y or n>"
+Ignore docstrings when computing similarities.
+
+.SH TYPECHECK
+.IP "--ignore-mixin-members=<y_or_n>"
+Tells wether missing members accessed in mixin class should be ignored. A mixin class is detected if its name ends with "mixin" (case insensitive).
+.IP "--zope=<y_or_n>"
+When zope mode is activated, consider the acquired-members option to ignore access to some undefined attributes.
+.IP "--acquired-members=<members names>"
+List of members which are usually get through zope's acquisition mecanism and so shouldn't trigger E0201 when accessed (need zope=yes to be considered).
+
+.SH VARIABLES
+.IP "--init-import=<y_or_n>"
+Tells wether we should check for unused import in __init__ files.
+.IP "--dummy-variables-rgx=<regexp>"
+A regular expression matching names used                  for dummy variables (i.e. not used).
+.IP "--additional-builtins=<comma separated list>"
+List of additional names supposed to be defined in builtins. Remember that you should avoid to define new builtins when possible.
 
 .SH ENVIRONMENT VARIABLES