minor #4539 Normalization of method listings (pedronofuentes)

This PR was merged into the 2.3 branch.

Discussion
----------

Normalization of method listings

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | no
| Applies to    | all
| Fixed tickets | fixes #3903

Commits
-------

3fd3963 Changed to definition lists from Book section
dda1905 Changed to definition lists
3649bdb Fixed heading capitalization to follow the standards
6b68e48 Changed paragraph to heading
1d571ca Changed unordered list to definition list

book/forms.rst

@@ -716,14 +716,16 @@ the correct values of a number of field options.
     And though you'll need to manually add your server-side validation, these
     field type options can then be guessed from that information.
 
-* ``required``: The ``required`` option can be guessed based on the validation
-  rules (i.e. is the field ``NotBlank`` or ``NotNull``) or the Doctrine metadata
-  (i.e. is the field ``nullable``). This is very useful, as your client-side
-  validation will automatically match your validation rules.
+``required``
+    The ``required`` option can be guessed based on the validation rules (i.e. is
+    the field ``NotBlank`` or ``NotNull``) or the Doctrine metadata (i.e. is the
+    field ``nullable``). This is very useful, as your client-side validation will
+    automatically match your validation rules.
 
-* ``max_length``: If the field is some sort of text field, then the ``max_length``
-  option can be guessed from the validation constraints (if ``Length`` or
-  ``Range`` is used) or from the Doctrine metadata (via the field's length).
+``max_length``
+    If the field is some sort of text field, then the ``max_length`` option can be
+    guessed from the validation constraints (if ``Length`` or ``Range`` is used) or
+    from the Doctrine metadata (via the field's length).
 
 .. note::
 
@@ -771,12 +773,13 @@ of code. Of course, you'll usually need much more flexibility when rendering:
 You already know the ``form_start()`` and ``form_end()`` functions, but what do
 the other functions do?
 
-* ``form_errors(form)`` - Renders any errors global to the whole form
-  (field-specific errors are displayed next to each field);
+``form_errors(form)``
+    Renders any errors global to the whole form (field-specific errors are displayed
+    next to each field).
 
-* ``form_row(form.dueDate)`` - Renders the label, any errors, and the HTML
-  form widget for the given field (e.g. ``dueDate``) inside, by default, a
-  ``div`` element.
+``form_row(form.dueDate)``
+    Renders the label, any errors, and the HTML form widget for the given field
+    (e.g. ``dueDate``) inside, by default, a ``div`` element.
 
 The majority of the work is done by the ``form_row`` helper, which renders
 the label, errors and HTML form widget of each field inside a ``div`` tag by

book/http_cache.rst

@@ -202,34 +202,39 @@ method::
 
 Here is a list of the main options:
 
-* ``default_ttl``: The number of seconds that a cache entry should be
-  considered fresh when no explicit freshness information is provided in a
-  response. Explicit ``Cache-Control`` or ``Expires`` headers override this
-  value (default: ``0``);
-
-* ``private_headers``: Set of request headers that trigger "private"
-  ``Cache-Control`` behavior on responses that don't explicitly state whether
-  the response is ``public`` or ``private`` via a ``Cache-Control`` directive.
-  (default: ``Authorization`` and ``Cookie``);
-
-* ``allow_reload``: Specifies whether the client can force a cache reload by
-  including a ``Cache-Control`` "no-cache" directive in the request. Set it to
-  ``true`` for compliance with RFC 2616 (default: ``false``);
-
-* ``allow_revalidate``: Specifies whether the client can force a cache
-  revalidate by including a ``Cache-Control`` "max-age=0" directive in the
-  request. Set it to ``true`` for compliance with RFC 2616 (default: false);
-
-* ``stale_while_revalidate``: Specifies the default number of seconds (the
-  granularity is the second as the Response TTL precision is a second) during
-  which the cache can immediately return a stale response while it revalidates
-  it in the background (default: ``2``); this setting is overridden by the
-  ``stale-while-revalidate`` HTTP ``Cache-Control`` extension (see RFC 5861);
-
-* ``stale_if_error``: Specifies the default number of seconds (the granularity
-  is the second) during which the cache can serve a stale response when an
-  error is encountered (default: ``60``). This setting is overridden by the
-  ``stale-if-error`` HTTP ``Cache-Control`` extension (see RFC 5861).
+``default_ttl``
+    The number of seconds that a cache entry should be considered fresh when no
+    explicit freshness information is provided in a response. Explicit
+    ``Cache-Control`` or ``Expires`` headers override this value (default: ``0``).
+
+``private_headers``
+    Set of request headers that trigger "private" ``Cache-Control`` behavior on
+    responses that don't explicitly state whether the response is ``public`` or
+    ``private`` via a ``Cache-Control`` directive (default: ``Authorization``
+    and ``Cookie``).
+
+``allow_reload``
+    Specifies whether the client can force a cache reload by including a
+    ``Cache-Control`` "no-cache" directive in the request. Set it to ``true`` for
+    compliance with RFC 2616 (default: ``false``).
+
+``allow_revalidate``
+    Specifies whether the client can force a cache revalidate by including a
+    ``Cache-Control`` "max-age=0" directive in the request. Set it to ``true`` for
+    compliance with RFC 2616 (default: false).
+
+``stale_while_revalidate``
+    Specifies the default number of seconds (the granularity is the second as the
+    Response TTL precision is a second) during which the cache can immediately
+    return a stale response while it revalidates it in the background (default:
+    ``2``); this setting is overridden by the ``stale-while-revalidate`` HTTP
+    ``Cache-Control`` extension (see RFC 5861).
+
+``stale_if_error``
+    Specifies the default number of seconds (the granularity is the second) during
+    which the cache can serve a stale response when an error is encountered
+    (default: ``60``). This setting is overridden by the ``stale-if-error`` HTTP
+    ``Cache-Control`` extension (see RFC 5861).
 
 If ``debug`` is ``true``, Symfony automatically adds a ``X-Symfony-Cache``
 header to the response containing useful information about cache hits and
@@ -339,11 +344,12 @@ and then returned to every subsequent user who asked for their account page!
 
 To handle this situation, every response may be set to be public or private:
 
-* *public*: Indicates that the response may be cached by both private and
-  shared caches;
+*public*
+    Indicates that the response may be cached by both private and shared caches.
 
-* *private*: Indicates that all or part of the response message is intended
-  for a single user and must not be cached by a shared cache.
+*private*
+    Indicates that all or part of the response message is intended for a single
+    user and must not be cached by a shared cache.
 
 Symfony conservatively defaults each response to be private. To take advantage
 of shared caches (like the Symfony reverse proxy), the response will need
@@ -1033,12 +1039,14 @@ possible.
 
 The ``render_esi`` helper supports two other useful options:
 
-* ``alt``: used as the ``alt`` attribute on the ESI tag, which allows you
-  to specify an alternative URL to be used if the ``src`` cannot be found;
+``alt``
+    Used as the ``alt`` attribute on the ESI tag, which allows you to specify an
+    alternative URL to be used if the ``src`` cannot be found.
 
-* ``ignore_errors``: if set to true, an ``onerror`` attribute will be added
-  to the ESI with a value of ``continue`` indicating that, in the event of
-  a failure, the gateway cache will simply remove the ESI tag silently.
+``ignore_errors``
+    If set to true, an ``onerror`` attribute will be added to the ESI with a value
+    of ``continue`` indicating that, in the event of a failure, the gateway cache
+    will simply remove the ESI tag silently.
 
 .. index::
     single: Cache; Invalidation

book/http_fundamentals.rst

@@ -515,30 +515,32 @@ libraries that can be used inside *any* PHP project. These libraries, called
 the *Symfony Components*, contain something useful for almost any situation,
 regardless of how your project is developed. To name a few:
 
-* :doc:`HttpFoundation </components/http_foundation/introduction>` - Contains
-  the ``Request`` and ``Response`` classes, as well as other classes for handling
-  sessions and file uploads;
+:doc:`HttpFoundation </components/http_foundation/introduction>`
+    Contains the ``Request`` and ``Response`` classes, as well as other classes for
+    handling sessions and file uploads.
 
-* :doc:`Routing </components/routing/introduction>` - Powerful and fast routing system that
-  allows you to map a specific URI (e.g. ``/contact``) to some information
-  about how that request should be handled (e.g. execute the ``contactAction()``
-  method);
+:doc:`Routing </components/routing/introduction>`
+    Powerful and fast routing system that allows you to map a specific URI
+    (e.g. ``/contact``) to some information about how that request should be handled
+    (e.g. execute the ``contactAction()`` method).
 
-* :doc:`Form </components/form/introduction>` - A full-featured and flexible
-  framework for creating forms and handling form submissions;
+:doc:`Form </components/form/introduction>`
+    A full-featured and flexible framework for creating forms and handling form
+    submissions.
 
-* `Validator`_ - A system for creating rules about data and then validating
-  whether or not user-submitted data follows those rules;
+`Validator`_
+    A system for creating rules about data and then validating whether or not
+    user-submitted data follows those rules.
 
-* :doc:`Templating </components/templating/introduction>` - A toolkit for rendering
-  templates, handling template inheritance (i.e. a template is decorated with
-  a layout) and performing other common template tasks;
+:doc:`Templating </components/templating/introduction>`
+    A toolkit for rendering templates, handling template inheritance (i.e. a
+    template is decorated with a layout) and performing other common template tasks.
 
-* :doc:`Security </components/security/introduction>` - A powerful library for
-  handling all types of security inside an application;
+:doc:`Security </components/security/introduction>`
+    A powerful library for handling all types of security inside an application.
 
-* :doc:`Translation </components/translation/introduction>` - A framework for
-  translating strings in your application.
+:doc:`Translation </components/translation/introduction>`
+    A framework for translating strings in your application.
 
 Each and every one of these components is decoupled and can be used in *any*
 PHP project, regardless of whether or not you use the Symfony framework.

book/internals.rst

@@ -212,15 +212,15 @@ Each event thrown by the Kernel is a subclass of
 :class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`. This means that
 each event has access to the same basic information:
 
-* :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequestType`
-  - returns the *type* of the request (``HttpKernelInterface::MASTER_REQUEST``
-  or ``HttpKernelInterface::SUB_REQUEST``);
+:method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequestType`
+    Returns the *type* of the request (``HttpKernelInterface::MASTER_REQUEST`` or
+    ``HttpKernelInterface::SUB_REQUEST``).
 
-* :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getKernel`
-  - returns the Kernel handling the request;
+:method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getKernel`
+    Returns the Kernel handling the request.
 
-* :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequest`
-  - returns the current ``Request`` being handled.
+:method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequest`
+    Returns the current ``Request`` being handled.
 
 ``getRequestType()``
 ....................
@@ -347,18 +347,18 @@ The purpose of this event is to allow other systems to modify or replace the
 
 The FrameworkBundle registers several listeners:
 
-* :class:`Symfony\\Component\\HttpKernel\\EventListener\\ProfilerListener`:
-  collects data for the current request;
+:class:`Symfony\\Component\\HttpKernel\\EventListener\\ProfilerListener`
+    Collects data for the current request.
 
-* :class:`Symfony\\Bundle\\WebProfilerBundle\\EventListener\\WebDebugToolbarListener`:
-  injects the Web Debug Toolbar;
+:class:`Symfony\\Bundle\\WebProfilerBundle\\EventListener\\WebDebugToolbarListener`
+    Injects the Web Debug Toolbar.
 
-* :class:`Symfony\\Component\\HttpKernel\\EventListener\\ResponseListener`: fixes the
-  Response ``Content-Type`` based on the request format;
+:class:`Symfony\\Component\\HttpKernel\\EventListener\\ResponseListener`
+    Fixes the Response ``Content-Type`` based on the request format.
 
-* :class:`Symfony\\Component\\HttpKernel\\EventListener\\EsiListener`: adds a
-  ``Surrogate-Control`` HTTP header when the Response needs to be parsed for
-  ESI tags.
+:class:`Symfony\\Component\\HttpKernel\\EventListener\\EsiListener`
+    Adds a ``Surrogate-Control`` HTTP header when the Response needs to be parsed
+    for ESI tags.
 
 .. seealso::
 

book/page_creation.rst

@@ -488,13 +488,17 @@ you'll know where to find and put different types of files and why.
 Though entirely flexible, by default, each Symfony :term:`application` has
 the same basic and recommended directory structure:
 
-* ``app/``: This directory contains the application configuration;
+``app/``
+    This directory contains the application configuration.
 
-* ``src/``: All the project PHP code is stored under this directory;
+``src/``
+    All the project PHP code is stored under this directory.
 
-* ``vendor/``: Any vendor libraries are placed here by convention;
+``vendor/``
+    Any vendor libraries are placed here by convention.
 
-* ``web/``: This is the web root directory and contains any publicly accessible files;
+``web/``
+    This is the web root directory and contains any publicly accessible files.
 
 .. _the-web-directory:
 
@@ -554,11 +558,13 @@ needs to know about your application. You don't even need to worry about
 these methods when starting - Symfony fills them in for you with sensible
 defaults.
 
-* ``registerBundles()``: Returns an array of all bundles needed to run the
-  application (see :ref:`page-creation-bundles`);
+``registerBundles()``
+    Returns an array of all bundles needed to run the application (see
+    :ref:`page-creation-bundles`).
 
-* ``registerContainerConfiguration()``: Loads the main application configuration
-  resource file (see the `Application Configuration`_ section).
+``registerContainerConfiguration()``
+    Loads the main application configuration resource file (see the
+    `Application Configuration`_ section).
 
 In day-to-day development, you'll mostly use the ``app/`` directory to modify
 configuration and routing files in the ``app/config/`` directory (see
@@ -743,23 +749,27 @@ bundle system follows a set of conventions that help to keep code consistent
 between all Symfony bundles. Take a look at ``AcmeDemoBundle``, as it contains
 some of the most common elements of a bundle:
 
-* ``Controller/`` contains the controllers of the bundle (e.g. ``RandomController.php``);
+``Controller/``
+    Contains the controllers of the bundle (e.g. ``RandomController.php``).
 
-* ``DependencyInjection/`` holds certain dependency injection extension classes,
-  which may import service configuration, register compiler passes or more
-  (this directory is not necessary);
+``DependencyInjection/``
+    Holds certain dependency injection extension classes, which may import service
+    configuration, register compiler passes or more (this directory is not
+    necessary).
 
-* ``Resources/config/`` houses configuration, including routing configuration
-  (e.g. ``routing.yml``);
+``Resources/config/``
+    Houses configuration, including routing configuration (e.g. ``routing.yml``).
 
-* ``Resources/views/`` holds templates organized by controller name (e.g.
-  ``Hello/index.html.twig``);
+``Resources/views/``
+    Holds templates organized by controller name (e.g. ``Hello/index.html.twig``).
 
-* ``Resources/public/`` contains web assets (images, stylesheets, etc) and is
-  copied or symbolically linked into the project ``web/`` directory via
-  the ``assets:install`` console command;
+``Resources/public/``
+    Contains web assets (images, stylesheets, etc) and is copied or symbolically
+    linked into the project ``web/`` directory via the ``assets:install`` console
+    command.
 
-* ``Tests/`` holds all tests for the bundle.
+``Tests/``
+    Holds all tests for the bundle.
 
 A bundle can be as small or large as the feature it implements. It contains
 only the files you need and nothing else.

book/propel.rst

@@ -467,14 +467,22 @@ To add a hook, just add a new method to the object class::
 
 Propel provides the following hooks:
 
-* ``preInsert()`` code executed before insertion of a new object
-* ``postInsert()`` code executed after insertion of a new object
-* ``preUpdate()`` code executed before update of an existing object
-* ``postUpdate()`` code executed after update of an existing object
-* ``preSave()`` code executed before saving an object (new or existing)
-* ``postSave()`` code executed after saving an object (new or existing)
-* ``preDelete()`` code executed before deleting an object
-* ``postDelete()`` code executed after deleting an object
+``preInsert()``
+    Code executed before insertion of a new object.
+``postInsert()``
+    Code executed after insertion of a new object.
+``preUpdate()``
+    Code executed before update of an existing object.
+``postUpdate()``
+    Code executed after update of an existing object.
+``preSave()``
+    Code executed before saving an object (new or existing).
+``postSave()``
+    Code executed after saving an object (new or existing).
+``preDelete()``
+    Code executed before deleting an object.
+``postDelete()``
+    Code executed after deleting an object.
 
 Behaviors
 ---------

book/routing.rst

@@ -1036,12 +1036,15 @@ As you've seen, each routing parameter or default value is eventually available
 as an argument in the controller method. Additionally, there are three parameters
 that are special: each adds a unique piece of functionality inside your application:
 
-* ``_controller``: As you've seen, this parameter is used to determine which
-  controller is executed when the route is matched;
+``_controller``
+    As you've seen, this parameter is used to determine which controller is
+    executed when the route is matched.
 
-* ``_format``: Used to set the request format (:ref:`read more <book-routing-format-param>`);
+``_format``
+    Used to set the request format (:ref:`read more <book-routing-format-param>`).
 
-* ``_locale``: Used to set the locale on the request (:ref:`read more <book-translation-locale-url>`).
+``_locale``
+    Used to set the locale on the request (:ref:`read more <book-translation-locale-url>`).
 
 .. index::
    single: Routing; Controllers