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

["J. Bruce Fields" <bfields@xxxxxxxxxxxx>]

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