Errors in man git

     There are no indications in the "man git" pages as to how to report 
errors, so I'm following the instructions I googled at 
http://www.kernel.org/doc/man-pages/reporting_bugs.html (adding 
git-u79uwXL29TY76Z2rM5mHXA@public.gmane.org to the mailing list as it seems appropriate).

    The "man git" pages give the syntax (SYNOPSIS) as:

##########
git [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path]
            [-p|--paginate|--no-pager] [--no-replace-objects]
            [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]
            [--help] COMMAND [ARGS]
##########

    Hence "git COMMAND" should work once the appropriate value is 
substituted for COMMAND.  The COMMANDs are later documented (GIT 
COMMANDS) as long lists of "porcelain" and "plumbing" COMMANDs.  
However, *none* of the COMMANDs given actually work.  For instance, one 
(porcelain) COMMAND is "git-gui" but typing "git git-gui" in a command 
shell results in the message:

########## git: 'git-gui' is not a git command. See 'git --help'. ##########

    The actual COMMAND (documented under "man git-gui") is "gui".

    Now, if the intent of the COMMAND lists is to send the user off to 
the other man-pages, that is fine but ought to be clearly indicated by a 
preamble of some sort.  Maybe the man pages should read something like:

##########
GIT COMMANDS
        We divide git into high level ("porcelain") commands and low level
        ("plumbing") commands.

        The actual COMMAND strings are documented under the individual
        man pages listed in what follows.  For instance, the COMMAND for
        "adding file contents to the index" is given by the git-add man 
pages.
##########

Daniel U. Thibault
a.k.a. Urhixidur
a.k.a. Seigneur Bohémond de Nicée
URL: <http://www.bigfoot.com/~D.U.Thibault>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi,

"Daniel U. Thibault" <d.u.thibault@sympatico.ca> wrote:

Since the manpages are written by the git project only, I think it's more appropriate to address the git mailing list only. [pruning other recipients]

That's because of the way other manpages have to be referenced. Let me include a snippet from the manpage to clarify:

| HIGH-LEVEL COMMANDS (PORCELAIN)
|       We separate the porcelain commands into the main commands and
|       some ancillary user utilities.
|
|   Main porcelain commands
|       git-add(1)
|           Add file contents to the index.

Here, "git-add(1)" is written in one word because otherwise it's not a valid reference to another manpage. The only alternative is that we rename the manpage to "add"... but people probably won't like git polluting the manpage namespace that way, and "add" by itself isn't a valid command anyway.

If you look at "man git-add", you'll see that the synopsis given there shows the right way to invoke the command:

| NAME
|       git-add - Add file contents to the index
| 
| SYNOPSIS
|       git add [-n] [-v] [--force | -f] [--interactive | -i]
|                [--patch | -p] [--edit | -e] [--all | [--update | -u]]
|                [--intent-to-add | -N] [--refresh] [--ignore-errors]
|                [--ignore-missing] [--] [<filepattern>...]

I agree that it is potentially confusing, but the manpage references are clearly recognisable as such.

Personally I don't consider it necessary to change this, since it's clearly not horribly complicated to figure out the meaning, but here's a patch for the sake of completeness.

----8<----

Subject: [PATCH] Documentation/git.txt: explain that manpages for subcommands exist

On the off chance that it is not apparent that the manpages for individual git commands explain how to use git commands (e.g. if someone manages to conclude that "git git-add" is the way to use git-add(1)), add a small explanation about that.

Signed-off-by: Jan Krüger <jk@jk.gs>
---
 Documentation/git.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

That's always bothered me; I'd prefer to something more like

    Main porcelain commands
        git add (see git-add(1))
            Add file contents to the index.

/~\ The ASCII				  Mouse
\ / Ribbon Campaign
 X  Against HTML		mouse@rodents-montreal.org
/ \ Email!	     7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B

der Mouse <mouse@Rodents-Montreal.ORG> wrote:

To what end? I have never seen anyone who got genuinely confused by the way it currently reads, and I've been hanging out on #git for over two years now.

Also, please address your concerns to the department of redundancy department. ;)

In a word, accuracy. To refer to foo(1) without further annotation implies the existence of both the manpage and the command. Violating that expectation grates and annoys even after it's clear what is really going on.

I was. Briefly. Initially. The colleague who introduced me to git cleared up the confusion, of course, and it hasn't confused me more than momentarily since - but it still grates every time I see it. Not in a truly confusing sense, but more in an "oh yes, this is a git-related manpage, I have to remember to mentally correct for their misnamed manpages" special-case sort of sense. Knowing how to correct for it, even (I think) understanding why it was done, those do not make it any less expensive to maintain special-case interpretations.

Redundancy is not an inherently bad thing. Writing manpages in English (or any other natural language, for that matter) at all introduces tremendous redundancy. Shannon estimated the information content of normal connected English at about one bit per letter; even if this is low by a factor of two (and manpages probably have less redundancy than Shannon's sample), it means manpages are still 3/4 redundant even if you look at only the content, never mind the formatting.

Redundancy greatly improves communication between people; that's why all natural langauges have a great deal of it - and manpages are just a specialized form of such communication. Especially when dealing with things like computer interfaces, where precision is essential, I am entirely willing to tolerate additional redundancy for the sake of greater precision.

Of course, it's not my decision to make. And I don't know to what extent the arguments you cite are the real reasons for keeping the style you have. But I don't think these arguments really hold all that much weight.

/~\ The ASCII				  Mouse
\ / Ribbon Campaign
 X  Against HTML		mouse@rodents-montreal.org
/ \ Email!	     7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B