diff mbox series

[v2,4/9] doc: use only hyphens as word separators in placeholders

Message ID 984b6d687a2e779c775de6ea80536afe6ecc0aaf.1635438124.git.gitgitgadget@gmail.com (mailing list archive)
State Superseded
Headers show
Series doc: fix grammar rules in commands' syntax | expand

Commit Message

Jean-Noël Avila Oct. 28, 2021, 4:21 p.m. UTC
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

According to CodingGuidelines, spaces and underscores are not
allowed in placeholders.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/date-formats.txt   |  4 +--
 Documentation/git-checkout.txt   | 36 +++++++++++-----------
 Documentation/git-clone.txt      |  8 ++---
 Documentation/git-cvsimport.txt  |  8 ++---
 Documentation/git-diff-files.txt |  2 +-
 Documentation/git-diff-index.txt |  2 +-
 Documentation/git-diff-tree.txt  |  2 +-
 Documentation/git-init-db.txt    |  2 +-
 Documentation/git-init.txt       |  8 ++---
 Documentation/git-log.txt        |  8 ++---
 Documentation/git-p4.txt         |  6 ++--
 Documentation/git-shortlog.txt   |  8 ++---
 Documentation/git-svn.txt        |  2 +-
 Documentation/pretty-formats.txt | 52 ++++++++++++++++----------------
 14 files changed, 74 insertions(+), 74 deletions(-)

Comments

Martin Ågren Oct. 28, 2021, 6:47 p.m. UTC | #1
On Thu, 28 Oct 2021 at 18:22, Jean-Noël Avila via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> -       It is `<unix timestamp> <time zone offset>`, where `<unix
> +       It is `<unix-timestamp> <time-zone-offset>`, where `<unix-
>         timestamp>` is the number of seconds since the UNIX epoch.

This still effectively has a space -- it renders as "<unix- timestamp>".
You'll probably need to rewrap the lines a little to get rid of that.

> -** 'separator=<SEP>': specify a separator inserted between trailer
> +** 'separator=<sep>': specify a separator inserted between trailer
>     lines. When this option is not given each trailer line is
>     terminated with a line feed character. The string SEP may contain

s/SEP/<sep>/ ?

Thanks for taking on this large task.


Martin
Junio C Hamano Oct. 28, 2021, 7:35 p.m. UTC | #2
Martin Ågren <martin.agren@gmail.com> writes:

> On Thu, 28 Oct 2021 at 18:22, Jean-Noël Avila via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>>
>> -       It is `<unix timestamp> <time zone offset>`, where `<unix
>> +       It is `<unix-timestamp> <time-zone-offset>`, where `<unix-
>>         timestamp>` is the number of seconds since the UNIX epoch.
>
> This still effectively has a space -- it renders as "<unix- timestamp>".
> You'll probably need to rewrap the lines a little to get rid of that.

Thanks for sharp eyes.  grep -e '<[^ ]*-$' Documentation/ spots only this
instance, so I'll fix it locally.


>> -** 'separator=<SEP>': specify a separator inserted between trailer
>> +** 'separator=<sep>': specify a separator inserted between trailer
>>     lines. When this option is not given each trailer line is
>>     terminated with a line feed character. The string SEP may contain
>
> s/SEP/<sep>/ ?

Also, this one.
Eli Schwartz Oct. 31, 2021, 6:58 p.m. UTC | #3
On 10/28/21 12:21 PM, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
> 
> According to CodingGuidelines, spaces and underscores are not
> allowed in placeholders.


I have a patch under review that touches the same files you are
modifying here. As I've been pointed to these changes, I'd like to make
a quick observation.


> @@ -101,9 +101,9 @@ commits are displayed, but not the way the diff is shown e.g. with
>  `git log --raw`. To get full object names in a raw diff format,
>  use `--no-abbrev`.
>  
> -* 'format:<string>'
> +* 'format:<format-string>'
>  +
> -The 'format:<string>' format allows you to specify which information
> +The 'format:<format-string>' format allows you to specify which information
>  you want to show. It works a little bit like printf format,
>  with the notable exception that you get a newline with '%n'
>  instead of '\n'.
> @@ -273,12 +273,12 @@ endif::git-rev-list[]
>  			  If any option is provided multiple times the
>  			  last occurrence wins.
>  +
> -The boolean options accept an optional value `[=<BOOL>]`. The values
> +The boolean options accept an optional value `[=<value>]`. The values


Here you change "BOOL" to "value", below you change it to "bool-value".


