Add a new "EAPI 2 Draft" section which unifies the content of the EAPI 2_pre*

sections.

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

1 files changed, 285 insertions, 6 deletions

diff --git a/doc/package/ebuild/eapi/2.docbook b/doc/package/ebuild/eapi/2.docbook
index 20f7434d..b2f9e412 100644
--- a/doc/package/ebuild/eapi/2.docbook
+++ b/doc/package/ebuild/eapi/2.docbook
@@ -274,15 +274,294 @@ src_compile() {
 		</section>
 	</section>
 </section>
-<section id='package-ebuild-eapi-2_pre3'>
-	<title>EAPI 2_pre3</title>
-	<section id='package-ebuild-eapi-2-phases'>
+<section id='package-ebuild-eapi-2-draft'>
+	<title>EAPI 2 Draft</title>
+	<section id='package-ebuild-eapi-2-draft-helpers'>
+	<title>Helpers</title>
+	<section id='package-ebuild-eapi-2-draft-helpers-doman'>
+	<title>doman</title>
+	<para>
+	Language codes in file names are now used for path translation.
+	</para>
+	<table><title>Man Page Path Translation</title>
+	<tgroup cols='2' align='left' >
+	<colspec colname='source'/>
+	<colspec colname='destination'/>
+	<thead>
+	<row>
+	<entry>Source</entry>
+	<entry>Destination</entry>
+	</row>
+	</thead>
+	<tbody>
+	<row>
+	<entry>foo.1</entry>
+	<entry>/usr/share/man/man1/foo.1</entry>
+	</row>
+	<row>
+	<entry>foo.lang.1</entry>
+	<entry>/usr/share/man/lang/man1/foo.1</entry>
+	</row>
+	</tbody>
+	</tgroup>
+	</table>
+	</section>
+	</section>
+	<section id='package-ebuild-eapi-2-draft-use-deps'>
+	<title>USE Dependencies</title>
+	<section id='package-ebuild-eapi-2-draft-use-deps-unconditional'>
+	<title>Unconditional USE Dependencies</title>
+	<table><title>Syntax Examples</title>
+	<tgroup cols='2' align='left' >
+	<colspec colname='example'/>
+	<colspec colname='meaning'/>
+	<thead>
+	<row>
+	<entry>Example</entry>
+	<entry>Meaning</entry>
+	</row>
+	</thead>
+	<tbody>
+	<row>
+	<entry>foo[bar]</entry>
+	<entry>foo must have bar enabled</entry>
+	</row>
+	<row>
+	<entry>foo[bar,baz]</entry>
+	<entry>foo must have both bar and baz enabled</entry>
+	</row>
+	<row>
+	<entry>foo[-bar,baz]</entry>
+	<entry>foo must have bar disabled and baz enabled</entry>
+	</row>
+	</tbody>
+	</tgroup>
+	</table>
+	</section>
+	<section id='package-ebuild-eapi-2-draft-use-deps-conditional'>
+	<title>Conditional USE Dependencies</title>
+	<table><title>Syntax Examples</title>
+	<tgroup cols='2' align='left' >
+	<colspec colname='compact'/>
+	<colspec colname='expanded'/>
+	<thead>
+	<row>
+	<entry>Compact Form</entry>
+	<entry>Equivalent Expanded Form</entry>
+	</row>
+	</thead>
+	<tbody>
+	<row>
+	<entry>foo[bar?]</entry>
+	<entry>bar? ( foo[bar]  ) !bar? ( foo       )</entry>
+	</row>
+	<row>
+	<entry>foo[!bar?]</entry>
+	<entry>bar? ( foo       ) !bar? ( foo[-bar] )</entry>
+	</row>
+	<row>
+	<entry>foo[bar=]</entry>
+	<entry>bar? ( foo[bar]  ) !bar? ( foo[-bar] )</entry>
+	</row>
+	<row>
+	<entry>foo[!bar=]</entry>
+	<entry>bar? ( foo[-bar] ) !bar? ( foo[bar]  )</entry>
+	</row>
+	</tbody>
+	</tgroup>
+	</table>
+	</section>
+	</section>
+	<section id='package-ebuild-eapi-2-draft-phases'>
 		<title>Phases</title>
-		<section id='package-ebuild-eapi-2-phases-src-prepare'>
+		<section id='package-ebuild-eapi-2-draft-phases-src-prepare'>
 			<title>New src_prepare Phase Function</title>
 			<para>
-			A new src_prepare function is called in-between the src_unpack and
-			src_configure functions, with cwd initially set to $S.
+			A new src_prepare function is called after the src_unpack
+			function, with cwd initially set to $S.
+			</para>
+		</section>
+		<section id='package-ebuild-eapi-2-draft-phases-src-configure'>
+			<title>New src_configure Phase Function</title>
+			<para>
+			The configure portion of the src_compile function has been
+			split into a separate function which is named src_configure. The
+			src_configure function is called in-between the src_prepare and
+			src_compile functions.
+			</para>
+			<programlisting>
+src_configure() {
+	if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then
+		econf
+	fi
+}
+
+src_compile() {
+	if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then
+		emake || die "emake failed"
+	fi
+}
+			</programlisting>
+		</section>
+		<section id='package-ebuild-eapi-2-draft-phases-order'>
+			<title>Execution Order of Phase Functions</title>
+			<table><title>Execution Order of Phase Functions</title>
+				<tgroup cols='1' align='left' >
+				<colspec colname='name'/>
+				<thead>
+				<row>
+					<entry>Phase Function Name</entry>
+				</row>
+				</thead>
+				<tbody>
+				<row>
+					<entry>pkg_setup</entry>
+				</row>
+				<row>
+					<entry>src_unpack</entry>
+				</row>
+				<row>
+					<entry>src_prepare</entry>
+				</row>
+				<row>
+					<entry>src_configure</entry>
+				</row>
+				<row>
+					<entry>src_compile</entry>
+				</row>
+				<row>
+					<entry>src_test</entry>
+				</row>
+				<row>
+					<entry>src_install</entry>
+				</row>
+				<row>
+					<entry>pkg_preinst</entry>
+				</row>
+				<row>
+					<entry>pkg_postinst</entry>
+				</row>
+				<row>
+					<entry>pkg_prerm</entry>
+				</row>
+				<row>
+					<entry>pkg_postrm</entry>
+				</row>
+				</tbody>
+				</tgroup>
+			</table>
+		</section>
+		<section id='package-ebuild-eapi-2-draft-phases-default-functions'>
+			<title>Default Phase Functions</title>
+			<para>
+			The default pkg_nofetch and src_* phase functions are now
+			accessible via a function having a name
+			that begins with default_ and
+			ends with the respective phase function name. For example,
+			a call to a function with the name default_src_compile is
+			equivalent to a call to the default src_compile
+			implementation.
+			</para>
+			<table><title>Default Phase Functions</title>
+				<tgroup cols='1' align='left' >
+				<colspec colname='name'/>
+				<thead>
+				<row>
+					<entry>Function Name</entry>
+				</row>
+				</thead>
+				<tbody>
+				<row>
+					<entry>default_pkg_nofetch</entry>
+				</row>
+				<row>
+					<entry>default_src_unpack</entry>
+				</row>
+				<row>
+					<entry>default_src_prepare</entry>
+				</row>
+				<row>
+					<entry>default_src_configure</entry>
+				</row>
+				<row>
+					<entry>default_src_compile</entry>
+				</row>
+				<row>
+					<entry>default_src_test</entry>
+				</row>
+				</tbody>
+				</tgroup>
+			</table>
+			<para>
+			The default phase functions for a particular EAPI are also
+			accessible as functions having names that start with 'eapi'
+			followed by the EAPI value. For example, a call to a function
+			named eapi0_src_compile is equivalent to a call to the
+			default src_compile implementation that is provided with EAPI 0.
+			</para>
+			<table><title>Default EAPI Phase Functions</title>
+				<tgroup cols='1' align='left' >
+				<colspec colname='name'/>
+				<thead>
+				<row>
+					<entry>Function Name</entry>
+				</row>
+				</thead>
+				<tbody>
+				<row>
+					<entry>eapi0_pkg_nofetch</entry>
+				</row>
+				<row>
+					<entry>eapi0_src_unpack</entry>
+				</row>
+				<row>
+					<entry>eapi0_src_compile</entry>
+				</row>
+				<row>
+					<entry>eapi0_src_test</entry>
+				</row>
+				<row>
+					<entry>eapi1_pkg_nofetch</entry>
+				</row>
+				<row>
+					<entry>eapi1_src_unpack</entry>
+				</row>
+				<row>
+					<entry>eapi1_src_compile</entry>
+				</row>
+				<row>
+					<entry>eapi1_src_test</entry>
+				</row>
+				<row>
+					<entry>eapi2_pkg_nofetch</entry>
+				</row>
+				<row>
+					<entry>eapi2_src_unpack</entry>
+				</row>
+				<row>
+					<entry>eapi2_src_prepare</entry>
+				</row>
+				<row>
+					<entry>eapi2_src_configure</entry>
+				</row>
+				<row>
+					<entry>eapi2_src_compile</entry>
+				</row>
+				<row>
+					<entry>eapi2_src_test</entry>
+				</row>
+				</tbody>
+				</tgroup>
+			</table>
+		</section>
+		<section id='package-ebuild-eapi-2-draft-phases-default-function-alias'>
+			<title>Default Phase Function Alias</title>
+			<para>
+			A function named "default" is redefined for each phase so that it
+			will call the default_* function corresponding to the current phase.
+			For example, a call to the function named "default" during the
+			src_compile phase is equivalent to a call to the function named
+			default_src_compile.
 			</para>
 		</section>
 	</section>