Re: [RFD/PATCH] Documentation: mention category

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx> 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?

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

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




[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]