On Wed, Jul 02, 2008 at 08:45:59PM -0500, Jonathan Nieder wrote: > J. Bruce Fields wrote: > > > On Tue, Jul 01, 2008 at 04:54:53PM -0700, Junio C Hamano wrote: > > > >> 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. > > I agree, but I think it doesn't hurt. I think the point was to > establish the word and concept "subcommand". We don't need to define it. (The word "subcommand" is pretty intuitive, especially for anyone with some commandline experience, which we do assume throughout.) > > > [example showing typographical conventions] > > > > Typographical conventions shouldn't need so much explanation. > > Yes, I suppose. I'm used to printed manuals having a page on > the meaning of different typefaces inside, but that's a bit > of a different situation. Yes. > > I'm curious: Jonathan, was this the original patch the result of a > > real-life instance of confusion? What happened? > > No, I'm actually a bit ashamed to have sent the patch... I was just > changing `git subcommand` to `git-subcommand` wherever it was the name > of a command, rather than the command line to run it, that was in > question. Consistency would have made the old example awkward, so I > looked around for alternatives. That being the case, I'd rather leave the text as is; I'm uncomfortable adding new text to address something that isn't in practice a problem. --b. > > Why worry about whether the man pages have no consistent rule about > dashes? Since it is not obvious why the man pages use the dashed form > when they do, I think a fraction of people will naturally use the > dashed form by default. That means trouble once Git 1.6.0 comes out > (e.g. see Ingo's recent post > <http://thread.gmane.org/gmane.comp.version-control.git/87012/focus=87020>). > > Here's a patch implementing Junio's suggestion, because I do like it. > Please let me know what you think (especially ideas for making it > shorter). > > Thanks for all your thoughts so far. Sorry I took so long to get back. > > --- %< --- %< --- %< ---- > Subject: gittutorial(7): add "Conventions used in this document" section > > The manual page for the git subcommand invoked as "git clone" is > named git-clone(1), and similarly for the rest of the git > subcommands. This patch should make the convention a little > clearer when it is introduced at the beginning of gittutorial(7). > > Thanks to Junio C Hamano for the idea and wording. > > It remains to make an analogous change for user-manual.html > and maybe git(1). > > Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxxxxx> > --- > Documentation/gittutorial.txt | 35 ++++++++++++++++++++++++++++++----- > 1 files changed, 30 insertions(+), 5 deletions(-) > > diff --git a/Documentation/gittutorial.txt > b/Documentation/gittutorial.txt > index 036a27c..51ad814 100644 > --- a/Documentation/gittutorial.txt > +++ b/Documentation/gittutorial.txt > @@ -19,12 +19,37 @@ If you are instead primarily interested in using > git to fetch a project, > 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 log --graph` with: > +Conventions used in this document > +--------------------------------- > > ------------------------------------------------- > -$ man git-log > ------------------------------------------------- > +When discussing 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 by. > + > +Examples are typeset like this: `$ git cmd`. (`$` is your command > +prompt; do not actually type it to your shell.) A subcommand > +is specified as the first parameter to the 'git' program > +when you actually run it from the command line. > + > +So a typical command description may go like this: > + > +To propagate the changes you made back to the original subversion > +repository, you would use the '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 > +------------ > + > +Introducing yourself to git > +--------------------------- > > It is a good idea to introduce yourself to git with your name and > public email address before doing any operation. The easiest > -- > 1.5.5.GIT > -- 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
