Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PEP 12: Update outdated image and comment formatting guidance #2365

Merged
merged 1 commit into from
Feb 27, 2022
Merged

PEP 12: Update outdated image and comment formatting guidance #2365

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 22 additions & 14 deletions pep-0012.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +578 to +579
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"PNG should be preferred for graphics, JPEG for photos" where does this guidance come from?

Equally, do we want to allow animated GIF images in a PEP?

Copy link
Member Author

@CAM-Gerlach CAM-Gerlach Feb 26, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"PNG should be preferred for graphics, JPEG for photos" where does this guidance come from?

For one thing, from the name of each format, following from their defined purpose and fundamental to how their respective compression strategies were designed.

The Joint Photographic Experts Group format was developed to use for, well, photographs, and its DCT-based compression handles their complex scenes, smooth gradients and high degrees of color variability well, but performs poorly on graphics, resulting in visibly inferior quality yet larger file size.

By contrast, Portable Network Graphics was explicitly created for, well, graphics, and uses a lossless DEFLATE + pre-filtering compression scheme plus color paletting to achieve excellent compression ratios on images with vector-style art, fewer discrete colors and defined shapes. but hugely balloons file size on photographs and similar relative to even a visually-lossless JPEG.

Equally, do we want to allow animated GIF images in a PEP?

I don't really have any opinion here; we can remove that if others do. I included it because it was mentioned in the original text (TIFF was elided, as it is not at all web-friendly and its use cases for this were better covered by JPEG and PNG).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the explanation. To an extent my challenge was do we really need to care about the differences between JPEG and PNG. It's rare enough though that we can take case by case if need be.

A

Copy link
Member Author

@CAM-Gerlach CAM-Gerlach Feb 27, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't need a long explanation, but I don't think it hurts to spend a mere few words briefly mentioning which format to use for what, when we're bringing up the formats anyway.

Currently, SVG must be avoided due to compatibility issues with the
PEP build system.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Out of scope here, so just a note as accessibility is mentioned in the next paragraph, SVGs can be good for accessibility.

(Although it might require more work to create an accessible SVG than is usually put into images here.)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mmm, good point. One more reason for PEP 676, which should get them working, hopefully.


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.

Expand Down