Merge branch '6.4' into 7.0

* 6.4: [RFC] Add alt texts to images
alzee · Sep 1, 2023 · 565af2b · 565af2b
2 parents 3b26e4c + f471484
commit 565af2b
Show file tree

Hide file tree

Showing 74 changed files with 4,264 additions and 280 deletions.
diff --git a/_images/contributing/docs-github-edit-page.png b/_images/contributing/docs-github-edit-page.png
diff --git a/_images/doctrine/mapping_relations.png b/_images/doctrine/mapping_relations.png
diff --git a/_images/doctrine/mapping_relations.svg b/_images/doctrine/mapping_relations.svg
diff --git a/_images/doctrine/mapping_relations_proxy.png b/_images/doctrine/mapping_relations_proxy.png
diff --git a/_images/doctrine/mapping_relations_proxy.svg b/_images/doctrine/mapping_relations_proxy.svg
diff --git a/_images/doctrine/mapping_single_entity.png b/_images/doctrine/mapping_single_entity.png
diff --git a/_images/doctrine/mapping_single_entity.svg b/_images/doctrine/mapping_single_entity.svg
diff --git a/_images/form/data-transformer-types.png b/_images/form/data-transformer-types.png
diff --git a/_images/form/data-transformer-types.svg b/_images/form/data-transformer-types.svg
diff --git a/_images/form/form_prepopulation_workflow.svg b/_images/form/form_prepopulation_workflow.svg
diff --git a/_images/form/form_submission_workflow.svg b/_images/form/form_submission_workflow.svg
diff --git a/_images/form/form_workflow.svg b/_images/form/form_workflow.svg
diff --git a/_images/http/xkcd-full.png b/_images/http/xkcd-full.png
diff --git a/_images/http/xkcd-full.svg b/_images/http/xkcd-full.svg
diff --git a/_images/http/xkcd-request.png b/_images/http/xkcd-request.png
diff --git a/_images/http/xkcd-request.svg b/_images/http/xkcd-request.svg
diff --git a/_images/mercure/discovery.png b/_images/mercure/discovery.png
diff --git a/_images/mercure/discovery.svg b/_images/mercure/discovery.svg
diff --git a/_images/mercure/hub.svg b/_images/mercure/hub.svg
diff --git a/_images/mercure/schema.png b/_images/mercure/schema.png
diff --git a/_images/sources/README.md b/_images/sources/README.md
@@ -39,7 +39,9 @@ Use the following snippet to embed the diagram in the docs:
 ```
 .. raw:: html
 
-    <object data="../_images/<folder-name>/<diagram-file-name>.svg" type="image/svg+xml"></object>
+    <object data="../_images/<folder-name>/<diagram-file-name>.svg" type="image/svg+xml"
+        alt="<alt description>"
+    ></object>
 ```
 
 ### Reasoning

diff --git a/_images/sources/doctrine/mapping_relations.dia b/_images/sources/doctrine/mapping_relations.dia
diff --git a/_images/sources/doctrine/mapping_relations_proxy.dia b/_images/sources/doctrine/mapping_relations_proxy.dia
diff --git a/_images/sources/doctrine/mapping_single_entity.dia b/_images/sources/doctrine/mapping_single_entity.dia
diff --git a/_images/sources/form/data-transformer-types.dia b/_images/sources/form/data-transformer-types.dia
diff --git a/_images/sources/form/form_prepopulation_workflow.dia b/_images/sources/form/form_prepopulation_workflow.dia
diff --git a/_images/sources/form/form_submission_workflow.dia b/_images/sources/form/form_submission_workflow.dia
diff --git a/_images/sources/form/form_workflow.dia b/_images/sources/form/form_workflow.dia
diff --git a/_images/sources/http/xkcd-full.dia b/_images/sources/http/xkcd-full.dia
diff --git a/_images/sources/http/xkcd-request.dia b/_images/sources/http/xkcd-request.dia
diff --git a/_images/sources/mercure/discovery.dia b/_images/sources/mercure/discovery.dia
diff --git a/_images/sources/mercure/hub.dia b/_images/sources/mercure/hub.dia
diff --git a/components/console/helpers/cursor.rst b/components/console/helpers/cursor.rst
@@ -6,7 +6,7 @@ cursor position in a console command. This allows you to write on any position
 of the output:
 
 .. image:: /_images/components/console/cursor.gif
