-
-
Notifications
You must be signed in to change notification settings - Fork 21.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Rewrite some @GlobalScope
keys in documentation to use [code]
tags
#99364
Rewrite some @GlobalScope
keys in documentation to use [code]
tags
#99364
Conversation
de9b6e8
to
d54e0e6
Compare
@@ -2143,49 +2143,49 @@ | |||
Space key. | |||
</constant> | |||
<constant name="KEY_EXCLAM" value="33" enum="Key"> | |||
! key. | |||
Exclamation mark ([code]![/code]) key. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In US English this is commonly known as an "Exclamation point". however, for consistency with the surrounding descriptions, I'd rather personally call it "Exclamation mark". Feel free to argue against this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Both seem perfectly fine to me as a native American English speaker. I don't think the American English standard that Godot uses needs to apply to the choice of terms to use, it's mostly important to standardize spelling
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm from the US (lived in CA, TX, NC) and I've only ever heard it referred to as "Exclamation mark".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Midwest perspective: I've most commonly heard either "Exclamation Point" or simply "Exclamation;" while comparatively uncommon, it's obvious what "Exclamation Mark" is referring to & it does fit better overall
This comment was marked as resolved.
This comment was marked as resolved.
b0f9724
to
f4b00dd
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(Assuming that Mickeon knows what they're doing with formatting) Good as-is, left some optional comments
@@ -2143,49 +2143,49 @@ | |||
Space key. | |||
</constant> | |||
<constant name="KEY_EXCLAM" value="33" enum="Key"> | |||
! key. | |||
Exclamation mark ([code]![/code]) key. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Both seem perfectly fine to me as a native American English speaker. I don't think the American English standard that Godot uses needs to apply to the choice of terms to use, it's mostly important to standardize spelling
doc/classes/@GlobalScope.xml
Outdated
<constant name="KEY_BAR" value="124" enum="Key"> | ||
| key. | ||
<constant name="KEY_BAR" value="124" enum="Key" keywords="KEY_PIPE"> | ||
Vertical bar ([code]|[/code]) key. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Vertical bar ([code]|[/code]) key. | |
Vertical bar or pipe ([code]|[/code]) key. |
Potentially?
For some reason it seems weird to not use the name as it appears in the enum itself. But I also see the logic of only including one name for the character, and choosing the most popular one, even if it's not the one in the enum itself.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was going to add things along the lines of "also known as...", but I believed it to be out of scope of this PR, or potentially be just a bit too verbose for my tastes.
dd02459
to
139bd06
Compare
139bd06
to
2afe7b4
Compare
Addressed @akien-mga 's keyword issue. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good, but I would personally prefer to mention the word "pipe" directly in the description of |
, and "hash" for #
. These are arguably the more common names, though not the official ones according to Wikipedia.
2afe7b4
to
344a55f
Compare
As @tetrapod00 also wanted, I updated the PR to also mention both of the above. |
doc/classes/@GlobalScope.xml
Outdated
</constant> | ||
<constant name="KEY_PARENLEFT" value="40" enum="Key"> | ||
( key. | ||
<constant name="KEY_PARENLEFT" value="40" enum="Key" keywords="round_bracket_left"> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I still don't understand why we're using "snake_case" keywords here?
Keywords are related words that users might type in the search bar. They're meant to be natural language, not pseudo API.
I would just put "round bracket left" as a keyword, or no keywords.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Unsure now that I think about it, it's just been convention. Keywords don't really rely on the underscore
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated the PR. Because they're not in snake_case
anymore, I believed it was worth rewriting the "left" and "right" bracket keywords to be "open" and "close", respectively.
344a55f
to
e653f19
Compare
Thanks! |
Fixes godotengine/godot-docs#8127
This PR changes the descriptions of some
@GlobalScope
Key constants to be a bit more elaborate and use[code]
tags, instead of beginning with the symbol. This not only prevents the symbols from accidentally being used for formatting, but allows the descriptions to be localized a lot better.In the meantime, keywords are also added to the affected keys.
This PR originally was going to use
[kbd]
tags across ALL Keys. However, the idea fell through.Content in
[kbd]
tags is assumed to be untranslatable, as the engine does not localize keycode text. It also oftentimes made readability worse (for the sake of accuracy), and would've been a massive change for a somewhat cosmetic change. This can be reconsidered another time.