[IMP] doc: grammar and readability

Backport of most of #6827 by J Bradshaw with additional
modifications (and some reverts) during review.

closes #6827

7 files changed, 74 insertions, 65 deletions

diff --git a/doc/reference/async.rst b/doc/reference/async.rst
index c2aded839aa..d8d9c7db90f 100644
--- a/doc/reference/async.rst
+++ b/doc/reference/async.rst
@@ -7,8 +7,8 @@ Asynchronous Operations
 
 As a language (and runtime), javascript is fundamentally
 single-threaded. This means any blocking request or computation will
-blocks the whole page (and, in older browsers, the software itself
-even preventing users from switching to an other tab): a javascript
+block the whole page (and, in older browsers, the software itself
+even preventing users from switching to another tab): a javascript
 environment can be seen as an event-based runloop where application
 developers have no control over the runloop itself.
 
diff --git a/doc/reference/guidelines.rst b/doc/reference/guidelines.rst
index 6c03fd2b2e2..e2cccf19905 100644
--- a/doc/reference/guidelines.rst
+++ b/doc/reference/guidelines.rst
@@ -2,21 +2,20 @@
 
 .. highlight:: python
 
-=================
+===============
 Odoo Guidelines
-=================
+===============
 
-This page introduce the new Odoo Coding Guidelines. This guidelines
-aims to improve the quality of the code (better readability of source,
-...) but also to improve Odoo Apps ! Indeed, a proper code will ease
-the maintenance and debugging, lower the complexity and promote the
-reliability.
+This page introduce the new Odoo Coding Guidelines. These guidelines
+aim to improve the quality of the code (better readability of source,
+...) and  Odoo Apps. Indeed, proper code ought ease maintenance, aid
+debugging, lower complexity and promote reliability.
 
 Module structure
 ================
 
 Directories
