included Robert Kirkpatrick's tutorial and typos fixes

7 files changed, 444 insertions, 66 deletions

diff --git a/doc/FAQ.txt b/doc/FAQ.txt
index 3789a48..f8eb869 100644
--- a/doc/FAQ.txt
+++ b/doc/FAQ.txt
@@ -71,7 +71,7 @@ Answer:
 
 
 Question:
-  When pylint is considering a class as an interface ?
+  When is pylint considering a class as an interface ?
 
 Answer:
   A class is considered as an interface if there is a class named
@@ -80,7 +80,7 @@ Answer:
 
 
 Question:
-  When pylint is considering that a class is implementing a given
+  When is pylint considering that a class is implementing a given
   interface ?
 
 Answer:
@@ -91,7 +91,7 @@ Answer:
 
 
 Question:
-  When pylint is considering a class as an abstract class ?
+  When is pylint considering a class as an abstract class ?
 
 Answer:
   A class is considered as an abstract class if at least one of its
@@ -114,7 +114,7 @@ Answer:
 
 
 Question:
-  I've a mixin class relying on attributes of the mixed class, and I
+  I have a mixin class relying on attributes of the mixed class, and I
   would like to not have the "access to undefined member" message on
   this class. Is it possible ?
 
@@ -126,8 +126,9 @@ Answer:
 
 
 Question:
-  Is it possible to locally disabling a particular message for a block
+  Is it possible to locally disable a particular message for a block
   of code or for a single line of code ?
+  
 Answer:
   Yes, this feature has been added in pylint 0.11. This may be done by
   adding "#pylint: disable-msg=W0123,E4567" at the desired block level
@@ -136,8 +137,8 @@ Answer:
 
 
 Question:
-  Where are stored persistent data necessary to make comparison between
-   to successive run ?
+  Where is the persistent data stored to make comparison between
+   two successive runs ?
 
 Answer:
   Analysis data are stored as pickle file in a directory which is 
@@ -158,7 +159,7 @@ Question:
 
 Answer:
   You can always generate a sample pylintrc file with --generate-rcfile
-  Every options present on the command line before this will be included in
+  Every option present on the command line before this will be included in
   the rc file
   
   For example::
