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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 1, 2008, 23:54 UTC
Message-ID: <7vmyl1kvn6.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <20080701162358.GA18305@fieldses.org>

"J. Bruce Fields" <bfields@fieldses.org> writes:

Show 16 quoted lines

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

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.

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

        For full details, type:

	------------
        $ man git-svn
        ------------