"J. Bruce Fields" <bfields@xxxxxxxxxxxx> 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?
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
------------
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