diff --git a/doc/beginner_pylint_tutorial.txt b/doc/beginner_pylint_tutorial.txt
new file mode 100644
index 0000000..20875d5
--- /dev/null
+++ b/doc/beginner_pylint_tutorial.txt
@@ -0,0 +1,376 @@
+================================================================
+A Beginner's Guide to Code Standards in Python - Pylint Tutorial
+================================================================
+
+:Author: Robert Kirkpatrick
+
+For a detailed description of Pylint, see http://www.logilab.org/project/pylint.
+
+
+Intro
+-----
+
+Beginner to coding standards?  Pylint can be your guide to reveal what's really 
+going on behind the scenes and help you to become a more aware programmer.
+
+Sharing code is a rewarding endeavor.  Putting your code 'out there' can be 
+either an act of philanthropy, 'coming of age', or a basic extension of belief 
+in open source.  Whatever the motivation, your good intentions may not have the 
+desired outcome if people find your code hard to use or understand.  The Python
+community has formalized some recommended programming styles to help everyone 
+write code in a common, agreed-upon style that makes the most sense for shared 
+code.  This style is captured in PEP-8.  Pylint can be a quick and easy way of 
+seeing if your code has captured the essence of PEP-8 and is therefore 
+'friendly' to other potential users.
+
+Perhaps you're not ready to share your code but you'd like to learn a bit more
+about writing better code and don't know where to start.  Pylint can tell you 
+where you may have run astray and point you in the direction to figure out what
+you have done and how to do better.
+
+This tutorial is all about approaching coding standards with little or no 
+knowledge of in-depth programming or the code standards themselves.  It's the 
+equivalent of skipping the manual and jumping right in.
+
+My command line prompt for these examples is: ::
+
+  robertk01 Desktop$
+
+Getting Started
+---------------
+
+Running Pylint with no arguments will invoke the help dialogue and give you a
+idea of the arguments available to you.  Do that now, i.e.:  ::
+
+
+  robertk01 Desktop$ pylint
+  ...
+  a bunch of stuff
+  ...
+
+
+A couple of the options that we'll focus on here are: ::
+
+  Master:
+    --rcfile=<file>
+  Commands:
+    --help-msg=<msg-id>
+  Commands:
+    --help-msg=<msg-id>
+  Message control:
+    --disable-msg=<msg-ids>
+  Reports:
+    --files-output=<y_or_n>
+    --reports=<y_or_n>
+    --include-ids=<y_or_n>
+    --output-format=<format>
+
+Also pay attention to the last bit of help output.  This gives you a hint of what
+Pylint is going to 'pick on': ::
+
+  Output:
+     Using the default text output, the message format is :
+    MESSAGE_TYPE: LINE_NUM:[OBJECT:] MESSAGE
+    There are 5 kind of message types :
+    * (C) convention, for programming standard violation
+    * (R) refactor, for bad code smell
+    * (W) warning, for python specific problems
+    * (E) error, for much probably bugs in the code
+    * (F) fatal, if an error occured which prevented pylint from doing
+    further processing.
+
+When Pylint is first run on a fresh piece of code, a common complaint is that it
+is too 'noisy'.  The current default configuration is set to enforce all possible
+warnings.  We'll use some of the options I noted above to make it suit your 
+preferences a bit better (and thus make it 'scream only when needed').
+
+
+Your First Pylint'ing
+---------------------
+
+We'll use a basic python script as fodder for our tutorial.  I borrowed 
+extensively from the code here: http://www.daniweb.com/code/snippet748.html
+The starting code we will use is called simplecaeser.py and is here in it's 
+entirety: ::
+
+   1  #!/usr/bin/env python
+   2  
+   3  import string
+   4  
+   5  shift = 3
+   6  choice = raw_input("would you like to encode or decode?")
+   7  word = (raw_input("Please enter text"))
+   8  letters = string.ascii_letters + string.punctuation + string.digits
+   9  encoded = ''
+  10  if choice == "encode":
+  11      for letter in word:
+  12          if letter == ' ':
+  13              encoded = encoded + ' '
+  14          else:
+  15              x = letters.index(letter) + shift
+  16              encoded=encoded + letters[x]
+  17  if choice == "decode":
+  18      for letter in word:
+  19          if letter == ' ':
+  20              encoded = encoded + ' '
+  21          else:
+  22              x = letters.index(letter) - shift
+  23              encoded = encoded + letters[x]
+  24  
+  25  print encoded
+
+
+Let's get started.
+
+If we run this: ::
+
+  robertk01 Desktop$ pylint simplecaeser.py 
+  No config file found, using default configuration
+  ************* Module simplecaeser
+  C:  1: Missing docstring
+  W:  3: Uses of a deprecated module 'string'
+  C:  5: Invalid name "shift" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C:  6: Invalid name "choice" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C:  7: Invalid name "word" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C:  8: Invalid name "letters" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C:  9: Invalid name "encoded" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C: 16: Operator not preceded by a space
+              encoded=encoded + letters[x]
+                   ^
+
+
+  Report
+  ======
+  19 statements analysed.
+
+  Duplication
+  -----------
+
+  +-------------------------+------+---------+-----------+
+  |                         |now   |previous |difference |
+  +=========================+======+=========+===========+
+  |nb duplicated lines      |0     |0        |=          |
+  +-------------------------+------+---------+-----------+
+  |percent duplicated lines |0.000 |0.000    |=          |
+  +-------------------------+------+---------+-----------+
+
+
+
+  Raw metrics
+  -----------
+
+  +----------+-------+------+---------+-----------+
+  |type      |number |%     |previous |difference |
+  +==========+=======+======+=========+===========+
+  |code      |21     |87.50 |21       |=          |
+  +----------+-------+------+---------+-----------+
+  |docstring |0      |0.00  |0        |=          |
+  +----------+-------+------+---------+-----------+
+  |comment   |1      |4.17  |1        |=          |
+  +----------+-------+------+---------+-----------+
+  |empty     |2      |8.33  |2        |=          |
+  +----------+-------+------+---------+-----------+
+
+
+
+  Statistics by type
+  ------------------
+
+  +---------+-------+-----------+-----------+------------+---------+
+  |type     |number |old number |difference |%documented |%badname |
+  +=========+=======+===========+===========+============+=========+
+  |module   |1      |1          |=          |0.00        |0.00     |
+  +---------+-------+-----------+-----------+------------+---------+
+  |class    |0      |0          |=          |0.00        |0.00     |
+  +---------+-------+-----------+-----------+------------+---------+
+  |method   |0      |0          |=          |0.00        |0.00     |
+  +---------+-------+-----------+-----------+------------+---------+
+  |function |0      |0          |=          |0.00        |0.00     |
+  +---------+-------+-----------+-----------+------------+---------+
+
+
+
+  Messages by category
+  --------------------
+
+  +-----------+-------+---------+-----------+
+  |type       |number |previous |difference |
+  +===========+=======+=========+===========+
+  |convention |7      |7        |=          |
+  +-----------+-------+---------+-----------+
+  |refactor   |0      |0        |=          |
+  +-----------+-------+---------+-----------+
+  |warning    |1      |1        |=          |
+  +-----------+-------+---------+-----------+
+  |error      |0      |0        |=          |
+  +-----------+-------+---------+-----------+
+
+
+
+  Messages
+  --------
+
+  +-----------+-----------+
+  |message id |occurences |
+  +===========+===========+
+  |C0103      |5          |
+  +-----------+-----------+
+  |W0402      |1          |
+  +-----------+-----------+
+  |C0322      |1          |
+  +-----------+-----------+
+  |C0111      |1          |
+  +-----------+-----------+
+
+
+
+  Global evaluation
+  -----------------
+  Your code has been rated at 5.79/10
+
+
+Wow.  That's a lot of stuff.  The first part is the 'messages' section while the
+second part is the 'report' section.  There are two points I want to tackle here.
+
+First point is that all the tables of statistics (i.e. the report) are a bit 
+overwhelming so I want to silence them.  To do that, I will use the "--reports=n" option.
+
+Second, previous experience taught me that the default output for the messages 
+needed a bit more info.  We can see the first line is: ::
+
+  "C:  1: Missing docstring"
+
+This basically means that line 1 violates a convention 'C'.  It's telling me I 
+really should have a docstring.  I agree, but what if I didn't fully understand
+what rule I violated.  Knowing only that I violated a convention isn't much help
+if I'm a newbie.  So let's turn on a bit more info by using the option 
+"--include-ids=y".
+
+Let's do it again! ::
+
+  robertk01 Desktop$ pylint --reports=n --include-ids=y simplecaeser.py 
+  No config file found, using default configuration
+  ************* Module simplecaeser
+  C0111:  1: Missing docstring
+  W0402:  3: Uses of a deprecated module 'string'
+  C0103:  5: Invalid name "shift" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C0103:  6: Invalid name "choice" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C0103:  7: Invalid name "word" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C0103:  8: Invalid name "letters" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C0103:  9: Invalid name "encoded" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C0322: 16: Operator not preceded by a space
+              encoded=encoded + letters[x]
+
+Oooh.  I like that better.  Now I know that I violated the convention number 
+C0111 and now I can read up a bit more about that.  Let's go back to the 
+command line and try this: ::
+
+  robertk01 Desktop$ pylint --help-msg=C0111
+  No config file found, using default configuration
+  :C0111: *Missing docstring*
+    Used when a module, function, class or method has no docstring. Some special
+    methods like __init__ doesn't necessary require a docstring. This message 
+    belongs to the basic checker.
+
+Yeah, ok.  That one was a bit of a no-brainer but I have run into error messages
+that left me with no clue about what went wrong, simply because I was unfamiliar
+with the underlying mechanism of code theory.  One error that puzzled my newbie 
+mind was: ::
+
+  :R0902: *Too many instance attributes (%s/%s)*
+
+I get it now thanks to Pylint pointing it out to me.  If you don't get that one,
+pour a fresh cup of coffee and look into it - let your programmer mind grow!
+
+
+The Next Step
+-------------
+
+Now that we got some configuration stuff out of the way, let's see what we can 
+do with the remaining warnings.
+
+If we add a docstring to describe what the code is meant to do that will help.  
+I'm also going to be a bit cowboy and ignore the W0402 message because I like to
+take risks in life.  A deprecation warning means that future versions of Python
+may not support that code so my code may break in the future.  There are 5 C0103
+messages that we will get to later.  Lastly, I violated the convention of using
+spaces around an operator such as "=" so I'll fix that too.  To sum up, I'll add
+a docstring to line 2, put spaces around the = sign on line 16 and use the 
+"--disable-msg=W0402" to ignore the deprecation warning.
+
+Here's the updated code: ::
+
+   1  #!/usr/bin/env python
+   2  """This script prompts a user to enter a messsage to encode or decode
+   3  using a classic Caeser shift substitution (3 letter shift)"""
+   4  
+   5  import string
+   6  
+   7  shift = 3
+   8  choice = raw_input("would you like to encode or decode?")
+   9  word = (raw_input("Please enter text"))
+  10  letters = string.ascii_letters + string.punctuation + string.digits
+  11  encoded = ''
+  12  if choice == "encode":
+  13      for letter in word:
+  14          if letter == ' ':
+  15              encoded = encoded + ' '
+  16          else:
+  17              x = letters.index(letter) + shift
+  18              encoded = encoded + letters[x]
+  19  if choice == "decode":
+  20      for letter in word:
+  21          if letter == ' ':
+  22              encoded = encoded + ' '
+  23          else:
+  24              x = letters.index(letter) - shift
+  25              encoded = encoded + letters[x]
+  26  
+  27  print encoded
+
+And here's what happens when we run it with our --disable-msg=W0402 option: ::
+
+  robertk01 Desktop$ pylint --reports=n --include-ids=y --disable-msg=W0402 simplecaeser.py 
+  No config file found, using default configuration
+  ************* Module simplecaeser
+  C0103:  7: Invalid name "shift" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C0103:  8: Invalid name "choice" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C0103:  9: Invalid name "word" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C0103: 10: Invalid name "letters" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+  C0103: 11: Invalid name "encoded" (should match (([A-Z_][A-Z1-9_]*)|(__.*__))$)
+
+Nice!  We're down to just the C0103 messages.  
+
+There are fairly well defined conventions around naming things like instance 
+variables, functions, classes, etc.  The conventions focus on the use of 
+UPPERCASE and lowercase as well as the characters that separate multiple words 
+in the name.  This lends itself well to checking via a regular expression, thus 
+the "should match (([A-Z\_][A-Z1-9\_]*)|(__.*__))$".
+
+In this case Pylint is telling me that those variables appear to be constants 
+and should be all UPPERCASE.  This rule is in fact a naming convention that is
+specific to the folks at Logilab who created Pylint.  That is the way they have
+chosen to name those variables.  You too can create your own in-house naming
+conventions but for the purpose of this tutorial, we want to stick to the PEP-8
+standard.  In this case, the variables I declared should follow the convention
+of all lowercase.  The appropriate rule would be something like:
+"should match [a-z\_][a-z0-9\_]{2,30}$".  Notice the lowercase letters in the 
+regular expression (a-z versus A-Z).
+
+If we run that rule using a --const-rgx='[a-z\_][a-z0-9\_]{2,30}$' option, it 
+will now be quite quiet: ::
+
+  robertk01 Desktop$ pylint --reports=n --include-ids=y --disable-msg=W0402 --const-rgx='[a-z_][a-z0-9_]{2,30}$'  simplecaeser.py 
+  No config file found, using default configuration
+
+Regular expressions can be quite a beast so take my word on this particular 
+example but go ahead and read up on them if you want.
+
+It would really be a pain in the butt to have to use all these options on the 
+command line all the time.  That's what the rc file is for.  We can configure
+our Pylint to store our options for us so we don't have to declare them on the 
+command line.  Using the rc file is a nice way of formalizing your rules and 
+quickly sharing them with others and/or forcing your style on them.  Go ahead, 
+conquer the standards world by spreading your rc file...I dare you.
+
+That's it for the basic intro.  More tutorials will follow.
diff --git a/doc/features.txt b/doc/features.txt
index bb6dbe5..a0cdd30 100644
--- a/doc/features.txt
+++ b/doc/features.txt
@@ -20,7 +20,7 @@ General options
 :ignore:
   Add <file or directory> to the black list. It should be a base name, not a
   path. You may set this option multiple times.
