Re: [PATCH v2 5/5] Help doc: Include --guide option description

> Philip Oakley <philipoakley@iee.org> writes:
>
>> Note that the ability to display an individual guide was
>> always possible. Include this in the update.
>>
>> Also tell readers how git(1) can be accessed, especially for
>> Git for Windows users who do not have the 'man' command.
>> Likewise include a commentary on how to access this page (Catch 22).
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>  Documentation/git-help.txt | 28 +++++++++++++++++++++-------
>>  1 file changed, 21 insertions(+), 7 deletions(-)
>>
>> diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
>> index e07b6dc..498a94e 100644
>> --- a/Documentation/git-help.txt
>> +++ b/Documentation/git-help.txt
>> @@ -8,31 +8,45 @@ git-help - Display help information about Git
>>  SYNOPSIS
>>  --------
>>  [verse]
>> -'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND]
>> +'git help' [-a|--all] [-g|--guide]
>> +    [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]
>>
>>  DESCRIPTION
>>  -----------
>>
>> -With no options and no COMMAND given, the synopsis of the 'git'
>> +With no options and no COMMAND|GUIDE given, the synopsis of the 
>> 'git'
>
> Please avoid BNF in the prose meant for human consumption unless
> necessary.  I think you can just say " or " here.

>
>>  command and a list of the most commonly used Git commands are 
>> printed
>>  on the standard output.
>>
>>  If the option '--all' or '-a' is given, then all available commands 
>> are
>>  printed on the standard output.
>>
>> -If a Git subcommand is named, a manual page for that subcommand is 
>> brought
>> -up. The 'man' program is used by default for this purpose, but this
>> -can be overridden by other options or configuration variables.
>> +If the option '--guide' or '-g' is given then, a list of the useful
>> +Git guides is also printed on the standard output.
>
> s/given then,/given, then/ or just s/ then// make it easier to
> follow?  I personally would vote for doing s/given, then/given, /
> for the previous paragraph on "--all" as well.

>
>> -Note that `git --help ...` is identical to `git help ...` because 
>> the
>> +If a Git subcommand, or a Git guide, is given, a manual page for 
>> that
>
> "If the name of a command or a guide is given" without "Git/git"
> would be much easier to read, especially when the first paragraph
> talks about "COMMAND or GUIDE".  I also think s/command/subcommand/
> in the synopsis and in the first paragraph may be good for consistency
> with this part.

>
>> +subcommand is brought up. The 'man' program is used by default for 
>> this
>> +purpose, but this can be overridden by other options or 
>> configuration
>> +variables.
>> +
>> +Note that 'git --help ...' is identical to 'git help ...' because 
>> the
>>  former is internally converted into the latter.
>>
>> +To display the linkgit:git[1] man page use 'git help git'.
>
> s/man page use/man page, use/;

>
>> +
>> +This page can be displayed with 'git help help' or 'git help --help'
>> +
>>  OPTIONS
>>  -------
>>  -a::
>>  --all::
>>  Prints all the available commands on the standard output. This
>> - option supersedes any other option.
>> + option overides any given command or guide name.
>> +
>> +-g::
>> +--guides::
>> + Prints a list of useful guides on the standard output. This
>> + option overides any given command or guide name.
>
> Thanks. Overall this round looks a lot more manageable than the
> previous one.
>