From 5592d3460edc20b7be72d1b4644a2be22ab5f50d Mon Sep 17 00:00:00 2001
From: Zac Medico <zmedico@gentoo.org>
Date: Mon, 16 Aug 2010 01:15:34 -0700
Subject: [PATCH] Bug #273646 - Copy PMS section 12.1.2 EAPI 4 docs for
 REPLACING_VERSIONS and REPLACED_BY_VERSION variables.

---
 doc/package/ebuild/eapi/4.docbook | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/doc/package/ebuild/eapi/4.docbook b/doc/package/ebuild/eapi/4.docbook
index eda4dc37d..44e005f45 100644
--- a/doc/package/ebuild/eapi/4.docbook
+++ b/doc/package/ebuild/eapi/4.docbook
@@ -202,5 +202,23 @@ src_install() {
 			The AA and KV variables are no longer exported to the ebuild environment.
 			</para>
 		</section>
+		<section id='package-ebuild-eapi-4_pre1-variables-replaced-versions'>
+			<title>REPLACING_VERSIONS and REPLACED_BY_VERSION</title>
+			<para>
+			The REPLACING_VERSIONS variable
+			shall be defined in pkg_preinst and pkg_postinst. In addition, it may be
+			defined in pkg_pretend and pkg_setup, although ebuild authors should take care
+			to handle binary package creation and installation correctly when using it in
+			these phases.
+			</para>
+			<para>
+			REPLACING_VERSIONS is a list, not a single optional value, to handle
+			pathological cases such as installing foo-2:2 to replace foo-2:1 and foo-3:2.
+			</para>
+			<para>
+			The REPLACED_BY variable shall
+			be defined in pkg_prerm and pkg_postrm. It shall contain at most one value. 
+			</para>
+		</section>
 	</section>
 </section>
-- 
2.26.2