How to Deal with Obscure Problems on UNIX

[Gary Perlman]

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