Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Splitted yaml component documentation #2178

Merged
merged 4 commits into from

2 participants

@WouterJ
Collaborator
Q A
Doc fix? yes
New docs? no
Applies to all
Closes tickets ~

We have learned that smaller documents are more readable and user friendly than long documents. I have splitted the Yaml documentation in 2 parts: the component and the yaml format. This makes it better findable and readable.

@weaverryan weaverryan merged commit a8c87a5 into symfony:2.0
@weaverryan
Collaborator

Nice idea Wouter - merged in!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
View
3  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;
View
5 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`
View
8 components/yaml/index.rst
@@ -0,0 +1,8 @@
+Yaml
+====
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction
+ yaml_format
View
272 components/yaml.rst → 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
View
269 components/yaml/yaml_format.rst
@@ -0,0 +1,269 @@
+.. index::
+ single: Yaml; Yaml Format
+
+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.
View
3  redirection_map
@@ -17,4 +17,5 @@
/components/http_foundation /components/http_foundation/introduction
/components/console /components/console/introduction
/components/routing /components/routing/introduction
-/cookbook/console/generating_urls /cookbook/console/sending_emails
+/cookbook/console/generating_urls /cookbook/console/sending_emails
+/components/yaml /components/yaml/introduction
Something went wrong with that request. Please try again.