-  Default: CVS
+  Default: CSV
 :persistent:
   Pickle collected data for later comparisons.
   Default: yes
@@ -225,7 +225,7 @@ Messages
   Used when a statement is endend by a semi-colon (";"), which isn't necessary
   (that's python, not C ;).
 :W0107: *Unnecessary pass statement*
-  Used when a "pass" statement that can be avoided is encountered.)
+  Used when a "pass" statement that can be avoided is encountered.
 :W0122: *Use of the exec statement*
   Used when you use the "exec" statement, to discourage its usage. That doesn't
   mean you can not use it !
@@ -274,24 +274,24 @@ Options
   When zope mode is activated, consider the acquired-members option to ignore
   access to some undefined attributes.
 :acquired-members:
-  List of members which are usually get through zope's acquisition mecanism and
+  List of members which usually get through zope's acquisition mecanism and
   so shouldn't trigger E0201 when accessed (need zope=yes to be considered).
   Default: REQUEST,acl_users,aq_parent
 
 Messages
 ~~~~~~~~
 :E1101: *%s %r has no %r member*
-  Used when a variable is accessed for an unexistant member.
+  Used when a variable is accessed for an nonexistent member.
 :E1102: *%s is not callable*
-  Used when an object being called has been infered to a non callable object
+  Used when an object being called has been inferred to a non callable object
 :E1103: *%s %r has no %r member (but some types could not be inferred)*
