In <[email protected]>, on 01/14/2010
at 04:26 PM, Tom Ross <[email protected]> said:
>We felt that the LRM was the documentation.
It's the documentation for the syntax; it's not the documentation for what
syntax error purportedly exists in a particular line of code. Certainly
the error messages in the old COBOL compiler were nowhere near self
explanatory, despite the claim in M&C.
>For 90% of messages the explanation will say to read the Language
>Reference Manual about the statement pointed to by the error message
>in question.
I don't see how that would be helpful unless the error messages were very
explicit, in which case they might be longer than you want. The text in
the messages manual should assume that the programmer knows the syntax and
that he is likely to see what he expects to see. Thus, it helps if the
error messages quote anything small that is misspelled or otherwise
malformed.
>The only other option we see is for us to copy the information from
>the LRM into a message manual. Are we missing a 3rd option?
Yes. The preferred option is to describe the specific class of syntax
error that causes the message and to indicate[1] in the message the exact
position in the line where the error was detected.
>Would a message manual that tells you to read another manual be helpful?
Not by itself.
[1] I suspect that it's better human factors to point to the column
in error rather than to give a column number.
--
Shmuel (Seymour J.) Metz, SysProg and JOAT
ISO position; see <http://patriot.net/~shmuel/resume/brief.html>
We don't care. We don't have to care, we're Congress.
(S877: The Shut up and Eat Your spam act of 2003)
----------------------------------------------------------------------
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to [email protected] with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html
