EAPI 3 has controllable compression and docompress

Signed-off-by: Ulrich Mueller <ulm@gentoo.org>

1 files changed, 77 insertions, 0 deletions

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index d4dd27a..770cfe8 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -398,6 +398,83 @@ already exist.
 
 \end{description}
 
+\subsubsection{Commands affecting install compression}
+In EAPIs listed in table~\ref{tab:compression-table} as supporting controllable compression, the
+package manager may optionally compress a subset of the files under the \t{D} directory. To control
+which directories may or may not be compressed, the package manager shall maintain two lists:
+
+\begin{compactitem}
+\item An inclusion list, which initially contains \t{/usr/share/doc}, \t{/usr/share/info} and
+    \t{/usr/share/man}.
+\item An exclusion list, which initially contains \t{/usr/share/doc/\$\{PF\}/html}.
+\end{compactitem}
+
+The optional compression shall be carried out after \t{src\_install} has completed, and before the
+execution of any subsequent phase function. For each item in the inclusion list, pretend it has the
+value of the \t{D} variable prepended, then:
+
+\begin{compactitem}
+\item If it is a directory, act as if every file or directory immediately under this directory
+    were in the inclusion list.
+\item If the item is a file, it may be compressed unless it has been excluded as described below.
+\item If the item does not exist, it is ignored.
+\end{compactitem}
+
+Whether an item is to be excluded is determined as follows: For each item in the exclusion list,
+pretend it has the value of the \t{D} variable prepended, then:
+
+\begin{compactitem}
+\item If it is a directory, act as if every file or directory immediately under this directory
+    were in the exclusion list.
+\item If the item is a file, it shall not be compressed.
+\item If the item does not exist, it is ignored.
+\end{compactitem}
+
+The package manager shall take appropriate steps to ensure that its compression mechanisms behave
+sensibly even if an item is listed in the inclusion list multiple times, if an item is a symlink,
+or if a file is already compressed.
+
+The following commands may be used in \t{src\_install} to alter these lists. It is an error to call
+any of these functions from any other phase.
+
+\begin{description}
+\item[docompress] If the first argument is \t{-x}, add each of its subsequent arguments to the
+exclusion list. Otherwise, add each argument to the inclusion list. Only available in EAPIs listed
+in table~\ref{tab:compression-table} as supporting \t{docompress}.
+\end{description}
+
+\begin{centertable}{EAPIs supporting controllable compression} \label{tab:compression-table}
+\IFKDEBUILDELSE
+{
+    \begin{tabular}{ l l l }
+        \toprule
+            \multicolumn{1}{c}{\textbf{EAPI}} &
+            \multicolumn{1}{c}{\textbf{Supports controllable compression?}} &
+            \multicolumn{1}{c}{\textbf{Supports \t{docompress}?}} \\
+            \midrule
+    \t{0} & No & No \\
+    \t{1} & No & No \\
+    \t{kdebuild-1} & No & No \\
+    \t{2} & No & No \\
+    \t{3} & Yes & Yes \\
+    \bottomrule
+    \end{tabular}
+}{
+    \begin{tabular}{ l l l }
+        \toprule
+            \multicolumn{1}{c}{\textbf{EAPI}} &
+            \multicolumn{1}{c}{\textbf{Supports controllable compression?}} &
+            \multicolumn{1}{c}{\textbf{Supports \t{docompress}?}} \\
+            \midrule
+    \t{0} & No & No \\
+    \t{1} & No & No \\
+    \t{2} & No & No \\
+    \t{3} & Yes & Yes \\
+    \bottomrule
+    \end{tabular}
+}
+\end{centertable}
+
 \subsubsection{List Functions}
 These functions work on variables containing whitespace-delimited lists (e.g. \t{USE}). Ebuilds must
 not run any of these commands once the current phase function has returned. Ebuilds must not call