Documentation for what blocks are and FAQ clean up (#4800)

Closes #2452

1 files changed, 25 insertions, 24 deletions

diff --git a/doc/faq.rst b/doc/faq.rst
index 3d020aa21..d679bc286 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -30,9 +30,7 @@ Everything should be explained on :ref:`installation`.
 2.2 What kind of versioning system does Pylint use?
 ---------------------------------------------------
 
-Pylint uses the git distributed version control system. The URL of the
-repository is: https://github.com/PyCQA/pylint . To get the latest version of
-Pylint from the repository, simply invoke ::
+Pylint uses git. To get the latest version of Pylint from the repository, simply invoke ::
 
     git clone https://github.com/PyCQA/pylint
 
@@ -60,8 +58,7 @@ The supported running environment since Pylint 2.7.X is Python 3.6+.
 -----------------------------------------------------------------
 
 Pylint expects the name of a package or module as its argument. As a
-convenience,
-you can give it a file name if it's possible to guess a module name from
+convenience, you can give it a file name if it's possible to guess a module name from
 the file's path using the python path. Some examples :
 
 "pylint mymodule.py" should always work since the current working
@@ -73,16 +70,16 @@ or if "directory" is in the python path.
 
 "pylint /whatever/directory/mymodule.py" will work if either:
 
-	- "/whatever/directory" is in the python path
+    - "/whatever/directory" is in the python path
 
-	- your cwd is "/whatever/directory"
+    - your cwd is "/whatever/directory"
 
-	- "directory" is a python package and "/whatever" is in the python
+    - "directory" is a python package and "/whatever" is in the python
           path
 
         - "directory" is an implicit namespace package and is in the python path.
 
-	- "directory" is a python package and your cwd is "/whatever" and so
+    - "directory" is a python package and your cwd is "/whatever" and so
           on...
 
 3.2 Where is the persistent data stored to compare between successive runs?
@@ -106,13 +103,13 @@ localized using the following rules:
 3.3 How do I find the option name (for pylintrc) corresponding to a specific command line option?
 --------------------------------------------------------------------------------------------------------
 
-You can always generate a sample pylintrc file with --generate-rcfile
+You can generate a sample pylintrc file with --generate-rcfile
 Every option present on the command line before this will be included in
 the rc file
 
 For example::
 
-	pylint --disable=bare-except,invalid-name --class-rgx='[A-Z][a-z]+' --generate-rcfile
+    pylint --disable=bare-except,invalid-name --class-rgx='[A-Z][a-z]+' --generate-rcfile
 
 3.4 I'd rather not run Pylint from the command line. Can I integrate it with my editor?
 ---------------------------------------------------------------------------------------
@@ -123,12 +120,16 @@ Much probably. Read :ref:`ide-integration`
 4. Message Control
 ==================
 
-4.1 Is it possible to locally disable a particular message?
+4.1 How to disable a particular message?
 -----------------------------------------------------------
 
-Yes, this feature has been added in Pylint 0.11. This may be done by
-adding "#pylint: disable=some-message,another-one" at the desired block level
-or at the end of the desired line of code
+Add "#pylint: disable=some-message,another-one" at the desired block level
+or at the end of the desired line of code.
+
+A block is either a scope (say a function, a module), or a multiline statement (Try, Finally, if statements, for loops).
+`It's currently impossible to disable inside an else block`_
+
+.. _`It's currently impossible to disable inside an else block`: https://github.com/PyCQA/pylint/issues/872
 
 4.2 Is there a way to disable a message for a particular module only?
 ---------------------------------------------------------------------
@@ -137,25 +138,21 @@ Yes, you can disable or enable (globally disabled) messages at the
 module level by adding the corresponding option in a comment at the
 top of the file: ::
 
-	# pylint: disable=wildcard-import, method-hidden
-	# pylint: enable=too-many-lines
+    # pylint: disable=wildcard-import, method-hidden
+    # pylint: enable=too-many-lines
 
 4.3 How can I tell Pylint to never check a given module?
 --------------------------------------------------------
 
-With Pylint < 0.25, add "#pylint: disable-all" at the beginning of the
-module. Pylint 0.26.1 and up have renamed that directive to
-"#pylint: skip-file" (but the first version will be kept for backward
-compatibility).
+Add ``#pylint: skip-file`` at the beginning of the module.
 
 In order to ease finding which modules are ignored an Information-level message
-`file-ignored` is emitted. With recent versions of Pylint, if you use the old
-syntax, an additional `deprecated-disable-all` message is emitted.
+`file-ignored` is emitted.
 
 4.4 Do I have to remember all these numbers?
 --------------------------------------------
 
-No, starting from 0.25.3, you can use symbolic names for messages::
+No, you can use symbolic names for messages::
 
     # pylint: disable=fixme, line-too-long
 
@@ -191,6 +188,10 @@ for not being included as default messages. But most of the disabled
 messages are from the Python 3 porting checker, which is disabled by
 default. It needs special activation with the ``--py3k`` flag.
 
+You can see the plugin you need to explicitly `load in the technical reference`_
+
+.. _`load in the technical reference`: http://pylint.pycqa.org/en/latest/technical_reference/extensions.html?highlight=load%20plugin
+
 4.8 I am using another popular linter alongside pylint. Which messages should I disable to avoid duplicates?
 ------------------------------------------------------------------------------------------------------------