1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
<?xml version="1.0"?>
<guide self="ebuild-writing/users-and-groups/">
<chapter>
<title>Messages</title>
<body>
<p>
Sometimes it is necessary to display messages for the user. This can be for
errors, post-install help messages, pre-install warnings or simply to notify the
user of what's going on. It is considered good form to display a message
before any particularly long and silent task is carried out, for example (and it
also helps cut down on bogus "compiling foo froze!" bugs).
</p>
<note>
It is a policy violation to use any of these functions to display a line
of characters (a banner header). The use of colours and special leading
characters provided by these functions is sufficient to make a message stand
out.
</note>
<p>
In all cases, assume that the user's terminal is no wider than 79 columns, and
that the <c>einfo</c>, <c>ewarn</c> and <c>eerror</c> functions will occupy 4 columns
with their fancy leading markers.
</p>
</body>
<section>
<title>Information Messages</title>
<body>
<p>
There are a number of functions available to assist here. The `echo` bash
internal is the simplest -- it simply displays its parameters as a message.
</p>
<p>
The <c>einfo</c> function can be used to display an informational message which is
meant to 'stand out'. On a colour terminal, the message provided will be
prefixed with a green asterisk.
</p>
<codesample lang="ebuild">
pkg_postinst() {
einfo "You will need to set up your /etc/foo/foo.conf file before"
einfo "running foo for the first time. For details, please see the"
einfo "foo.conf(5) manual page."
}
</codesample>
</body>
</section>
<section>
<title>Warning Messages</title>
<body>
<p>
The <c>ewarn</c> function is similar, but displays a yellow asterisk. This should be
used for warning messages rather than information.
</p>
</body>
</section>
<section>
<title>Error Messages</title>
<body>
<p>
The <c>eerror</c> function displays a red star, and is used for displaying error
messages. It should almost always be followed by a <c>die</c> call. This function
is mainly used for displaying additional error details before bailing out.
</p>
</body>
</section>
<section>
<title>Important Messages</title>
<body>
<p>
For <e>really</e> important messages, <c>eutils.eclass</c> provides <c>ebeep</c> and
<c>epause</c>. The former will beep a number of times, and the latter will pause
for several seconds to allow the user to read any messages. Both can be disabled
by the user -- you must <b>not</b> attempt to override the user's preference in
this. <c>ebeep</c> takes an optional parameter specifying how many times to beep.
<c>epause</c> takes an optional parameter (which <b>must</b> be an exact whole number)
specifying for how long it should sleep.
</p>
<p>
Do not abuse these functions -- better to save them for when things really are
important.
</p>
<p>
See `Message Functions Reference`_ for a full list of functions.
</p>
</body>
</section>
<section>
<title>Good and Bad Messages</title>
<body>
<p>
Here is an example of a bad message:
</p>
<codesample lang="ebuild">
i=10
while ((i--)) ; do
ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass"
done
</codesample>
<ul>
<li>Displaying the same message repeatedly is excessive.</li>
<li>The uppercase is excessive.</li>
<li>The bad English looks unprofessional.</li>
<li>
The message will only confuse the end user and will not help them work out
whether they have a problem and how to solve it if they do.
</li>
</ul>
<p>
It would be better written as:
</p>
<codesample lang="ebuild">
ewarn "The 'frozbinate' function provided by eutils.eclass is deprecated"
ewarn "in favour of frozbinate.eclass, but this package has not been"
ewarn "updated yet. If this is a package from the main tree, please check"
ewarn "http://bugs.gentoo.org/ and file a bug if there is not one already."
ewarn "If this is your own package, please read the comments in the"
ewarn "frozbinate eclass for instructions on how to convert."
</codesample>
</body>
</section>
</chapter>
</guide>
|
GitWeb