PEP 638: Typographic fixes

[davidfstr]

I'm excited about the potential introduction of Lisp-style syntactic macros into Python. 😁

Most of this PR is a set of comments on PEP 638, directed to the PEP author @markshannon, expressed as inline .rst comments.

Not sure if this is appropriate to actually merge, but I did want to pose various comments/questions to parts of PEP 638 inline and this seemed like a reasonable way to start.

Edit: This PR now only contains typographic fixes to PEP 638. I have moved discussion of more-substantial points to python-dev.

[CAM-Gerlach]

Thanks much for your feedback.

In general, for format/textual fixes on the PEP source, its best to make them as a PR for the PEP author(s) to review (as you did here, for such). To note, as a PEP editor, I reviewed and second all of them.

There isn't an ideal way to ask for clarification on specific textual items, headers, etc. (which were a lot of your comments) that you aren't able to propose yourself, but instead of baking inline comments into the file (especially all in the same commit as the previous, and thus have to be manually edited out instead of simply dropped), you could consider make them as review comments in the PR (if you've modified nearby lines), make them in a regular reply comment on the same, or as commit comments on the original commit that added/modified the line in question (probably 5c7d3aa in this case).

Generally speaking, it is usually better to direct more substantive questions and comments (whcih it looked like at least a few of yours were) about the content and decisions made in the PEP to the PEP's designed Discussions-To thread, so it can be considered by the authors, reviewers (particularly the SC/PEP delegate) and the interested community. In this case, the PEP doesn't actually specify it, making that difficult (or even the date that it was posted in Post-History); however, we've recently clarified and improved our guidance on this following #2346 which implemented #2266 (and is further improved by several other merged and in-review PRs), which explicitly requests that authors link the actual discussion thread, so that interested readers don't have to dig through Google and guess at what the current one is (which I think might be this one.

I was already working on a PR to clarify in the Contributing Guide what contributions are particularly helpful here, and I can try to clarify this as well as part of that (once we discuss it).

[CAM-Gerlach]

Per our recently revised guidance (as of after this PEP was last updated), the Discussions-To header should point directly to the actual current discussion thread, rather than just mentioning the venue. This one appears to be the latest I can find after some digging. There were also at least one tangential thread posted by other users on the Python Discourse.

[davidfstr]

Thanks for taking the time to point me in a better direction @CAM-Gerlach .

I’ll plan to revise this PR to only make typographic fixes and insert a presumed Discussions-To link. Then make it non-draft.

Then I will move my inline comments to the actual discussions thread.

[CAM-Gerlach]

LGTM pending @markshannon 's review. Thanks @davidfstr

[hugovk]

Ping again @markshannon.

These changes look uncontroversial.

[davidfstr]

I haven't been able to reach @markshannon by any means in months. And this PR in particular has now been open for 2 months.

@CAM-Gerlach / @hugovk Any chance this set of minor revisions could be merged even without his explicit approval?

[AA-Turner]

Rebased to do the new CLA check.

A

[AA-Turner]

Thanks! (Edit: yes, at least three editors have approved and the edits were beneficial to the text)

A

[davidfstr]

Thanks all!

Amusingly I actually ran into Mark Shannon in-person today at PyCon US. ^_^

[CAM-Gerlach]

Ha, I figured you might since I saw both of you there!