Re: Errors in man git
- From
- der Mouse <mouse@rodents-montreal.org>
- Date
- Sep 9, 2010, 00:48 UTC
- Message-ID
- <201009090048.UAA08864@Sparkle.Rodents-Montreal.ORG>
- In-Reply-To
- <20100909001411.067f29f8@jk.gs>
>> 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