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

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

On Tue, Jul 01, 2008 at 04:54:53PM -0700, Junio C Hamano wrote:
> "J. Bruce Fields" <bfields@fieldses.org> writes:
> 
> > 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.
> 
> While I agree with the above, are we ready to talk about "git-svn"
> or "git-remote" that early in the tutorial material?

No, but for the purposes of this example it's not necessary to be
familiar with the command.  (Though it might be less distracting to use
something that'll be discussed early on.)

> We would want to mention the typesetting convention early in the manuals
> (git(7), gittutorial(7) and user-manual.html) as well, so how about...
> 
> 	Conventions used in this document
>         ---------------------------------
> 
> 	When talking about a git subcommand 'cmd', this documentation
> 	typesets the name of it like 'git-cmd', and that is the name you
> 	ask for its manual page.
> 
>         Examples are typeset like this: `$ git cmd` (`$` is your command
> 	prompt, do not actually type it to your shell).  Note that a
> 	subcommand is specified as the first parameter to the 'git'
> 	program when you actually run it from the command line.

I'm not convinced this last sentence is necessary.

> 
> 	E.g. a typical command description may go like this:
> 
>         To propagate the changes you made back to the original subversion
>         repository, you would use 'git-svn dcommit' command.  It does
>         these things (long description here).  Some examples:

> 
>         ------------
> 	$ ... some example command sequence ...
>         $ git svn dcommit
>         ------------

Typographical conventions shouldn't need so much explanation.

I'm curious: Jonathan, was this the original patch the result of a
real-life instance of confusion?  What happened?

--b.

> 
>         For full details, type:
> 
> 	------------
>         $ man git-svn
>         ------------