Add command line syntax doc by probablycorey · Pull Request #862 · cli/cli

probablycorey · 2020-05-04T18:59:31Z

Here is my first pass at some documentation for how we use this.

Questions:

We don't have good examples for some simple patterns, like mutually exclusive arguments. We have examples, but they are kind of complicated.
Do we want to include more examples of things like "a required flag with mutually exclusive placeholder arguments"

References:
google - pretty thorough, but doesn't follow the standards we've been using
microsoft - very simple, but matches what we have
ibm - like microsoft's but with more examples

vilmibm

I this is is a good first step!

We don't have good examples for some simple patterns, like mutually exclusive arguments. We have examples, but they are kind of complicated.

I think the example you used is fine.

Do we want to include more examples of things like "a required flag with mutually exclusive placeholder arguments"

Are there specific things we do right now that you are thinking of? I think it's okay to use a complicated example here; in trying to document it we might think of better ways to express or implement certain things.

mislav

google's document is pretty thorough, but doesn't follow the standards we've been using

I'm interested in where you've found google's document to differ from the standards we've been using? I've just combed through it and I cannot find it. It matches microsoft's document, except that it goes more in depth.

mislav · 2020-05-05T10:53:46Z

docs/command-line-syntax.md

@@ -0,0 +1,39 @@
+# How we document our command line syntax
+
+## Required arguments


Could we say "literal" arguments instead of "required"?

E.g. in this invocation none of the arguments are really "required":

gh repo create myproject

The last argument could be omitted and the command would still work, and the create argument isn't really a "required" argument for repo as much as it is one of the possible arguments for repo.

So I would say that anything that appears in plain text (i.e. not enclosed in brackets) should be taken verbatim.

This is tricky. I think I see the word "required" modifying something different than you. I see it as "in the given usage string this arg is required" but you seeing as "this argument is required". The difference being in my interpretation the arg isn't always required, but in your interpretation it is.

So in the usage string gh repo create [<my-project>] all the plain text is required to be unchanged, but the parts in the brackets can change or be left out.

But I see where your coming from and I'm going to think about this for a bit.

Ah I see where you're coming from too! I could go either way.

Maybe it also goes without saying that any text that is not explicitly marked with [...], <...>, or {...} has no special properties.

docs/command-line-syntax.md

mislav · 2020-05-05T11:31:32Z

docs/command-line-syntax.md

+Ellipsis represent arguments that can appear multiple times
+
+_*example:*_
+`gh pr close <numbers … >`


The ellipsis should be outside of angled brackets

Suggested change

`gh pr close <numbers … >`

`gh pr close <number>...`

This is one where I had trouble. Google's example of using ellipsis looks like this.

gcloud dns group [global-flag ...]

IBM has a cli document that shows ellipsis inside [] but outside {}. That kind of makes sense because {} is treated like a set, so the set is repeating.

So based on the docs and examples I see it looks like it goes inside angled brackets. Do you have examples of ellipses in existing cli apps we can look at?

Inspecting the HTML source of google's document reveals ellipsis was outside of the placeholder:

<code> gcloud dns <var>group</var> [<var>global-flag</var> ...] </code>

The cat(1) manual says:

cat [<OPTION>]... [<FILE>]...

git-rev-parse(1) says:

git rev-parse [<options>] <args>...

AWS CLI says:

aws s3 <Command> [<Arg> ...]

probablycorey · 2020-05-05T16:36:04Z

I'm interested in where you've found google's document to differ from the standards we've been using?

The thing I noticed was their examples for placeholder text. The doc says use the <var> element but none of their examples use <>, they all use plain text to represent text the user needs to replace.

mislav · 2020-05-07T12:02:29Z

The thing I noticed was their examples for placeholder text. The doc says use the <var> element but none of their examples use <>

I see! I've interpreted that to be due to their HTML rendering of the documentation. All instances of <placeholder> in the google document are replaced with <var>placeholder</var> in HTML, but rendered without angle brackets. However, they are still placeholders, and I'm pretty sure they still have angle brackets in the original source.

probablycorey · 2020-05-07T17:14:27Z

I've made some additional changes to this. Let me know what you think.

docs/command-line-syntax.md

mislav · 2020-05-08T15:09:11Z

Updated thoughts after sitting on this for a bit:

