[IMP] source formatting: fill-paragraph to 78

leaves a bit of room for diff mark & a small gutter in a 80c system

1 files changed, 183 insertions, 197 deletions

diff --git a/doc/howto/howto_website.rst b/doc/howto/howto_website.rst
index a3e938a0a52..025cc3a5c1a 100644
--- a/doc/howto/howto_website.rst
+++ b/doc/howto/howto_website.rst
@@ -9,18 +9,18 @@ Howto: build a website with OpenERP
    This guide assumes `basic knowledge of python
    <http://docs.python.org/2/tutorial/>`_.
 
-   This guide assumes :ref:`an OpenERP installed and ready for
-   development <getting_started_installation_source-link>`.
+   This guide assumes :ref:`an OpenERP installed and ready for development
+   <getting_started_installation_source-link>`.
 
-   For production deployment, see the dedicated guides
-   :ref:`using-gunicorn` and :ref:`using-mod-wsgi`.
+   For production deployment, see the dedicated guides :ref:`using-gunicorn`
+   and :ref:`using-mod-wsgi`.
 
 Hello, world!
 =============
 
-In OpenERP, doing things takes the form of creating modules, and these
-modules customize the behavior of the OpenERP installation. The first
-step is thus to create a module:
+In OpenERP, doing things takes the form of creating modules, and these modules
+customize the behavior of the OpenERP installation. The first step is thus to
+create a module:
 
 .. todo:: code generator in oe?
 
@@ -29,15 +29,15 @@ step is thus to create a module:
     * Create model (concrete/abstract? Inherit?)
     * Add field?
 
-* Create a new folder called :file:`academy` in a module directory,
-  inside it create an empty file called :file:`__openerp__.py` with
-  the following content:
+* Create a new folder called :file:`academy` in a module directory, inside it
+  create an empty file called :file:`__openerp__.py` with the following
+  content:
 
   .. patch::
 
 * Create a second file :file:`controllers.py`. This is where the code
-  interacting directly with your web browser will live. For starters,
-  just include the following in it:
+  interacting directly with your web browser will live. For starters, just
+  include the following in it:
 
   .. patch::
 
@@ -45,8 +45,8 @@ step is thus to create a module:
 
   .. patch::
 
-  This makes :file:`controllers.py` "visible" to openerp (by running
-  the code it holds).
+  This makes :file:`controllers.py` "visible" to openerp (by running the code
+  it holds).
 
 .. todo::
 
@@ -56,15 +56,15 @@ step is thus to create a module:
      - if no existing db, nodb -> login -> login of first db
      - dbfilter
 
-Now start your OpenERP server and install your module in it, open a
-web browser and navigate to http://localhost:8069. A page should
-appear with just the words "Hello, world!" on it.
+Now start your OpenERP server and install your module in it, open a web
+browser and navigate to http://localhost:8069. A page should appear with just
+the words "Hello, world!" on it.
 
-The default response type is HTML (although we only sent some text,
-browsers are pretty good at finding ways to turn stuff into things
-they can display). Let's prettify things a bit: instead of returning
-just a bit of text, we can return a page, and use a tool/library like
-bootstrap_ to get a nicer rendering than the default.
+The default response type is HTML (although we only sent some text, browsers
+are pretty good at finding ways to turn stuff into things they can
+display). Let's prettify things a bit: instead of returning just a bit of
+text, we can return a page, and use a tool/library like bootstrap_ to get a
+nicer rendering than the default.
 
 Change the string returned by the ``index`` method to get a more page-ish
 output:
@@ -73,17 +73,17 @@ output:
 
 .. note::
 
-   this example requires internet access at all time, as we're
-   accessing a :abbr:`CDN (Content Delivery Network, large distributed
-   networks hosting static files and trying to provide
-   high-performance and high-availability of these files)`-hosted
-   file.
+   this example requires internet access at all time, as we're accessing a
+   :abbr:`CDN (Content Delivery Network, large distributed networks hosting
+   static files and trying to provide high-performance and high-availability
+   of these files)`-hosted file.
 
 Data input: URL and query
 =========================
 
 Being able to build a static page in code is nice, but makes for limited
