Clarify 'time zone' in a Specific words section - #1352
Conversation
Sorry, something went wrong.
AA-Turner
left a comment
There was a problem hiding this comment.
We could perhaps use a .. glossary:: directive here?
A
Sorry, something went wrong.
| Only spell as one word when referring to a Python term like a module, | ||
| class, or argument. |
There was a problem hiding this comment.
Shouldn't they have markup like :mod: or similar in this case?
If that's the case, "timezone" should never appear in plain text.
Not sure if it's worth clarifying this.
Sorry, something went wrong.
There was a problem hiding this comment.
Not sure if it's worth clarifying this.
Anyone reading the devguide style guide will probably already know how to mark up classes, so I'm not sure it's worth complicating the current wording.
Sorry, something went wrong.
There was a problem hiding this comment.
What I meant is:
- talking about the concept? Always use two words and no markup.
- talking about the module/class/arg? Always use one word and the appropriate markup.
This implies that "timezone" will never appear in plain text and "time zone" will never appear within markup.
IOW, the fact that you are using markup or not already determines whether to use one or two words, without having to think if you are referring to a module/class/argument or not.
Sorry, something went wrong.
There was a problem hiding this comment.
Sure, if it does not clutter the wording too much, I'm fine with such a change.
Sorry, something went wrong.
I'm not sure this rises to that level yet, but will keep it in mind. |
Sorry, something went wrong.
| .. _glossary: | ||
|
|
||
| Specific words | ||
| ============== |
There was a problem hiding this comment.
I predict this will confuse me, shall we have the same name for both the link and the title?
Sorry, something went wrong.
There was a problem hiding this comment.
The link might also be confused with the glossary directive.
Sorry, something went wrong.
There was a problem hiding this comment.
I changed the reference to specific words.
Sorry, something went wrong.
Sorry, something went wrong.
| Spell out as two words when talking about the real-world concept. | ||
| Only spell as one word when referring to a Python term like a module, | ||
| class, or argument. |
There was a problem hiding this comment.
| Spell out as two words when talking about the real-world concept. | |
| Only spell as one word when referring to a Python term like a module, | |
| class, or argument. | |
| When referring to a Python term like a module, class, or argument | |
| it is always spelled as one word and surrounded by the appropriate markup | |
| (for example, ``:mod:`timezone```). | |
| When talking about the real-world concept it is spelled as two words. |
Sorry, something went wrong.
There was a problem hiding this comment.
I added a modified version of this text.
Sorry, something went wrong.
python/cpython#118449 corrects "timezone" to "time zone". This records the guidance for posterity.
📚 Documentation preview 📚: https://cpython-devguide--1352.org.readthedocs.build/