unix documentation

[utzoo!decvax!ucbvax!mhtsa!research!god]

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 at berkeley]