CAM-Gerlach
commented
2 years ago As a corollary, a broader issue I've noticed is a somewhat unclear separation between PEP 1 and PEP 12, with a number of details of the format leaking from the latter into the former (which would be nice to decouple from abstract process, and more concretely from the more governance-y aspects of that PEP that make me leery of proposing even mundane changes to even the purely technical/editorial parts without high-level review).
What's more, some things, like the header spec and the list of suggested sections, are duplicated two or even three places between PEP 1, PEP 12 and the standalone template, often with significant differences in content or simply drifting out of sync (which came up in at least one PR lately, where the three say different things about whether the email address can/should/must be listed for PEP authors, sponsors and delegates).
While this issue doesn't address this concern directly, it does substantially reduce the length and tighten the focus of PEP 12 on the specifics of the PEP format (rather than a guide to generic RST syntax), which lends itself well to a future PR potentially consolidating the other purely technical details of the PEP format (primarily, the headers and the suggested sections) currently split/duplicated between PEP 1 and PEP 12 into PEP 12 as well, allowing PEP 1 to focus more cleanly on the PEP purpose, process, governance and other higher-level concerns.
This would both benefit PEP authors and reviewers (as it makes it easier and more logical to find the information specific to their needs while avoiding conflicting guidance from different sources), and us PEP editors (by improving maintainability, reducing duplication of effort and more cleanly separating purely technical from potentially process/governance changes that might need higher-level review). If and when we have consensus on this issue and I go ahead with a PR, I can open another to consider these ideas further, if there's interest.
encukou
Spawned out of a discussion with @brettcannon and @AA-Turner on #2302 .
PEP 12 (PEP-0012) contains a large amount of detailed explanations and examples of generic reST syntax, directives and usage that in large part duplicates the content of the reST Primer, quickref and specification.
As @brettcannon mentions there, this is largely a historical artifact of the fact that
While it is potentially helpful to PEP writers to keep everything in one PEP-focused document, and the maintenance cost for us to retain it is not so high, to follow the existing conventions we will need to continue to update all of the detailed explanations and examples (rather than just the PEP-specific content) to reflect changes in practice over time (some of which are likely the case already), changes due to PEP 676 if/when it is approved, and other future changes in reST, docutils and Sphinx.
Furthermore, it might better serve most readers to focus on high-level recommendations and notes specific to the formatting of PEPs, our extensions/custom rules, stylistic conventions, and best practices; while linking to (instead of duplicating) the more comprehensive and authoritative resources on reST syntax. Most PEP writers are likely pretty familiar with the basics (if not all the details) of reST already, and if not will be well- (or even better-) served by handy direct links to the tutorial, examples and full reference for each main element in question (rather than just links to the top-level resources at the bottom of the PEP).
Therefore, for each of the major generic reST syntax elements described (i.e. the various headings under the top-level "ReStructuredText PEP Formatting Requirements" section, e.g. hyperlinks, tables, etc), I propose:
We could also consider mentioning the main reST resources in the "Resources" section nearer the top, e.g. as part of the introduction of the reST formatting section, so readers can start be e.g. reading the primer or browsing the quickref rather than jumping straight into the PEP-specific elements.
Thoughts?