Errors in man git

Errors in man git

[Daniel U. Thibault]

     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

Re: Errors in man git

[Jan Krüger]

Hi,

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

> 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@vger.kernel.org to the mailing list as it seems appropriate).  

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]

> [...] 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:  

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

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 93e3b07..fbceb12 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -316,7 +316,8 @@ GIT COMMANDS
 ------------
 
 We divide git into high level ("porcelain") commands and low level
-("plumbing") commands.
+("plumbing") commands. Please refer to the individual manpages listed
+in the sections below for details on how to invoke each command.
 
 High-level commands (porcelain)
 -------------------------------
-- 
1.7.2.3.392.g02377

Re: Errors in man git

[der Mouse]

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

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

Re: Errors in man git

[Jan Krüger]

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

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

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

Re: Errors in man git

[der Mouse]

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

>>         git add (see git-add(1))

> To what end?

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

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.

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

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