Aresearch.22 fa.unix-wizards utzoo!decvax!ucbvax!mhtsa!research!god Mon Aug 17 23:49:53 1981 unix documentation Subject: unix documentation I think ihuxl!jej's arguments are strong ones. Consider the following problem: cc file.o ... ld:file.o:bad magic number Nowhere in the man pages for cc(1) or ld(1) is this (or several others) explained. In harpo!ber's reply, he suggests that "if you want to know more, look at the source". This is absolutely wrong, for these reasons: 1) I don't see why a user should have to know where the source IS. 2) It violates one of the few genuine principles of unix programming, e.g., that a program or subroutine should do something reasonable regardless of its input. 3) Have you ever LOOKED at /usr/src/cmd/ld.c??? I have. Gimme a break. All this crap [as ber puts it] about unix being unfriendly and lacking documentation can be absolutely TRUE if all of those "dozens" (sic) of unix experts in every hallway take the attitude that complaints of this sort is just a "bitch bitch bitch" and if you don't like it, why don't you just read my code? It's all there in /a2/vvpl/simul/1175bkp/src/arch/blah.c. Why do people keep talking about unix as if it were a person, or ONE BIG PROGRAM? We are really talking about a large set of programs and libraries written by individuals, not the HAL2000. Every single program, and every subroutine and system call, was written by some individual, who, in my mind, is RESPONSIBLE for the reliability, consistency, improvements, and --documentation-- (excuse my language) for that thing. Nobody is "restricting creativity" by insisting that the behavior and documentation of that thing make sense. I think the lorder command is stupid. You are right, the only thing you can do with it is order libraries. So why doesn't it just DO that, instead of making me type in (much less try to understand) that "brash one-liner"? Don't tell me that someone might want to use a program which outputs file-name, external identifier pairs for something else. I don't believe it. If they do, well, we'll see THEN. I do not intend to criticize the efforts of the unix support group, or any other groups, who have taken on the immense task of providing a set of software that they agree to be responsible for. Our complaints/discussion of aspects of the unix operating system indicate that the job is not complete. They KNOW that. I think that it is the user's responsibility to identify and report problems in a clear, specific, and nonjudgemental narrative, not Flame On! . [usg should also improve the means to do this]. Look, I know what "bad magic number" is; I also fully understand the "brash one-liner". That's a non-issue. I happen to be one of those unix experts in every hallway; if I stayed in my office, I wouldn't be able to get any work done -- 37 people are at my door asking questions about magic numbers because the author didn't do the documentation right, and I don't know how to find her to point it out. Does it always mean "lowering to the least common denominatior" to improve the software & documentation? Ridiculous. If the road signs are too high, what are we going to do -- shorten the poles, or raise the road? Steve Hartwell [research!god, csvax.god@berkeley] ----------------------------------------------------------------- gopher://quux.org/ conversion by John Goerzen of http://communication.ucsd.edu/A-News/ This Usenet Oldnews Archive article may be copied and distributed freely, provided: 1. There is no money collected for the text(s) of the articles. 2. The following notice remains appended to each copy: The Usenet Oldnews Archive: Compilation Copyright (C) 1981, 1996 Bruce Jones, Henry Spencer, David Wiseman.