From 2f8d3a0247d45461f82f74b6106f552a92fc1617 Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Mon, 4 May 2020 11:52:09 -0700 Subject: [PATCH 1/9] Add doc --- docs/command-line-syntax.md | 39 +++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/command-line-syntax.md diff --git a/docs/command-line-syntax.md b/docs/command-line-syntax.md new file mode 100644 index 000000000..727f2b5b6 --- /dev/null +++ b/docs/command-line-syntax.md @@ -0,0 +1,39 @@ +# How we document our command line syntax + +## Required arguments + +Use plain text + +_*example:*_ +`gh help` +help is a required argument in this command + +## Placeholder values + +Use Angled brackets to represent text that you must supply + +_*example:*_ +`gh pr view ` +Replace `` with an issue number + +## Optional arguments + +Place optional arguments in square brackets + +_*example:*_ +`gh pr checkout [--web]` +Replace `--web` is an optional argument + +## Mutually exclusive arguments + +Place mutually exclusive arguments inside braces separated by a vertical bar. + +_*example:*_ +`gh pr {view | create}` + +## Repeatable arguements + +One or more arguments can replace arguments with ellipsis + +_*example:*_ +`gh pr close ` From 1694ea29b4df0102da5bbbf7d081d05b81e60b3c Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Mon, 4 May 2020 11:57:05 -0700 Subject: [PATCH 2/9] Update text --- docs/command-line-syntax.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/command-line-syntax.md b/docs/command-line-syntax.md index 727f2b5b6..95f924bc8 100644 --- a/docs/command-line-syntax.md +++ b/docs/command-line-syntax.md @@ -6,11 +6,11 @@ Use plain text _*example:*_ `gh help` -help is a required argument in this command +The argument help is required in this command ## Placeholder values -Use Angled brackets to represent text that you must supply +Use angled brackets to represent text that a user must supply _*example:*_ `gh pr view ` @@ -22,18 +22,18 @@ Place optional arguments in square brackets _*example:*_ `gh pr checkout [--web]` -Replace `--web` is an optional argument +The argument `--web` is optional. ## Mutually exclusive arguments -Place mutually exclusive arguments inside braces separated by a vertical bar. +Place mutually exclusive arguments inside braces, separate arguments with vertical bars. _*example:*_ `gh pr {view | create}` ## Repeatable arguements -One or more arguments can replace arguments with ellipsis +Ellipsis represent arguments that can appear multiple times _*example:*_ `gh pr close ` From 7d1910d94589a75d9507338cd9eb6f08cc836f28 Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Tue, 5 May 2020 09:52:36 -0700 Subject: [PATCH 3/9] Use "a value" --- docs/command-line-syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/command-line-syntax.md b/docs/command-line-syntax.md index 95f924bc8..c44461c29 100644 --- a/docs/command-line-syntax.md +++ b/docs/command-line-syntax.md @@ -10,7 +10,7 @@ The argument help is required in this command ## Placeholder values -Use angled brackets to represent text that a user must supply +Use angled brackets to represent a value the user must supply _*example:*_ `gh pr view ` From 4e548880d536d677904caa1dc3b6f90734f68a37 Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Tue, 5 May 2020 09:52:50 -0700 Subject: [PATCH 4/9] don't use camel case --- docs/command-line-syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/command-line-syntax.md b/docs/command-line-syntax.md index c44461c29..684da5799 100644 --- a/docs/command-line-syntax.md +++ b/docs/command-line-syntax.md @@ -14,7 +14,7 @@ Use angled brackets to represent a value the user must supply _*example:*_ `gh pr view ` -Replace `` with an issue number +Replace `` with an issue number ## Optional arguments From cb8d9963e3a2c000754d268508b9418dfcbd2124 Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Tue, 5 May 2020 09:55:27 -0700 Subject: [PATCH 5/9] Add note for variable naming --- docs/command-line-syntax.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/command-line-syntax.md b/docs/command-line-syntax.md index 684da5799..c4914bea5 100644 --- a/docs/command-line-syntax.md +++ b/docs/command-line-syntax.md @@ -37,3 +37,10 @@ Ellipsis represent arguments that can appear multiple times _*example:*_ `gh pr close ` + +## Variable naming + +For multi-word variables use dash-case (all lower case with words seperated by dashes) + +_*example:*_ +`gh pr checkout ` From 67f65a09d012c2d8bef7665749df65c0ae2a515e Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Thu, 7 May 2020 09:28:34 -0700 Subject: [PATCH 6/9] Update doc --- docs/command-line-syntax.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/command-line-syntax.md b/docs/command-line-syntax.md index c4914bea5..7da20588e 100644 --- a/docs/command-line-syntax.md +++ b/docs/command-line-syntax.md @@ -1,8 +1,8 @@ # How we document our command line syntax -## Required arguments +## Required text -Use plain text +Use plain text for any part of the command that can not be changed _*example:*_ `gh help` @@ -36,7 +36,7 @@ _*example:*_ Ellipsis represent arguments that can appear multiple times _*example:*_ -`gh pr close ` +`gh pr close ...` ## Variable naming @@ -44,3 +44,11 @@ For multi-word variables use dash-case (all lower case with words seperated by d _*example:*_ `gh pr checkout ` + +## Complex examples + +_*required argument with mutually exclusive optoins:*_ +`gh pr close <{number | url}>` + +_*optional argument with mutually exclusive optoins:*_ +`gh pr close [{ | }]` From 5cf6fb4af47132f981dab05658c42008619ad781 Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Thu, 7 May 2020 10:13:36 -0700 Subject: [PATCH 7/9] Update doc --- docs/command-line-syntax.md | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/command-line-syntax.md b/docs/command-line-syntax.md index 7da20588e..dc828961d 100644 --- a/docs/command-line-syntax.md +++ b/docs/command-line-syntax.md @@ -2,25 +2,25 @@ ## Required text -Use plain text for any part of the command that can not be changed +Use plain text for parts of the command that cannot be changed -_*example:*_ +_example:_ `gh help` The argument help is required in this command ## Placeholder values -Use angled brackets to represent a value the user must supply +Use angled brackets to represent a value the user must replace -_*example:*_ -`gh pr view ` +_example:_ +`gh pr view ` Replace `` with an issue number ## Optional arguments Place optional arguments in square brackets -_*example:*_ +_example:_ `gh pr checkout [--web]` The argument `--web` is optional. @@ -28,27 +28,30 @@ The argument `--web` is optional. Place mutually exclusive arguments inside braces, separate arguments with vertical bars. -_*example:*_ +_example:_ `gh pr {view | create}` -## Repeatable arguements +## Repeatable arguments Ellipsis represent arguments that can appear multiple times -_*example:*_ -`gh pr close ...` +_example:_ +`gh pr close ...` ## Variable naming -For multi-word variables use dash-case (all lower case with words seperated by dashes) +For multi-word variables use dash-case (all lower case with words separated by dashes) -_*example:*_ +_example:_ `gh pr checkout ` -## Complex examples +## Additional examples -_*required argument with mutually exclusive optoins:*_ -`gh pr close <{number | url}>` +_optional argument with placeholder:_ +`command sub-command []` -_*optional argument with mutually exclusive optoins:*_ -`gh pr close [{ | }]` +_required argument with mutually exclusive options:_ +`command sub-command <{path | string}>` + +_optional argument with mutually exclusive options:_ +`command sub-command [{ | }]` From 9267804ef371dd695c88693cf0fda291aa0f7bc2 Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Fri, 8 May 2020 11:44:30 -0700 Subject: [PATCH 8/9] Update docs --- docs/command-line-syntax.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/command-line-syntax.md b/docs/command-line-syntax.md index dc828961d..f931eec13 100644 --- a/docs/command-line-syntax.md +++ b/docs/command-line-syntax.md @@ -51,7 +51,7 @@ _optional argument with placeholder:_ `command sub-command []` _required argument with mutually exclusive options:_ -`command sub-command <{path | string}>` +`command sub-command { | | literal}` _optional argument with mutually exclusive options:_ -`command sub-command [{ | }]` +`command sub-command [ | ]` From a46e7cab2fa321409414b7ea38811b571988330b Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Fri, 8 May 2020 11:54:13 -0700 Subject: [PATCH 9/9] Update docs --- docs/command-line-syntax.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/command-line-syntax.md b/docs/command-line-syntax.md index f931eec13..b7c359051 100644 --- a/docs/command-line-syntax.md +++ b/docs/command-line-syntax.md @@ -1,6 +1,6 @@ # How we document our command line syntax -## Required text +## Literal text Use plain text for parts of the command that cannot be changed @@ -10,7 +10,7 @@ The argument help is required in this command ## Placeholder values -Use angled brackets to represent a value the user must replace +Use angled brackets to represent a value the user must replace. No other expressions can be contained within the angeled brackets. _example:_ `gh pr view ` @@ -18,15 +18,18 @@ Replace `` with an issue number ## Optional arguments -Place optional arguments in square brackets +Place optional arguments in square brackets. Mutually exclusive arguments can be included inside square brackets if they are separated with vertical bars. _example:_ `gh pr checkout [--web]` The argument `--web` is optional. -## Mutually exclusive arguments +`gh pr view [ | ]` +The `` and `` arguments are optional. -Place mutually exclusive arguments inside braces, separate arguments with vertical bars. +## Required mutually exclusive arguments + +Place required mutually exclusive arguments inside braces, separate arguments with vertical bars. _example:_ `gh pr {view | create}`