Improvements to registering an extension (#2)

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets | #9644 (symfony) and #3231 (symfony-docs)

1. The original text is good but the topic of that paragraph is not "extension conventions" but "registering an extension" (i.e. if you follow these conventions then register goes like so ..)

2. Cleaned up different terminology "Conventions" v "Standards" -> just conventions now

3. Move this part to a more logical place. First create then register, then modify for additional needs.

Author: flip111

cookbook/bundles/extension.rst

@@ -177,6 +177,49 @@ You can begin specifying configuration under this namespace immediately:
     array. You can still provide some sensible defaults for your bundle if
     you want.
 
+Registering the Extension class
+-------------------------------
+
+An Extension class will automatically be registered by Symfony2 when following these simple conventions:
+
+* The extension must be stored in the ``DependencyInjection`` sub-namespace;
+
+* The extension must be named after the bundle name and suffixed with
+  ``Extension`` (``AcmeHelloExtension`` for ``AcmeHelloBundle``);
+
+* The extension should provide an XSD schema.
+
+Manually registering an Extension class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To manually register an extension class override the
+:method:`Bundle::build() <Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build>`
+method in your bundle::
+
+    // ...
+    use Acme\HelloBundle\DependencyInjection\UnconventionalExtensionClass;
+
+    class AcmeHelloBundle extends Bundle
+    {
+        public function build(ContainerBuilder $container)
+        {
+            parent::build($container);
+
+            // register extensions that do not follow the conventions manually
+            $container->registerExtension(new UnconventionalExtensionClass());
+        }
+    }
+
+In this case, the extension class must also implement a ``getAlias()`` method
+and return a unique alias named after the bundle (e.g. ``acme_hello``). This
+is required because the class name doesn't follow the conventions by ending
+in ``Extension``.
+
+Additionally, the ``load()`` method of your extension will *only* be called
+if the user specifies the ``acme_hello`` alias in at least one configuration
+file. Once again, this is because the Extension class doesn't follow the
+conventions set out above, so nothing happens automatically.
+
 Parsing the ``$configs`` Array
 ------------------------------
 
@@ -511,9 +554,6 @@ For more details, see :doc:`/cookbook/bundles/prepend_extension`.
 Default Configuration Dump
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 2.1
-    The ``config:dump-reference`` command was added in Symfony 2.1
-
 The ``config:dump-reference`` command allows a bundle's default configuration to
 be output to the console in YAML.
 
@@ -561,46 +601,5 @@ command.
 .. index::
    pair: Convention; Configuration
 
-Extension Conventions
----------------------
-
-When creating an extension, follow these simple conventions:
-
-* The extension must be stored in the ``DependencyInjection`` sub-namespace;
-
-* The extension must be named after the bundle name and suffixed with
-  ``Extension`` (``AcmeHelloExtension`` for ``AcmeHelloBundle``);
-
-* The extension should provide an XSD schema.
-
-If you follow these simple conventions, your extensions will be registered
-automatically by Symfony2. If not, override the
-:method:`Bundle::build() <Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build>`
-method in your bundle::
-
-    // ...
-    use Acme\HelloBundle\DependencyInjection\UnconventionalExtensionClass;
-
-    class AcmeHelloBundle extends Bundle
-    {
-        public function build(ContainerBuilder $container)
-        {
-            parent::build($container);
-
-            // register extensions that do not follow the conventions manually
-            $container->registerExtension(new UnconventionalExtensionClass());
-        }
-    }
-
-In this case, the extension class must also implement a ``getAlias()`` method
-and return a unique alias named after the bundle (e.g. ``acme_hello``). This
-is required because the class name doesn't follow the standards by ending
-in ``Extension``.
-
-Additionally, the ``load()`` method of your extension will *only* be called
-if the user specifies the ``acme_hello`` alias in at least one configuration
-file. Once again, this is because the Extension class doesn't follow the
-standards set out above, so nothing happens automatically.
-
 .. _`FrameworkBundle Configuration`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php
 .. _`TwigBundle Configuration`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/TwigBundle/DependencyInjection/Configuration.php