>  `true`, `false`, `on`, `off` etc. are all accepted. See the "boolean"
>  sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean
>  option is given with no value, it's enabled.
>  +
> -** 'key=<K>': only show trailers with specified key. Matching is done
> +** 'key=<key>': only show trailers with specified <key>. Matching is done
>     case-insensitively and trailing colon is optional. If option is
>     given multiple times trailer lines matching any of the keys are
>     shown. This option automatically enables the `only` option so that
> @@ -286,9 +286,9 @@ option is given with no value, it's enabled.
>     desired it can be disabled with `only=false`.  E.g.,
>     `%(trailers:key=Reviewed-by)` shows trailer lines with key
>     `Reviewed-by`.
> -** 'only[=<BOOL>]': select whether non-trailer lines from the trailer
> +** 'only[=<bool-value>]': select whether non-trailer lines from the trailer
>     block should be included.
> -** 'separator=<SEP>': specify a separator inserted between trailer
> +** 'separator=<sep>': specify a separator inserted between trailer
>     lines. When this option is not given each trailer line is
>     terminated with a line feed character. The string SEP may contain
>     the literal formatting codes described above. To use comma as
> @@ -296,15 +296,15 @@ option is given with no value, it's enabled.
>     next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`
>     shows all trailer lines whose key is "Ticket" separated by a comma
>     and a space.
> -** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold`
> +** 'unfold[=<bool-value>]': make it behave as if interpret-trailer's `--unfold`
>     option was given. E.g.,
>     `%(trailers:only,unfold=true)` unfolds and shows all trailer lines.
> -** 'keyonly[=<BOOL>]': only show the key part of the trailer.
> -** 'valueonly[=<BOOL>]': only show the value part of the trailer.
> -** 'key_value_separator=<SEP>': specify a separator inserted between
> +** 'keyonly[=<bool-value>]': only show the key part of the trailer.
> +** 'valueonly[=<bool-value>]': only show the value part of the trailer.
> +** 'key_value_separator=<sep>': specify a separator inserted between
>     trailer lines. When this option is not given each trailer key-value
>     pair is separated by ": ". Otherwise it shares the same semantics
> -   as 'separator=<SEP>' above.
> +   as 'separator=<sep>' above.
>  
>  NOTE: Some placeholders may depend on other options given to the
>  revision traversal engine. For example, the `%g*` reflog options will


These changes over here are contrary to the statement in the commit
message. In addition to switching to hyphens, they:

- switch casing (okay, makes sense, you point this out in the cover
  letter but maybe it's worth mentioning it in the commit message too?
  idk)

- change the terms used -- and this I don't understand. I'm not really
  bothered by switching <n> to <number> or <k> to <key>, as these
  changes seem reasonable (though again, they are not mentioned in the
  commit message). However, "bool-value" seems odd. Why that and not
  "number-value"? IMHO the "value" is redundant here, let it be "bool"
  and "number".

  Similarly "the 'format:<format-string>' format" feels highly
  redundant, I expect the reader knows that <string> contains a format
  inside it as it's mentioned immediately before *and* after.
Jean-Noël Avila Oct. 31, 2021, 8:23 p.m. UTC | #4
Le dimanche 31 octobre 2021, 19:58:56 CET Eli Schwartz a écrit :
> On 10/28/21 12:21 PM, Jean-Noël Avila via GitGitGadget wrote:
> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
> > 
> > According to CodingGuidelines, spaces and underscores are not
> > allowed in placeholders.
> 
> 
> I have a patch under review that touches the same files you are
> modifying here. As I've been pointed to these changes, I'd like to make
> a quick observation.
> 
> 
> > @@ -101,9 +101,9 @@ commits are displayed, but not the way the diff is 
shown e.g. with
> >  `git log --raw`. To get full object names in a raw diff format,
> >  use `--no-abbrev`.
> >  
> > -* 'format:<string>'
> > +* 'format:<format-string>'
> >  +
> > -The 'format:<string>' format allows you to specify which information
> > +The 'format:<format-string>' format allows you to specify which 
information
> >  you want to show. It works a little bit like printf format,
> >  with the notable exception that you get a newline with '%n'
> >  instead of '\n'.
> > @@ -273,12 +273,12 @@ endif::git-rev-list[]
> >  			  If any option is provided multiple times the
> >  			  last occurrence wins.
> >  +
> > -The boolean options accept an optional value `[=<BOOL>]`. The values
> > +The boolean options accept an optional value `[=<value>]`. The values
> 
> 
> Here you change "BOOL" to "value", below you change it to "bool-value".

Indeed. Should be fixed.

