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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 3, 2013, 23:39 UTC
Message-ID: <7vd2vgyrxh.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1362342072-1412-6-git-send-email-philipoakley@iee.org>

Philip Oakley <philipoakley@iee.org> writes:

Show 29 quoted lines

> 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.

Show 11 quoted lines

>  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.

Show 8 quoted lines

> +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/;

Show 15 quoted lines

> +
> +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.