Unify doc mark-ups

[muzimuzhi]

Mark-up all commands (gh help issue), flags (--json), environment variables (GH_PATH), and paths to files found in doc strings with backticks consistently. Currently various delimiters are used: "...", '...', `...`, and no delimiters.

• All cases found in raw strings in long: heredoc.Doc(`...`), Long: heredoc.Doc(`...`), and Long: heredoc.Docf(`...`, "`") are adapted.
• Some types of special words are changed to be surrounded by double-quotes: scopes ("repo"), special values ("POST"), patterns ("OWNER/REPO").
• Line wraps are not adjusted, partially because I find the max character number per line is inconsistent.

[cliAutomation]

Hi! Thanks for the pull request. Please ensure that this change is linked to an issue by mentioning an issue number in the description of the pull request. If this pull request would close the issue, please put the word 'Fixes' before the issue number somewhere in the pull request body. If this is a tiny change like fixing a typo, feel free to ignore this message.

[andyfeller]

@muzimuzhi : Thanks for your efforts to improve the CLI! I believe I understand the changes you have made and see what impact this would have regarding the formatting of help usage within the CLI and on the website.

As per our contributing guidelines we ask that PRs are created only for pre-approved work. Often there is more than one outcome for a solution and it helps us a lot to understand what our users are trying to do without muddying PRs with loosely related discussions.

Could I trouble you with creating this issue while we review these changes for any concerns or additional ideas please? 🙇

[muzimuzhi]

@andyfeller #8348 is created

[andyfeller]

Firstly, I appreciate the level of effort to review all of these commands and align formatting, spacing issues, and typos/wordage! 🙇

I've left a few suggestions for additional places that might/should be quoted to follow this style. Let me know what you think and whether these suggestions are consistent/inconsistent with what you found while doing this work. 👍

[muzimuzhi]

@andyfeller Thanks for your careful review! I was aware of (all but graphql) cases you pointed out (and struggled with them for quite some time). The line I drawn when opening this PR was

• Some types of special words are changed to be surrounded by double-quotes: scopes ("repo"), special values ("POST"), patterns ("OWNER/REPO").

(I classified value "0", argument(?) "-" and keys pressed like "q" all to type "special values".)

I'm open to changing all such cases, and I'm also willing to wait to see what feedbacks #8348 will receive.

[andyfeller]

@andyfeller Thanks for your careful review! I was aware of (all but graphql) cases you pointed out (and struggled with them for quite some time). The line I drawn when opening this PR was

• Some types of special words are changed to be surrounded by double-quotes: scopes ("repo"), special values ("POST"), patterns ("OWNER/REPO").

(I classified value "0", argument(?) "-" and keys pressed like "q" all to type "special values".)

I'm open to changing all such cases, and I'm also willing to wait to see what feedbacks #8348 will receive.

@muzimuzhi : I can understand the struggle!!!

In an effort to be as objective as possible, how about we take a look at GitHub Docs for similar examples to help guide how to handle:

1. Scopes
2. HTTP methods
3. Patterns
4. Key shortcuts

If the GitHub Docs highlights them with code blocks / fencing, then we should feel confident of doing the same. As such, let me see about finding examples and will update the issue with links for consideration.

[muzimuzhi]

GitHub Docs (https://docs.github.com/en / https://github.com/github/docs) itself is not 100% consistent on formatting special phrases.

1. Scopes

Inconsistent

• The "admin:enterprise" scope
  https://github.com/github/docs/blob/main/content/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users.md
• with the **admin:enterprise** scope
  https://github.com/github/docs/blob/main/content/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-with-okta.md
• with the `admin:enterprise` scope
  https://github.com/github/docs/blob/main/content/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-okta.md

2. HTTP methods

send a `POST` request to
https://docs.github.com/en/actions/deployment/protecting-deployments/creating-custom-deployment-protection-rules#approving-or-rejecting-deployments

3. Patterns

If the `OWNER/` portion of the `OWNER/REPO` repository
https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository?tool=cli#cloning-a-repository

In this example, replace `owner/repo` with the repository identifier.
https://docs.github.com/en/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository

4. Key shortcuts

A special tag <kbd> like press <kbd>Shift</kbd> which rendered as framed inline code.
https://docs.github.com/en/issues/planning-and-tracking-with-projects/managing-items-in-your-project/editing-items-in-your-project

For remaining types other than scopes, I think the suggestion from GitHub Docs is: use code blocks.

[muzimuzhi]

4. Key shortcuts

A special tag <kbd> like press <kbd>Shift</kbd> which rendered as framed inline code. https://docs.github.com/en/issues/planning-and-tracking-with-projects/managing-items-in-your-project/editing-items-in-your-project

Also in italic Press _Shift_
https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile#viewing-contributions-from-specific-times

[muzimuzhi]

I wrapped all cases, including scopes in backticks.

Changes to scopes are committed at last, so it's easy to drop them if the final decision is to not format them like inline code.

Some small doc fixing/improvements are also applied in separate commits. Feel free to ask me to propose them in separate PR(s) if that's the right way.

[andyfeller]

I wrapped all cases, including scopes in backticks.

Changes to scopes are committed at last, so it's easy to drop them if the final decision is to not format them like inline code.

Some small doc fixing/improvements are also applied in separate commits. Feel free to ask me to propose them in separate PR(s) if that's the right way.

@muzimuzhi : Excellent! My apologies for the delayed follow up on my part with the holiday last week. Let's get this re-reviewed and merged in, thank you so much for being a great contributor, Yukai! 🙇

[andyfeller]

@muzimuzhi : I think this is ready to go!

I've manually built this branch and iterated over every command changed, catching a few things that remained including the footer added for help at the end of every command.

Once again, tremendous effort which I look forward to seeing on the CLI manual once shipped! 🎉

[andyfeller]

All manual testing looks good, will confirm website changes once release 👍

[YT026]

🧙🏻‍♂️

[andyfeller]

@muzimuzhi : looking at https://cli.github.com/manual/gh_api versus https://web.archive.org/web/20231123042701/https://cli.github.com/manual/gh_api, sooooo much better! thank you again for your diligence adding the polish our docs needed ❤️ 🙇

[muzimuzhi]

@andyfeller Thank you too. It's only possible and made even better with your careful review.