-   :align: center
+    :alt: A command outputs on various positions on the screen, eventually drawing the letters "SF".
 
 .. code-block:: php
 

diff --git a/components/console/helpers/debug_formatter.rst b/components/console/helpers/debug_formatter.rst
@@ -8,7 +8,7 @@ the results of running ``figlet symfony``, it might output something like
 this:
 
 .. image:: /_images/components/console/debug_formatter.png
-   :align: center
+    :alt: Console output, with the first line showing "RUN Running figlet", followed by lines showing the output of the command prefixed with "OUT" and "RES Finished the command" as last line in the output.
 
 Using the debug_formatter
 -------------------------

diff --git a/components/console/helpers/processhelper.rst b/components/console/helpers/processhelper.rst
@@ -19,14 +19,17 @@ a very verbose verbosity (e.g. ``-vv``)::
 will result in this output:
 
 .. image:: /_images/components/console/process-helper-verbose.png
+    :alt: Console output showing two lines: "RUN 'figlet' 'Symfony'" and "RES Command ran successfully".
 
 It will result in more detailed output with debug verbosity (e.g. ``-vvv``):
 
 .. image:: /_images/components/console/process-helper-debug.png
+    :alt: In between the command line and the result line, the command's output is now shown prefixed by "OUT".
 
 In case the process fails, debugging is easier:
 
 .. image:: /_images/components/console/process-helper-error-debug.png
+    :alt: The last line shows "RES 127 Command dit not run successfully", and the output lines show more the error information from the command.
 
 Arguments
 ---------

diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst
@@ -5,6 +5,7 @@ When executing longer-running commands, it may be helpful to show progress
 information, which updates as your command runs:
 
 .. image:: /_images/components/console/progressbar.gif
+    :alt: Console output showing a progress bar advance to 100%, with the esimated time left, the memory usage and a special message that changes when the bar closes completion.
 
 .. note::
 

