@@ -119,7 +119,8 @@ Markup format Use it to display
119119Adding Links
120120~~~~~~~~~~~~
121121
122- **Internal links ** to other documentation pages use the following syntax:
122+ The most common type of links are **internal links ** to other documentation pages,
123+ which use the following syntax:
123124
124125..code-block ::rst
125126
@@ -135,23 +136,25 @@ The page name should not include the file extension (``.rst``). For example:
135136
136137 :doc:`/cookbook/configuration/environments`
137138
138- Although they are technically correct, avoid theuse ofrelative internal links
139- such as the following :
139+ The title of the linked page will be automatically used as thetext ofthe link.
140+ If you want to modify that title, use this alternative syntax :
140141
141142..code-block ::rst
142143
143- :doc:`controller `
144+ :doc:`Spooling Email </cookbook/email/spool> `
144145
145- :doc:`event_dispatcher/introduction`
146+ .. note ::
146147
147- :doc:`environments`
148+ Although they are technically correct, avoid the use of relative internal
149+ links such as the following:
148150
149-
150- If you want to modify that title, use this alternative syntax:
151+ ..code-block ::rst
151152
152- .. code-block :: rst
153+ :doc:`controller`
153154
154- :doc:`Spooling Email </cookbook/email/spool>`
155+ :doc:`event_dispatcher/introduction`
156+
157+ :doc:`environments`
155158
156159Links to the API ** follow a different syntax, where you must specify the type
157160of linked resource (``namespace ``, ``class `` or ``method ``):
@@ -178,15 +181,15 @@ New Features or Behavior Changes
178181~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
179182
180183If you're documenting a brand new feature or a change that's been made in
181- Symfony2 , you should precede your description of the change with a
184+ Symfony , you should precede your description of the change with a
182185``.. versionadded:: 2.X `` directive and a short description:
183186
184187..code-block ::text
185188
186189 .. versionadded:: 2.3
187190 The ``askHiddenResponse`` method was introduced in Symfony 2.3.
188191
189- You can also ask a question and hide the response. This is particularly...
192+ You can also ask a question and hide the response. This is particularly [ ...]
190193
191194briefly * describe
192195how the behavior has changed.
@@ -197,9 +200,9 @@ how the behavior has changed.
197200 The ``include()`` function is a new Twig feature that's available in
198201 Symfony 2.3. Prior, the ``{% include %}`` tag was used.
199202
200- Symfony2 is released (e.g. 2.4, 2.5, etc),
203+ Symfony is released (e.g. 2.4, 2.5, etc),
201204a new branch of the documentation is created from the ``master `` branch.
202- At this point, all the ``versionadded `` tags forSymfony2 versions that have
205+ At this point, all the ``versionadded `` tags forSymfony versions that have
203206reached end-of-life will be removed. For example, if Symfony 2.5 were released
204207today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded ``
205208tags would be removed from the new 2.5 branch.