From 598e522f3f68682e11fd3e4d418b2fd55eca77ae Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 6 Mar 2015 17:34:07 +0100 Subject: [PATCH 1/4] Updated documentation standards (code examples and English use) --- contributing/documentation/standards.rst | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 39d073ec0da..ce68e98d2a3 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -8,7 +8,8 @@ Sphinx ------ * The following characters are chosen for different heading levels: level 1 - is ``=``, level 2 ``-``, level 3 ``~``, level 4 ``.`` and level 5 ``"``; + is ``=`` (equal sign), level 2 ``-`` (dash), level 3 ``~`` (tilde), level 4 + ``.`` (dot) and level 5 ``"`` (double quote); * Each line should break approximately after the first word that crosses the 72nd character (so most lines end up being 72-78 characters); * The ``::`` shorthand is *preferred* over ``.. code-block:: php`` to begin a PHP @@ -48,6 +49,12 @@ Example Code Examples ------------- +* The code examples should look real for a web application context. Avoid abstract + and puerile examples (``foo``, ``bar``, ``demo``, etc.); +* Use ``Acme`` when the code requires to explicit a vendor name; +* The code should follow the :doc:`Symfony Best Practices `. + Unless the example requires to use a custom bundle, make sure to always use the + ``AppBundle`` bundle to store your code; * The code follows the :doc:`Symfony Coding Standards ` as well as the `Twig Coding Standards`_; * To avoid horizontal scrolling on code blocks, we prefer to break a line @@ -137,8 +144,17 @@ Files and Directories English Language Standards -------------------------- -* **English Dialect**: use the United States English dialect, commonly called - `American English`_. +Symfony documentation uses the United States English dialect, commonly called +`American English`_. + +Unlike most popular languages, the English language doesn't have a central +language authority and there is no official grammar or dictionary. Symfony +documentation uses the `American English Oxford Dictionary`_ to resolve disputes +over common words. In case a technical word isn't included in the dictionary yet, +Symfony Documentation maintainers will decide over the disputes. + +In addition, documentation contents should follow these rules: + * **Section titles**: use a variant of the title case, where the first word is always capitalized and all other words are capitalized, except for the closed-class words (read Wikipedia article about `headings and titles`_). @@ -160,6 +176,7 @@ English Language Standards .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html .. _`American English`: http://en.wikipedia.org/wiki/American_English +.. _`American English Oxford Dictionary`: http://www.oxforddictionaries.com/ .. _`headings and titles`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles .. _`Serial (Oxford) Commas`: http://en.wikipedia.org/wiki/Serial_comma .. _`nosism`: http://en.wikipedia.org/wiki/Nosism From 9c443518b0f4ccd9f6301514f126b2af70754671 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 7 Mar 2015 17:14:50 +0100 Subject: [PATCH 2/4] Rewords, tweaks and fixes --- contributing/documentation/standards.rst | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index ce68e98d2a3..a0e1a611a4d 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -49,14 +49,14 @@ Example Code Examples ------------- +* The code follows the :doc:`Symfony Coding Standards ` + as well as the `Twig Coding Standards`_; * The code examples should look real for a web application context. Avoid abstract - and puerile examples (``foo``, ``bar``, ``demo``, etc.); -* Use ``Acme`` when the code requires to explicit a vendor name; -* The code should follow the :doc:`Symfony Best Practices `. + or puerile examples (``foo``, ``bar``, ``demo``, etc.); +* The code should follow the :doc:`Symfony Best Practices `. Unless the example requires to use a custom bundle, make sure to always use the ``AppBundle`` bundle to store your code; -* The code follows the :doc:`Symfony Coding Standards ` - as well as the `Twig Coding Standards`_; +* Use ``Acme`` when the code requires a vendor name; * To avoid horizontal scrolling on code blocks, we prefer to break a line correctly if it crosses the 85th character; * When you fold one or more lines of code, place ``...`` in a comment at the point @@ -145,13 +145,9 @@ English Language Standards -------------------------- Symfony documentation uses the United States English dialect, commonly called -`American English`_. - -Unlike most popular languages, the English language doesn't have a central -language authority and there is no official grammar or dictionary. Symfony -documentation uses the `American English Oxford Dictionary`_ to resolve disputes -over common words. In case a technical word isn't included in the dictionary yet, -Symfony Documentation maintainers will decide over the disputes. +`American English`_. Disputes over vocabulary will always be resolved using the +`American English Oxford Dictionary`_ reference. Disputes over neologisms not +included yet in the dictionary will be resolved by Symfony Documentation maintainers. In addition, documentation contents should follow these rules: From b96abbb3ae62a7ff23356bb44d17a2e2263b72f4 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 9 Mar 2015 11:59:33 +0100 Subject: [PATCH 3/4] Reworded the paragraph about enforcing an English reference --- contributing/documentation/standards.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index a0e1a611a4d..db3e0624585 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -145,11 +145,10 @@ English Language Standards -------------------------- Symfony documentation uses the United States English dialect, commonly called -`American English`_. Disputes over vocabulary will always be resolved using the -`American English Oxford Dictionary`_ reference. Disputes over neologisms not -included yet in the dictionary will be resolved by Symfony Documentation maintainers. +`American English`_. The `American English Oxford Dictionary`_ is used as the +vocabulary reference. -In addition, documentation contents should follow these rules: +In addition, documentation follows these rules: * **Section titles**: use a variant of the title case, where the first word is always capitalized and all other words are capitalized, except for From e5b6145aaba6bd93e7bdc885eb2e60b4135f5df3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 9 Mar 2015 12:00:22 +0100 Subject: [PATCH 4/4] Improved the URL of the English reference dictionary --- contributing/documentation/standards.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index db3e0624585..e87e065c8ca 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -171,7 +171,7 @@ In addition, documentation follows these rules: .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html .. _`American English`: http://en.wikipedia.org/wiki/American_English -.. _`American English Oxford Dictionary`: http://www.oxforddictionaries.com/ +.. _`American English Oxford Dictionary`: http://www.oxforddictionaries.com/definition/american_english/ .. _`headings and titles`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles .. _`Serial (Oxford) Commas`: http://en.wikipedia.org/wiki/Serial_comma .. _`nosism`: http://en.wikipedia.org/wiki/Nosism pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy