This has been too much (long) chatter without simple solutions.
"Research is seeing the obvious." [1]
1) The missing part is information.
Solution:
a) Provide a message (warning, error), if "\snn" is in the input.
b) Augment the documentation to tell the readers,
that "\snn" is deprecated, obsolete, out of date, etc.
and what they should use instead.
2) About the "\snn" problem.
The current executing code is not the problem.
The current existing roff-files are not the problem.
The problem is the people who (still, will) write "\snn"
instead of "\s(nn" (portability) or "\s[nn]" (for "groff" and
compatibles).
"Since breaking out of bad habits, rather than acquiring new
ones, is the toughest part of learning we must expect from that
system permanent mental damage for most students exposed to
it." [2]
3) Other things.
a) A missing part of messages is the name of the culprit,
in this case the s-escape (\s).
Solution: Provide the name ("\\s escape" is already used once in the
subroutine).
b) Adding details of the argument of the escape in messages is not
necessary.
c) Adding specific code to report specific syntax errors is not
necessary.
A look in the documentation should reveal, what the correct, best
syntax is.
----
Examples:
A) Report bad practice:
else {
val = val*10 + (c - '0');
error("Use \\s(%1... instead of \\s%1... for more \
robustness.\n\tSee the documentation.", val);
}
}
val *= sizescale;
B) Add informations to messages
a)
const char *s_escape_msg = "Previous error message is caused by the \
\\s escape";
const char *escape = "\\s escape";
b) (a = add, c = changed)
else if (!tok.delimiter(1)) {
a error("%1", s_escape_msg);
return 0;
if (!get_number(&val, 'z')) {
a error("%1", s_escape_msg);
return 0;
if (start.ch() == '[')
c error("%1: missing ']'", escape);
else
c error("%1: missing closing delimiter", escape);
return 0;
else {
c error("%1: bad digit in point size", escape);
return 0;
____
[1]
The important part of research, which I describe to my
students as "seeing the obvious", and as it has otherwise been
put:
"Scientific research consists in seeing what everyone else has
seen, but thinking what no one else has thought"
-A. Szent-Gyorgyi
Herman Rubin in the Usenet group "misc.education".
#
[2] Page xxxvii in:
On the Cruelty of Really Teaching Computing Science
Edsger W. Dijkstra
SIGCSE Bulletin 1989, 21(1), pp. xxv-xxxix.
Also "www.cs.utexas.edu/users/EWD/"
--
Bjarni I. Gislason