-  Used when a variable is accessed for an unexistant member, but astng was not
+  Used when a variable is accessed for an nonexistent member, but astng was not
   able to interpret all possible types of this variable.
 :E1111: *Assigning to function call which doesn't return*
-  Used when an assigment is done on a function call but the infered function
+  Used when an assigment is done on a function call but the inferred function
   doesn't return anything.
 :W1111: *Assigning to function call which only returns None*
-  Used when an assigment is done on a function call but the infered function
+  Used when an assigment is done on a function call but the inferred function
   returns nothing but None.
 
 
@@ -312,12 +312,12 @@ Options
   Default: _|dummy
 :additional-builtins:
   List of additional names supposed to be defined in builtins. Remember that
-  you should avoid to define new builtins when possible.
+  you should avoid defining new builtins when possible.
 
 Messages
 ~~~~~~~~
 :E0601: *Using variable %r before assignment*
-  Used when a local variable is accessed before it's assignment.
+  Used when a local variable is accessed before its assignment.
 :E0602: *Undefined variable %r*
   Used when an undefined variable is accessed.
 :E0611: *No name %r in module %r*
@@ -327,13 +327,13 @@ Messages
   variable is not defined in the module scope.
 :W0602: *Using global for %r but no assigment is done*
   Used when a variable is defined through the "global" statement but no