-------------
+-----------
 A module is organised in a few directory :
 
 - *data/* : demo and data xml
@@ -26,24 +25,24 @@ A module is organised in a few directory :
 - *static/* : contains the web assets, separated into *css/, js/, img/, lib/, ...*
 
 File naming
-------------
+-----------
 For *views* declarations, split backend views from (frontend)
 templates in 2 differents files.
 
-For *models*, split the business logic by sets of models, in each sets
+For *models*, split the business logic by sets of models, in each set
 select a main model, this model gives its name to the set. If there is
-only one set of module, its name is the same as the module name. For
+only one model, its name is the same as the module name. For
 each set named <main_model> the following files may be created:
 
-- models/<main_model>.py
-- models/<inherited_main_model.py
-- views/<main_model>_templates.xml
-- views/<main_model>_views.xml
+- :file:`models/{<main_model>}.py`
+- :file:`models/{<inherited_main_model>}.py`
+- :file:`views/{<main_model>}_templates.xml`
+- :file:`views/{<main_model>}_views.xml`
 
-For instance, *sale* module introduce ``sale_order`` and
+For instance, *sale* module introduces ``sale_order`` and
 ``sale_order_line`` where ``sale_order`` is dominant. So the
-<main_model> files will be named *models/sale_order.py* and
-*views/sale_order_views.py*.
+``<main_model>`` files will be named :file:`models/sale_order.py` and
+:file:`views/sale_order_views.py`.
 
 
 For *data*, split them by purpose : demo or data. The filename will be
@@ -56,7 +55,7 @@ static/js/im_chat.js, static/css/im_chat.css, static/xml/im_chat.xml,
 ...). Don't link data (image, libraries) outside Odoo : don't use an
 url to an image but copy it in our codebase instead.
 
-The complete tree should looks like
+The complete tree should look like
 
 .. code-block:: text
 
@@ -98,7 +97,8 @@ The complete tree should looks like
         `-- <inherited_main_model>_views.xml
 
 
-.. note:: Filename should only use only ``[a-z0-9_]``
+.. note:: File names should only contain ``[a-z0-9_]`` (lowercase
+          alphanumerics and ``_``)
 
 .. warning:: Use correct file permissions : folder 755 and file 644.
 
@@ -143,16 +143,17 @@ Security, View and Action
 
 Use the following pattern :
 
-* For a menu : *<model_name>_menu*
-* For a view : *<model_name>_view_<view_type>*, where *view_type* is kanban, form, tree, search, ...
-* For an action : the main action respects *<model_name>_action*.
-  Others are suffixed with *_<detail>*, where *detail* is a underscore
-  lowercase string explaining a little bit the action (Should not be
-  long). This is used only if multiple action are declared for the
+* For a menu: :samp:`{<model_name>}_menu`
+* For a view: :samp:`{<model_name>}_view_{<view_type>}`, where *view_type* is
+  ``kanban``, ``form``, ``tree``, ``search``, ...
+* For an action: the main action respects :samp:`{<model_name>}_action`.
+  Others are suffixed with :samp:`_{<detail>}`, where *detail* is a
+  lowercase string briefly explaining the action.
+  This is used only if multiple actions are declared for the
   model.
-* For a group : *<model_name>_group_<group_name>* where *group_name*
-  is the name of the group, genrally 'user', 'manager', ...
-* For a rule : *<model_name>_rule_<concerned_group>* where
+* For a group: :samp:`{<model_name>}_group_{<group_name>} where *group_name*
+  is the name of the group, generally 'user', 'manager', ...
+* For a rule: :samp:`{<model_name>}_rule_{<concerned_group>}` where
   *concerned_group* is the short name of the concerned group ('user'
   for the 'model_name_group_user', 'public' for public user, 'company'
   for multi-company rules, ...).
@@ -196,12 +197,19 @@ Use the following pattern :
 
 
 
-.. note:: View name use dot notation ``my.model.view_type`` or ``my.model.view_type.inherit`` instead of *"This is the form view of My Model"*.
+.. note:: View names use dot notation ``my.model.view_type`` or
+          ``my.model.view_type.inherit`` instead of *"This is the form view of
+          My Model"*.
 
 
 Inherited XML
 ~~~~~~~~~~~~~
-The naming pattern of inherited view is *<base_view>_inherit_<current_module_name>*. A module can extend a view only one time, suffix the orginal name with *_inherit_<current_module_name>*, where *current_module_name* is the technical name of the module extending the view.
+
+The naming pattern of inherited view is
+:samp:`{<base_view>}_inherit_{<current_module_name>}`. A module may only
+extend a view once.  Suffix the orginal name with
+:samp:`_inherit_{<current_module_name>}` where *current_module_name* is the
+technical name of the module extending the view.
 
 
 .. code-block:: xml
@@ -217,7 +225,8 @@ Python
 PEP8 options
 ------------
 
-Using a linter can help to see syntax and semantic warning or error. Odoo Source Code try to respect Python standard, but some of them can be ignored.
+Using a linter can help show syntax and semantic warnings or errors. Odoo
+source code tries to respect Python standard, but some of them can be ignored.
 
 - E501: line too long
 - E301: expected 1 blank line, found 0
@@ -232,7 +241,7 @@ Imports
 -------
 The imports are ordered as
 
-#. Externals libs (One per line sorted and splitted in python stdlib)
+#. External libraries (one per line sorted and split in python stdlib)
 #. Imports of ``openerp``
 #. Imports from Odoo modules (rarely, and only if necessary)
 
@@ -255,7 +264,7 @@ Inside these 3 groups, the imported lines are alphabetically sorted.
 
 
 Idioms
--------
+------
 
 - Prefer ``%`` over ``.format()``, prefer ``%(varname)`` instead of position (This is better for translation)
 - Try to avoid generators and decorators
@@ -306,8 +315,8 @@ Symbols
 - In a Model attribute order should be
     #. Private attributes (``_name``, ``_description``, ``_inherit``, ...)
     #. Default method and ``_default_get``
-    #. Fields declarations
-    #. Compute and search methods in the same order than field declaration
+    #. Field declarations
+    #. Compute and search methods in the same order as field declaration
     #. Constrains methods (``@api.constrains``) and onchange methods (``@api.onchange``)
     #. CRUD methods (ORM overrides)
     #. Action methods
@@ -396,19 +405,18 @@ Prefix your commit with
 
 Then, in the message itself, specify the part of the code impacted by your changes (module name, lib, transversal object, ...) and a description of the changes.
 
-- Always put meaning full commit message: commit message should be
-  self explanatory (long enough) including the name of the module that
-  has been changed and the reason behind that change. Do not use
-  single words like "bugfix" or "improvements".
-
-- Avoid commits which simultaneously impacts lots of modules. Try to
-  splits into different commits where impacted modules are different
-  (It will be helpful when we are going to revert that module
-  separately).
+- Always include a meaningful commit message: it should be self explanatory
+  (long enough) including the name of the module that has been changed and the
+  reason behind the change. Do not use single words like "bugfix" or
+  "improvements".
+- Avoid commits which simultaneously impact multiple modules. Try to
+  split into different commits where impacted modules are different
+  (It will be helpful if we need to revert a module separately).
 
 .. code-block:: text
 
     [FIX] website, website_mail: remove unused alert div, fixes look of input-group-btn
+
     Bootstrap's CSS depends on the input-group-btn
     element being the first/last child of its parent.
     This was not the case because of the invisible
@@ -417,10 +425,11 @@ Then, in the message itself, specify the part of the code impacted by your chang
     [IMP] fields: reduce memory footprint of list/set field attributes
 
     [REF] web: add module system to the web client
+
     This commit introduces a new module system for the javascript code.
     Instead of using global ...
 
 
-.. note:: The long description try to explain the *why* not the
-   *what*, the *what* can be seen in the diff
+.. note:: Use the long description to explain the *why* not the
+          *what*, the *what* can be seen in the diff
 
diff --git a/doc/reference/module.rst b/doc/reference/module.rst
index 2005cf60569..94edfb2eefc 100644
--- a/doc/reference/module.rst
+++ b/doc/reference/module.rst
@@ -11,11 +11,11 @@ Modules
 Manifest
 ========
 
-The manifest file serves to both declare a python package as an Odoo module,
-and to specify a number of module metadata.
+The manifest file serves to declare a python package as an Odoo module
+and to specify module metadata.
 
 It is a file called ``__openerp__.py`` and contains a single Python
-dictionary, each dictionary key specifying a module metadatum.
+dictionary, where each key specifies module metadatum.
 
 ::
 
@@ -66,7 +66,7 @@ Available manifest fields are:
     define.
 
     When a module is installed, all of its dependencies are installed before
-    it. Likewise during modules loading.
+    it. Likewise dependencies are loaded before a module is loaded.
 ``data`` (``list(str)``)
     List of data files which must always be installed or updated with the
     module. A list of paths from the module root directory
diff --git a/doc/reference/security.rst b/doc/reference/security.rst
index b1cb05e9037..98999bf415b 100644
--- a/doc/reference/security.rst
+++ b/doc/reference/security.rst
@@ -24,12 +24,12 @@ Each access control has a model to which it grants permissions, the
 permissions it grants and optionally a group.
 
 Access controls are additive, for a given model a user has access all
-permissions granted to any of its groups: if the user belongs to group *A*
-which allows writing and group *B* which allows deleting, he can both write
+permissions granted to any of its groups: if the user belongs to one group
+which allows writing and another which allows deleting, they can both write
 and delete.
 
 If no group is specified, the access control applies to all users, otherwise
-it only applies to the users belonging to the specific group.
+it only applies to the members of the given group.
 
 Available permissions are creation (``perm_create``), searching and reading
 (``perm_read``), updating existing records (``perm_write``) and deleting
diff --git a/doc/reference/translations.rst b/doc/reference/translations.rst
index 07b87ef2b3d..9a2b6ae8b82 100644
--- a/doc/reference/translations.rst
+++ b/doc/reference/translations.rst
@@ -16,7 +16,7 @@ your module's translatable terms and may find content to work with.
 
 .. todo:: needs technical features
 
-Translations export is done via the administration interface by logging into
+Translations export is performed via the administration interface by logging into
 the backend interface and opening :menuselection:`Settings --> Translations
 --> Import / Export --> Export Translations`
 
@@ -68,7 +68,7 @@ Explicit exports
 ================
 
 When it comes to more "imperative" situations in Python code or Javascript
-code, Odoo is not able to automatically export translatable terms and they
+code, Odoo cannot automatically export translatable terms so they
 must be marked explicitly for export. This is done by wrapping a literal
 string in a function call.
 
@@ -84,11 +84,11 @@ In JavaScript, the wrapping function is generally :js:func:`openerp.web._t`:
 
 .. warning::
 
-    Only literal strings can be marked for exports, not expressions and not
+    Only literal strings can be marked for exports, not expressions or
     variables. For situations where strings are formatted, this means the
     format string must be marked, not the formatted string::
 
-        # bad, the extract may work but it will not correctly translate the text
+        # bad, the extract may work but it will not translate the text correctly
         _("Scheduled meeting with %s" % invitee.name)
 
         # good
diff --git a/doc/reference/views.rst b/doc/reference/views.rst
index 6670ac05c33..b1cc0255520 100644
--- a/doc/reference/views.rst
+++ b/doc/reference/views.rst
@@ -13,7 +13,7 @@ Common Structure
 ================
 
 View objects expose a number of fields, they are optional unless specified
-otherwise)
+otherwise.
 
 ``name`` (mandatory)
     only useful as a mnemonic/description of the view when looking for one in
@@ -22,7 +22,7 @@ otherwise)
     the model linked to the view, if applicable (it doesn't for QWeb views)
 ``priority``
     client programs can request views by ``id``, or by ``(model, type)``. For
-    the latter, all the views for the right type and model will be looked for,
+    the latter, all the views for the right type and model will be searched,
     and the one with the lowest ``priority`` number will be returned (it is
     the "default view").
 
@@ -147,7 +147,7 @@ root can have the following attributes:
 
     Defined as a mapping of colors to Python expressions. Values are of the
     form: :samp:`{color}:{expr}[;...]`. For each record, pairs are tested
-    in-order, the expression is evaluated for the record and if ``true`` the
+    in order, the expression is evaluated for the record and if ``true`` the
     corresponding color is applied to the row. If no color matches, uses the
     default text color (black).
 
@@ -572,7 +572,7 @@ Button Box
 ..........
 
 Many relevant actions or links can be displayed in the form. For example, in
-Opportunity form, the actions "Schedule a Call" and "Schedule a Meeting" take
+Opportunity form, the actions "Schedule a Call" and "Schedule a Meeting" have
 an important place in the use of the CRM. Instead of placing them in the
 "More" menu, put them directly in the sheet as buttons (on the top right) to
 make them more visible and more easily accessible.
diff --git a/doc/reference/workflows.rst b/doc/reference/workflows.rst
index a6890f05ab6..db57880436e 100644
--- a/doc/reference/workflows.rst
+++ b/doc/reference/workflows.rst
@@ -115,7 +115,7 @@ Activities
 ----------
 
 While the transitions can be seen as the control structures of the workflows,
-activities are the places where everything happens, from changing record
+activities are where everything happens, from changing record
 states to sending email.
 
 Different kinds of activities exist: ``Dummy``, ``Function``, ``Subflow``, and