[gentoo-pms] [PATCH] Ding dong, old-style virtuals are dead

[Ciaran McCreesh <ciaran.mccreesh@googlemail.com>]

---
 appendices.tex     |    9 +++++++++
 dependencies.tex   |    4 +---
 ebuild-vars.tex    |    3 ---
 glossary.tex       |    8 +++-----
 metadata-cache.tex |    2 +-
 pms.tex            |    2 --
 profiles.tex       |   13 -------------
 virtuals.tex       |   45 ---------------------------------------------
 8 files changed, 14 insertions(+), 72 deletions(-)
 delete mode 100644 virtuals.tex

diff --git a/appendices.tex b/appendices.tex
index 9e91ede..46503bc 100644
--- a/appendices.tex
+++ b/appendices.tex
@@ -56,6 +56,15 @@ The \t{use.defaults} file in the profile directory was used to implement `autous
 flags on or off depending upon which packages are installed. It was deprecated long ago and finally
 removed in 2009.
 
+\section{Old-style Virtuals}
+
+Historically, virtuals were special packages rather than regular ebuilds. An ebuild could specify in
+the \t{PROVIDE} metadata that it supplied certain virtuals, and the package manager had to bear this
+in mind when handling dependencies.
+
+Old-style virtuals were supported by EAPIs \t{0}, \t{1}, \t{2}, \t{3} and \t{4}, and were phased out
+via GLEP 37.
+
 % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
 
 %%% Local Variables:
diff --git a/dependencies.tex b/dependencies.tex
index f6318d8..45081fe 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -13,7 +13,7 @@ There are three classes of dependencies supported by ebuilds:
 \item Post dependencies (\t{PDEPEND}). These must be installed at some point.
 \end{compactitem}
 
-In addition, \t{SRC\_URI}, \t{HOMEPAGE}, \t{PROVIDE}, \t{RESTRICT}, \t{PROPERTIES}, \t{LICENSE} and
+In addition, \t{SRC\_URI}, \t{HOMEPAGE}, \t{RESTRICT}, \t{PROPERTIES}, \t{LICENSE} and
 \t{REQUIRED\_USE} use dependency-style specifications to specify their values.
 
 \section{Dependency Specification Format}
@@ -23,8 +23,6 @@ be surrounded on both sides by whitespace, except at the start and end of the st
 
 \begin{compactitem}
 \item A package dependency specification. Permitted in \t{DEPEND}, \t{RDEPEND}, \t{PDEPEND}.
-\item A simple qualified package name. Permitted in \t{PROVIDE} (and inside \t{DEPEND} etc
-    via the previous item).
 \item A URI, in the form \t{proto://host/path}. Permitted in \t{SRC\_URI} and \t{HOMEPAGE}. In EAPIs
     listed in table~\ref{tab:uri-arrows-table} as supporting \t{SRC\_URI} arrows, may optionally be
     followed by whitespace, then \t{->}, then whitespace, then a simple filename when in
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index 8df94e9..d183305 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -77,9 +77,6 @@ Ebuilds may define any of the following variables:
 \item[DEPEND] See section~\ref{sec:dependencies}.
 \item[EAPI] The EAPI. See below for defaults.
 \item[PDEPEND] See section~\ref{sec:dependencies}.
-\item[PROVIDE] Zero or more qualified package names of any \i{old style}
-    virtuals provided by this package. See section~\ref{sec:dependencies} for full syntax.
-    \label{ebuild-var-provide}
 \item[RDEPEND] See section~\ref{sec:dependencies}. For some EAPIs, \t{RDEPEND} has special behaviour
     for its value if unset and when used with an eclass. See section~\ref{sec:rdepend-depend} for
     details.
diff --git a/glossary.tex b/glossary.tex
index 2acbeb1..03ecace 100644
--- a/glossary.tex
+++ b/glossary.tex
@@ -7,12 +7,10 @@ be immediately obvious.
 \begin{description}
 \item[qualified package name] A package name along with its associated category. For example,
     \t{app-editors/vim} is a qualified package name.
-\item[old-style virtual] An old-style virtual is a pseudo-package which exists if it is listed in an
-    ebuild's \t{PROVIDE} variable. See chapter~\ref{sec:old-virtuals}.
 \item[new-style virtual] A new-style virtual is a normal package in the \t{virtual} category which
-    installs no files and uses its dependency requirements to pull in a `provider'. This is more
-    flexible than the old-style virtuals described above, and requires no special package manager
-    code.
+    installs no files and uses its dependency requirements to pull in a `provider'. Historically,
+    old-style virtuals required special handling from the package manager; new-style virtuals do
+    not.
 \item[stand-alone repository] An (ebuild) repository which is intended to function on its own as the
     only, or primary, repository on a system. Contrast with \i{slave repository} below.
 \item[slave repository, non-stand-alone repository] An (ebuild) repository which is not complete
diff --git a/metadata-cache.tex b/metadata-cache.tex
index 8e7a09d..52c0aee 100644
--- a/metadata-cache.tex
+++ b/metadata-cache.tex
@@ -29,7 +29,7 @@ order. Other lines may be present following these; their meanings are not define
 \item Use flags that this package requires (\t{REQUIRED\_USE}).
     Blank in some EAPIs; see table~\ref{tab:optional-vars-table}.
 \item Post dependencies (\t{PDEPEND})
-\item Old-style virtuals provided by this package (\t{PROVIDE})
+\item Unused; previously used for old-style virtual \t{PROVIDE}.
 \item The ebuild API version to which this package conforms (\t{EAPI})
 \item Properties (\t{PROPERTIES}). In some EAPIs, may optionally be blank, regardless of ebuild
     metadata; see table~\ref{tab:optional-vars-table}.
diff --git a/pms.tex b/pms.tex
index efa50de..4ada8ec 100644
--- a/pms.tex
+++ b/pms.tex
@@ -20,8 +20,6 @@
 
 \include{profiles}
 
-\include{virtuals}
-
 \include{ebuild-format}
 
 \include{ebuild-vars}
diff --git a/profiles.tex b/profiles.tex
index 2dba163..8246431 100644
--- a/profiles.tex
+++ b/profiles.tex
@@ -63,19 +63,6 @@ bash syntax, is allowed as follows:
 \item Backslashes, except for line continuations, are not allowed.
 \end{compactitem}
 
-\subsection{virtuals}
-\label{sec:profiles-virtuals}
-The \t{virtuals} file defines default providers for ``old-style'' virtual packages. It is a simple
-line-based file, with each line containing two whitespace-delimited tokens. The first is a virtual
-package name (for example, \t{virtual/alsa}) and the second is a qualified package name. Blank lines
-and those beginning with a \# character are ignored. When attempting to resolve a virtual name to a
-concrete package, the specification defined in the active profile's \t{virtuals} list should be used if no
-provider is already installed.
-
-The \t{virtuals} file is inherited in the simplest manner: all entries from the parent profile are
-loaded, then entries from the current profile. If a virtual package name appears in both, the entry
-in the parent profile is discarded.
-
 \subsection{Simple line-based files}
 \label{sec:line-stacking}
 These files are a simple one-item-per-line list, which is inherited in the following manner: the
diff --git a/virtuals.tex b/virtuals.tex
deleted file mode 100644
index 8ac05aa..0000000
--- a/virtuals.tex
+++ /dev/null
@@ -1,45 +0,0 @@
-\chapter{Old-Style Virtual Packages}
-\label{sec:old-virtuals}
-
-Old-style virtuals are pseudo-packages---they can be depended upon or
-installed, but do not exist in the ebuild repository.  An old-style
-virtual requires several things in the repository: at least one ebuild
-must list the virtual in its \t{PROVIDE} variable, and there must be
-at least one entry in a profiles \t{virtuals} file listing the default
-provider for each profile---see sections~\ref{ebuild-var-provide} and
-\ref{sec:profiles-virtuals} for specifics on these two. Old-style virtuals
-require special handling as regards dependencies; this is described
-below.
-
-All old-style virtuals must use the category \t{virtual}. Not all packages using the \t{virtual}
-category may be assumed to be old style virtuals.
-
-\note A \i{new-style} virtual is simply an ebuild which install no files and use its dependency
-strings to select providers. By convention, and to ease migration, these are also placed in the
-\t{virtual} category.
-
-\section{Dependencies on virtual packages}
-
-When a dependency on a virtual package is encountered, it must be
-resolved into a real package before it can be satisfied. There are two
-factors that affect this process: whether a package providing the
-virtual is installed, and the \t{virtuals} file in the active profile
-(section~\ref{sec:profiles-virtuals}). If a package is already installed
-which satisfies the virtual requirement (via \t{PROVIDE}), then it
-should be used to satisfy the dependency. Otherwise, the profiles
-\t{virtuals} file (section~\ref{sec:profiles-virtuals}) should be
-consulted to choose an appropriate provider.
-
-Dependencies on old style virtuals must not use any kind of version restriction.
-
-Blocks on provided virtuals have special behaviour documented in section~\ref{provided-blocks}.
-
-% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pms"
-%%% LaTeX-indent-level: 4
-%%% LaTeX-item-indent: 0
-%%% TeX-brace-indent-level: 4
-%%% End:
-- 
1.7.5.1