> 
> 
> >  `true`, `false`, `on`, `off` etc. are all accepted. See the "boolean"
> >  sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean
> >  option is given with no value, it's enabled.
> >  +
> > -** 'key=<K>': only show trailers with specified key. Matching is done
> > +** 'key=<key>': only show trailers with specified <key>. Matching is done
> >     case-insensitively and trailing colon is optional. If option is
> >     given multiple times trailer lines matching any of the keys are
> >     shown. This option automatically enables the `only` option so that
> > @@ -286,9 +286,9 @@ option is given with no value, it's enabled.
> >     desired it can be disabled with `only=false`.  E.g.,
> >     `%(trailers:key=Reviewed-by)` shows trailer lines with key
> >     `Reviewed-by`.
> > -** 'only[=<BOOL>]': select whether non-trailer lines from the trailer
> > +** 'only[=<bool-value>]': select whether non-trailer lines from the 
trailer
> >     block should be included.
> > -** 'separator=<SEP>': specify a separator inserted between trailer
> > +** 'separator=<sep>': specify a separator inserted between trailer
> >     lines. When this option is not given each trailer line is
> >     terminated with a line feed character. The string SEP may contain
> >     the literal formatting codes described above. To use comma as
> > @@ -296,15 +296,15 @@ option is given with no value, it's enabled.
> >     next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`
> >     shows all trailer lines whose key is "Ticket" separated by a comma
> >     and a space.
> > -** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold`
> > +** 'unfold[=<bool-value>]': make it behave as if interpret-trailer's `--
unfold`
> >     option was given. E.g.,
> >     `%(trailers:only,unfold=true)` unfolds and shows all trailer lines.
> > -** 'keyonly[=<BOOL>]': only show the key part of the trailer.
> > -** 'valueonly[=<BOOL>]': only show the value part of the trailer.
> > -** 'key_value_separator=<SEP>': specify a separator inserted between
> > +** 'keyonly[=<bool-value>]': only show the key part of the trailer.
> > +** 'valueonly[=<bool-value>]': only show the value part of the trailer.
> > +** 'key_value_separator=<sep>': specify a separator inserted between
> >     trailer lines. When this option is not given each trailer key-value
> >     pair is separated by ": ". Otherwise it shares the same semantics
> > -   as 'separator=<SEP>' above.
> > +   as 'separator=<sep>' above.
> >  
> >  NOTE: Some placeholders may depend on other options given to the
> >  revision traversal engine. For example, the `%g*` reflog options will
> 
> 
> These changes over here are contrary to the statement in the commit
> message. In addition to switching to hyphens, they:
> 
> - switch casing (okay, makes sense, you point this out in the cover
>   letter but maybe it's worth mentioning it in the commit message too?
>   idk)
> 
> - change the terms used -- and this I don't understand. I'm not really
>   bothered by switching <n> to <number> or <k> to <key>, as these
>   changes seem reasonable (though again, they are not mentioned in the
>   commit message). However, "bool-value" seems odd. Why that and not
>   "number-value"? IMHO the "value" is redundant here, let it be "bool"
>   and "number".

My initial aim was to be more descriptive. The placeholders act as variables 
and you don't name variables with their types.	
Fair enough, "bool-value" isn't the best example, but there are some facts 
that drove these choices:
 * You can't expect manpage readers to be seasoned C programmers that 
understand what the word "bool" means. Using boolean-value, makes the 
reference to the description in the previous paragraph.
 * I'm facing a similar issue with translators. Some of them have some culture 
of computer science, but most of them are not programmers. Having more 
meaningful placeholders helps them find a correct translation: this is a bool 
value, not the bool type.

I did not push far to change all the placeholders that were not descriptive. 
Maybe another set of patches, if it is acceptable.

The choices here may be awkward; no problem to propose even more descriptive 
names.

> 
>   Similarly "the 'format:<format-string>' format" feels highly
>   redundant, I expect the reader knows that <string> contains a format
>   inside it as it's mentioned immediately before *and* after.
> 

The fact that it is a string doesn't tell you much about what you can do with 
it. For me, this isn't a problem that the explanation is redundant.
Junio C Hamano Nov. 1, 2021, 6:47 a.m. UTC | #5
Jean-Noël AVILA <jn.avila@free.fr> writes:

> The choices here may be awkward; no problem to propose even more descriptive 
> names.
>
>> 
>>   Similarly "the 'format:<format-string>' format" feels highly
>>   redundant, I expect the reader knows that <string> contains a format
>>   inside it as it's mentioned immediately before *and* after.
>> 
>
> The fact that it is a string doesn't tell you much about what you can do with 
> it. For me, this isn't a problem that the explanation is redundant.

I agree that --format:<string> is quite poor, as type alone does not
give readers any information on what it means and how it is supposed
to look like.  Calling it <format-string> does make quite a lot of
sense.

It is a bit less obvious how much value we get out of <bool-value>,
though.  In --opt=<arg> scheme of things, what comes after '=' are
all <value>s, so <bool-value> does not clarify over <bool> like the
way <format-string> clarifies over <string>.
Jean-Noël Avila Nov. 3, 2021, 12:46 p.m. UTC | #6
Junio C Hamano wrote:
> Jean-Noël AVILA <jn.avila@free.fr> writes:
>
>> The choices here may be awkward; no problem to propose even more descriptive 
>> names.
>>
>>>   Similarly "the 'format:<format-string>' format" feels highly
>>>   redundant, I expect the reader knows that <string> contains a format
>>>   inside it as it's mentioned immediately before *and* after.
>>>
>> The fact that it is a string doesn't tell you much about what you can do with 
>> it. For me, this isn't a problem that the explanation is redundant.
> I agree that --format:<string> is quite poor, as type alone does not
> give readers any information on what it means and how it is supposed
> to look like.  Calling it <format-string> does make quite a lot of
> sense.
>
> It is a bit less obvious how much value we get out of <bool-value>,
> though.  In --opt=<arg> scheme of things, what comes after '=' are
> all <value>s, so <bool-value> does not clarify over <bool> like the
> way <format-string> clarifies over <string>.
>
Agreed. Should reroll the patch series?
Junio C Hamano Nov. 3, 2021, 4:28 p.m. UTC | #7
Jean-Noël Avila <avila.jn@gmail.com> writes:

> Junio C Hamano wrote:
>> Jean-Noël AVILA <jn.avila@free.fr> writes:
>>
>>> The choices here may be awkward; no problem to propose even more descriptive 
>>> names.
>>>
>>>>   Similarly "the 'format:<format-string>' format" feels highly
>>>>   redundant, I expect the reader knows that <string> contains a format
>>>>   inside it as it's mentioned immediately before *and* after.
>>>>
>>> The fact that it is a string doesn't tell you much about what you can do with 
>>> it. For me, this isn't a problem that the explanation is redundant.
>> I agree that --format:<string> is quite poor, as type alone does not
>> give readers any information on what it means and how it is supposed
>> to look like.  Calling it <format-string> does make quite a lot of
>> sense.
>>
>> It is a bit less obvious how much value we get out of <bool-value>,
>> though.  In --opt=<arg> scheme of things, what comes after '=' are
>> all <value>s, so <bool-value> does not clarify over <bool> like the
>> way <format-string> clarifies over <string>.
>>
> Agreed. Should reroll the patch series?

I guess another (hopefully the final) reroll would not hurt (but we
are not in hurry---this may be among the topics that graduate early
in the next cycle, but not during this cycle).

Thanks.
Johannes Schindelin Nov. 4, 2021, 12:38 a.m. UTC | #8
Hi,

On Wed, 3 Nov 2021, Junio C Hamano wrote:

> Jean-Noël Avila <avila.jn@gmail.com> writes:
>
> > Junio C Hamano wrote:
> >> Jean-Noël AVILA <jn.avila@free.fr> writes:
> >>
> >>> The choices here may be awkward; no problem to propose even more descriptive
> >>> names.
> >>>
> >>>>   Similarly "the 'format:<format-string>' format" feels highly
> >>>>   redundant, I expect the reader knows that <string> contains a format
> >>>>   inside it as it's mentioned immediately before *and* after.
> >>>>
> >>> The fact that it is a string doesn't tell you much about what you can do with
> >>> it. For me, this isn't a problem that the explanation is redundant.
> >> I agree that --format:<string> is quite poor, as type alone does not
> >> give readers any information on what it means and how it is supposed
> >> to look like.  Calling it <format-string> does make quite a lot of
> >> sense.
> >>
> >> It is a bit less obvious how much value we get out of <bool-value>,
> >> though.  In --opt=<arg> scheme of things, what comes after '=' are
> >> all <value>s, so <bool-value> does not clarify over <bool> like the
> >> way <format-string> clarifies over <string>.
> >>
> > Agreed. Should reroll the patch series?
>
> I guess another (hopefully the final) reroll would not hurt (but we
> are not in hurry---this may be among the topics that graduate early
> in the next cycle, but not during this cycle).

I fear that it won't be as easy to send the next iteration as one might
think: GitGitGadget works off of open Pull Requests on GitHub. And the
branch for the Pull Request corresponding to this series has been deleted,
thereby permanently closing the Pull Request (it cannot be reopened
anymore): https://github.com/gitgitgadget/git/pull/1066#event-5541689437

That means that none of GitGitGadget's convenience can be used to send v3
with a range-diff. All that can be done at this point is to open a new
Pull Request, generate a range-diff manually (which could very easily
differ from the actual range-diff, whether by design or mistake) and put
it into the cover letter, then send a "v3" (which is actually a v1).

Ciao,
Johannes
Junio C Hamano Nov. 4, 2021, 5:36 p.m. UTC | #9
Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

>> Jean-Noël Avila <avila.jn@gmail.com> writes:
>> ...
>> > Agreed. Should reroll the patch series?
>>
>> I guess another (hopefully the final) reroll would not hurt (but we
>> are not in hurry---this may be among the topics that graduate early
>> in the next cycle, but not during this cycle).
>
> I fear that it won't be as easy to send the next iteration as one might
> think: GitGitGadget works off of open Pull Requests on GitHub. And ...
> ...it into the cover letter, then send a "v3" (which is actually a v1).

I see Jean-Noël is a long-time community member whose contribution
dates back to 2012, which presumably predates GGG, so I suspect that
"contributors who use GGG cannot send a series without it" would not
apply here.
Eli Schwartz Nov. 7, 2021, 12:40 p.m. UTC | #10
On 11/3/21 8:38 PM, Johannes Schindelin wrote:
> I fear that it won't be as easy to send the next iteration as one might
> think: GitGitGadget works off of open Pull Requests on GitHub. And the
> branch for the Pull Request corresponding to this series has been deleted,
> thereby permanently closing the Pull Request (it cannot be reopened
> anymore): https://github.com/gitgitgadget/git/pull/1066#event-5541689437


In fact, I know you *can* re-open such a PR. The author of the PR would
need to restore the branch in the fork, and ensure that the latest
commit on the branch is the same commit that it was when the branch got
deleted.

I know this is possible because I've accidentally deleted branches that
I thought were already merged, when they got reused for another PR that
was still open --I restored the PR by restoring the branch immediately,
I *think* github may offer a button to do that on the PR webpage but I'm
not sure.
diff mbox series

Patch

diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt
index 99c455f51c0..4a1e7bd43bf 100644
--- a/Documentation/date-formats.txt
+++ b/Documentation/date-formats.txt
@@ -5,9 +5,9 @@  The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables
 support the following date formats:
 
 Git internal format::
-	It is `<unix timestamp> <time zone offset>`, where `<unix
+	It is `<unix-timestamp> <time-zone-offset>`, where `<unix-
 	timestamp>` is the number of seconds since the UNIX epoch.