-usefulness (you could do that with static files in the first place, after all).
+usefulness (you could do that with static files in the first place, after
+all).
 
 But you can also create controllers which use data provided in the access URL,
 for instance so you have a single controller generating multiple pages. Any
@@ -98,14 +98,15 @@ formatted. For this reason, query parameters are generally used to provide
 "options" to a given page, and "required" data tends (when possible) to be
 inserted directly in the URL.
 
-This can be done by adding `converter patterns`_ to the URL in ``@http.route``:
+This can be done by adding `converter patterns`_ to the URL in
+``@http.route``:
 
 .. patch::
 
 These patterns can perform conversions directly (in this case the conversion
 from a string URL section to a python integer) and will perform a some
-validation (if the ``id`` is not a valid integer, the converter will return
-a ``404 Not Found`` instead of generating a server error when the conversion
+validation (if the ``id`` is not a valid integer, the converter will return a
+``404 Not Found`` instead of generating a server error when the conversion
 fails).
 
 Templating: better experience in editing
@@ -116,171 +117,164 @@ string concatenation and formatting. It works, but is not exactly fun to edit
 (and somewhat unsafe to boot) as even advanced text editors have a hard time
 understanding they're dealing with HTML embedded in Python code.
 
-The usual solution is to use templates_, documents with placeholders which
-can be "rendered" to produce final pages (or others). OpenERP lets you use
-any Python templating system you want, but bundles its own
-:doc:`QWeb </06_ir_qweb>` templating system which we'll later see offers
-some useful features.
+The usual solution is to use templates_, documents with placeholders which can
+be "rendered" to produce final pages (or others). OpenERP lets you use any
+Python templating system you want, but bundles its own :doc:`QWeb
+</06_ir_qweb>` templating system which we'll later see offers some useful
+features.
 
 Let's move our 2 pseudo-templates from inline strings to actual templates:
 
 .. patch::
 
-.. todo:: how can I access a QWeb template from a auth=none
-          controller? explicitly fetch a registry using
-          request.session.db? That's a bit horrendous now innit?
+.. todo:: how can I access a QWeb template from a auth=none controller?
+          explicitly fetch a registry using request.session.db? That's a bit
+          horrendous now innit?
 
-This simplifies the controller code by moving data formatting out of
-it, and generally makes it simpler for designers to edit the markup.
+This simplifies the controller code by moving data formatting out of it, and
+generally makes it simpler for designers to edit the markup.
 
-.. todo:: link to section about reusing/altering existing stuff,
-          template overriding
+.. todo:: link to section about reusing/altering existing stuff, template
+          overriding
 
 OpenERP's Website support
 =========================
 
-OpenERP 8 is bundled with new modules dedicated specifically to
-building websites (whether it be simply sets of pages or more complex
-components such as blogs).
+OpenERP 8 is bundled with new modules dedicated specifically to building
+websites (whether it be simply sets of pages or more complex components such
+as blogs).
 
 First, we'll install the ``website`` module: ``oe install website``.
 
 .. todo:: is it possible that the page has *not* been replaced?
 
-If you navigate to `your openerp`_, your basic page has now been
-replaced by the generic empty index page. Because you are not
-logged-in yet, the page has no content and just basic placeholders in
-the header and footer. Click on the :guilabel:`Sign In` link, fill in
-your credentials (``admin``/``admin`` by default), click
-:guilabel:`Log in`.
+If you navigate to `your openerp`_, your basic page has now been replaced by
+the generic empty index page. Because you are not logged-in yet, the page has
+no content and just basic placeholders in the header and footer. Click on the
+:guilabel:`Sign In` link, fill in your credentials (``admin``/``admin`` by
+default), click :guilabel:`Log in`.
 
-You're now in OpenERP "proper", the backend/administrative
-interface. We'll deal with it in :ref:`a latter section
-<howto-website-administration>`, for how click on the
-:menuselection:`Website` menu item, in the top-left of the browser
-between :menuselection:`Messaging` and :menuselection:`Settings`.
+You're now in OpenERP "proper", the backend/administrative interface. We'll
+deal with it in :ref:`a latter section <howto-website-administration>`, for
+how click on the :menuselection:`Website` menu item, in the top-left of the
+browser between :menuselection:`Messaging` and :menuselection:`Settings`.
 
-You're back to your website, but are now an administrator and thus
-have access to the advanced edition features of an OpenERP-build
-website. Let's quickly run through them.
+You're back to your website, but are now an administrator and thus have access
+to the advanced edition features of an OpenERP-build website. Let's quickly
+run through them.
 
 Mobile Preview
 --------------
 
 .. todo:: insert menu bar, mobile preview icon outlined
 
-Because the OpenERP website system is built with bootstrap_, it is
-easy to build "responsive" websites reacting to the size of the screen
-and making best use of the available space.
+Because the OpenERP website system is built with bootstrap_, it is easy to
+build "responsive" websites reacting to the size of the screen and making best
+use of the available space.
 
-The mobile preview does not give you the exact rendering of a
-smartphone (if there's such a thing), but it goes some of the way and
-lets you know if it's completely unusable without having to actually
-switch to a smartphone and try to find out how to see your site with
-it (especially during edition).
+The mobile preview does not give you the exact rendering of a smartphone (if
+there's such a thing), but it goes some of the way and lets you know if it's
+completely unusable without having to actually switch to a smartphone and try
+to find out how to see your site with it (especially during edition).
 
 .. todo:: screenshot of page in desktop v mobile preview layout
 
 Promote
 -------
 
-Lets you easily configure how your page should advertise its existence
-to search engines: keywords matching the page's subject, nice titles
-and descriptions for visitors finding the page via search engines.
+Lets you easily configure how your page should advertise its existence to
+search engines: keywords matching the page's subject, nice titles and
+descriptions for visitors finding the page via search engines.
 
 .. todo:: screenshot promote
 
 Content
 -------
 
-The content menu provides "top level" operations: manipulation of the
-main menu (creation of new links, submenus, etc...) and creation of
-high-level objects. At the moment only pages (they're the top-level
-object for the ``website`` module), but installing the recruitment
-module will add an entry to quick-create a new job offer, and the
-events module one for a new event.
+The content menu provides "top level" operations: manipulation of the main
+menu (creation of new links, submenus, etc...) and creation of high-level
+objects. At the moment only pages (they're the top-level object for the
+``website`` module), but installing the recruitment module will add an entry
+to quick-create a new job offer, and the events module one for a new event.
 
 Customize
 ---------
 
-The customize menu provides a number of loosely associated features,
-broadly split in two sections:
+The customize menu provides a number of loosely associated features, broadly
+split in two sections:
 
 Templates configuration
 ```````````````````````
 
-Some templates provide alternative versions/structures. These
-alternative version can be toggled from the template configuration
-checkboxes. Two of these are bundled in ``website``, providing an
-alternative blank footer to fill, and the other one replacing your
-company's name by your company's logo in the navigation bar.
+Some templates provide alternative versions/structures. These alternative
+version can be toggled from the template configuration checkboxes. Two of
+these are bundled in ``website``, providing an alternative blank footer to
+fill, and the other one replacing your company's name by your company's logo
+in the navigation bar.
 
 Theming
 ```````
 
-As previously mentioned, OpenERP's website module uses bootstrap_ for
-much of its basic styles and layout. This, in turns, allows using
-existing bootstrap themes to alter the color scheme of your website.
+As previously mentioned, OpenERP's website module uses bootstrap_ for much of
+its basic styles and layout. This, in turns, allows using existing bootstrap
+themes to alter the color scheme of your website.
 
-:menuselection:`Customize --> Change Theme` opens a picker to a few
-bundled Bootstrap themes, and lets you change the look of your site
-quickly and on-the-fly.
+:menuselection:`Customize --> Change Theme` opens a picker to a few bundled
+Bootstrap themes, and lets you change the look of your site quickly and
+on-the-fly.
 
 .. todo:: creating or installing new boostrap themes?
 
 HTML Editor
 ```````````
 
-Opens a full-blown code editor on the current template, and lets you
-easily edit templates in-place, either for a quick fix which is
-simpler to perform in code yet from the page, or to try things out
-before moving them to template files.
+Opens a full-blown code editor on the current template, and lets you easily
+edit templates in-place, either for a quick fix which is simpler to perform in
+code yet from the page, or to try things out before moving them to template
+files.
 
 Help
 ----
 
 Lists available tutorials, step-by-step lessons in using the website.
-``website`` only provides :menuselection:`Help --> Insert a banner`
-which shows some basic features of the website (snippets, edition,
-mobile preview) while guiding the user through. Other modules can
-provide additional tutorials for their advanced features.
+``website`` only provides :menuselection:`Help --> Insert a banner` which
+shows some basic features of the website (snippets, edition, mobile preview)
+while guiding the user through. Other modules can provide additional tutorials
+for their advanced features.
 
 Edit
 ----
 
-Starts up the rich text editor, which lets you alter page text, add
-links and images, change colors, etc…
+Starts up the rich text editor, which lets you alter page text, add links and
+images, change colors, etc…
 
 Snippets
 ````````
 
-:guilabel:`Insert Blocks` opens the snippets UI: pre-built layout
-blocks which you can then fill with your own content (text, pictures,
-…). Simply select a snippet and drag-and-drop it on your page. Guides
-should appear when you start dragging a snippet, showing where the
-snippet can be dropped.
+:guilabel:`Insert Blocks` opens the snippets UI: pre-built layout blocks which
+you can then fill with your own content (text, pictures, …). Simply select a
+snippet and drag-and-drop it on your page. Guides should appear when you start
+dragging a snippet, showing where the snippet can be dropped.
 
 Building your pages with OpenERP Website
 ========================================
 
-As we've seen, your index page has "disappeared" and been replaced by
-the one provided by ``website``. The page is not lost, but because
-``website`` was installed after the ``academy`` module, its index
-page takes over routing (two index pages exist, and one is picked
-over the other).
+As we've seen, your index page has "disappeared" and been replaced by the one
+provided by ``website``. The page is not lost, but because ``website`` was
+installed after the ``academy`` module, its index page takes over routing (two
+index pages exist, and one is picked over the other).
 
-To fix the issue, we can simply add ``website`` as a dependency to
-``academy`` (that is, tell OpenERP that ``academy`` needs ``website``
-to work right):
+To fix the issue, we can simply add ``website`` as a dependency to ``academy``
+(that is, tell OpenERP that ``academy`` needs ``website`` to work right):
 
 .. needs -u all to update metadata
 
 .. patch::
 
 .. todo:: website dispatch overrides blows up on auth=none (implicitly
-          inherits website's index -> ``website_enabled`` -> tries to
-          access ``request.registry['website']`` even though
-          ``request.registry is None`` because ``auth='none'``)
+          inherits website's index -> ``website_enabled`` -> tries to access
+          ``request.registry['website']`` even though ``request.registry is
+          None`` because ``auth='none'``)
 
           also template issues (see above) (enabled website to "fix")
 
