Aresearch.24 fa.unix-wizards utzoo!decvax!ucbvax!mhtsa!research!god Wed Sep 2 20:19:16 1981 Unix documentation 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@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.