-	`<time zone offset>` is a positive or negative offset from UTC.
+	`<time-zone-offset>` is a positive or negative offset from UTC.
 	For example CET (which is 1 hour ahead of UTC) is `+0100`.
 
 RFC 2822::
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index d473c9bf387..a52dc49a3dc 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -11,7 +11,7 @@  SYNOPSIS
 'git checkout' [-q] [-f] [-m] [<branch>]
 'git checkout' [-q] [-f] [-m] --detach [<branch>]
 'git checkout' [-q] [-f] [-m] [--detach] <commit>
-'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
+'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]
 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
@@ -43,7 +43,7 @@  You could omit `<branch>`, in which case the command degenerates to
 rather expensive side-effects to show only the tracking information,
 if exists, for the current branch.
 
-'git checkout' -b|-B <new_branch> [<start point>]::
+'git checkout' -b|-B <new-branch> [<start-point>]::
 
 	Specifying `-b` causes a new branch to be created as if
 	linkgit:git-branch[1] were called and then checked out.  In
@@ -52,11 +52,11 @@  if exists, for the current branch.
 	`--track` without `-b` implies branch creation; see the
 	description of `--track` below.
 +
-If `-B` is given, `<new_branch>` is created if it doesn't exist; otherwise, it
+If `-B` is given, `<new-branch>` is created if it doesn't exist; otherwise, it
 is reset. This is the transactional equivalent of
 +
 ------------
