Re: Errors in man git

quoted

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

quoted

        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