-  assigment to this variable is done.
+  assignment to this variable is done.
 :W0603: *Using the global statement*
   Used when you use the "global" statement to update a global variable. PyLint
-  just try to discourage this usage. That doesn't mean you can not use it !
+  just tries to discourage this usage. That doesn't mean you can not use it !
 :W0604: *Using the global statement at the module level*
   Used when you use the "global" statement at the module level since it has no
-  effect
+  effect.
 :W0611: *Unused import %s*
   Used when an imported module or variable is not used.
 :W0612: *Unused variable %r*
@@ -344,11 +344,11 @@ Messages
   Used when an imported module or variable is not used from a 'from X import *'
   style import.
 :W0621: *Redefining name %r from outer scope (line %s)*
-  Used when a variable's name hide a name defined in the outer scope.
+  Used when a variable's name hides a name defined in the outer scope.
 :W0622: *Redefining built-in %r*
-  Used when a variable or function override a built-in.
+  Used when a variable or function overrides a built-in.
 :W0631: *Using possibly undefined loop variable %r*
-  Used when an loop variable (i.e. defined by a for loop or a list comprehension
+  Used when a loop variable (i.e. defined by a for loop or a list comprehension
   or a generator expression) is used outside the loop.
 
 
@@ -434,7 +434,7 @@ Classes checker
 checks for :
 * methods without self as first argument
 * overridden methods signature
-* access only to existant members via self
+* access only to existent members via self
 * attributes not defined in the __init__ method
 * supported interfaces implementation
 * unreachable code
@@ -443,7 +443,7 @@ Options
 ~~~~~~~
 :ignore-iface-methods:
   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.
+  instance to not check methods defined in Zope's Interface base class.
   Default: isImplementedBy,deferred,extends,names,namesAndDescriptions,queryDescriptionFor,getBases,getDescriptionFor,getDoc,getName,getTaggedValue,getTaggedValueTags,isEqualOrExtendedBy,setTaggedValue,isImplementedByInstancesOf,adaptWith,is_implemented_by
 :defining-attr-methods:
   List of method names used to declare (i.e. assign) instance attributes.
@@ -451,7 +451,7 @@ Options
 
 Messages
 ~~~~~~~~
-:E0202: *An attribute inherited from %s hide this method*
+:E0202: *An attribute inherited from %s hides this method*
   Used when a class defines a method which is hiden by an instance attribute
   from an ancestor class.
 :E0203: *Access to member %r before its definition line %s*
@@ -460,14 +460,14 @@ Messages
   Used when a method which should have the bound instance as first argument has
   no argument defined.
 :E0213: *Method should have "self" as first argument*
-  Used when a method has an attribute different the "self" as first argument.
-  This is considered as an error since this is a soooo common convention that
-  you should'nt break it!
+  Used when a method has an attribute other than "self" as first argument.
+  This is considered an error since this is a soooo common convention that
+  you shouldn't break it!
 :E0221: *Interface resolved to %s is not a class*
   Used when a class claims to implement an interface which is not a class.
 :E0222: *Missing method %r from %s interface*
   Used when a method declared in an interface is missing from a class
-  implementing this interface
+  implementing this interface.
 :W0201: *Attribute %r defined outside __init__*
   Used when an instance attribute is defined outside the __init__ method.
 :W0211: *Static method with %r as first argument*
@@ -500,13 +500,13 @@ Messages
   Used when a class method has an attribute different than "cls" as first
   argument, to easily differentiate them from regular instance methods.
 :C0203: *Metaclass method should have "mcs" as first argument*
-  Used when a metaclass method has an attribute different the "mcs" as first
+  Used when a metaclass method has an attribute different than "mcs" as first
   argument.
 :F0202: *Unable to check methods signature (%s / %s)*
   Used when PyLint has been unable to check methods signature compatibility for
-  an unexpected raison. Please report this kind if you don't make sense of it.
+  an unexpected reason. Please report this kind if you don't make sense of it.
 :F0220: *failed to resolve interfaces implemented by %s (%s)*
-  Used when a PyLint as failed to find interfaces implemented by a class
+  Used when PyLint has failed to find interfaces implemented by a class
 
 
 Design checker
@@ -527,7 +527,7 @@ Options
   Maximum number of return / yield for function / method body
   Default: 6
 :max-branchs:
-  Maximum number of branch for function / method body
+  Maximum number of branches for function / method body
   Default: 12
 :max-statements:
   Maximum number of statements in function / method body
@@ -559,7 +559,7 @@ Messages
   Used when class has too many public methods, try to reduce this to get a more
   simple (and so easier to use) class.
 :R0911: *Too many return statements (%s/%s)*
-  Used when a function or method has too many return statement, making it hard
+  Used when a function or method has too many return statements, making it hard
   to follow.
 :R0912: *Too many branches (%s/%s)*
   Used when a function or method has too many branches, making it hard to
@@ -692,7 +692,7 @@ Options
   Maximum number of characters on a single line.
   Default: 80
 :max-module-lines:
-  Maximum number of lines in a module
+  Maximum number of lines in a module.
   Default: 1000
 :indent-string:
   String used as indentation unit. This is usually " " (4 spaces) or "\t" (1
diff --git a/doc/makefile b/doc/makefile
index 2e19479..cf99023 100644
--- a/doc/makefile
+++ b/doc/makefile
@@ -15,6 +15,9 @@ quickstart.html: ${SRC}/quickstart.txt
 manual.html: ${SRC}/manual.txt
 	${MKHTML} ${MKHTML_OPT} ${SRC}/manual.txt
 
+beginner_pylint_tutorial.html: ${SRC}/beginner_pylint_tutorial.txt
+	${MKHTML} ${MKHTML_OPT} ${SRC}/beginner_pylint_tutorial.txt
+
 features.html:
 	chmod u+w ${SRC}/features.txt
 	echo "PyLint features" > ${SRC}/features.txt
diff --git a/doc/manual.txt b/doc/manual.txt
index 6e8dad3..2a3a45b 100644
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -25,18 +25,18 @@ What is pylint?
 ---------------
 
 Pylint is a tool that checks for errors in python code, tries to enforce a
-coding standard and looks for smelling code . This is similar but nevertheless
+coding standard and looks for smelling code. This is similar but nevertheless
 different from what pychecker_ provides, especially since pychecker explicitely
 does not bother with coding style. The default coding style used by pylint is
 close to `PEP 008`_ (aka `Guido's style guide`_). For more information about
 code smells, refer to Martin Fowler's `refactoring book`_
 
 One important thing to note is that Pylint isn't smarter than you are: it may
-warn you about things that you have consciensiously done. That's for example
+warn you about things that you have conscientiously done. That's for example
 because it tries to detect things that may be dangerous in a context, but maybe
 not in others, or because it checks for some things that you don't care
-about. Generally, you shouldn't expect to be pylint totally quiet about your
-code, so don't necessarily be alarmed if it give you a hell lot of messages for
+about. Generally, you shouldn't expect pylint to be totally quiet about your
+code, so don't necessarily be alarmed if it gives you a hell lot of messages for
 your proudly(XXX) project ;)
 
 Pylint will display a number of messages as it analyzes the code, as well as
@@ -147,7 +147,7 @@ directory on your system -- e.g. C:\Python24\Scripts\pylint.bat).
 Invoking pylint
 ---------------
 
