Re: [PATCH 2/5] hwclock: clean up message periods/full stops

[Benno Schulenberg <bensberg@justemail.net>]

On Fri, Oct 24, 2014, at 18:07, JWP wrote:
> So what is the util-linux position on message punctuation in general, and
> line termination specifically?  The documentation seem to imply not using any.

The current situation is a mess.  And the documentation does not say
anything about what error messages, status reports, and imperatives
to the user should look like.  The general style seems to be:

1) Error messages (anything that is preceded by the program name
followed by a colon and a space, in thise case "hwclock: ") start with
a lowercase letter and do not end in a period, nor use any period.

2) Status reports and imperatives to the user use full sentences:
they start with a capital letter and end in a period.

So I think the following output is fairly good.

$ ./hwclock --debug
hwclock from util-linux 2.25.379-04c10
hwclock: cannot open /dev/rtc: Permission denied
Using direct I/O instructions to ISA clock.
hwclock: unable to get I/O port access:  the iopl(3) call failed.: Operation not permitted
hwclock: Probably you need root privileges.

The last line should not be preceded by "hwclock" as it's not
an error message.  And "the iopl(3) call failed." should obviously
not end in a period, and it starts with a space too many.

(Also, the phrases "Permission denied" and "Operation not permitted"
should not be capitalized, but they come from libc, so util-linux
cannot do anything about that.)

With line termination you mean the placings of \n?  When they
are needed, to break up a long message, preferably wrap the
text in the program at the same place.

To come back to your patch for a moment:

>  				printf(_("Clock drift factor was calculated as "
> -					 "%f seconds/day.\n"
> -					 "It is far too much. Resetting to zero.\n"),
> +					 "%f seconds/day\n"
> +					 "It is far too much, resetting to zero\n"),
>  				       drift_factor);

This would simply be a wrong change.  Literally your second line
says that resetting to zero is far too much.  When giving status
reports it won't hurt to be very clear, and punctuation is part
of that.  If asked, I would rewrite the above message as:

"The clock drift factor was calculated as %f seconds per day.\n"
"This is far too much.  It has been reset to zero.\n"

Benno

-- 
http://www.fastmail.fm - mmm... Fastmail...