Clarify 'time zone' in a Specific words section #1352
Conversation
documentation/style-guide.rst
Outdated
| 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.
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.
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.
There was a problem hiding this comment.
Sure, if it does not clutter the wording too much, I'm fine with such a change.
I'm not sure this rises to that level yet, but will keep it in mind. |
documentation/style-guide.rst
Outdated
| .. _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?
There was a problem hiding this comment.
The link might also be confused with the glossary directive.
There was a problem hiding this comment.
I changed the reference to specific words.
documentation/style-guide.rst
Outdated
| 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. |
There was a problem hiding this comment.
I added a modified version of this text.
python/cpython#118449 corrects "timezone" to "time zone". This records the guidance for posterity.
📚 Documentation preview 📚: https://cpython-devguide--1352.org.readthedocs.build/