[components][config] Tweaks for #1550 - mostly making lines shorter, …

…other small tweaks

components/config/caching.rst

@@ -4,23 +4,23 @@
 Caching based on resources
 ==========================
 
-When all configuration resources are loaded, you may want to process the configuration values and
-combine them all in one file. This file acts like a cache. Its contents don’t have to be
-regenerated every time the application runs – only when the configuration resources are modified.
-
-For example, the Symfony Routing component allows you to load all routes, and then dump a URL
-matcher or a URL generator based on these routes. In this case, when one of the resources is
-modified (and you are working in a development environment), the generated file should be
-invalidated and regenerated. This can be accomplished by making use of the
-:class:`Symfony\\Component\\Config\\ConfigCache` class.
-
-The example below shows you how to collect resources, then generate some code based on the
-resources that were loaded, and write this code to the cache. The cache also receives the
-collection of resources that were used for generating the code. By looking at the "last modified"
-timestamp of these resources, the cache can tell if it is still fresh or that its contents should
-be regenerated.
-
-.. code-block:: php
+When all configuration resources are loaded, you may want to process the configuration
+values and combine them all in one file. This file acts like a cache. Its
+contents don’t have to be regenerated every time the application runs – only
+when the configuration resources are modified.
+
+For example, the Symfony Routing component allows you to load all routes,
+and then dump a URL matcher or a URL generator based on these routes. In
+this case, when one of the resources is modified (and you are working in a
+development environment), the generated file should be invalidated and regenerated.
+This can be accomplished by making use of the :class:`Symfony\\Component\\Config\\ConfigCache`
+class.
+
+The example below shows you how to collect resources, then generate some code
+based on the resources that were loaded, and write this code to the cache. The
+cache also receives the collection of resources that were used for generating
+the code. By looking at the "last modified" timestamp of these resources,
+the cache can tell if it is still fresh or that its contents should be regenerated::
 
     use Symfony\Component\Config\ConfigCache;
     use Symfony\Component\Config\Resource\FileResource;
@@ -50,7 +50,8 @@ be regenerated.
     // you may want to require the cached code:
     require $cachePath;
 
-In debug mode, a ``.meta`` file will be created in the same directory as the cache file itself.
-This ``.meta`` file contains the serialized resources, whose timestamps are used to determine if
-the cache is still fresh. When not in debug mode, the cache is considered to be "fresh" as soon
-as it exists, and therefore no ``.meta`` file will be generated.
+In debug mode, a ``.meta`` file will be created in the same directory as the
+cache file itself. This ``.meta`` file contains the serialized resources,
+whose timestamps are used to determine if the cache is still fresh. When not
+in debug mode, the cache is considered to be "fresh" as soon as it exists,
+and therefore no ``.meta`` file will be generated.

components/config/definition.rst

@@ -7,12 +7,13 @@ Define and process configuration values
 Validate configuration values
 -----------------------------
 