-$ git branch -f <branch> [<start point>]
+$ git branch -f <branch> [<start-point>]
 $ git checkout <branch>
 ------------
 +
@@ -145,13 +145,13 @@  as `ours` (i.e. "our shared canonical history"), while what you did
 on your side branch as `theirs` (i.e. "one contributor's work on top
 of it").
 
--b <new_branch>::
-	Create a new branch named `<new_branch>` and start it at
-	`<start_point>`; see linkgit:git-branch[1] for details.
+-b <new-branch>::
+	Create a new branch named `<new-branch>` and start it at
+	`<start-point>`; see linkgit:git-branch[1] for details.
 
--B <new_branch>::
-	Creates the branch `<new_branch>` and start it at `<start_point>`;
-	if it already exists, then reset it to `<start_point>`. This is
+-B <new-branch>::
+	Creates the branch `<new-branch>` and start it at `<start-point>`;
+	if it already exists, then reset it to `<start-point>`. This is
 	equivalent to running "git branch" with "-f"; see
 	linkgit:git-branch[1] for details.
 
@@ -210,16 +210,16 @@  variable.
 	`<commit>` is not a branch name.  See the "DETACHED HEAD" section
 	below for details.
 
---orphan <new_branch>::
-	Create a new 'orphan' branch, named `<new_branch>`, started from
-	`<start_point>` and switch to it.  The first commit made on this
+--orphan <new-branch>::
+	Create a new 'orphan' branch, named `<new-branch>`, started from
+	`<start-point>` and switch to it.  The first commit made on this
 	new branch will have no parents and it will be the root of a new
 	history totally disconnected from all the other branches and
 	commits.
 +
 The index and the working tree are adjusted as if you had previously run
-`git checkout <start_point>`.  This allows you to start a new history
-that records a set of paths similar to `<start_point>` by easily running
+`git checkout <start-point>`.  This allows you to start a new history
+that records a set of paths similar to `<start-point>` by easily running
 `git commit -a` to make the root commit.
 +
 This can be useful when you want to publish the tree from a commit
@@ -229,7 +229,7 @@  whose full history contains proprietary or otherwise encumbered bits of
 code.
 +
 If you want to start a disconnected history that records a set of paths
-that is totally different from the one of `<start_point>`, then you should
+that is totally different from the one of `<start-point>`, then you should
 clear the index and the working tree right after creating the orphan
 branch by running `git rm -rf .` from the top level of the working tree.
 Afterwards you will be ready to prepare your new files, repopulating the
@@ -341,10 +341,10 @@  As a special case, you may use `A...B` as a shortcut for the
 merge base of `A` and `B` if there is exactly one merge base. You can
 leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
 
-<new_branch>::
+<new-branch>::
 	Name for the new branch.
 
-<start_point>::
+<start-point>::
 	The name of a commit at which to start the new branch; see
 	linkgit:git-branch[1] for details. Defaults to `HEAD`.
 +
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 3fe3810f1ce..9685ea06915 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -9,10 +9,10 @@  git-clone - Clone a repository into a new directory
 SYNOPSIS
 --------
 [verse]
-'git clone' [--template=<template_directory>]
+'git clone' [--template=<template-directory>]
 	  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
 	  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
-	  [--dissociate] [--separate-git-dir <git dir>]
+	  [--dissociate] [--separate-git-dir <git-dir>]
 	  [--depth <depth>] [--[no-]single-branch] [--no-tags]
 	  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
 	  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
@@ -211,7 +211,7 @@  objects from the source repository into a pack in the cloned repository.
 	via ssh, this specifies a non-default path for the command
 	run on the other end.
 
---template=<template_directory>::
+--template=<template-directory>::
 	Specify the directory from which templates will be used;
 	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
 
@@ -294,7 +294,7 @@  or `--mirror` is given)
 	superproject's recorded SHA-1. Equivalent to passing `--remote` to
 	`git submodule update`.
 