If our goal is readability/cleanliness, we could allow [one | two] as a shorthand syntax for [{one | two}] (with both being "correct"), meaning "optional and mutually-exclusive". I'm now seeing more and more commands that adopt this guideline, such as git's own docs.
I do believe placeholders should always be marked up with <...>, no exceptions, so the above syntax becomes [<number> | <url>] when it comes to alternate input formats for user values.
Specifically for our pr docs: if repeating [<number> | <url> | <branch>] or {[<number> | <url> | <branch>]}argument in the usage of every command is getting unwieldy (and it feels like it is), maybe we could go back to simply printing usage synopsis lines like so: gh pr view <pr>. We can leave the user to guess what the <pr> argument could be, and their guesses will probably be correct. Otherwise, the docs itself have a note about us accepting PR numbers, URLs, and branch expressions as argument to most commands.
Maybe we should clarify that no expressions (no other bracket/brace styles) are allowed within <...>. This is because we may in the future post-process our docs to format placeholders somehow when showing man pages or HTML docs. (For example, Google renders their placeholders using <var>...</var> in their HTML docs and styles them with CSS.) If a placeholder name would contain an expression <{foo | bar }>, then the whole expression {foo | bar } would get formatted as a placeholder name, which might look weird.

probablycorey · 2020-05-08T18:50:36Z

If our goal is readability/cleanliness, we could allow [one | two] as a shorthand syntax for [{one | two}]

I think this makes sense. [one | two] is more readable and if others are doing that I think we should adopt it as our standard.

I do believe placeholders should always be marked up with <...>, no exceptions

I'm behind this stance as well

Specifically for our pr docs: if repeating [ | | ] or {[ | | ]}argument in the usage of every command is getting unwieldy (and it feels like it is), maybe we could go back to simply printing usage synopsis lines like so: gh pr view .

This hasn't passed the threshold for me yet (but it is right on the line.) I'm leaning towards listing out the three examples right now because it still feels readable to me.

Maybe we should clarify that no expressions (no other bracket/brace styles) are allowed within <...>

Yes, I'll add this.

mislav

Thank you for the updates!

🚀🌔

probablycorey added 2 commits May 4, 2020 11:52

Add doc

2f8d3a0

Update text

1694ea2

probablycorey self-assigned this May 4, 2020

vilmibm approved these changes May 4, 2020

View reviewed changes

mislav mentioned this pull request May 5, 2020

Tweak syntax in issue/pr close docs #863

Merged

mislav suggested changes May 5, 2020

View reviewed changes

probablycorey added 3 commits May 5, 2020 09:52

Use "a value"

7d1910d

don't use camel case

4e54888

Add note for variable naming

cb8d996

probablycorey added 2 commits May 7, 2020 09:28

Update doc

67f65a0

Update doc

5cf6fb4

mislav reviewed May 7, 2020

View reviewed changes

docs/command-line-syntax.md Outdated Show resolved Hide resolved

Update docs

9267804

Update docs

a46e7ca

mislav approved these changes May 11, 2020

View reviewed changes

probablycorey merged commit fe49c2d into master May 11, 2020

mislav deleted the cli-syntax branch June 25, 2020 14:37

		@@ -0,0 +1,39 @@
		# How we document our command line syntax

		## Required arguments

Conversation

probablycorey commented May 4, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vilmibm left a comment

Choose a reason for hiding this comment

Uh oh!

mislav left a comment

Choose a reason for hiding this comment

Uh oh!

mislav May 5, 2020

Choose a reason for hiding this comment

Uh oh!

probablycorey May 5, 2020

Choose a reason for hiding this comment

Uh oh!

mislav May 7, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mislav May 5, 2020

Choose a reason for hiding this comment

Uh oh!

probablycorey May 5, 2020

Choose a reason for hiding this comment

Uh oh!

mislav May 7, 2020

Choose a reason for hiding this comment

Uh oh!

probablycorey commented May 5, 2020 • edited by mislav Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mislav commented May 7, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

probablycorey commented May 7, 2020

Uh oh!

Uh oh!

mislav commented May 8, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

probablycorey commented May 8, 2020

Uh oh!

mislav left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

probablycorey commented May 4, 2020 •

edited

Loading

probablycorey commented May 5, 2020 •

edited by mislav

Loading

mislav commented May 7, 2020 •

edited

Loading

mislav commented May 8, 2020 •

edited

Loading