On Apr 13, 2007, at 1:22 PM, David Hoerl wrote: Abstract: Apple should remove all man pages, and replace man with something that can read the man pages contained in XCode (but where are the pages???)
Concrete: No.
Yes, people have talked for ages about "updating man" with some format that's infinitely more powerful, flexible, pervasive, whatever, but it hasn't happened yet and just about every effort to consolidate on some intermediate format, like HTML, has met with almost universal derision (OK, perhaps not universal, but it's raised as much ire as anything else when vendors have attempted it before).
No one at Apple has claimed, to my knowledge, to have cracked this problem yet and so we continue to ship, support and, yes, even write new man pages.
The standard man pages (obtained by running "man" from the command line are woefully out of date, and often are incorrect or missing information.
Please file radars against any such man pages. Seriously. Now, I can hear the retort even now, so let's just get it out of the way quickly: "I filed a radar against man page blah.3 back in 2002 and not only did you people not fix blah.3, one of your support people said horrible things about my probable ancestry and then attempted to run over my dog." I know that many people have horror stories to tell about some neglected radar, or might even question whether "something as minor as a man page bug" deserves a radar, but I can tell you that my group alone has fixed many hundreds of man page bugs (and, back in 2001, some of them were in pretty egregious shape) and have even assigned specific individuals the task of doing nothing but fixing man page bugs (it was something of an intern rite-of-passage for awhile).
We take man pages seriously, despite any notions you may have to the contrary, and know that for large sections of the system, there really is nothing better so we'd better do our best to keep them readable and up-to-date. Are we 100% successful? Of course not. There are only so many hours in the day, and frankly, we're some of the worst at finding man page bugs since we don't actually need to read man pages to answer questions we already know the answers to (and reading man pages iteratively, in alphabetical order, would be so stupifyingly boring that no one has ever volunteered for such a task).
I have dutifully submitted a few documentaion bugs on this, but was recently stunned when I read the reply to my latest submission (where I had suggested a one line addition to help future programmers find information that it took me 1/2 day to find). In essence, the reply was its not necessary, develops can always use google to find this information.
And ya know, I'm sure there was some misunderstanding on at least one end of this conversatio, since I can see "just google it" being both the right and the wrong answer, depending on how someone might have understood (or not) your question. Let's take two scenarios where "just google it" is the right and the wrong answer:
1. "I would like to propose altering the strlcpy() man page to talk about secure programming practices and point to several articles on the topic of buffer overflows, also quoting something Bruce Schneier said on that topic which I found particularly priceless."
2. "I found the following typos in the strlcpy() man page and an entry in the SEE ALSO section which references a man page which does not exist."
Obviously, #1 is a clear "google" target since man pages aren't mini web pages or substitutes for a good book on the subject. They're supposed to be concise, clear reference material with, when necessary, a smattering of code examples when such will make the subject material significantly easier to understand (some APIs are pretty complex). Just as obviously, #2 absolutely should be fixed and would make an excellent radar (were it true, of course - sorry to pick on poor strlcpy). Anyone who told you to google for strlcpy() documentation rather than fixing ours in such a scenario would need to be pointed out so we could "have a little chat" with them about the difference between the two cases.
Now, in rdar://5119334 (which I read), you fell somewhere between these two examples. You wanted the man pages to cross-reference something on the Apple Developer website, perhaps unaware of the fact that the two bodies of documentation move at very different speeds relative to one another and even the section you reference might be renumbered at some point, so not including a URL to it is no defense against a "404" on following the reference. It's also not standard. SEE ALSO sections are for referencing other man pages. Period. If they became a bibliography section instead, they wouldn't really be man pages anymore (and see my first paragraph for why that kind of well-intentioned creeping featurism is a bad thing).
Now, I happen to spend a lot of time in Terminal every day, and I often use "apropos" to find section 2 or section 3 functions. But once I have the page open, I really cannot count on the information being accurate as the pages are so out of date.
Again, please cite specific instances of which pages are out of date (and why you think so) and we'll look at them. So, I entered another bug, rdar://5128510 that suggests that Apple just get rid of all the man pages if they aren't going to keep them current. Really, if the company position is that these are not going to ever get updated, why leave them around for people like me to use, potentially incorrectly?
And now we're in "when are you going to stop beating your wife?" territory and I'm not surprised that rdar://5128510 is already closed. Let's try to avoid the hyperbole and keep this conversation productive. We put a lot of time and effort into keeping the man pages current, and with over 6000(!) of them shipping on the system, I'd say it's more than possible that you haven't read some of the ones we just updated. Likewise, I'm sure you've read a few which need attention. File radars and if you think you have one in "category two" above which isn't getting the attention it deserves, bring the radar # to my attention and I'll look into it personally. How's that?
- Jordan
|