@@ -288,139 +282,132 @@ This will cause ``academy``'s index page to overwrite ``website``'s.
 
 Reload `your openerp`_. Your old index page is back.
 
-However, none of the website edition tools are available. That is
-because much of these tools are inserted and enabled by the website
-layout template.  Let's use that layout instead of our own page
-structure:
+However, none of the website edition tools are available. That is because much
+of these tools are inserted and enabled by the website layout template.  Let's
+use that layout instead of our own page structure:
 
 .. patch::
 
-* ``website.layout`` is the main Website layout, it provides standard
-  headers and footers as well as integration with various
-  customization tools.
+* ``website.layout`` is the main Website layout, it provides standard headers
+  and footers as well as integration with various customization tools.
 
-* there's quite a bit of complex markup, used as hooks for various
-  features (e.g. snippets). Although technically not mandatory, some
-  things will not work if they're not there.
+* there's quite a bit of complex markup, used as hooks for various features
+  (e.g. snippets). Although technically not mandatory, some things will not
+  work if they're not there.
 
-* if you go in the HTML editor (:menuselection:`Customize --> HTML
-  Editor`), you can see and edit your template
+* if you go in the HTML editor (:menuselection:`Customize --> HTML Editor`),
+  you can see and edit your template
 
 .. todo:: website template generator
 
