Re: [RFD/PATCH] Documentation: mention category

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 9, 2014, 20:26 UTC
Message-ID: <xmqqiohklgbx.fsf@gitster.dls.corp.google.com>
In-Reply-To: <538d1a10bda3793ea10ec6f7de43de371d17e709.1418123780.git.git@drmicha.warpmail.net>

Michael J Gruber <git@drmicha.warpmail.net> writes:

> Rather than changing git-foo.txt, we could do the substitution magic
> from Documentation/Makefile, of course, to keep man pages and command-list
> in sync. Although this would keep me from submitting the final series
> with 1 patch per file :)

I do not get that smiley. Are you saying that these noisy patches add to your karma points?

Show 14 quoted lines

> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index 9631526..b6a8bc6 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -13,6 +13,10 @@ SYNOPSIS
>  	  [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing]
>  	  [--] [<pathspec>...]
>  
> +CATEGORY
> +--------
> +Main user interface command (porcelain)
> +
>  DESCRIPTION
>  -----------

While I do not have objection to adding this information, I have a few problems with the execution:

 - These four lines at the very beginning is a precious real
   estate.  The new reader would not benefit from the distinction
   before reading the first paragraph of description to learn what
   it does and what it is for anyway.  Move it much later, perhaps
   at the end.

 - A phrase "Main user interface command" to a new user does not
   help very much if it does not tell enough what that phrase really
   means (e.g. you should not be using it for scripting).  Extend
   the description more, after moving it to the end.

 - As you said, this should be done in a way to keep the two sources
   of information in sync.  Either add these from command-list, or
   generate command-list from these.