PEP 282: Improve upon colloquial phrasing #2667
Conversation
Also it is better readable for non-English native speakers.
|
All commit authors signed the Contributor License Agreement. |
|
We generally avoid unnecessary changes to old PEPs, so I'd rather keep the previous wording here. It's true though that the syntax highlighting is wrong in the second code block: https://peps.python.org/pep-0282/#simple-example. We should fix that so it doesn't get formatted as if it's Python code. |
|
Yeah, the real fix here is replacing the non-Python
This really should be done consistently for older PEPs that use non-Python syntax in code blocks so they render as intended, which in many/most cases can be done by adding You're welcome to implement that here if you'd like, otherwise I'd be happy to submit a replacement PR to take care of it. Just let us know! |
Done.
Done. Not sure if it works as expected. Any way for me to review the results before comitting?
Done. Did not change contents either, so now there are three adjacent code blocks.
Done.
Did not understand. Did not touch any other PEP files, as it seems out of scope here. |
| CRITICAL | ||
| * DEBUG | ||
| * INFO | ||
| * WARN |
There was a problem hiding this comment.
After the PEP was written, WARN was replaced by WARNING as preferable.though WARN remains as an alias. Perhaps this should be reflected here too?
There was a problem hiding this comment.
We can defer to your judgement as PEP author, but per PEP 1,
In general, PEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected or Superseded state. Once resolution is reached, a PEP is considered a historical document rather than a living specification. Formal documentation of the expected behavior should be maintained elsewhere, such as the Language Reference for core features, the Library Reference for standard library modules or the PyPA Specifications for packaging.
Presumably there are other things that are out of date here too, so IMO there isn't a need to update this just because it happened to be touched in a syntax update to ensure the PEP renders as intended.
I just merged #2702 which adds a new banner to point readers to where they can find the up to date, canonical documentation for the feature proposed by the PEP once its Final, which we could use to add a prominent link directing readers to the stdlib logging module reference.
|
Looks like this is generally good to go from a PEP editor perspective on my end, with one comment. Thanks!
As mentioned in the README, you can both check the RTD rendered preview on the PR, or build the PEPs yourself locally.
Sorry, I realize that was confusing—that was not intended to be anything you needed to do. |
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
Syntax highligting interprets ' as start of a string and colors the following text differently.
Also this change makes the text fragment better readable for non-English native speakers.