how to format an error?

how to format an error?

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 283 bytes --]

(no one commented last time, I'll try again).

Given the attached, which is the correct way of formatting an error message:

	This is an error message.
	this is an error message.
	This is an error message
	this is an error message

GDB (no suprize) does all of the above :-)

Andrew

[-- Attachment #2: [Fwd: [PATCH] Various source cleanup/enhancements] --]
[-- Type: message/rfc822, Size: 6537 bytes --]

[-- Attachment #2.1.1: Type: text/plain, Size: 110 bytes --]

What is the correct format of an error message string?  The attached, 
from binutils is interesting.

	Andrew

[-- Attachment #2.1.2: Re: [PATCH] Various source cleanup/enhancements --]
[-- Type: message/rfc822, Size: 3930 bytes --]

From: Alan Modra <amodra@bigpond.net.au>
To: Eric Christopher <echristo@redhat.com>
Cc: Thiemo Seufer <ica2_ts@csv.ica.uni-stuttgart.de>, binutils@sources.redhat.com
Subject: Re: [PATCH] Various source cleanup/enhancements
Date: Tue, 4 Dec 2001 09:04:24 +1030
Message-ID: <20011204090424.O1047@bubble.sa.bigpond.net.au>

On Mon, Dec 03, 2001 at 01:59:46PM -0800, Eric Christopher wrote:
> On Mon, 2001-12-03 at 13:57, Alan Modra wrote:
> > On Mon, Dec 03, 2001 at 01:47:04PM -0800, Eric Christopher wrote:
> > > Ok except for these.  Make sure they are capitals before checking in :)
> > 
> > Err, the standard (from gcc) for error messages is as Thiemo had it.
> > This text is prefixed with "Error: " so it doesn't start a sentence, and
> > thus should not start with a capital.
> 
> Ah ha.  Thanks :)

BTW, I'm not too sure about the rationale I gave regarding not starting
a sentence.  That opinion was just parroted from someone on the gcc list.
I'd say the text following the colon _is_ the start of a new sentence,
but I don't want to get into grammar wars.  :)

http://www.gnu.org/prep/standards_15.html#SEC15 says

"The string message should not begin with a capital letter when it follows
a program name and/or file name.  Also, it should not end with a period.

Error messages from interactive programs, and other messages such as usage
messages, should start with a capital letter.  But they should not end
with a period."

Re: how to format an error?

[Eli Zaretskii]

On Sun, 13 Jan 2002, Andrew Cagney wrote:

> Given the attached, which is the correct way of formatting an error message:
> 
> 	This is an error message.
> 	this is an error message.
> 	This is an error message
> 	this is an error message

I suggest the last variant.  It goes with the GNU coding standards
except for the capitalization.  But capitalization is
language-specific (e.g., in German, all nouns are capitalized), and it
was recently discovered in Emacs development that a 100% adherence to
the capitalization rule you cited produces wrong results in some
cases.  Most of the messages don't need caps, so I think losing that
is the best alternative which is simple enough to adher to.

Re: how to format an error?

[Richard Earnshaw]

> 
> On Sun, 13 Jan 2002, Andrew Cagney wrote:
> 
> > Given the attached, which is the correct way of formatting an error message:
> > 
> > 	This is an error message.
> > 	this is an error message.
> > 	This is an error message
> > 	this is an error message
> 
> I suggest the last variant.  It goes with the GNU coding standards
> except for the capitalization.  But capitalization is
> language-specific (e.g., in German, all nouns are capitalized), and it
> was recently discovered in Emacs development that a 100% adherence to
> the capitalization rule you cited produces wrong results in some
> cases.  Most of the messages don't need caps, so I think losing that
> is the best alternative which is simple enough to adher to.

Hmm, I'd go for the third.  If the message were to appear in a GUI box, it 
could well be a line of text on its own, such as

         ************* ERROR **************
         *                                *
         *    This is an error message    *
         *                                *
         **********************************

In such a context I think it would be very wrong to start this with a 
lower-case letter.

However, exceptions:

strings extracted from user code shouldn't have the case changed, so

print foo

error: Foo doesn't exist

would be wrong.  Though I think this should be "'foo' doesn't exist"

Given that, (and that a litteral will never appear in the first letter) 
can we safely assume that we can capitalize the first letter during 
printing?  If so, we could mandate that all messages in the source code 
should start with a lower case letter (except where other capitalization 
rules apply) and then have the UI output routine capitalize the first 
letter as appropriate for the output stream?

R.

Re: how to format an error?

[Eli Zaretskii]

On Mon, 14 Jan 2002, Richard Earnshaw wrote:

> Hmm, I'd go for the third.  If the message were to appear in a GUI box, it 
> could well be a line of text on its own, such as
> 
>          ************* ERROR **************
>          *                                *
>          *    This is an error message    *
>          *                                *
>          **********************************
> 
> In such a context I think it would be very wrong to start this with a 
> lower-case letter.

It usually comes with something before it, like in

         foobar: this is an error message

So I think the problem that bothers you mostly doesn't exist.

> Given that, (and that a litteral will never appear in the first letter) 
> can we safely assume that we can capitalize the first letter during 
> printing?

No.  That's exactly what we discovered in Emacs: you cannot assume 
anything about proper capitalization, unless you are certain the message 
will always be in US English.  Any assumption you make will break in too 
many cases.

Re: how to format an error?

[Andrew Cagney]

> On Sun, 13 Jan 2002, Andrew Cagney wrote:
> 
> 
>> Given the attached, which is the correct way of formatting an error message:
>> 
>> This is an error message.
>> this is an error message.
>> This is an error message
>> this is an error message
> 
> 
> I suggest the last variant.  It goes with the GNU coding standards
> except for the capitalization.  But capitalization is
> language-specific (e.g., in German, all nouns are capitalized), and it
> was recently discovered in Emacs development that a 100% adherence to
> the capitalization rule you cited produces wrong results in some
> cases.  Most of the messages don't need caps, so I think losing that
> is the best alternative which is simple enough to adher to.


Wouldn't the gettext stuff let the german translator do this?  The 
translator certainly isn't required to follow the capitalization 
convention used in the Australian English version.

Anyway, we agree on one thing - the trailing fullstop.  I'll ARI that :-)

Andrew

http://www.gnu.org/prep/standards_15.html#SEC15
http://www.gnu.org/prep/standards_30.html#SEC30

Re: how to format an error?

[Eli Zaretskii]

> Date: Sat, 02 Feb 2002 11:09:15 -0500
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> Wouldn't the gettext stuff let the german translator do this?

gettext? what gettext? there _is_ no gettext in GDB ;-)

Anyway, the specific case I cited was with system error messages
returned by strerror.  These are not subject to translations.

Re: how to format an error?

[Andrew Cagney]

> Date: Sat, 02 Feb 2002 11:09:15 -0500
>> From: Andrew Cagney <ac131313@cygnus.com>
>> 
>> Wouldn't the gettext stuff let the german translator do this?
> 
> 
> gettext? what gettext? there _is_ no gettext in GDB ;-)


> Anyway, the specific case I cited was with system error messages
> returned by strerror.  These are not subject to translations.


My manual says:

     The strerror() function returns a pointer to the language-dependent error
     message string affiliated with an error number.


with a SEE ALSO to setlocale().  I guess something like:

   error ("Cannot perform exponentiation: %s", strerror (errno));

is ok, but:

   error ("%s on target_read", safe_strerror (err));

is really bad.

Andrew

(Hmm, I like the swapping between strerror and save_strerror ...)