Merge pull request symfony#2178 from WouterJ/split_yaml

weaverryan · weaverryan · commit a8c87a5365f7 · 2013-01-23T06:40:08.000-08:00
Splitted yaml component documentation
diff --git a/book/page_creation.rst b/book/page_creation.rst
@@ -830,7 +830,8 @@ options of each feature.
     three formats (YAML, XML and PHP). Each has its own advantages and
     disadvantages. The choice of which to use is up to you:
 
-    * *YAML*: Simple, clean and readable;
+    * *YAML*: Simple, clean and readable (learn more about yaml in
+    * ":doc:`/components/yaml/yaml_format`");
 
     * *XML*: More powerful than YAML at times and supports IDE autocompletion;
 
diff --git a/components/map.rst.inc b/components/map.rst.inc
@@ -82,6 +82,7 @@
 
   * :doc:`/components/templating`
 
-* **YAML**
+* :doc:`/components/yaml/index`
 
-  * :doc:`/components/yaml`
+  * :doc:`/components/yaml/introduction`
+  * :doc:`/components/yaml/yaml_format`
diff --git a/components/yaml/index.rst b/components/yaml/index.rst
@@ -0,0 +1,8 @@
+Yaml
+====
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    yaml_format
diff --git a/components/yaml/introduction.rst b/components/yaml/introduction.rst
@@ -21,6 +21,11 @@ as INI files.
 The Symfony2 YAML Component implements the YAML 1.2 version of the
 specification.
 
+.. tip::
+
+    Learn more about the Yaml component in the
+    :doc:`/components/yaml/yaml_format` article.
+
 Installation
 ------------
 
@@ -207,272 +212,5 @@ representation to the inline one:
         foo: bar
         bar: baz
 
