Re: [PATCH v2] Use proper syntax for replaceables in command docs

[Junio C Hamano]

"Robert P. J. Day"  writes:

> The standard for command documentation synopses appears to be:
>
>   [...] means optional
>   <...> means replaceable
>   [<...>] means both optional and replaceable
>
> So fix a number of doc pages that use incorrect variations of the
> above.
>
> Signed-off-by: Robert P. J. Day 
>
> ---
>
> diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt
> index 05fd482b7..e44a83133 100644
> --- a/Documentation/git-annotate.txt
> +++ b/Documentation/git-annotate.txt
> @@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information
>  SYNOPSIS
>  
>  [verse]
> -'git annotate' [options] file [revision]
> +'git annotate' []  []
> ...
> -'git check-mailmap' [options] ...
> +'git check-mailmap' [] ...

A pedant in me screams s//.../ after seeing this
line, but  appears _very_ _very_ often and extremely handy,
compared to having to spell "...".  So let's standardise
the way this patch does.

Thanks.

Re: [PATCH v2] Use proper syntax for replaceables in command docs

[Simon Ruderich]

On Thu, May 24, 2018 at 04:11:39PM -0400, Robert P. J. Day wrote:
> diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
> index 37b96c545..f98b7c6ed 100644
> --- a/Documentation/git-cvsserver.txt
> +++ b/Documentation/git-cvsserver.txt
> @@ -22,7 +22,7 @@ cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver 
> git-cvsserver pserver
>  Usage:
>
>  [verse]
> -'git-cvsserver' [options] [pserver|server] [ ...]
> +'git-cvsserver' [] [pserver|server] [ ...]

No space in front of "..." for consistency?

Regards
Simon
-- 
+ privacy is necessary
+ using gnupg http://gnupg.org
+ public key id: 0x92FEFDB7E44C32F9

[PATCH v2] Use proper syntax for replaceables in command docs

[Robert P. J. Day]

The standard for command documentation synopses appears to be:

  [...] means optional
  <...> means replaceable
  [<...>] means both optional and replaceable

So fix a number of doc pages that use incorrect variations of the
above.

Signed-off-by: Robert P. J. Day 

---

diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt
index 05fd482b7..e44a83133 100644
--- a/Documentation/git-annotate.txt
+++ b/Documentation/git-annotate.txt
@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information
 SYNOPSIS
 
 [verse]
-'git annotate' [options] file [revision]
+'git annotate' []  []

 DESCRIPTION
 ---
diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
index aa3b2bf2f..3c0578217 100644
--- a/Documentation/git-check-attr.txt
+++ b/Documentation/git-check-attr.txt
@@ -9,8 +9,8 @@ git-check-attr - Display gitattributes information
 SYNOPSIS
 
 [verse]
-'git check-attr' [-a | --all | attr...] [--] pathname...
-'git check-attr' --stdin [-z] [-a | --all | attr...]
+'git check-attr' [-a | --all | ...] [--] ...
+'git check-attr' --stdin [-z] [-a | --all | ...]

 DESCRIPTION
 ---
diff --git a/Documentation/git-check-ignore.txt 
b/Documentation/git-check-ignore.txt
index 611754f10..8b42cb3fb 100644
--- a/Documentation/git-check-ignore.txt
+++ b/Documentation/git-check-ignore.txt
@@ -9,8 +9,8 @@ git-check-ignore - Debug gitignore / exclude files
 SYNOPSIS
 
 [verse]
-'git check-ignore' [options] pathname...
-'git check-ignore' [options] --stdin
+'git check-ignore' [] ...
+'git check-ignore' [] --stdin

 DESCRIPTION
 ---
diff --git a/Documentation/git-check-mailmap.txt 
b/Documentation/git-check-mailmap.txt
index 39028ee1a..aa2055dbe 100644
--- a/Documentation/git-check-mailmap.txt
+++ b/Documentation/git-check-mailmap.txt
@@ -9,7 +9,7 @@ git-check-mailmap - Show canonical names and email addresses of 
contacts
 SYNOPSIS
 
 [verse]
-'git check-mailmap' [options] ...
+'git check-mailmap' [] ...


 DESCRIPTION
diff --git a/Documentation/git-credential-cache.txt 
b/Documentation/git-credential-cache.txt
index 2b8582639..0216c18ef 100644
--- a/Documentation/git-credential-cache.txt
+++ b/Documentation/git-credential-cache.txt
@@ -8,7 +8,7 @@ git-credential-cache - Helper to temporarily store passwords in 
memory
 SYNOPSIS
 
 -
-git config credential.helper 'cache [options]'
+git config credential.helper 'cache []'
 -

 DESCRIPTION
diff --git a/Documentation/git-credential-store.txt 
b/Documentation/git-credential-store.txt
index 25fb963f4..693dd9d9d 100644
--- a/Documentation/git-credential-store.txt
+++ b/Documentation/git-credential-store.txt
@@ -8,7 +8,7 @@ git-credential-store - Helper to store credentials on disk
 SYNOPSIS
 
 ---
-git config credential.helper 'store [options]'
+git config credential.helper 'store []'
 ---

 DESCRIPTION
diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
index 37b96c545..f98b7c6ed 100644
--- a/Documentation/git-cvsserver.txt
+++ b/Documentation/git-cvsserver.txt
@@ -22,7 +22,7 @@ cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver 
git-cvsserver pserver
 Usage:

 [verse]
-'git-cvsserver' [options] [pserver|server] [ ...]
+'git-cvsserver' [] [pserver|server] [ ...]

 OPTIONS
 ---
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 7c2c44270..b180f1fa5 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -9,11 +9,11 @@ git-diff - Show changes between commits, commit and working 
tree, etc
 SYNOPSIS
 
 [verse]
-'git diff' [options] [] [--] [...]
-'git diff' [options] --cached [] [--] [...]
-'git diff' [options]   [--] [...]
-'git diff' [options]  
-'git diff' [options] --no-index [--]  
+'git diff' [] [] [--] [...]
+'git diff' [] --cached [] [--] [...]
+'git diff' []   [--] [...]
+'git diff' []  
+'git diff' [] --no-index [--]  

 DESCRIPTION
 ---
@@ -21,7 +21,7 @@ Show changes between the working tree and the index or a 
tree, changes
 between the index and a tree, changes between two trees, changes between
 two blob objects, or changes between two files on disk.

-'git diff' [options] [--] [...]::
+'git diff' [] [--] [...]::

This form is to view the changes you made relative to
the index (staging area for the next commit).  In other
@@ -29,7 +29,7 @@ two blob objects, or changes between two files on disk.
further add to the index but you still haven't.  You can
stage these changes by using linkgit:git-add[1].

-'git diff' [options] --no-index [--]  ::
+'git diff' [] --no-index [--]  ::

This form is to compare the given two paths on the
filesystem.  You can omit the `--no-index` option when
@@ -38,7 +38,7 @@ two blob objects, or changes between two files on disk.
or when running the command