Re: [PATCH 3/7] Documentation: complicate example of "man git-command"

["J. Bruce Fields" <bfields@fieldses.org>]

On Mon, Jun 30, 2008 at 05:10:25PM -0500, Jonathan Nieder wrote:
> The manual page for the command invoked as "git clone" is named
> git-clone(1), and similarly for the rest of the git commands.
> Make sure our first example of this in tutorials makes it clear
> that it is the first two words of a command line that make up the
> command's name (that is: for example, the effect of "git svn
> dcommit" is described in git-svn(1)).

Is this confusion really common?

I can see how it might be possible in the case of a subcommand that
itself has subcommands, but it seems less likely in the two examples you
add below (where the third token is an option or a url).  I like your
"git svn" example better.  Or "git remote" might be good.

--b.

> 
> Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
> ---
> 	If I didn't make this change, consistency would mean
> 	saying "you can get documentation for a command such
> 	as `git-diff` with `man git-diff`", which might not be
> 	very enlightening.
> 
>  Documentation/gittutorial.txt |    4 ++--
>  Documentation/user-manual.txt |    2 +-
>  2 files changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
> index 3d16e3d..b833167 100644
> --- a/Documentation/gittutorial.txt
> +++ b/Documentation/gittutorial.txt
> @@ -20,10 +20,10 @@ for example, to test the latest version, you may prefer to start with
>  the first two chapters of link:user-manual.html[The Git User's Manual].
>  
>  First, note that you can get documentation for a command such as "git
> -diff" with:
> +log --graph" with:
>  
>  ------------------------------------------------
> -$ man git-diff
> +$ man git-log
>  ------------------------------------------------
>  
>  It is a good idea to introduce yourself to git with your name and
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index ca4363f..36ab372 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -18,7 +18,7 @@ People needing to do actual development will also want to read
>  Further chapters cover more specialized topics.
>  
>  Comprehensive reference documentation is available through the man
> -pages.  For a command such as "git clone", just use
> +pages.  For a command such as "git clone <repo>", just use
>  
>  ------------------------------------------------
>  $ man git-clone
> -- 
> 1.5.5.GIT
> 
>