perlman@giza.cis.ohio-state.edu (Gary Perlman) (11/13/90)
Around 1980, Don Norman wrote his infamous paper on the Trouble With UNIX. In it, he cited the long forgotten program, dsw (delete from switches), which was documented as (I paraphrase) "this little known but indispensable utility lets you interactively delete files." Norman's comment was (again I paraphrase) "Only on UNIX would an indispensable utility be little known." The rm -i option made dsw obsolete, but the problem of obscure information remains, and I note the volume of this news group as supporting evidence. When my students do exercises in my software engineering class, some subset inevitably encounter error messages like: Make: Must be a separator on rules line 4. Stop. Tcov lock file is busy - could not write data Even though I try to warn them of these messages, there are so many among the 20+ programs we use that even the best students fail to understand them all. The MAKE message means that the command in a rule was indented with spaces, not a TAB, because their editor maps tabs to spaces. Grepping -i the Pyramid and Sun manual entries for make shows no mention of "separator." The message from the Sun test coverage tool, TCOV, means that a lock file has been found in /tmp; this can happen if a program you are testing crashes. The Sun manual entry for TCOV does not contain the word "lock," overlooks this file, and the error message does not say that the file is in /tmp. A partial solution to this problem might be to gather all these error messages, write possible explanations for them, and provide a tool to take a message and try to make sense of it. The tool itself could probably be written in shell and use pattern matching for the messages. The hard part may be to gather a comprehensive set of error messages, and even harder, program behaviors, that are not well documented. Do people have such lists? I know that in various places, primarily from teaching software development on UNIX, I have some such lists. I would be happy to collate other lists and post a summary with a simple script. Do people have any ideas about how to map questions like: I put a command into my makefile but make does not know it's there. to the response: If you use emacs, then the last character of your makefile might not be a newline and many versions of make will ignore a file line that does not terminate in a newline. I don't think the answer is to expand the BUGS section, which was removed by many vendors. The BUGS section for Sun make is a full page, and does not get into the problems like the ones above. Send me your ideas and I will summarize. -- Name: Gary Perlman | Computer and Information Science Department Email: perlman@cis.ohio-state.edu | Ohio State University, 228 Bolz Hall Phone: 614-292-2566 | 2036 Neil Avenue Mall Fax: 614-785-9837 or 292-9021 | Columbus, OH 43210-1277 USA
brnstnd@kramden.acf.nyu.edu (Dan Bernstein) (11/14/90)
In article <85864@tut.cis.ohio-state.edu> perlman@giza.cis.ohio-state.edu (Gary Perlman) writes: > When my students do exercises in my software engineering class, some subset > inevitably encounter error messages like: > Make: Must be a separator on rules line 4. Stop. > Tcov lock file is busy - could not write data > Even though I try to warn them of these messages, there are so many among the > 20+ programs we use that even the best students fail to understand them all. I make sure that all error messages in my programs are documented. This doesn't help much for getting around really weird errors, but for them I provide an address to write to for help. I can't convince Berkeley that it'd be nice if foo -A always showed the author of foo, but hopefully they'll see the light at some point. > A partial solution to this problem might be to gather all these error > messages, write possible explanations for them, and provide a tool to > take a message and try to make sense of it. It'd probably be easier to rewrite the program. ---Dan
les@chinet.chi.il.us (Leslie Mikesell) (11/15/90)
In article <7220:Nov1408:26:4390@kramden.acf.nyu.edu> brnstnd@kramden.acf.nyu.edu (Dan Bernstein) writes: >I make sure that all error messages in my programs are documented. What about the ones you get back from perror() that you might not know about when you write the program? The "not a typewriter" message that you get from calling perror after a successful stdio operation to a file is probably the classic, but displaying the "Multihop attempted" message you might get on a system with RFS could be equally confusing out of context. BTW, my all-time favorite error message comes from the AT&T starlan network listen program. It displays it on the console and puts it in the log file as it dies: "Software bug -- should not happen" Yes, it happens... (but only on one of several nearly identical machines). Les Mikesell les@chinet.chi.il.us
chris@mimsy.umd.edu (Chris Torek) (11/15/90)
In article <7220:Nov1408:26:4390@kramden.acf.nyu.edu> brnstnd@kramden.acf.nyu.edu (Dan Bernstein) writes: >I make sure that all error messages in my programs are documented. This >doesn't help much for getting around really weird errors, but for them I >provide an address to write to for help. I can't convince Berkeley that >it'd be nice if foo -A always showed the author of foo, but hopefully >they'll see the light at some point. Hmm. If `vi -A' told you that vi was written by Ken Thompson, Brian Kernighan, Bill Joy, Mark Horton, Jim Bloom, Keith Bostic, Mike Karels, Ralph <lastnameforgotten>, Conrad Huang, Kirk McKusick, Sam Leffler, Bill Jolitz, Peter <someone>, and a few others, who would you ask about `Internal error: vclreol'? -- In-Real-Life: Chris Torek, Univ of MD Comp Sci Dept (+1 301 405 2750) Domain: chris@cs.umd.edu Path: uunet!mimsy!chris
brnstnd@kramden.acf.nyu.edu (Dan Bernstein) (11/15/90)
In article <27680@mimsy.umd.edu> chris@mimsy.umd.edu (Chris Torek) writes: > Hmm. If `vi -A' told you that vi was written by Ken Thompson, Brian > Kernighan, Bill Joy, Mark Horton, Jim Bloom, Keith Bostic, Mike Karels, > Ralph <lastnameforgotten>, Conrad Huang, Kirk McKusick, Sam Leffler, > Bill Jolitz, Peter <someone>, and a few others, who would you ask about > `Internal error: vclreol'? The implication was that foo -A would also show a current address for the most recent author, or at least someone coordinating upgrades and fixes. (Then again, it's not clear that you folks want to hear from users.) ---Dan
em@dce.ie (Eamonn McManus) (11/15/90)
In article <27680@mimsy.umd.edu> chris@mimsy.umd.edu (Chris Torek) writes: >Hmm. If `vi -A' told you that vi was written by Ken Thompson, Brian >Kernighan, Bill Joy, Mark Horton, Jim Bloom, Keith Bostic, Mike Karels, >Ralph <lastnameforgotten>, Conrad Huang, Kirk McKusick, Sam Leffler, >Bill Jolitz, Peter <someone>, and a few others, who would you ask about >`Internal error: vclreol'? Craig Shergold. On a postcard. -- Eamonn McManus <em@dce.ie>
terryl@sail.LABS.TEK.COM (11/16/90)
In article <16694:Nov1421:44:4790@kramden.acf.nyu.edu> brnstnd@kramden.acf.nyu.edu (Dan Bernstein) writes: +In article <27680@mimsy.umd.edu> chris@mimsy.umd.edu (Chris Torek) writes: +> Hmm. If `vi -A' told you that vi was written by Ken Thompson, Brian +> Kernighan, Bill Joy, Mark Horton, Jim Bloom, Keith Bostic, Mike Karels, +> Ralph <lastnameforgotten>, Conrad Huang, Kirk McKusick, Sam Leffler, +> Bill Jolitz, Peter <someone>, and a few others, who would you ask about +> `Internal error: vclreol'? + +The implication was that foo -A would also show a current address for +the most recent author, or at least someone coordinating upgrades and +fixes. (Then again, it's not clear that you folks want to hear from +users.) And that implication was that an end user has the *ABSOLUETLY* latest and greatest up-to-the-minute gosh-darn-wiz-wasn't-that-nice version of said pro- gram in question...... It is up to reader to supply his own proof for the above statement, either true or false. You can assume that the end user did indeed obtain said program through legitimate channels (i.e. it wasn't pirated...)