andyfeller
commented
11 months ago @muzimuzhi : once again, thank you for both the PR and the issue ❤ going to re-review, I appreciate your patience given the holidays and a few other priorities emerging 🙇
Reviewing GitHub Docs for consideration on formatting
From https://github.com/cli/cli/pull/8342#issuecomment-1819177979:
@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:
- Scopes
- HTTP methods
- Patterns
- 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.
Scopes
TLDR: Wrapped / emphasized
Basically every single endpoint in the GitHub REST API reference uses backticks to emphasize scopes.
HTTP methods
TLDR: Wrapped and emphasized
-
"REST API / Guides / Getting started with the REST API"
To make a request, first find the HTTP method and the path for the operation that you want to use. For example, the "Get Octocat" operation uses the
GETmethod and the /octocat path. For the full reference documentation for this operation, see "Meta." -
"REST API / Guides / Best practices for using the REST API"
If you are making a large number of
POST,PATCH,PUT, orDELETErequests, wait at least one second between each request. This will help you avoid secondary rate limits.
Patterns
TLDR: OWNER/REPO appears to be consistent form
-
"Repositories / Create * manage repositories / Duplicating a repository"
Before you can push the original repository to your new copy, or mirror, of the repository, you must create the new repository on GitHub.com. In these examples,
exampleuser/new-repositoryorexampleuser/mirroredare the mirrors. -
"Account and profile / Personal accounts / Personal account settings / About username changes"
If the account namespace includes any public repositories that contain an action listed on GitHub Marketplace, or that had more than 100 clones or more than 100 uses of GitHub Actions in the week prior to you renaming your account, GitHub permanently retires the old owner name and repository name combination (
OLD-OWNER/REPOSITORY-NAME) when you rename your account. If you try to create a repository using a retired owner name and repository name combination, you will see the error: "The repository<REPOSITORY_NAME>has been retired and cannot be reused." -
"Repositories / Create & manage repositories / Transferring a repository"
If the transferred repository contains an action listed on GitHub Marketplace, or had more than 100 clones or more than 100 uses of GitHub Actions in the week prior to the transfer, GitHub permanently retires the owner name and repository name combination (
OWNER/REPOSITORY-NAME) when you transfer the repository. If you try to create a repository using a retired owner name and repository name combination, you will see the error: "The repositoryREPOSITORY_NAMEhas been retired and cannot be reused."
Key shortcuts
TLDR: Wrapped / emphasized
-
"GitHub Actions / Learn GitHub Actions / Expressions"
You don't need to enclose strings in
${{and}}. However, if you do, you must use single quotes (') around the string. To use a literal single quote, escape the literal single quote using an additional single quote (''). Wrapping with double quotes (") will throw an error. -
"GitHub CLI / GitHub CLI / Using GitHub CLI extensions"
To install an extension in development from the current directory, use
.as the value for the repo parameter. -
"GitHub Codespaces / The github.dev web-based editor"
To open the repository in the same browser tab, press
.while browsing any repository or pull request on GitHub.To open the repository in a new browser tab, press
>.
Addendum
Though not the GitHub Docs, I think we should adopt the same contribution guidelines they use including:
muzimuzhi
CLI Feedback
Among all the manual pages (https://cli.github.com/manual/), currently special code-like phrases used inline are marked inconsistently: each of the style
"...",'...',..., and no delimiters can be found.To list some types:
gh help issue)--json)GH_PATH, mostly in https://cli.github.com/manual/gh_help_environment)repo)true)[HOST/]OWNER/REPO)sh,POST)For example, in command description part,
gh release downloadmanual page uses double quotes"--pattern" or "--archive"https://cli.github.com/manual/gh_release_downloadgh release uploadmanual page uses single quotestext starting with '#'https://cli.github.com/manual/gh_release_uploadgh release createmanual page uses backtickstext starting with `#`,Use `--target` to point to,do `git fetch --tags origin`https://cli.github.com/manual/gh_release_creategh auth logoutmanual page uses raw textor via --hostnamehttps://cli.github.com/manual/gh_auth_logoutWhat have you loved?
A consistent styling
What was confusing or gave you pause?
These special phrases appear not only in multiline command descriptions, but also in command-line help outputs.
In the latter case, currently double quotes are most frequently used.
Anything else?
In https://github.com/cli/cli/pull/8342 I proposed changes which unifies styling of commands, flags, env vars, and paths to files to be surrounded by a pair of backticks
`...`, for all cases found in raw strings used inlong: heredoc.Doc(`...`),Long: heredoc.Doc(`...`), andLong: heredoc.Docf(`...`, "`").This makes those phrases styled the same as flags in "Options" sections.