misc updates

svn path=/main/trunk/; revision=2829

1 files changed, 38 insertions, 22 deletions

diff --git a/man/ebuild.5 b/man/ebuild.5
index af8443df..9a03e7d5 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -1,4 +1,4 @@
-.TH "EBUILD" "5" "Dec 2005" "Portage 2.1" "portage"
+.TH "EBUILD" "5" "Mar 2006" "Portage 2.1" "portage"
 .SH "NAME"
 ebuild \- the internal format, variables, and functions in an ebuild script
 .SH "DESCRIPTION"
@@ -8,13 +8,14 @@ program accepts a single ebuild script as an argument.  This script
 contains variables and commands that specify how to download, unpack,
 patch, compile, install and merge a particular software package from
 its original sources.  In addition to all of this, the ebuild script
-can also contain pre/post install/remove commands, as required.
+can also contain pre/post install/remove commands, as required.  All 
+ebuild scripts are written in bash.
 .SH "EXAMPLES"
 Here's a simple example ebuild:
 
 .DS
 .nf
-# Copyright 1999\-2005 Gentoo Foundation
+# Copyright 1999\-2006 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
 # $Header: $
 
@@ -51,10 +52,11 @@ src_install() {
 .SH "VARIABLES"
 .TP
 .B MISC USAGE NOTES
-- PORTAGE* and PORTDIR* variables may be found in \fBmake.conf\fR(5).
+- All variables defined in \fBmake.conf\fR(5) are available for use in 
+ebuilds (such as the PORTAGE* and PORTDIR* variables)
 .br
-- When assigning values to variables in ebuilds, you \fBcannot have a space\fR
-between the variable name and the equal sign.
+- When assigning values to variables in ebuilds, you \fBcannot have a 
+space\fR between the variable name and the equal sign.
 .TP
 .B P
 This variable contains the package name without the ebuild revision.
@@ -92,7 +94,7 @@ Contains the package category name.
 .TP
 .B A
 Contains all source files required for the package.  This variable must
-not be defined. It is autogenerated from the \fISRC_URI\fR variables.
+not be defined. It is autogenerated from the \fISRC_URI\fR variable.
 .TP
 \fBWORKDIR\fR = \fI"${PORTAGE_TMPDIR}/portage/${PF}/work"\fR
 Contains the path to the package build root.  Do not modify this variable.
@@ -121,8 +123,8 @@ Should contain a short description of the package.
 .TP
 \fBSRC_URI\fR = \fI"http://happy.com/little/${P}.tar.gz"\fR
 Contains a list of URI's for the required source files.  It can contain
-multiple URI's for a single source file.  The fastest location is chosen
-if the file was not found at \fIGENTOO_MIRROR\fB\fR.
+multiple URI's for a single source file.  The list is processed in order 
+if the file was not found on any of the \fIGENTOO_MIRROR\fRs.
 .TP
 \fBHOMEPAGE\fR = \fI"http://happy.com/"\fR
 Should contain a list of URL's for the sources main sites and other further
@@ -137,17 +139,18 @@ being submitted for inclusion, it must have ~arch set for architectures
 where it has been PROVEN TO WORK.  (Packages KEYWORDed this way may be
 unmasked for testing by setting ACCEPT_KEYWORDS="~arch" on the command
 line, or in \fBmake.conf\fR(5)) For an authoritative list please review
-/usr/portage/profiles/arch.list.
+/usr/portage/profiles/arch.list.  Please keep this list in alphabetical order.
 .TP
 \fBSLOT\fR
-This sets the SLOT for packages that may need to co\-exist.  By default
-you should set \fBSLOT\fR="0" unless you know what you are doing and need
-to do otherwise.  This value should \fINEVER\fR be left undefined.
+This sets the SLOT for packages that may need to have multiple versions 
+co\-exist.  By default you should set \fBSLOT\fR="0".  If you are unsure, then 
+do not fiddle with this until you seek some guidance from some guru.  This 
+value should \fINEVER\fR be left undefined.
 .TP
 \fBLICENSE\fR
 This should be a space delimited list of licenses that the package falls
 under.  This \fB_must_\fR be set to a matching license in
-/usr/portage/licenses/. If the license does not exist in portage yet you
+/usr/portage/licenses/. If the license does not exist in portage yet, you
 must add it first.
 .TP
 \fBIUSE\fR
@@ -342,13 +345,14 @@ or sun specifically.
 .SH "PORTAGE DECLARATIONS"
 .TP
 .B inherit
-Inherit is portage's maintainance of extra classes of functions that
-are external to ebuilds and provided as inheritable capabilities and
-data. They define functions and set data types as drop-in replacements,
-expanded, and simplified routines for extremely common tasks to streamline
-the build process. Inherit may only be called once in an ebuild and it may
-\fBnever be wrapped within any conditionals\fR of any kind. Specification of
-the eclasses contains only their name and not the \fI.eclass\fR extention.
+Inherit is portage's maintainance of extra classes of functions that are 
+external to ebuilds and provided as inheritable capabilities and data. They 
+define functions and set data types as drop-in replacements, expanded, and 
+simplified routines for extremely common tasks to streamline the build 
+process.  Inherit may only be called once in an ebuild and it may \fBnever be 
+wrapped within any conditionals\fR of any kind.  Specification of the eclasses 
+contains only their name and not the \fI.eclass\fR extention.  Also note that 
+the inherit statement must come before other variable declarations.
 .SH "FUNCTIONS"
 .TP
 .B pkg_nofetch
@@ -507,6 +511,16 @@ Same as \fBeinfo\fR, but should be used when showing a warning to the user.
 .TP
 \fBeerror\fR \fI"error message"\fR
 Same as \fBeinfo\fR, but should be used when showing an error to the user.
+.TP
+\fBebegin\fR \fI"helpful message"\fR
+Like \fBeinfo\fR, we output a \fIhelpful message\fR and then hint that the 
+following operation may take some time to complete.  Once the task is 
+finished, you need to call \fBeend\fR.
+.TP
+\fBeend\fR \fI<status>\fR \fI["error message"]\fR
+Followup the \fBebegin\fR message with an appropriate "OK" or "!!" (for 
+errors) marker.  If \fIstatus\fR is non-zero, then the additional \fIerror 
+message\fR is displayed.
 .SH "HELPER FUNCTIONS: UNPACK"
 .TP
 \fBunpack\fR \fI<source>\fR \fI[list of more sources]\fR
@@ -540,7 +554,9 @@ This is used as a replacement for make.  Performs 'make ${MAKEOPTS}
 .br
 if you are going to use \fBemake\fR, make sure your build is happy with
 parallel makes (make \-j2).  It should be tested thoroughly as parallel
-makes are notorious for failing _sometimes_ but not always.
+makes are notorious for failing _sometimes_ but not always.  If you determine 
+that your package fails to build in parallel, and you are unable to resolve 
+the issue, then you should run '\fBemake\fR -j1' instead of 'make'.
 .SH "HELPER FUNCTIONS: INSTALL"
 .TP
 \fBeinstall\fR \fI[make options]\fR