-After loading configuration values from all kinds of resources, the values and their structure can
-be validated using the "Definition" part of the Config Component. Configuration values are usually
-expected to show some kind of hierarchy. Also, values should be of a certain type, be restricted in
-number or be one of a given set of values. For example, the following configuration (in Yaml) shows
-a clear hierarchy and some validation rules that should be applied to it (like: "the value for
-'auto_connect' must be a boolean value"):
+After loading configuration values from all kinds of resources, the values
+and their structure can be validated using the "Definition" part of the Config
+Component. Configuration values are usually expected to show some kind of
+hierarchy. Also, values should be of a certain type, be restricted in number
+or be one of a given set of values. For example, the following configuration
+(in Yaml) shows a clear hierarchy and some validation rules that should be
+applied to it (like: "the value for ``auto_connect`` must be a boolean value"):
 
 .. code-block:: yaml
 
@@ -31,22 +32,21 @@ a clear hierarchy and some validation rules that should be applied to it (like:
             username: user
             password: pass
 
-When loading multiple configuration files, it should be possible to merge and overwrite some
-values. Other values should not be merged and stay as they are when first encountered. Also,
-some keys are only available, when another key has a specific value (in the sample configuration
-above: the "memory" key only makes sense when the "driver" is "sqlite").
+When loading multiple configuration files, it should be possible to merge
+and overwrite some values. Other values should not be merged and stay as
+they are when first encountered. Also, some keys are only available when
+another key has a specific value (in the sample configuration above: the
+``memory`` key only makes sense when the ``driver`` is ``sqlite``).
 
 Define a hierarchy of configuration values using the TreeBuilder
 ----------------------------------------------------------------
 
 All the rules concerning configuration values can be defined using the
 :class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder`.
 
-A :class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder` instance should be returned
-from a custom ``Configuration`` class which implements the
-:class:`Symfony\\Component\\Config\\Definition\\ConfigurationInterface`:
-
-.. code-block:: php
+A :class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder` instance
+should be returned from a custom ``Configuration`` class which implements the
+:class:`Symfony\\Component\\Config\\Definition\\ConfigurationInterface`::
 
     namespace Acme\DatabaseConfiguration;
 
@@ -72,11 +72,9 @@ Add node definitions to the tree
 Variable nodes
 ~~~~~~~~~~~~~~
 
-A tree contains node definitions which can be layed out in a semantic way. This means, using
-indentation and the fluent notation, it is possible to reflect the real structure of the
-configuration values:
-
-.. code-block:: php
+A tree contains node definitions which can be layed out in a semantic way.
+This means, using indentation and the fluent notation, it is possible to
+reflect the real structure of the configuration values::
 
     $rootNode
         ->children()
@@ -89,15 +87,15 @@ configuration values:
         ->end()
     ;
 
-The root node itself is an array node, and has children, like the boolean node "auto_connect"
-and the scalar node "default_connection". In general: after defining a node, a call to ``end()``
-takes you one step up in the hierarchy.
+The root node itself is an array node, and has children, like the boolean
+node ``auto_connect`` and the scalar node ``default_connection``. In general:
+after defining a node, a call to ``end()`` takes you one step up in the hierarchy.
 
 Array nodes
 ~~~~~~~~~~~
 
-It is possible to add a deeper level to the hierarchy, by adding an array node. The array node
-itself, may have a pre-defined set of variable nodes:
+It is possible to add a deeper level to the hierarchy, by adding an array
+node. The array node itself, may have a pre-defined set of variable nodes:
 
 .. code-block:: php
 
@@ -116,7 +114,7 @@ Or you may define a prototype for each node inside an array node:
 
     $rootNode
         ->arrayNode('connections')
-            ->prototype('array)
+            ->prototype('array')
                 ->children()
                     ->scalarNode('driver')->end()
                     ->scalarNode('host')->end()
@@ -127,17 +125,18 @@ Or you may define a prototype for each node inside an array node:
         ->end()
     ;
 
-A prototype can be used to add a definition which may be repeated many times inside the current
-node. According to the prototype definition in the example above, it is possible to have multiple
-connection arrays (containing a "driver", "host", etc.).
+A prototype can be used to add a definition which may be repeated many times
+inside the current node. According to the prototype definition in the example
+above, it is possible to have multiple connection arrays (containing a ``driver``,
+``host``, etc.).
 
 Array node options
 ~~~~~~~~~~~~~~~~~~
 
 Before defining the children of an array node, you can provide options like:
 
 ``useAttributeAsKey()``
-    Provide the name of a childnode, whose value should be used as the key in the resulting array
+    Provide the name of a child node, whose value should be used as the key in the resulting array
 ``requiresAtLeastOneElement()``
     There should be at least one element in the array (works only when ``isRequired()`` is also
     called).
@@ -163,7 +162,8 @@ An example of this:
 Default and required values
 ---------------------------
 
-For all node types, it is possible to define default values and replacement values in case a node
+For all node types, it is possible to define default values and replacement
+values in case a node
 has a certain value:
 
 ``defaultValue()``
@@ -173,9 +173,9 @@ has a certain value:
 ``cannotBeEmpty()``
     May not contain an empty value
 ``default*()``
-    (``Null``, ``True``, ``False``), shortcut for ``defaultValue()``
+    (``null``, ``true``, ``false``), shortcut for ``defaultValue()``
 ``treat*Like()``
-    (``Null``, ``True``, ``False``), provide a replacement value in case the value is *.
+    (``null``, ``true``, ``false``), provide a replacement value in case the value is ``*.``
 
 .. code-block:: php
 
@@ -204,8 +204,8 @@ Merging options
 Extra options concerning the merge process may be provided. For arrays:
 
 ``performNoDeepMerging()``
-    When the value is also defined in a second configuration array, don’t try to merge an array,
-    but overwrite it entirely
+    When the value is also defined in a second configuration array, don’t
+    try to merge an array, but overwrite it entirely
 
 For all nodes:
 
@@ -216,11 +216,9 @@ Validation rules
 ----------------
 
 More advanced validation rules can be provided using the
-:class:`Symfony\\Component\\Config\\Definition\\Builder\\ExprBuilder`. This builder implements a
-fluent interface for a well-known control structure. The builder is used for adding advanced
-validation rules to node definitions, like:
-
-.. code-block:: php
+:class:`Symfony\\Component\\Config\\Definition\\Builder\\ExprBuilder`. This
+builder implements a fluent interface for a well-known control structure.
+The builder is used for adding advanced validation rules to node definitions, like::
 
     $rootNode
         ->arrayNode('connection')
@@ -236,7 +234,8 @@ validation rules to node definitions, like:
         ->end()
     ;
 
-A validation rule always has an "if" part. You can specify this part in the following ways:
+A validation rule always has an "if" part. You can specify this part in the
+following ways:
 
 - ``ifTrue()``
 - ``ifString()``
@@ -253,19 +252,19 @@ A validation rule also requires a "then" part:
 - ``thenInvalid()``
 - ``thenUnset()``
 
-Usually, "then" is a closure. Its return value will be used as a new value for the node, instead
+Usually, "then" is a closure. Its return value will be used as a new value
+for the node, instead
 of the node's original value.
 
 Processing configuration values
 -------------------------------
 
-The :class:`Symfony\\Component\\Config\\Definition\\Processor` uses the tree as it was built
-using the :class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder` to process
-multiple arrays of configuration values that should be merged. If any value is not of the
-expected type, is mandatory and yet undefined, or could not be validated in some other way,
-an exception will be thrown. Otherwise the result is a clean array of configuration values.
-
-.. code-block:: php
+The :class:`Symfony\\Component\\Config\\Definition\\Processor` uses the tree
+as it was built using the :class:`Symfony\\Component\\Config\\Definition\\Builder\\TreeBuilder`
+to process multiple arrays of configuration values that should be merged.
+If any value is not of the expected type, is mandatory and yet undefined,
+or could not be validated in some other way, an exception will be thrown.
+Otherwise the result is a clean array of configuration values::
 
     use Symfony\Component\Yaml\Yaml;
     use Symfony\Component\Config\Definition\Processor;

components/config/introduction.rst

@@ -7,9 +7,9 @@ The Config Component
 Introduction
 ------------
 
-The Config Component provides several classes to help you find, load, combine, autofill and
-validate configuration values of any kind, whatever their source may be (Yaml, XML, INI files, or
-for instance a database).
+The Config Component provides several classes to help you find, load, combine,
+autofill and validate configuration values of any kind, whatever their source
+may be (Yaml, XML, INI files, or for instance a database).
 
 Installation
 ------------
@@ -19,3 +19,10 @@ You can install the component in many different ways:
 * Use the official Git repository (https://github.com/symfony/Config);
 * Install it via PEAR ( `pear.symfony.com/Config`);
 * Install it via Composer (`symfony/config` on Packagist).
+
+Sections
+--------
+
+* :doc:`/components/config/resources`
+* :doc:`/components/config/caching`
+* :doc:`/components/config/definition`

components/config/resources.rst

@@ -7,10 +7,8 @@ Loading resources
 Locating resources
 ------------------
 
-Loading the configuration normally starts with a search for resources – in most cases: files. This
-can be done with the :class:`Symfony\\Component\\Config\\FileLocator`:
-
-.. code-block:: php
+Loading the configuration normally starts with a search for resources – in
+most cases: files. This can be done with the :class:`Symfony\\Component\\Config\\FileLocator`::
 
     use Symfony\Component\Config\FileLocator;
 
@@ -19,21 +17,20 @@ can be done with the :class:`Symfony\\Component\\Config\\FileLocator`:
     $locator = new FileLocator($configDirectories);
     $yamlUserFiles = $locator->locate('users.yml', null, false);
 
-The locator receives a collection of locations where it should look for files. The first argument of
-``locate()`` is the name of the file to look for. The second argument may be the current path and
-when supplied, the locator will look in this directory first.
-The third argument indicates whether or not the locator should return the first file it has found,
-or an array containing all matches.
+The locator receives a collection of locations where it should look for files.
+The first argument of ``locate()`` is the name of the file to look for. The
+second argument may be the current path and when supplied, the locator will
+look in this directory first. The third argument indicates whether or not the
+locator should return the first file it has found, or an array containing
+all matches.
 
 Resource loaders
 ----------------
 
-For each type of resource (Yaml, XML, annotation, etc.) a loader must be defined. Each loader should
-implement :class:`Symfony\\Component\\Config\\Loader\\LoaderInterface` or extend the abstract
-:class:`Symfony\\Component\\Config\\Loader\\FileLoader` class, which allows for recursively
-importing other resources.
-
-.. code-block:: php
+For each type of resource (Yaml, XML, annotation, etc.) a loader must be defined.
+Each loader should implement :class:`Symfony\\Component\\Config\\Loader\\LoaderInterface`
+or extend the abstract :class:`Symfony\\Component\\Config\\Loader\\FileLoader`
+class, which allows for recursively importing other resources::
 
     use Symfony\Component\Config\Loader\FileLoader;
     use Symfony\Component\Yaml\Yaml;
@@ -60,16 +57,16 @@ importing other resources.
 Finding the right loader
 ------------------------
 
-The :class:`Symfony\\Component\\Config\\Loader\\LoaderResolver` receives as its first constructor
-argument a collection of loaders. When a resource (for instance an XML file) should be loaded,
-it loops through this collection of loaders and returns the loader which supports this
-particular resource type.
-
-The :class:`Symfony\\Component\\Config\\Loader\\DelegatingLoader` makes use of the :class:`Symfony\\Component\\Config\\Loader\\LoaderResolver`. When it is asked to load a resource,
-it delegates this question to the :class:`Symfony\\Component\\Config\\Loader\\LoaderResolver`.
-In case the resolver has found a suitable loader, this loader will be asked to load the resource.
+The :class:`Symfony\\Component\\Config\\Loader\\LoaderResolver` receives as
+its first constructor argument a collection of loaders. When a resource (for
+instance an XML file) should be loaded, it loops through this collection
+of loaders and returns the loader which supports this particular resource type.
 
-.. code-block:: php
+The :class:`Symfony\\Component\\Config\\Loader\\DelegatingLoader` makes use
+of the :class:`Symfony\\Component\\Config\\Loader\\LoaderResolver`. When
+it is asked to load a resource, it delegates this question to the
+:class:`Symfony\\Component\\Config\\Loader\\LoaderResolver`. In case the resolver
+has found a suitable loader, this loader will be asked to load the resource::
 
     use Symfony\Component\Config\Loader\LoaderResolver;
     use Symfony\Component\Config\Loader\DelegatingLoader;