-Pylint is meant to be called from the commant line. The usage is ::
+Pylint is meant to be called from the command line. The usage is ::
 
    pylint [options] module_or_package
 
@@ -163,8 +163,8 @@ the file if it succeeds.  ::
 
   pylint mymodule.py 
 
-should always works since the current working
-directory is automatically added on top  of the python path ::
+should always work since the current working
+directory is automatically added on top of the python path ::
 
   pylint directory/mymodule.py
 
@@ -234,13 +234,12 @@ Example (extracted from a run of pylint on itself...):
 
 Reports section
 ''''''''''''''' 
-Following the analysis message, pylint will display a set of report,
+Following the analysis message, pylint will display a set of reports,
 each one focusing on a particular aspect of the project, such as number
 of messages by categories, modules dependancies...
 
 For instance, the metrics report displays summaries gathered from the
-current 
-run. 
+current run. 
 
   * the number of processed modules
   * for each module, the percentage of errors and warnings
@@ -248,7 +247,7 @@ run.
   * percentage of classes, functions and modules with docstrings, and
     a comparison from the previous run 
   * percentage of classes, functions and modules with correct name
-  * (according the the coding standard), and a comparison from the
+    (according the the coding standard), and a comparison from the
     previous run 
   * a list of external dependencies found in the code, and where they appear
 
@@ -315,9 +314,9 @@ python makes it hard enough, it is not the case for warnings.
 :Quoting Alexandre:
   My usage pattern for pylint is to generally run pylint -e quite often to
   get stupid errors flagged before launching an application (or before
-  comitting). I generally run pyling whith the whole bells and whistles
+  comitting). I generally run pylint with all the bells and whistles
   activated some time before a release, when I want to cleanup the code.
-  And when I do that I simply ignore tons all the false warnings (and I
+  And when I do that I simply ignore tons of the false warnings (and I
   can do that without being driven mad by this dumb program which is not
   smart enough to understand the dynamicity of Python because I only run
   it once or twice a week in this mode)
@@ -356,7 +355,7 @@ lists.
 You can check for already reported bugs, planned features on pylint's tracker
 web page: http://www.logilab.org/project/name/pylint
 
-Notice that if you don't find something you have expected in the pylint's
+Notice that if you don't find something you have expected in pylint's
 tracker page, it may be on the tracker page of one of its dependancies, namely
 astng and common:
 
@@ -368,7 +367,7 @@ astng and common:
 Mailing lists
 -------------
 Use the python-projects@logilab.org mailing list for anything related
-to Pylint. This is in most case better than sending an email directly
+to Pylint. This is in most cases better than sending an email directly
 to the author, since others will benefit from the exchange, and you'll
 be more likely answered by someone subscribed to the list. This is a 
 moderated mailing list, so if you're not subscribed email you send will have to
@@ -521,9 +520,9 @@ Writing your own checker
 ------------------------
 You can find some simple examples in the examples
 directory of the distribution (custom.py and custom_raw.py). I'll try to
-quickly explain the essential here.
+quickly explain the essentials here.
 
-First, there is two kinds of checker :
+First, there are two kinds of checkers :
 * raw checkers, which are analysing each module as a raw file stream
 * ast checkers, which are working on an ast representation of the module
 
@@ -532,7 +531,7 @@ standard python distribution in the `compiler package`_. The extension
 adds additional information and methods on the tree nodes to ease
 navigation and code introspection.
 
-An AST checker is a visitor, and should implements
+An AST checker is a visitor, and should implement
 visit_<lowered class name>
 leave_<lowered class name>
 methods for the nodes it's interested in. To get description of the different
@@ -554,7 +553,7 @@ ask for any information on the python-projects mailing list.
 
 Contribute !
 ------------
-All our softwares are developped using the mercurial_ version control
+All our software is developped using the mercurial_ version control
 system. This is a very cool distributed vcs and its usage is very similar to
 other ones such as cvs or subversion (though the distributed feature introduced
 some different usage patterns). See mercurial home page for installation on
diff --git a/doc/quickstart.txt b/doc/quickstart.txt
index 042d377..82de686 100644
--- a/doc/quickstart.txt
+++ b/doc/quickstart.txt
@@ -21,7 +21,7 @@ What is pylint?
 Pylint is a tool that checks for errors in python code, tries to
 enforce a coding standard and looks for smelling code . This is
 similar but nevertheless different from what pychecker_ provides,
-especially since pychecker explicitely does not bother with coding
+especially since pychecker explicitly does not bother with coding
 style. The default coding style used by pylint is close to 
 `Guido's style guide`_. For more information about code smells, refer
 to Martin Fowler's `refactoring book`_
@@ -41,7 +41,7 @@ be very motivating for programmers.
 Invoking pylint
 ---------------
 
-Pylint is meant to be called from the commant line. The usage is ::
+Pylint is meant to be called from the command line. The usage is ::
 
    pylint [options] module_or_package
 
@@ -51,7 +51,7 @@ your ``PYTHONPATH``, since it is a common error to analyze an
 installed version of a module instead of the development version.
 
 It is also possible to analyze python files, with a few
-restriction. The thing to keep in mind is that pylint will try to 
+restrictions. The thing to keep in mind is that pylint will try to 
 convert the file name to a module name, and only be able to process
 the file if it succeeds.  ::
 
@@ -130,13 +130,12 @@ Example (extracted from a run of pylint on itself...):
 Reports section
 ''''''''''''''' 
 
