improved documentation

1 files changed, 20 insertions, 23 deletions

diff --git a/doc/manual.txt b/doc/manual.txt
index bad0be1a1..40ca62491 100644
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -52,6 +52,10 @@ Last but not least, the code is given an overall mark, based on the
 number an severity of the warnings and errors. This has proven to
 be very motivating for programmers.
 
+.. _pychecker: http://pychecker.sf.net
+.. _`PEP 008`: http://www.python.org/dev/peps/pep-0008/
+.. _`Guido's style guide`: http://www.python.org/doc/essays/styleguide.html
+.. _`refactoring book`: http://www.refactoring.com/
 
 Installation
 ------------
@@ -101,7 +105,7 @@ Note for Windows users
 On Windows, once you have installed pylint, the command line usage is
 ::
 
-pylint.bat [options] module_or_package
+  pylint.bat [options] module_or_package
 
 But this will only work if *pylint.bat* is either in the current
 directory, or on your system path. (*setup.py* install install *python.bat*
@@ -284,8 +288,8 @@ Other useful global options include:
 
 --zope                  Initialize Zope products before starting
 --ignore=file           Add <file> (may be a directory) to the black
-                        list. It should be a base name, not a path. 
-                        You may set this option multiple times.
+                          list. It should be a base name, not a path. 
+                          You may set this option multiple times.
 --statistics=y_or_n     Compute statistics on collected data.
 --persistent=y_or_n     Pickle collected data for later comparisons.
 --comment=y_or_n        Add a comment according to your evaluation note.
@@ -295,16 +299,9 @@ Other useful global options include:
 --disable-msg=msgids    Disable the given messages.
 --enable-msg-cat=cats   Enable all messages in the given categories.
 --disable-msg-cat=cats  Disable all messages in the given categories.
+--errors-only           Enable only checkers from the error category.
 
---errors-only option     This option will kindof
-"optimize" pylint execution to only look for bugs (ie messages in the
-ERROR category). In this execution mode, only relevant checkers are 
-enabled, so it should go quickly than in "regular" mode (remember that
-disabling a message is only preventing it from being printed, but the
-analyzis work is still done). So if you're only searching for possible
-bug in your project, remember to "pylint --errors-only myproject".
-This option has originaly been named "debug-mode".
-
+.. _features: features.html
 
 Bug reports
 -----------
@@ -343,7 +340,9 @@ Environment
 
 Messages control
 ----------------
-::
+
+An example available from the examples directory::
+
     """pylint option block-disable-msg"""
 
     __revision__ = None
@@ -439,9 +438,13 @@ About analysis
 Pylint heuristics
 -----------------
 
+To be written...
+
 About astng inference
 ---------------------
 
+To be written...
+
 Enhancing Pylint
 ================
 
@@ -477,7 +480,7 @@ documentation, it should be clear and well documented. Don't hesitate to
 ask for any information on the python-projects mailing list.
 
 .. _`compiler package`: http://python.org/doc/current/lib/module-compiler.html
-.._ `compiler.ast documentation`: http://www.python.org/doc/current/lib/module-compiler.ast.html
+.. _`compiler.ast documentation`: http://www.python.org/doc/current/lib/module-compiler.ast.html
 
 
 Contribute !
@@ -500,7 +503,7 @@ Pylint is integrated in the following editors/IDEs:
 To use pylint from within vim, see
 http://www.gonzo.kiev.ua/projects/pylint.vim 
 
-_pydev: http://pydev.sourceforge.net
+.. _pydev: http://pydev.sourceforge.net
 
 
 Some projects using Pylint
@@ -531,15 +534,9 @@ analyze the source code.
 .. _CheeseCake: http://cheesecake.sourceforge.net/
 
 
-FAQ
-===
-.. include FAX.txt
+
+.. include:: FAQ.txt
 
 
 
-.. _pychecker: http://pychecker.sf.net
-.. _features: features.html
-.. _`PEP 08`: http://www.python.org/dev/peps/pep-0008/
-.. _`Guido's style guide`: http://www.python.org/doc/essays/styleguide.html
-.. _`refactoring book`: http://www.refactoring.com/