---separate-git-dir=<git dir>::
+--separate-git-dir=<git-dir>::
 	Instead of placing the cloned repository where it is supposed
 	to be, place the cloned repository at the specified directory,
 	then make a filesystem-agnostic Git symbolic link to there.
diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt
index de1ebed67d7..b3f27671a0c 100644
--- a/Documentation/git-cvsimport.txt
+++ b/Documentation/git-cvsimport.txt
@@ -11,9 +11,9 @@  SYNOPSIS
 [verse]
 'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]
 	      [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]
-	      [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]
-	      [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>]
-	      [-r <remote>] [-R] [<CVS_module>]
+	      [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]
+	      [-a] [-m] [-M <regex>] [-S <regex>] [-L <commit-limit>]
+	      [-r <remote>] [-R] [<CVS-module>]
 
 
 DESCRIPTION
@@ -59,7 +59,7 @@  OPTIONS
 	from `CVS/Root`. If no such file exists, it checks for the
 	`CVSROOT` environment variable.
 
-<CVS_module>::
+<CVS-module>::
 	The CVS module you want to import. Relative to <CVSROOT>.
 	If not given, 'git cvsimport' tries to read it from
 	`CVS/Repository`.
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
index 906774f0f7e..bf1febb9ae7 100644
--- a/Documentation/git-diff-files.txt
+++ b/Documentation/git-diff-files.txt
@@ -9,7 +9,7 @@  git-diff-files - Compares files in the working tree and the index
 SYNOPSIS
 --------
 [verse]
-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...]
+'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index 27acb31cbf2..679cae27d9b 100644
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.txt
@@ -9,7 +9,7 @@  git-diff-index - Compare a tree to the working tree or index
 SYNOPSIS
 --------
 [verse]
-'git diff-index' [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>...]
+'git diff-index' [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>...]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 2fc24c542f8..274d5eaba93 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -11,7 +11,7 @@  SYNOPSIS
 [verse]
 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]
 	      [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]
-	      [<common diff options>] <tree-ish> [<tree-ish>] [<path>...]
+	      [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt
index 648a6cd78ad..18bf1a3c8ce 100644
--- a/Documentation/git-init-db.txt
+++ b/Documentation/git-init-db.txt
@@ -9,7 +9,7 @@  git-init-db - Creates an empty Git repository
 SYNOPSIS
 --------
 [verse]
-'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]]
+'git init-db' [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]]
 
 
 DESCRIPTION
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 7781d0b3545..fdb7b3f367d 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -9,8 +9,8 @@  git-init - Create an empty Git repository or reinitialize an existing one
 SYNOPSIS
 --------
 [verse]
