Final version of the Standard for Console Messages
Hi folks!
Here is the final version of our new standard for Console Messages. I
just changed some phrases (thanks to Bdale) and the placement of
spaces (thanks to Johnie), see diff below.
If there are no objections until Sat 4 Jan 97, 10:00 am MET +0100, I'll
send this to Ian to include it in our manuals.
Cheers,
Chris
The changes: -------------------------
--- draft.o Thu Jan 2 13:23:52 1997
+++ draft Thu Jan 2 13:30:48 1997
@@ -29,18 +29,18 @@
Starting network daemons: nfsd mountd.
-The following formats have to be used
+The following formats must be used
a. when daemons get started.
- You will use this format if your script starts one or more daemons.
+ 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).
+ The <description> should describe the subsystem the daemon or set of
+ daemons are part of, while <daemon-1> up to <daemon-n> denote each
+ daemon's name (typically the file name of the program).
For example, the output of /etc/init.d/lpd would look like:
@@ -55,14 +55,17 @@
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 -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.
+ the final daemon has been started. Please be careful where to put spaces:
+ In the example above the system administrator can easily comment out
+ a line if he don't wants to start a specific daemon, while the displayed
+ message still looks good.
b. when something needs to be configured.
--------------------------------------
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 must be used
a. when daemons get started.
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 subsystem the daemon or set of
daemons are part of, while <daemon-1> up to <daemon-n> denote each
daemon's name (typically 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. Please be careful where to put spaces:
In the example above the system administrator can easily comment out
a line if he don't wants to start a specific daemon, while the displayed
message still looks good.
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.
--------------------------------------
-- _,, 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: