Re: A Standard for Console Messages
On Sat, 21 Dec 1996, David Frey wrote:
> >I was working on a draft for a standard for the console messages. The
> >intension was to get a unique style for all messages displayed at system
> >bootup and shutdown. I posted a new version just before 1.2 was released
> >but I think it got lost since noone had time to think about it. So I post
> >this here again.
>
> Good work. It's about time to get this incorporated into the developper's
> manual.
>
> Minor nit-pick: I'd prefer to use "..." (no space) over "... ".
Ok, I agree. Does someone have any objections?
I already included this change in my draft and made a few bug
fixes.
Bdale, you told me some time ago you would have a look at the language
(grammar, spelling) of the draft. Could please do this and tell me if
everything is ok? Thanks, in advance.
So this is the last chance for changes. If I don't get any complaints
within the next few days (hope that's ok over holiday!) I send this to Ian
to include it in our Policy Manual (or should it go into the Programmers'
Manual?).
So here are the changes from the latest version postet here:
----------------------
--- draft.o Sat Nov 16 02:13:02 1996
+++ draft Tue Dec 24 13:20:19 1996
@@ -15,9 +15,9 @@
* If you want to express that the computer is working on something
(performing a specific task, not starting or stopping a program), we
- use three dots `...'. Note that we don't insert a space between the
- text but after the dots. If the task has been completed we write
- `done.' and put a line feed.
+ use an ``ellipsis'', namely three dots `...'. Note that we don't insert
+ spaces in front of or behind the dots.
+ If the task has been completed we write `done.' and a line feed.
* Design your messages as if the computer is telling you what he is
doing (let him be polite :-) but don't mention ``him'' directly.
@@ -29,7 +29,7 @@
Starting network daemons: nfsd mountd.
-The following formats can be used
+The following formats have to be used
a. when daemons get started.
@@ -58,7 +58,7 @@
echo -n "Starting remote filesystem services: "
echo -n "nfsd "; start-stop-daemon --start nfsd
echo -n "mountd "; start-stop-daemon --start mountd
- echo -n "ugidd "; start-stop-daemon --start ugidd
+ echo -n "ugidd"; start-stop-daemon --start ugidd
echo "."
This makes it possible for the user to see what takes so long and when
@@ -91,15 +91,15 @@
There a several examples where you have to run a program at system
startup or shutdown to perform a specific task. For example, setting
the system's clock via `netdate' or killing all processes when the
- system comes down. Then your message should like this:
+ system comes down. Your message should like this:
- Doing something very useful... done.
+ Doing something very useful...done.
You should print the `done.' right after the job has been completed,
so that the user gets informed why he has to wait. You can get this
behaviour by saying
- echo -n "Doing something very useful... "
+ echo -n "Doing something very useful..."
do_something
echo "done."
----------------------
and here is the complete version:
----------------------
This standard describes different formats for messages written to standard
output by the /etc/init.d packages. The intent of this standard is to improve
the consistency of Debian's startup and shutdown look and feel.
Please look very careful at the details. We want to get the messages to
look exactly the same way concerning spaces, punctuation, and case of letters.
Here is a list of overall rules that you should use when you create output
messages. They can be useful if you have a non-standard message that isn't
covered in the sections below.
* Every message should cover one line, start with a capital letter and
end with a period `.'.
* If you want to express that the computer is working on something
(performing a specific task, not starting or stopping a program), we
use an ``ellipsis'', namely three dots `...'. Note that we don't insert
spaces in front of or behind the dots.
If the task has been completed we write `done.' and a line feed.
* Design your messages as if the computer is telling you what he is
doing (let him be polite :-) but don't mention ``him'' directly.
For example, if you think of saying
I'm starting network daemons: nfsd mountd.
just say
Starting network daemons: nfsd mountd.
The following formats have to be used
a. when daemons get started.
You will use this format if your script starts one or more daemons.
The output should look like this (a single line, no leading spaces):
Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
The <description> should describe the daemon's job or the system the
daemon is useful for, while <daemon-1> up to <daemon-n> denote the
daemons names (this should be the file name of the program).
For example, the output of /etc/init.d/lpd would look like:
Starting printer spooler: lpd.
This can be achieved by saying
echo -n "Starting printer spooler: lpd"
start-stop-daemon --start --quiet lpd
echo "."
in the script. If you have more than one daemon to start, you should
do the following:
echo -n "Starting remote filesystem services: "
echo -n "nfsd "; start-stop-daemon --start nfsd
echo -n "mountd "; start-stop-daemon --start mountd
echo -n "ugidd"; start-stop-daemon --start ugidd
echo "."
This makes it possible for the user to see what takes so long and when
the final daemon has been started.
b. when something needs to be configured.
If you have to set up different parameters of the system upon boot up,
you can use this format:
Setting <parameter> to `<value>'.
You can use the following echo statement to get the quotes right:
echo "Setting DNS domainname to \`"value"'."
Note that the left quotation mark (`) is different from the right (').
c. when a daemon is stopped.
When you stop a daemon you should issue a message similar to the startup
message, except that `Starting' is replaced with `Stopping'.
So stopping the printer daemon will like like this:
Stopping printer spooler: lpd.
d. when something is executed.
There a several examples where you have to run a program at system
startup or shutdown to perform a specific task. For example, setting
the system's clock via `netdate' or killing all processes when the
system comes down. Your message should like this:
Doing something very useful...done.
You should print the `done.' right after the job has been completed,
so that the user gets informed why he has to wait. You can get this
behaviour by saying
echo -n "Doing something very useful..."
do_something
echo "done."
in your script.
e. when none of the above rules apply.
If you have to print a message that doesn't fit into the styles described
above, you can use something appropriate, but please have a look at the
overall rules listed above.
----------------------
Cheers,
Chris
-- _,, Christian Schwarz
/ o \__ schwarz@monet.m.isar.de, schwarz@debian.org,
! ___; schwarz@mathematik.tu-muenchen.de, bm955877@muenchen.org
\ /
\\\______/ ! PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
\ / http://fatman.mathematik.tu-muenchen.de/~schwarz/
-.-.,---,-,-..---,-,-.,----.-.-
"DIE ENTE BLEIBT DRAUSSEN!"
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-REQUEST@lists.debian.org . Trouble? e-mail to Bruce@Pixar.com
Reply to: