PEP 1: Make text/x-rst officially the default and update accordingly #2355

CAM-Gerlach · 2022-02-22T02:28:46Z

As mentioned in #2352 , despite every single PEP in the repo, even PEP-0009, using Content-Type: text/x-rst, the obsolete plain text format described in said PEP, with Content-Type: text/plain, is still the default (at least in the old docutils-based system; this is fixed in the new PEP 676 Sphinx-based one).

Therefore, this flips the default to text/x-rst, and updates PEP 1 and the reST PEP template accordingly (which up until now, lacked a Content-Type header entirely, meaning that PEPs would in fact render as plain-text). This makes the Sphinx and docutils build systems consistent, allows simplifying the Readme, Contributing Guide, PEP 1 and the template, and sets the stage for eliminating this now-redundant field entirely in the future (e.g. if/when acceptance of PEP 676).

warsaw

I have a few questions about the status of text/plain. I also wonder if it would be helpful to include a "Changes" section in the PEP. Yes, you can dig it out of the git history, but that's a pain.

FWIW, +1 on the switch to text/x-rst as the default. Thanks for all your great work on clean up the PEPs!

pep-0001.txt

warsaw · 2022-02-22T17:19:22Z

pep-0001.txt

-Content-Type header is present.
+All PEPs now use reStructuredText (see :pep:`12`),
+and have a value of ``text/x-rst``, the default.
+Previously, plaintext PEPs used ``text/plain`` (see :pep:`9`).


This should clearly explain whether text/plain will be accepted or not going forward.

I'd remove this line, PEP-0009 itself has a notice stating that it is withdrawn.

If people think this should simply be removed, I can remove it. Otherwise, I could revise the above to say "All PEPs must use reStructuredText"...

Yes, I think the must language is worth adding.

Added above, thanks

AA-Turner

Suggested changes make it much more explicit that only text/x-rst is allowed.

AA-Turner · 2022-02-22T18:33:10Z

pep-0001.txt

-All new and active PEPs must use reStructuredText, but for backwards
-compatibility, plain text is currently still the default if no
-Content-Type header is present.
+All PEPs now use reStructuredText (see :pep:`12`),


Remove now, and the reference to PEP 12. PEP 9 does not follow the reST template in PEP 12, but does use reST.

Suggested change

All PEPs now use reStructuredText (see :pep:`12`),

All PEPs use reStructuredText,

I removed now "now" and "must" per @warsaw 's suggestion. Unless there's something I'm misunderstanding, it seems rather silly to remove the reference to PEP 12 just because one withdrawn PEP doesn't include the suggested; in truth, many PEPs don't to varying extents, but they still use the standard headers and valid reST syntax (as does PEP 9).

Maybe "(see :pep:`12` for the reStructuredText template)"? It didn't feel particularly linked, but equally is rather minor.

AA-Turner · 2022-02-22T18:34:07Z

pep-0001.txt

@@ -603,11 +603,9 @@ The Type header specifies the type of PEP: Standards Track,
 Informational, or Process.

 The format of a PEP is specified with a Content-Type header.


Explicitly only support text/x-rst

Suggested change

The format of a PEP is specified with a Content-Type header.

The format of a PEP is specified with a Content-Type header.

The only valid value is ``text/x-rst``.

I ended up using the "must" verbiage suggested by @warsaw

AA-Turner · 2022-02-22T18:35:01Z

pep-0001.txt

-Content-Type header is present.
+All PEPs now use reStructuredText (see :pep:`12`),
+and have a value of ``text/x-rst``, the default.
+Previously, plaintext PEPs used ``text/plain`` (see :pep:`9`).


I'd remove this line, PEP-0009 itself has a notice stating that it is withdrawn.

AA-Turner · 2022-02-22T18:36:18Z

pep-0012/pep-NNNN.rst

@@ -6,6 +6,7 @@ PEP-Delegate: <PEP delegate's real name>
 Discussions-To: <email address or URL>
 Status: <REQUIRED: Draft | Active | Accepted | Provisional | Deferred | Rejected | Withdrawn | Final | Superseded>
 Type: <REQUIRED: Standards Track | Informational | Process>
+Content-Type: text/x-rst


Content Type is required, but as there's only one valid value it feels odd to use the <REQUIRED: spam> verbiage. Maybe it is better as is?

Suggested change

Content-Type: text/x-rst

Content-Type: <REQUIRED: text/x-rst>

Why is Content-Type still required?

I had the same thought. One possible reason is forward compatibility: maybe in the future we'll allow PEPs in markdown or something. Then again, even in that case we can just reintroduce the header later.

And another reason is just to avoid making a change without a strong reason. There is little cost to having PEP authors copy this field from the template.

I'm inclined to keep it, for clarity. Lots of things have their MIME types designated in headers. And as Jelle says, maybe in the future there will be others, so it'd mean we don't need to say "Optional - if omitted, defaults to text/x-rst".

There's no techincal reason the header couldn't simply be removed from the template (and even all PEPs), since they all use text/x-rst, the default, and likely will for the immediate future, and the only place this was actually used is by the old docutils-based rendering script to determine the rendering mode, if not the default (it isn't anywhere in the output, and it isn't needed or used at all by the PEP 676 based system).

If we did add support for a new format, it presumably would be handled via file extension, like any common format these days (e.g. MyST with .md) and a Content-Type would not really serve no technical purpose, since it is only (and could even be out of sync with the actual file type, unless we run a linter or custom build-time check to validate it). That would allow us to not have to mention it at all (optional or otherwise), lint it, or copy it as boilerplate.

That being said, while it is redundant, there isn't too much cost to keeping it around (at least on existing PEPs), so I don't feel too strongly about it.

pep2html.py

AA-Turner · 2022-02-24T19:06:58Z

@CAM-Gerlach are you happy for this to be merged? // are there any remaining blockers?

A

CAM-Gerlach · 2022-02-24T19:24:41Z

Nope, thanks, not from my end, and not that I see here. My intent was to discuss what to do about the Content-Type header going forward (remove, require or keep optional) in a separate PR after @warsaw officially makes a decision on PEP 676 🤞

Switch default Content-Type to text/x-rst, since all PEPs are now RST

64de899

CAM-Gerlach requested review from brettcannon, warsaw, ncoghlan and AA-Turner as code owners February 22, 2022 02:28

CAM-Gerlach self-assigned this Feb 22, 2022

the-knights-who-say-ni added the CLA signed label Feb 22, 2022

CAM-Gerlach requested review from hugovk and removed request for brettcannon, warsaw and ncoghlan February 22, 2022 02:29

warsaw requested changes Feb 22, 2022

View reviewed changes

AA-Turner requested changes Feb 22, 2022

View reviewed changes

CAM-Gerlach mentioned this pull request Feb 23, 2022

Update, copyedit and format Readme and Contributing Guide #2352

Merged

PEP 1: Clarify that reST is the default & no plaintext PEPs remain

51cf8cb

CAM-Gerlach force-pushed the pep-1-elide-obselete-plain-text-format branch from 3aa9d67 to 51cf8cb Compare February 23, 2022 05:25

hugovk approved these changes Feb 23, 2022

View reviewed changes

AA-Turner approved these changes Feb 24, 2022

View reviewed changes

AA-Turner merged commit d795805 into python:main Feb 24, 2022

CAM-Gerlach mentioned this pull request Apr 6, 2022

Is Content-Type optional? #2500

Closed

erlend-aasland mentioned this pull request May 13, 2022

pep8/greppable exception messages erlend-aasland/peps#1

Closed

erlend-aasland mentioned this pull request Jun 27, 2022

pep 687/mark as accepted erlend-aasland/peps#2

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PEP 1: Make text/x-rst officially the default and update accordingly #2355

PEP 1: Make text/x-rst officially the default and update accordingly #2355

CAM-Gerlach commented Feb 22, 2022

warsaw left a comment •

edited

Loading

warsaw Feb 22, 2022

AA-Turner Feb 22, 2022

CAM-Gerlach Feb 22, 2022

warsaw Feb 23, 2022

CAM-Gerlach Feb 23, 2022

AA-Turner left a comment

AA-Turner Feb 22, 2022

CAM-Gerlach Feb 23, 2022

AA-Turner Feb 23, 2022 •

edited

Loading

AA-Turner Feb 22, 2022

CAM-Gerlach Feb 23, 2022

AA-Turner Feb 22, 2022

AA-Turner Feb 22, 2022

warsaw Feb 23, 2022

JelleZijlstra Feb 23, 2022

Rosuav Feb 23, 2022

CAM-Gerlach Feb 23, 2022

AA-Turner commented Feb 24, 2022 •

edited

Loading

CAM-Gerlach commented Feb 24, 2022

	All PEPs now use reStructuredText (see :pep:`12`),
	All PEPs use reStructuredText,

		@@ -603,11 +603,9 @@ The Type header specifies the type of PEP: Standards Track,
		Informational, or Process.

		The format of a PEP is specified with a Content-Type header.

	The format of a PEP is specified with a Content-Type header.
	The format of a PEP is specified with a Content-Type header.
	The only valid value is ``text/x-rst``.

	Content-Type: text/x-rst
	Content-Type: <REQUIRED: text/x-rst>

PEP 1: Make text/x-rst officially the default and update accordingly #2355

PEP 1: Make text/x-rst officially the default and update accordingly #2355

Conversation

CAM-Gerlach commented Feb 22, 2022

warsaw left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AA-Turner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AA-Turner Feb 23, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AA-Turner commented Feb 24, 2022 • edited Loading

CAM-Gerlach commented Feb 24, 2022

warsaw left a comment •

edited

Loading

AA-Turner Feb 23, 2022 •

edited

Loading

AA-Turner commented Feb 24, 2022 •

edited

Loading