diff options
| author |   Tim Yamin <plasmaroo@gentoo.org> | 2006-02-22 04:01:23 +0000 |
|---|---|---|
| committer | Tim Yamin <plasmaroo@gentoo.org> | 2006-02-22 04:01:23 +0000 |
| commit | 07a0d2875d93c658d14a0ce87ce95b4150977596 (patch) | |
| tree | 8dfa36a3e97fabcf0ac9ec3313d03c06ec45e361 /ebuild-writing/messages/text.xml | |
| parent | More updates. Update the stylesheet adding a few new elements and more sh (diff) | |
| download | devmanual-07a0d2875d93c658d14a0ce87ce95b4150977596.tar.gz devmanual-07a0d2875d93c658d14a0ce87ce95b4150977596.tar.bz2 devmanual-07a0d2875d93c658d14a0ce87ce95b4150977596.zip | |
More goodies; change syntax highlighting mode within quotes for ebuilds.
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@5 176d3534-300d-0410-8db8-84e73ed771c3
Diffstat (limited to 'ebuild-writing/messages/text.xml')
| -rw-r--r-- | ebuild-writing/messages/text.xml | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/ebuild-writing/messages/text.xml b/ebuild-writing/messages/text.xml new file mode 100644 index 0000000..bcb002e --- /dev/null +++ b/ebuild-writing/messages/text.xml @@ -0,0 +1,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> |