Skip to content
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

Merged

Conversation

Mickeon
Copy link
Contributor

@Mickeon Mickeon commented Nov 17, 2024

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.

@Mickeon Mickeon added bug enhancement documentation cherrypick:4.3 Considered for cherry-picking into a future 4.3.x release labels Nov 17, 2024
@Mickeon Mickeon added this to the 4.4 milestone Nov 17, 2024
@Mickeon Mickeon requested a review from a team as a code owner November 17, 2024 17:15
@Mickeon Mickeon force-pushed the documentation-global-scope-keys-plus-minus branch from de9b6e8 to d54e0e6 Compare November 17, 2024 17:18
@@ -2143,49 +2143,49 @@
Space key.
</constant>
<constant name="KEY_EXCLAM" value="33" enum="Key">
! key.
Exclamation mark ([code]![/code]) key.
Copy link
Contributor Author

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.

Copy link
Contributor

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

Copy link
Member

@aaronfranke aaronfranke Nov 22, 2024

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".

Copy link
Contributor

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

@Mickeon

This comment was marked as resolved.

@Mickeon Mickeon force-pushed the documentation-global-scope-keys-plus-minus branch 2 times, most recently from b0f9724 to f4b00dd Compare November 17, 2024 17:40
Copy link
Contributor

@tetrapod00 tetrapod00 left a 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.
Copy link
Contributor

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

<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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Copy link
Contributor Author

@Mickeon Mickeon Nov 17, 2024

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.

@Mickeon Mickeon force-pushed the documentation-global-scope-keys-plus-minus branch 2 times, most recently from dd02459 to 139bd06 Compare November 17, 2024 18:58
@Mickeon Mickeon requested a review from akien-mga November 17, 2024 19:00
@Mickeon Mickeon force-pushed the documentation-global-scope-keys-plus-minus branch from 139bd06 to 2afe7b4 Compare November 22, 2024 20:39
@Mickeon
Copy link
Contributor Author

Mickeon commented Nov 22, 2024

Addressed @akien-mga 's keyword issue.

Copy link
Member

@aaronfranke aaronfranke left a 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.

@Mickeon Mickeon force-pushed the documentation-global-scope-keys-plus-minus branch from 2afe7b4 to 344a55f Compare November 26, 2024 17:25
@Mickeon
Copy link
Contributor Author

Mickeon commented Nov 26, 2024

As @tetrapod00 also wanted, I updated the PR to also mention both of the above.

</constant>
<constant name="KEY_PARENLEFT" value="40" enum="Key">
( key.
<constant name="KEY_PARENLEFT" value="40" enum="Key" keywords="round_bracket_left">
Copy link
Member

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.

Copy link
Contributor Author

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

Copy link
Contributor Author

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.

@Mickeon Mickeon force-pushed the documentation-global-scope-keys-plus-minus branch from 344a55f to e653f19 Compare November 26, 2024 17:42
@Repiteo Repiteo merged commit 19dd3ed into godotengine:master Nov 26, 2024
20 checks passed
@Repiteo
Copy link
Contributor

Repiteo commented Nov 26, 2024

Thanks!

@Mickeon Mickeon deleted the documentation-global-scope-keys-plus-minus branch November 26, 2024 20:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug cherrypick:4.3 Considered for cherry-picking into a future 4.3.x release documentation enhancement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Incorrect key descriptions for KEY_PLUS and KEY_MINUS in the Key Enumerator description
5 participants