-Following the analysis message, pylint will display a set of report,
+Following the analysis message, pylint will display a set of reports,
 each one focusing on a particular aspect of the project, such as number
 of messages by categories, modules dependancies...
 
 For instance, the metrics report displays summaries gathered from the
-current 
-run. 
+current run. 
 
   * the number of processed modules
   * for each module, the percentage of errors and warnings
@@ -144,7 +143,7 @@ run.
   * percentage of classes, functions and modules with docstrings, and
     a comparison from the previous run 
   * percentage of classes, functions and modules with correct name
-  * (according the the coding standard), and a comparison from the
+    (according the the coding standard), and a comparison from the
     previous run 
   * a list of external dependencies found in the code, and where they appear
 
diff --git a/doc/rpython.txt b/doc/rpython.txt
index cba843d..218f854 100644
--- a/doc/rpython.txt
+++ b/doc/rpython.txt
@@ -8,7 +8,7 @@ It contains the following checks:
 * global modification
 * negative slice index
 * using %r in format string
-* warn about special method that are not implicitly called
+* warn about special methods that are not implicitly called
 
 By default the rpython checker is deactivated. Activate it using :
 
@@ -18,11 +18,11 @@ By default the rpython checker is deactivated. Activate it using :
 
   pylint --enable-checker=rpython ...
 
-to get only rpython checks (though in this case you won't be warn about
+to get only rpython checks (though in this case you won't be warned about
 regular errors).
 
 Another interesting thing is the rpython dedicated testing framework,
-testing that checked things are actually not translatable. I've the idea
+testing that checked things are actually not translatable. I have the idea
 that this may be useful to generate some kind of documentation for
 features supported by rpython or not, and help spread information when a
 feature that wasn't supported is introduced in rpython. That's another