-If you try to add content to the TA pages using snippets, for instance
-insert an :guilabel:`image-text` snippet to add a picture and a short
-biography for a TA, you'll notice things don't work right: because
-snippets are added in the template itself, they're content which is
-the same across all pages using that template.
+If you try to add content to the TA pages using snippets, for instance insert
+an :guilabel:`image-text` snippet to add a picture and a short biography for a
+TA, you'll notice things don't work right: because snippets are added in the
+template itself, they're content which is the same across all pages using that
+template.
 
-Thus snippets are mostly for generic content, when a given template is
-only used for a single page, or to add content in HTML fields.
+Thus snippets are mostly for generic content, when a given template is only
+used for a single page, or to add content in HTML fields.
 
 .. note::
 
-    When creating a new page (e.g. via :menuselection:`Content --> New
-    Page`), OpenERP will duplicate a "source" template, and create a
-    new template for each page. As a result, it's safe to use
-    dedicated-content snippets for "static" pages.
+    When creating a new page (e.g. via :menuselection:`Content --> New Page`),
+    OpenERP will duplicate a "source" template, and create a new template for
+    each page. As a result, it's safe to use dedicated-content snippets for
+    "static" pages.
 
 Time, then, to create more specific content.
 
 Storing data in OpenERP
 =======================
 
