From 96139357aafc8c0f7bfb19964d38abd38f372ddc Mon Sep 17 00:00:00 2001
From: "Andreas K. Huettel (dilfridge)" <dilfridge@g.o>
Date: Sat, 23 Jun 2012 20:41:39 +0200
Subject: [PATCH] Add specification for stable use forcing/masking

---
 profiles.tex |   38 +++++++++++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 7 deletions(-)

diff --git a/profiles.tex b/profiles.tex
index 8246431..dbad6102 100644
--- a/profiles.tex
+++ b/profiles.tex
@@ -108,13 +108,23 @@ the forms defined by the directory's EAPI.
 
 \subsection{USE masking and forcing}
 \label{sec:use-masking}
-This section covers the four files \t{use.mask}, \t{use.force}, \t{package.use.mask} and
-\t{package.use.force}. They are described together because they interact in a non-trivial manner.
+This section covers the six files \t{use.mask}, \t{use.force}, \t{package.use.mask},
+\t{package.use.force}, \t{package.use.stable.mask}, and \t{package.use.stable.force}.
+They are described together because they interact in a non-trivial manner.
 
 Simply speaking, \t{use.mask} and \t{use.force} are used to say that a given USE flag must never or
-always, respectively, be enabled when using this profile. \t{package.use.mask} and
-\t{package.use.force} do the same thing on a per-package, or per-version, basis. The precise manner
-in which they interact is less simple, and is best described in terms of the algorithm used to
+always, respectively, be enabled when using this profile.
+
+\t{package.use.mask} and \t{package.use.force} do the same thing on a per-package, or per-version,
+basis.
+
+The same is true for \t{package.use.stable.mask} and \t{package.use.stable.force}, which
+however, only act on packages that are merged due to a stable keyword in the sense of subsection
+\ref{sec:keyword-names}. Thus, these files can be used to restrict the feature set deemed
+stable in a package.
+
+The precise manner in which the six files
+interact is less simple, and is best described in terms of the algorithm used to
 determine whether a flag is masked for a given package version. This is described in Algorithm~\ref{alg:use-masking}.
 \begin{algorithm}
 \caption{USE masking logic} \label{alg:use-masking}
@@ -133,12 +143,26 @@ determine whether a flag is masked for a given package version. This is describe
             \STATE let masked = false
         \ENDIF
     \ENDFOR
+    \IF{stable keyword in use}
+        \FOR{each $line$ in package.use.stable.mask, in order, for which the spec matches $package$}
+            \IF{$line$ contains \i{flag}}
+                \STATE let masked = true
+            \ELSIF{$line$ contains \i{-flag}}
+                \STATE let masked = false
+            \ENDIF
+        \ENDFOR
+    \ENDIF
 \ENDFOR
 \end{algorithmic}
 \end{algorithm}
 
-The logic for \t{use.force} and \t{package.use.force} is identical. If a flag is both masked and
-forced, the mask is considered to take precedence.
+Stable restrictions (``stable keyword in use'' in Algorithm~\ref{alg:use-masking}) are applied
+exactly if replacing in \t{KEYWORDS} all stable keywords by the corresponding tilde prefixed
+keywords (see subsection \ref{sec:keyword-names}) would result in the package installation being
+prevented due to the \t{KEYWORDS} setting.
+
+The logic for \t{use.force}, \t{package.use.force}, and \t{package.use.stable.force} is
+identical. If a flag is both masked and forced, the mask is considered to take precedence.
 
 \t{USE\_EXPAND} values may be forced or masked by using \t{expand\_name\_value}.
 
-- 
1.7.9.2