diff --git a/components/form.rst b/components/form.rst
@@ -513,7 +513,7 @@ done by passing a special form "view" object to your template (notice the
     {{ form_end(form) }}
 
 .. image:: /_images/form/simple-form.png
-    :align: center
+    :alt: An HTML form showing a text box labelled "Task", three select boxes for a year, month and day labelled "Due date" and a button labelled "Create Task".
 
 That's it! By printing ``form_widget(form)``, each field in the form is
 rendered, along with a label and error message (if there is one). While this is

diff --git a/components/http_kernel.rst b/components/http_kernel.rst
@@ -72,7 +72,9 @@ and ends with a :class:`Symfony\\Component\\HttpFoundation\\Response`.
 
 .. raw:: html
 
-    <object data="../_images/components/http_kernel/http-workflow.svg" type="image/svg+xml"></object>
+    <object data="../_images/components/http_kernel/http-workflow.svg" type="image/svg+xml"
+        alt="A flow diagram showing all HTTP Kernel events in the Request-Response lifecycle. Each event is numbered 1 to 8 and described in detail in the following subsections."
+    ></object>
 
 The exact details of this workflow are the key to understanding how the kernel
 (and the Symfony Framework or any other library that uses the kernel) works.
@@ -511,7 +513,9 @@ to the exception.
 
 .. raw:: html
 
-    <object data="../_images/components/http_kernel/http-workflow-exception.svg" type="image/svg+xml"></object>
+    <object data="../_images/components/http_kernel/http-workflow-exception.svg" type="image/svg+xml"
+        alt="The HTTP KErnel flow diagram showing how exceptions bypass all further steps and are directly transformed to responses."
+    ></object>
 
 Each listener to this event is passed a :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent`
 object, which you can use to access the original exception via the
@@ -670,7 +674,9 @@ your controller).
 
 .. raw:: html
 
-    <object data="../_images/components/http_kernel/http-workflow-subrequest.svg" type="image/svg+xml"></object>
+    <object data="../_images/components/http_kernel/http-workflow-subrequest.svg" type="image/svg+xml"
+        alt="The HTTP Kernel flow diagram with a sub request from a controller starting the lifecycle at step 1 again and feeding the sub Response content back into the controller."
+    ></object>
 
 To execute a sub request, use ``HttpKernel::handle()``, but change the second
 argument as follows::

diff --git a/components/messenger.rst b/components/messenger.rst
@@ -27,7 +27,9 @@ Concepts
 
 .. raw:: html
 
-    <object data="../_images/components/messenger/overview.svg" type="image/svg+xml"></object>
+    <object data="../_images/components/messenger/overview.svg" type="image/svg+xml"
+        alt="A flow diagram visualizing how each concept relates to eachother. Each concept is described in the subsequent text."
+    ></object>
 
 **Sender**:
    Responsible for serializing and sending messages to *something*. This

diff --git a/components/serializer.rst b/components/serializer.rst
@@ -8,15 +8,20 @@ In order to do so, the Serializer component follows the following schema.
 
 .. raw:: html
 
-    <object data="../_images/components/serializer/serializer_workflow.svg" type="image/svg+xml"></object>
-
-As you can see in the picture above, an array is used as an intermediary between
-objects and serialized contents. This way, encoders will only deal with turning
-specific **formats** into **arrays** and vice versa. The same way, Normalizers
-will deal with turning specific **objects** into **arrays** and vice versa.
-
-Serialization is a complex topic. This component may not cover all your use cases out of the box,
-but it can be useful for developing tools to serialize and deserialize your objects.
+    <object data="../_images/components/serializer/serializer_workflow.svg" type="image/svg+xml"
+        alt="A flow diagram showing how objects are serialized/deserialized. This is described in the subsequent paragraph."
+    ></object>
+
+When (de)serializing objects, the Serializer uses an array as the intermediary
+between objects and serialized contents. Encoders will only deal with
+turning specific **formats** into **arrays** and vice versa. The same way,
+normalizers will deal with turning specific **objects** into **arrays** and
+vice versa. The Serializer deals with calling the normalizers and encoders
+when serializing objects or deserializing formats.
+
+Serialization is a complex topic. This component may not cover all your use
+cases out of the box, but it can be useful for developing tools to
+serialize and deserialize your objects.
 
 Installation
 ------------

diff --git a/components/string.rst b/components/string.rst
@@ -44,7 +44,7 @@ The following image displays the bytes, code points and grapheme clusters for
 the same word written in English (``hello``) and Hindi (``नमस्ते``):
 
 .. image:: /_images/components/string/bytes-points-graphemes.png
-   :align: center
+    :alt: Each letter in "hello" is made up of one byte, one code point and one grapheme cluster. In the Hindi translation, the first two letters ("नम") take up three bytes, one code point and one grapheme cluster. The last letters ("स्ते") each take up six bytes, two code points and one grapheme cluster.
 
 Usage
 -----

diff --git a/components/var_dumper.rst b/components/var_dumper.rst
@@ -350,6 +350,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/01-simple.png
+    :alt: Dump output showing the array with length five and all keys and values.
 
 .. note::
 
@@ -367,6 +368,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/02-multi-line-str.png
+    :alt: Dump output showing the string on multiple lines in between three quotes.
 
 .. code-block:: php
 
@@ -381,6 +383,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/03-object.png
+    :alt: Dump output showing the PropertyExample object and all three properties with their values.
 
 .. note::
 
@@ -399,6 +402,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/04-dynamic-property.png
+    :alt: Dump output showing the DynamicPropertyExample object and both declared and undeclared properties with their values.
 
 .. code-block:: php
 
@@ -411,6 +415,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/05-soft-ref.png
+    :alt: Dump output showing the "aCircularReference" property value referencing the parent object, instead of showing all properties again.
 
 .. code-block:: php
 
@@ -424,6 +429,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/06-constants.png
+    :alt: Dump output with the "E_WARNING" constant shown as value of "severity".
 
 .. code-block:: php
 
@@ -437,6 +443,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/07-hard-ref.png
+    :alt: Dump output showing the referenced arrays.
 
 .. code-block:: php
 
@@ -447,6 +454,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/08-virtual-property.png
+    :alt: Dump output of the ArrayObject.
 
 .. code-block:: php
 
@@ -460,6 +468,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/09-cut.png
+    :alt: Dump output where the children of the Container object are hidden.
 
 .. code-block:: php
 

diff --git a/components/workflow.rst b/components/workflow.rst
@@ -22,6 +22,7 @@ process is called a *place*. You do also define *transitions* that describe
 the action to get from one place to another.
 
 .. image:: /_images/components/workflow/states_transitions.png
+    :alt: An example state diagram for a workflow, showing transitions and places.
 
 A set of places and transitions creates a **definition**. A workflow needs
 a ``Definition`` and a way to write the states to the objects (i.e. an

diff --git a/console.rst b/console.rst
@@ -81,6 +81,7 @@ terminal. All commands support name and option completion, and some can
 even complete values.
 
 .. image:: /_images/components/console/completion.gif
+    :alt: The terminal completes the command name "secrets:remove" and the argument "SOME_OTHER_SECRET".
 
 First, you have to install the completion script *once*. Run
 ``bin/console completion --help`` for the installation instructions for

diff --git a/contributing/code/stack_trace.rst b/contributing/code/stack_trace.rst
@@ -91,8 +91,8 @@ Several things need to be paid attention to when picking a stack trace
 from your development environment through a web browser:
 
 1. Are there several exceptions? If yes, the most interesting one is
-   often exception 1/n which, is shown *last* in the example below (it
-   is the one marked as an exception [1/2]).
+   often exception 1/n which, is shown *last* in the default exception page
+   (it is the one marked as ``exception [1/2]`` in the below example).
 2. Under the "Stack Traces" tab, you will find exceptions in plain
    text, so that you can easily share them in e.g. bug reports. Make
    sure to **remove any sensitive information** before doing so.
@@ -102,8 +102,8 @@ from your development environment through a web browser:
    are getting, but are not what the term "stack trace" refers to.
 
 .. image:: /_images/contributing/code/stack-trace.gif
-   :align: center
-   :class: with-browser
+    :alt: The default Symfony exception page with the "Exceptions", "Logs" and "Stack Traces" tabs.
+    :class: with-browser
 
 Since stack traces may contain sensitive data, they should not be
 exposed in production. Getting a stack trace from your production

diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst
@@ -25,8 +25,8 @@ while you're reading the Symfony documentation.
 and you'll be redirected to GitHub:
 
 .. image:: /_images/contributing/docs-github-edit-page.png
-   :align: center
-   :class: with-browser
+    :alt: The "Edit this page" button is located directly below the first heading.
+    :class: with-browser
 
 **Step 2.** Edit the contents, describe your changes and click on the
 **Propose file change** button.
@@ -36,8 +36,8 @@ and you'll be redirected to GitHub:
 also display a preview of your changes:
 
 .. image:: /_images/contributing/docs-github-create-pr.png
-   :align: center
-   :class: with-browser
+    :alt: The "Comparing changes" page on GitHub.
+    :class: with-browser
 
 If everything is correct, click on the **Create pull request** button.
 
@@ -152,7 +152,7 @@ exact changes that you want to propose, select the appropriate branches where
 changes should be applied:
 
 .. image:: /_images/contributing/docs-pull-request-change-base.png
-   :align: center
+    :alt: The base branch select option on the GitHub page.
 
 In this example, the **base fork** should be ``symfony/symfony-docs`` and
 the **base** branch should be the ``5.4``, which is the branch that you selected

diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst
@@ -146,6 +146,36 @@ Files and Directories
       ├─ vendor/
       └─ ...
 
+Images and Diagrams
+-------------------
+
+* **Diagrams** must adhere to the Symfony docs style. These are created
+  using the Dia_ application, to make sure everyone can edit them. See the
+  `README on GitHub`_ for instructions on how to create them.
+* All images and diagrams must contain **alt descriptions**:
+
+  * Keep the descriptions concise, do not duplicate information surrounding
+    the figure;
+  * Describe complex diagrams in text surrounding the diagram instead of
+    the alt description. In these cases, alt descriptions must describe
+    where the longer description can be found (e.g. "These elements are
+    described further in the next sections");
+  * Start descriptions with a capital letter and end with a period;
+  * Do not start with "A screenshot of", "Diagram of", etc. except when
+    it's useful to know the exact type (e.g. a specific diagram type).
+
+.. code-block:: text
+
+    .. image:: _images/example-screenshot.png
+        :alt: Some concise description of the screenshot.
+
+    .. raw:: html
+
+        <object data="_images/example-diagram.svg" type="image/svg+xml"
+            alt="Some concise description."
+        ></object>
+
+
 English Language Standards
 --------------------------
 
@@ -201,4 +231,6 @@ In addition, documentation follows these rules:
 .. _`American English Oxford Dictionary`: https://www.lexico.com/definition/american_english
 .. _`headings and titles`: https://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles
 .. _`Serial (Oxford) Commas`: https://en.wikipedia.org/wiki/Serial_comma
+.. _`Dia`: http://dia-installer.de/
+.. _`README on GitHub`: https://github.com/symfony/symfony-docs/blob/6.4/_images/sources/README.md
 .. _`nosism`: https://en.wikipedia.org/wiki/Nosism
diff --git a/controller/error_pages.rst b/controller/error_pages.rst
@@ -10,18 +10,16 @@ Symfony catches all the exceptions and displays a special **exception page**
 with lots of debug information to help you discover the root problem:
 
 .. image:: /_images/controller/error_pages/exceptions-in-dev-environment.png
-   :alt: A typical exception page in the development environment
-   :align: center
-   :class: with-browser
+    :alt: A typical exception page in the development environment with the full stacktrace and log information.
+    :class: with-browser
 
 Since these pages contain a lot of sensitive internal information, Symfony won't
 display them in the production environment. Instead, it'll show a minimal and
 generic **error page**:
 
 .. image:: /_images/controller/error_pages/errors-in-prod-environment.png
-   :alt: A typical error page in the production environment
-   :align: center
-   :class: with-browser
+    :alt: A typical error page in the production environment.
+    :class: with-browser
 
 Error pages for the production environment can be customized in different ways
 depending on your needs:

diff --git a/doctrine.rst b/doctrine.rst
@@ -185,8 +185,11 @@ objects to a ``product`` table in your database. Each property in the ``Product`
 entity can be mapped to a column in that table. This is usually done with attributes:
 the ``#[ORM\Column(...)]`` comments that you see above each property:
 
-.. image:: /_images/doctrine/mapping_single_entity.png
-   :align: center
+.. raw:: html
+
+    <object data="../_images/doctrine/mapping_single_entity.svg" type="image/svg+xml"
+        alt="Doctrine mapping between properties of a Product PHP object and the data in the product database table"
+    ></object>
 
 The ``make:entity`` command is a tool to make life easier. But this is *your* code:
 add/remove fields, add/remove methods or update configuration.
@@ -589,8 +592,8 @@ the :ref:`doctrine-queries` section.
     will display the number of queries and the time it took to execute them:
 
     .. image:: /_images/doctrine/doctrine_web_debug_toolbar.png
-       :align: center
-       :class: with-browser
+        :alt: The web dev toolbar showing the Doctrine item.
+        :class: with-browser
 
     If the number of database queries is too high, the icon will turn yellow to
     indicate that something may not be correct. Click on the icon to open the