Unix documentation

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

Subject: Unix documentation
Really, Brian, I think that if I were to take a sample of the people who
would be likely to encounter the bad magic number message (i.e. anyone
at all who uses the c compiler and inadvertently copies a text file to a
.o file) the proportion who would understand what "bad magic" meant is
probably small.  I'm not suggesting that it print a manual page.  I am
not worrying where it will end.  I am wondering when it will start.

I am sure any of our wizards out there is perfectly capable of nominating a
better message. "ld: file.o is not in expected format". Agreed, it does
sound irritatingly close to PL/1 "compiler informatory messages", but it does
its job in a manner which can be argued for.  Your own definition takes a
form of comment that I have seen in Kernighan's Elements of Programming Style:
	i += 5;		/* add 5 to i */
As I remember, it was not one of his suggested forms of documentation.

Wizards are wizards, and we ply our trade with every bit of mysticism that
the alchemists did; I think that this is an offhand consequence of scientific
terminology.  I do not, however, see anything wrong with feeling obligated to
present a coherent and well-behaved interface with the tools I offer others
to use, even if that means losing the awe of the magic number.

I agree that users should learn the structure of the system.  I think that they
should consult the source to learn how it works, not why it doesn't make sense.
I insist that the behavior and documentation of software make sense.  This
attitude is restrictive only in the sense that seatbelts are.  My insistence
is intended for the protection of the users, not the programmer.  The users.
The people who run the programs.  See the first paragraph, above.

I just don't see how this attitude is restrictive.  Expecting someone to
make sense of ": is not an identifier" -- now THAT'S restrictive.

Steve Hartwell	[research!god, csvax.god at Berkeley]