PEP 12: Update outdated image and comment formatting guidance

Author: CAM-Gerlach

pep-0012.rst

@@ -568,35 +568,43 @@ the numbers will always match.
 Images
 ------
 
-If your PEP contains a diagram, you may include it in the processed
-output using the "image" directive::
+If your PEP contains a diagram or other graphic, you may include it in the
+processed output using the ``image`` directive:
+
+.. code-block:: rst
 
     .. image:: diagram.png
 
-Any browser-friendly graphics format is possible: .png, .jpeg, .gif,
-.tiff, etc.
+Any browser-friendly graphics format is possible; PNG should be
+preferred for graphics, JPEG for photos and GIF for animations.
+Currently, SVG must be avoided due to compatibility issues with the
+PEP build system.
+
+For accessibility and readers of the source text, you should include
+a description of the image and any key information contained within
+using the ``:alt:`` option to the ``image`` directive:
+
+.. code-block:: rst
 
-Since this image will not be visible to readers of the PEP in source
-text form, you should consider including a description or ASCII art
-alternative, using a comment (below).
+     .. image:: dataflow.png
+        :alt: Data flows from the input module, through the "black box"
+              module, and finally into (and through) the output module.
 
 
 Comments
 --------
 
-A comment block is an indented block of arbitrary text immediately
+A comment is an indented block of arbitrary text immediately
 following an explicit markup start: two periods and whitespace.  Leave
 the ".." on a line by itself to ensure that the comment is not
 misinterpreted as another explicit markup construct.  Comments are not
-visible in the processed document.  For the benefit of those reading
-your PEP in source form, please consider including a descriptions of
-or ASCII art alternatives to any images you include.  For example::
+visible in the processed document.  For example:
 
-     .. image:: dataflow.png
+.. code-block:: rst
 
      ..
-        Data flows from the input module, through the "black box"
-        module, and finally into (and through) the output module.
+        This section should be updated in the final PEP.
+        Ensure the date is accurate.
 
 The Emacs stanza at the bottom of this document is inside a comment.