-The YAML Format
----------------
-
-According to the official `YAML`_ website, YAML is "a human friendly data
-serialization standard for all programming languages".
-
-Even if the YAML format can describe complex nested data structure, this
-chapter only describes the minimum set of features needed to use YAML as a
-configuration file format.
-
-YAML is a simple language that describes data. As PHP, it has a syntax for
-simple types like strings, booleans, floats, or integers. But unlike PHP, it
-makes a difference between arrays (sequences) and hashes (mappings).
-
-Scalars
-~~~~~~~
-
-The syntax for scalars is similar to the PHP syntax.
-
-Strings
-.......
-
-.. code-block:: yaml
-
-    A string in YAML
-
-.. code-block:: yaml
-
-    'A singled-quoted string in YAML'
-
-.. tip::
-
-    In a single quoted string, a single quote ``'`` must be doubled:
-
-    .. code-block:: yaml
-
-        'A single quote '' in a single-quoted string'
-
-.. code-block:: yaml
-
-    "A double-quoted string in YAML\n"
-
-Quoted styles are useful when a string starts or ends with one or more
-relevant spaces.
-
-.. tip::
-
-    The double-quoted style provides a way to express arbitrary strings, by
-    using ``\`` escape sequences. It is very useful when you need to embed a
-    ``\n`` or a unicode character in a string.
-
-When a string contains line breaks, you can use the literal style, indicated
-by the pipe (``|``), to indicate that the string will span several lines. In
-literals, newlines are preserved:
-
-.. code-block:: yaml
-
-    |
-      \/ /| |\/| |
-      / / | |  | |__
-
-Alternatively, strings can be written with the folded style, denoted by ``>``,
-where each line break is replaced by a space:
-
-.. code-block:: yaml
-
-    >
-      This is a very long sentence
-      that spans several lines in the YAML
-      but which will be rendered as a string
-      without carriage returns.
-
-.. note::
-
-    Notice the two spaces before each line in the previous examples. They
-    won't appear in the resulting PHP strings.
-
-Numbers
-.......
-
-.. code-block:: yaml
-
-    # an integer
-    12
-
-.. code-block:: yaml
-
-    # an octal
-    014
-
-.. code-block:: yaml
-
-    # an hexadecimal
-    0xC
-
-.. code-block:: yaml
-
-    # a float
-    13.4
-
-.. code-block:: yaml
-
-    # an exponential number
-    1.2e+34
-
-.. code-block:: yaml
-
-    # infinity
-    .inf
-
-Nulls
-.....
-
-Nulls in YAML can be expressed with ``null`` or ``~``.
-
-Booleans
-........
-
-Booleans in YAML are expressed with ``true`` and ``false``.
-
-Dates
-.....
-
-YAML uses the ISO-8601 standard to express dates:
-
-.. code-block:: yaml
-
-    2001-12-14t21:59:43.10-05:00
-
-.. code-block:: yaml
-
-    # simple date
-    2002-12-14
-
-Collections
-~~~~~~~~~~~
-
-A YAML file is rarely used to describe a simple scalar. Most of the time, it
-describes a collection. A collection can be a sequence or a mapping of
-elements. Both sequences and mappings are converted to PHP arrays.
-
-Sequences use a dash followed by a space:
-
-.. code-block:: yaml
-
-    - PHP
-    - Perl
-    - Python
-
-The previous YAML file is equivalent to the following PHP code:
-
-.. code-block:: php
-
-    array('PHP', 'Perl', 'Python');
-
-Mappings use a colon followed by a space (``:`` ) to mark each key/value pair:
-
-.. code-block:: yaml
-
-    PHP: 5.2
-    MySQL: 5.1
-    Apache: 2.2.20
-
-which is equivalent to this PHP code:
-
-.. code-block:: php
-
-    array('PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20');
-
-.. note::
-
-    In a mapping, a key can be any valid scalar.
-
-The number of spaces between the colon and the value does not matter:
-
-.. code-block:: yaml
-
-    PHP:    5.2
-    MySQL:  5.1
-    Apache: 2.2.20
-
-YAML uses indentation with one or more spaces to describe nested collections:
-
-.. code-block:: yaml
-
-    "symfony 1.0":
-      PHP:    5.0
-      Propel: 1.2
-    "symfony 1.2":
-      PHP:    5.2
-      Propel: 1.3
-
-The following YAML is equivalent to the following PHP code:
-
-.. code-block:: php
-
-    array(
-      'symfony 1.0' => array(
-        'PHP'    => 5.0,
-        'Propel' => 1.2,
-      ),
-      'symfony 1.2' => array(
-        'PHP'    => 5.2,
-        'Propel' => 1.3,
-      ),
-    );
-
-There is one important thing you need to remember when using indentation in a
-YAML file: *Indentation must be done with one or more spaces, but never with
-tabulations*.
-
-You can nest sequences and mappings as you like:
-
-.. code-block:: yaml
-
-    'Chapter 1':
-      - Introduction
-      - Event Types
-    'Chapter 2':
-      - Introduction
-      - Helpers
-
-YAML can also use flow styles for collections, using explicit indicators
-rather than indentation to denote scope.
-
-A sequence can be written as a comma separated list within square brackets
-(``[]``):
-
-.. code-block:: yaml
-
-    [PHP, Perl, Python]
-
-A mapping can be written as a comma separated list of key/values within curly
-braces (``{}``):
-
-.. code-block:: yaml
-
-    { PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }
-
-You can mix and match styles to achieve a better readability:
-
-.. code-block:: yaml
-
-    'Chapter 1': [Introduction, Event Types]
-    'Chapter 2': [Introduction, Helpers]
-
-.. code-block:: yaml
-
-    "symfony 1.0": { PHP: 5.0, Propel: 1.2 }
-    "symfony 1.2": { PHP: 5.2, Propel: 1.3 }
-
-Comments
-~~~~~~~~
-
-Comments can be added in YAML by prefixing them with a hash mark (``#``):
-
-.. code-block:: yaml
-
-    # Comment on a line
-    "symfony 1.0": { PHP: 5.0, Propel: 1.2 } # Comment at the end of a line
-    "symfony 1.2": { PHP: 5.2, Propel: 1.3 }
-
-.. note::
-
-    Comments are simply ignored by the YAML parser and do not need to be
-    indented according to the current level of nesting in a collection.
-
 .. _YAML: http://yaml.org/
 .. _Packagist: https://packagist.org/packages/symfony/yaml
diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst
diff --git a/redirection_map b/redirection_map