-The conceptual storage model of OpenERP is simple: there are storage
-tables, represented by OpenERP models, and inside these tables are
-records. The first step, then, is to define a model.
+The conceptual storage model of OpenERP is simple: there are storage tables,
+represented by OpenERP models, and inside these tables are records. The first
+step, then, is to define a model.
 
 We'll start by moving our teaching assistants in the database:
 
 .. patch::
 
 We've also altered the index method slightly, to retrieve our teaching
-assistants from the database instead of storing them in a global list
-in the module\ [#taprofile]_.
+assistants from the database instead of storing them in a global list in the
+module\ [#taprofile]_.
 
-.. note:: :file:`ir.model.access.csv` is necessary to tell OpenERP
-          that any user can *see* the teaching assistants: by default,
-          only the administrator can see, edit, create or destroy
-          objects.  Here, we only change the ``read`` permission to
-          allow any user to list and browse teaching assistants.
+.. note:: :file:`ir.model.access.csv` is necessary to tell OpenERP that any
+          user can *see* the teaching assistants: by default, only the
+          administrator can see, edit, create or destroy objects.  Here, we
+          only change the ``read`` permission to allow any user to list and
+          browse teaching assistants.
 
 .. todo:: command/shortcut
 
-Update the module, reload `your openerp`_… and the Teaching Assistants
-list is empty since we haven't put any TA in the database.
+Update the module, reload `your openerp`_… and the Teaching Assistants list is
+empty since we haven't put any TA in the database.
 
 Let's add them in data files:
 
 .. patch::
 
-Update the module again, reload `your openerp`_ and the TAs are
-back. Click on a TA name, and you'll see an error message. Let's fix
-the TA view now:
+Update the module again, reload `your openerp`_ and the TAs are back. Click on
+a TA name, and you'll see an error message. Let's fix the TA view now:
 
 .. todo:: if ta template was modified in previous section, it's marked
-          noupdate and updating the module will have no effect for no
-          known reason. That's really quite annoying.
+          noupdate and updating the module will have no effect for no known
+          reason. That's really quite annoying.
 
 .. patch::
 
-There are a few non-obvious things here, so let's go through them for
-clarity:
+There are a few non-obvious things here, so let's go through them for clarity:
 
-* OpenERP provides a has a special `converter pattern`_, which knows
-  how to retrieve OpenERP objects by identifier. Instead of an integer
-  or other similar basic value, ``ta`` thus gets a full-blown
-  ``academy.tas`` object, without having to retrieve it by hand (as is
-  done in ``index``).
+* OpenERP provides a has a special `converter pattern`_, which knows how to
+  retrieve OpenERP objects by identifier. Instead of an integer or other
+  similar basic value, ``ta`` thus gets a full-blown ``academy.tas`` object,
+  without having to retrieve it by hand (as is done in ``index``).
 
-* However because the ``model()`` `converter pattern`_ takes an
-  identifier, we have to alter the creation of ``ta``'s URL to include
-  such an identifier, rather than an index in an array
+* However because the ``model()`` `converter pattern`_ takes an identifier, we
+  have to alter the creation of ``ta``'s URL to include such an identifier,
+  rather than an index in an array
 
-* Finally, ``website.render()`` wants a dict as its rendering context,
-  not an object, which is why we wrap our ``ta`` object into one.
+* Finally, ``website.render()`` wants a dict as its rendering context, not an
+  object, which is why we wrap our ``ta`` object into one.
 
-We're still where we started this section though: if we add snippets
-to or edit the text of a TA's page, these editions will be visible
-across all TA pages since they'll be stored in the shared
-``academy.ta`` template.
+We're still where we started this section though: if we add snippets to or
+edit the text of a TA's page, these editions will be visible across all TA
+pages since they'll be stored in the shared ``academy.ta`` template.
 
-Not only that, but we can not even edit the TA's name, even though
-it's not shared content.
+Not only that, but we can not even edit the TA's name, even though it's not
+shared content.
 
-Let's fix that first, instead of using the basic "display this
-content" template tag ``t-esc``, we'll use one aware of OpenERP
-objects and their fields:
+Let's fix that first, instead of using the basic "display this content"
+template tag ``t-esc``, we'll use one aware of OpenERP objects and their
+fields:
 
 .. patch::
 
-Update the module, go into a TA page and activate the edition mode. If
-you move your mouse over the TA's name, it is surrounded by a yellow
-border, and you can edit its content. If you change the name of a TA
-and save the page, the change is correctly stored in the TA's record,
-the name is fixed when you go to the index page but other TAs remain
-unaffected.
+Update the module, go into a TA page and activate the edition mode. If you
+move your mouse over the TA's name, it is surrounded by a yellow border, and
+you can edit its content. If you change the name of a TA and save the page,
+the change is correctly stored in the TA's record, the name is fixed when you
+go to the index page but other TAs remain unaffected.
 
-For the issue of customizing our TA profiles, we can expand our model
-with a "freeform" HTML field:
+For the issue of customizing our TA profiles, we can expand our model with a
+"freeform" HTML field:
 
 .. patch::
 
-Then, insert the new biographical content in the template using the
-same object-aware template tag:
+Then, insert the new biographical content in the template using the same
+object-aware template tag:
 
 .. patch::
 
-.. todo:: updating the ``name`` field from the RTE altered the
-          template, which locked it...
+.. todo:: updating the ``name`` field from the RTE altered the template, which
+          locked it...
 
-Update the module, browse to a TA's page and open the edition mode
-(using the :guilabel:`Edit` button in the window's top-right).  The
-empty HTML field now displays a big placeholder image, if you drop
-snippets in or write some content for one of the teaching assistants,
-you will see that other TA profiles are unaffected.
+Update the module, browse to a TA's page and open the edition mode (using the
+:guilabel:`Edit` button in the window's top-right).  The empty HTML field now
+displays a big placeholder image, if you drop snippets in or write some
+content for one of the teaching assistants, you will see that other TA
+profiles are unaffected.
 
 A more complex model
 --------------------
@@ -450,9 +437,8 @@ Administration and ERP Integration
    .. improve generated views
 .. create list & form views for events
 
-.. [#taprofile] the teaching assistants profile view ends up
-                broken for now, but don't worry we'll get
-                around to it
+.. [#taprofile] the teaching assistants profile view ends up broken for now,
+                but don't worry we'll get around to it
 
 .. _bootstrap: http://getbootstrap.com