-'git init' [-q | --quiet] [--bare] [--template=<template_directory>]
-	  [--separate-git-dir <git dir>] [--object-format=<format>]
+'git init' [-q | --quiet] [--bare] [--template=<template-directory>]
+	  [--separate-git-dir <git-dir>] [--object-format=<format>]
 	  [-b <branch-name> | --initial-branch=<branch-name>]
 	  [--shared[=<permissions>]] [<directory>]
 
@@ -57,12 +57,12 @@  values are 'sha1' and (if enabled) 'sha256'.  'sha1' is the default.
 +
 include::object-format-disclaimer.txt[]
 
---template=<template_directory>::
+--template=<template-directory>::
 
 Specify the directory from which templates will be used.  (See the "TEMPLATE
 DIRECTORY" section below.)
 
---separate-git-dir=<git dir>::
+--separate-git-dir=<git-dir>::
 
 Instead of initializing the repository as a directory to either `$GIT_DIR` or
 `./.git/`, create a text file there containing the path to the actual
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 0498e7bacbe..20e87cecf49 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -9,7 +9,7 @@  git-log - Show commit logs
 SYNOPSIS
 --------
 [verse]
-'git log' [<options>] [<revision range>] [[--] <path>...]
+'git log' [<options>] [<revision-range>] [[--] <path>...]
 
 DESCRIPTION
 -----------
@@ -81,13 +81,13 @@  produced by `--stat`, etc.
 
 include::line-range-options.txt[]
 
-<revision range>::
+<revision-range>::
 	Show only commits in the specified revision range.  When no
-	<revision range> is specified, it defaults to `HEAD` (i.e. the
+	<revision-range> is specified, it defaults to `HEAD` (i.e. the
 	whole history leading to the current commit).  `origin..HEAD`
 	specifies all the commits reachable from the current commit
 	(i.e. `HEAD`), but not from `origin`. For a complete list of
-	ways to spell <revision range>, see the 'Specifying Ranges'
+	ways to spell <revision-range>, see the 'Specifying Ranges'
 	section of linkgit:gitrevisions[7].
 
 [--] <path>...::
diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt
index 8a6addcf72f..e21fcd8f712 100644
--- a/Documentation/git-p4.txt
+++ b/Documentation/git-p4.txt
@@ -9,10 +9,10 @@  git-p4 - Import from and submit to Perforce repositories
 SYNOPSIS
 --------
 [verse]
-'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>...
-'git p4 sync' [<sync options>] [<p4 depot path>...]
+'git p4 clone' [<sync-options>] [<clone-options>] <p4-depot-path>...
+'git p4 sync' [<sync-options>] [<p4-depot-path>...]
 'git p4 rebase'
-'git p4 submit' [<submit options>] [<master branch name>]
+'git p4 submit' [<submit-options>] [<master-branch-name>]
 
 
 DESCRIPTION
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index c9c7f3065ca..f64e77047b2 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -8,7 +8,7 @@  git-shortlog - Summarize 'git log' output
 SYNOPSIS
 --------
 [verse]
-'git shortlog' [<options>] [<revision range>] [[--] <path>...]
+'git shortlog' [<options>] [<revision-range>] [[--] <path>...]
 git log --pretty=short | 'git shortlog' [<options>]
 
 DESCRIPTION
@@ -89,13 +89,13 @@  counts both authors and co-authors.
 If width is `0` (zero) then indent the lines of the output without wrapping
 them.
 
-<revision range>::
+<revision-range>::
 	Show only commits in the specified revision range.  When no
-	<revision range> is specified, it defaults to `HEAD` (i.e. the
+	<revision-range> is specified, it defaults to `HEAD` (i.e. the
 	whole history leading to the current commit).  `origin..HEAD`
 	specifies all the commits reachable from the current commit
 	(i.e. `HEAD`), but not from `origin`. For a complete list of
-	ways to spell <revision range>, see the "Specifying Ranges"
+	ways to spell <revision-range>, see the "Specifying Ranges"
 	section of linkgit:gitrevisions[7].
 
 [--] <path>...::
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 222b556d7a9..4e92308e85d 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -575,7 +575,7 @@  OPTIONS
 -------
 
 --shared[=(false|true|umask|group|all|world|everybody)]::
---template=<template_directory>::
+--template=<template-directory>::
 	Only used with the 'init' command.
 	These are passed directly to 'git init'.
 
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index ef6bd420ae6..d61606caf41 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -20,7 +20,7 @@  built-in formats:
 
 * 'oneline'
 
-	  <hash> <title line>
+	  <hash> <title-line>
 +
 This is designed to be as compact as possible.
 
@@ -29,17 +29,17 @@  This is designed to be as compact as possible.
 	  commit <hash>
 	  Author: <author>
 
-	      <title line>
+	      <title-line>
 
 * 'medium'
 
 	  commit <hash>
 	  Author: <author>
-	  Date:   <author date>
+	  Date:   <author-date>
 
-	      <title line>
+	      <title-line>
 
-	      <full commit message>
+	      <full-commit-message>
 
 * 'full'
 
@@ -47,25 +47,25 @@  This is designed to be as compact as possible.
 	  Author: <author>
 	  Commit: <committer>
 
-	      <title line>
+	      <title-line>
 
-	      <full commit message>
+	      <full-commit-message>
 
 * 'fuller'
 
 	  commit <hash>
 	  Author:     <author>
-	  AuthorDate: <author date>
+	  AuthorDate: <author-date>
 	  Commit:     <committer>
-	  CommitDate: <committer date>
+	  CommitDate: <committer-date>
 
-	       <title line>
+	       <title-line>
 
-	       <full commit message>
+	       <full-commit-message>
 
 * 'reference'
 
-	  <abbrev hash> (<title line>, <short author date>)
+	  <abbrev-hash> (<title-line>, <short-author-date>)
 +
 This format is used to refer to another commit in a commit message and
 is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`.  By default,
@@ -78,10 +78,10 @@  placeholders, its output is not affected by other options like
 
 	  From <hash> <date>
 	  From: <author>
-	  Date: <author date>
-	  Subject: [PATCH] <title line>
+	  Date: <author-date>
+	  Subject: [PATCH] <title-line>
 
-	  <full commit message>
+	  <full-commit-message>
 
 * 'mboxrd'
 +
@@ -101,9 +101,9 @@  commits are displayed, but not the way the diff is shown e.g. with
 `git log --raw`. To get full object names in a raw diff format,
 use `--no-abbrev`.
 
-* 'format:<string>'
+* 'format:<format-string>'
 +
-The 'format:<string>' format allows you to specify which information
+The 'format:<format-string>' format allows you to specify which information
 you want to show. It works a little bit like printf format,
 with the notable exception that you get a newline with '%n'
 instead of '\n'.
@@ -273,12 +273,12 @@  endif::git-rev-list[]
 			  If any option is provided multiple times the
 			  last occurrence wins.
 +
-The boolean options accept an optional value `[=<BOOL>]`. The values
+The boolean options accept an optional value `[=<value>]`. The values
 `true`, `false`, `on`, `off` etc. are all accepted. See the "boolean"
 sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean
 option is given with no value, it's enabled.
 +
-** 'key=<K>': only show trailers with specified key. Matching is done
+** 'key=<key>': only show trailers with specified <key>. Matching is done
    case-insensitively and trailing colon is optional. If option is
    given multiple times trailer lines matching any of the keys are
    shown. This option automatically enables the `only` option so that
@@ -286,9 +286,9 @@  option is given with no value, it's enabled.
    desired it can be disabled with `only=false`.  E.g.,
    `%(trailers:key=Reviewed-by)` shows trailer lines with key
    `Reviewed-by`.
-** 'only[=<BOOL>]': select whether non-trailer lines from the trailer
+** 'only[=<bool-value>]': select whether non-trailer lines from the trailer
    block should be included.
-** 'separator=<SEP>': specify a separator inserted between trailer
+** 'separator=<sep>': specify a separator inserted between trailer
    lines. When this option is not given each trailer line is
    terminated with a line feed character. The string SEP may contain
    the literal formatting codes described above. To use comma as
@@ -296,15 +296,15 @@  option is given with no value, it's enabled.
    next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`
    shows all trailer lines whose key is "Ticket" separated by a comma
    and a space.
-** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold`
+** 'unfold[=<bool-value>]': make it behave as if interpret-trailer's `--unfold`
    option was given. E.g.,
    `%(trailers:only,unfold=true)` unfolds and shows all trailer lines.
-** 'keyonly[=<BOOL>]': only show the key part of the trailer.
-** 'valueonly[=<BOOL>]': only show the value part of the trailer.
-** 'key_value_separator=<SEP>': specify a separator inserted between
+** 'keyonly[=<bool-value>]': only show the key part of the trailer.
+** 'valueonly[=<bool-value>]': only show the value part of the trailer.
+** 'key_value_separator=<sep>': specify a separator inserted between
    trailer lines. When this option is not given each trailer key-value
    pair is separated by ": ". Otherwise it shares the same semantics
-   as 'separator=<SEP>' above.
+   as 'separator=<sep>' above.
 
 NOTE: Some placeholders may depend on other options given to the
 revision traversal engine. For example, the `%g*` reflog options will