First snapshot of trytond documentation refactoring

doc/topics/modules/index.rst

 .. _topics-modules:
 
 =======
 Modules
 =======
 
 The modules of Tryton extend the functionality of the platform. The server
-comes by default with only a basic functionality included in those modules:
+comes by default with only a basic functionality included in these modules:
 ``ir``, ``res``, ``webdav``, ``workflow``.
 
 Module Structure
-****************
+================
 
-A module is a directory in trytond/modules that contains at least two files:
+A module is a directory in trytond/modules which contains at least two files:
 
    * ``__init__.py``: a Tryton module must be a Python module.
 
    * ``__tryton__.py``: a Python file that describes the Tryton module.
 
 ``__init__.py`` file
-^^^^^^^^^^^^^^^^^^^^
+--------------------
 
 It is the Python ``__init__.py`` to define a module. It must import all the
-python files from the module.
+Python files from the module.
 
 
 ``__tryton__.py`` file
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 It is a Python file that must contain only one dictionary with those keywords:
 
    * ``name``: The name of the module.
 
    * ``name_language_code``: The name of the module in the language code.
 
    * ``version``: The version number of the module.
 
    * ``author``: The author name of the module.
 
    * ``email``: The email address of the author (optional).
 
    * ``website``: The url of the website for the module (optional).
 
    * ``description``: A long description of the module.
 
    * ``description_language_code``: The long description in the language code.
 
-   * ``depends``: A list of modules on which the module depends.
+   * ``depends``: A list of modules on which this module depends.
 
-   * ``xml``: The list of the XML files of the module. They will be loaded at
-     the installation or update of the module.
+   * ``xml``: The list of the XML files of the module. They will be loaded in
+     the given order at the installation or update of the module.
 
    * ``translation``: The list of csv files that contain the translation. The
      name of the files must be the language code.
 
 
 Here is an example:
 
 .. highlight:: python
 
 ::
@@ skipping 17 matching lines @@
           "address.xml",
           "contact_mechanism.xml",
       ],
       'translation': [
           'fr_FR.csv',
           'de_DE.csv',
           'es_ES.csv',
       ],
   }
 
-Python files
-************
+Python Files
+============
 
-The Python files define the Models for the modules.
+The Python files define the models for the modules.
 
-XML files
-*********
+XML Files
+=========
 
 The XML files define data that will be inserted into the database.
 
 There is an rnc for those files stored in ``trytond/tryton.rnc``.
 
 The following snippet gives a first idea of what an xml file looks:
 
 .. highlight:: xml
 
 ::
@@ skipping 41 matching lines @@
 
     * ``record``: Create a record of the model defined by the attribute
       ``model`` in the database. The ``id`` attribute can be used to refer to
       the record later in any xml file.
 
     * ``field``: Set the value of the field with the name defined by the
       attribute ``name``.
 
       Here is the list of attributes:
 
-        * ``search``: Only for relation field, it contains a domain on which
-          searching for the first record and use it as value.
+        * ``search``: Only for relation field. It contains a domain which is
+          used to search for the value to use. The first value found will be
+          used.
 
-        * ``ref``: Only for relation field, it contains an xml id of the
+        * ``ref``: Only for relation field. It contains an xml id of the
           relation to use as value. It must be prefixed by the module name with
           an ending dot, if the record is defined in an other module.
 
         * ``eval``: Python code to evaluate and use result as value.
 
         * ``type``: If set to xml, it will use the CDATA content as value.
+
+        .. note::
+            Field content is considered as a string. So for fields that require
+            other types, it is required to use the ``eval`` attribute.
+        ..
 
 
     * ``menuitem``: Shortcut to create ir.ui.menu records.
 
       Here is the list of attributes:
 
         * ``id``: The id of the menu.
 
         * ``name``: The name of the menu.
 
         * ``icon``: The icon of the menu.
 
         * ``sequence``: The sequence value used to order the menu entries.
 
         * ``parent``: The xml id of the parent menu.
 
         * ``action``: The xml id of the action linked to the menu.
 
         * ``groups``: A list of xml id of group, that have access to the menu,
           separated by commas.
 
         * ``active``: A boolean telling if the menu is active or not.