[gentoo-commits] proj/pms:eapi-7 commit in: /

[Ulrich Müller]

commit:     6bda8dc5d0d1b10bcdd6ef79db2947382706e7a8
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Nov  5 16:08:23 2017 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Feb 24 12:55:24 2018 +0000
URL:        https://gitweb.gentoo.org/proj/pms.git/commit/?id=6bda8dc5

pkg-mgr-commands.tex: Join docompress and dostrip sections.

 dependencies.tex     |   4 +-
 pkg-mgr-commands.tex | 130 +++++++++++++++++++--------------------------------
 2 files changed, 49 insertions(+), 85 deletions(-)

diff --git a/dependencies.tex b/dependencies.tex
index deede34..7ae119b 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -507,8 +507,8 @@ The following tokens are permitted inside \t{RESTRICT}:
 \item[fetch] The package's \t{SRC_URI} entries may not be downloaded automatically. If
     entries are not available, \t{pkg_nofetch} is called. Implies \t{mirror}.
 \item[strip] No stripping of debug symbols from files to be installed may be performed. In EAPIs
-    listed in table~\ref{tab:dostrip} as supporting controllable stripping, this behaviour may be
-    altered by the \t{dostrip} command.
+    listed in table~\ref{tab:staging-area-commands} as supporting controllable stripping, this
+    behaviour may be altered by the \t{dostrip} command.
 \item[userpriv] The package manager may not drop root privileges when building the package.
 \item[test] The \t{src_test} phase must not be run.
 \end{description}

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index dd0b02d..ed3af1b 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -768,27 +768,25 @@ has returned.
 
 \end{description}
 
-\subsection{Commands affecting install compression}
+\subsection{Commands controlling manipulation of files in the staging area}
+These commands are used to control optional manipulations that the package manager may perform on
+files in the staging directory \t{ED}, like compressing files or stripping symbols from object
+files.
 
-\featurelabel{docompress} 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{ED} 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}
+For each of the operations mentioned below, the package manager shall maintain an inclusion list
+and an exclusion list, in order to control which directories and files the operation may or may not
+be performed upon. The initial contents of the two lists is specified below for each of the
+commands, respectively.
 
-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{ED} variable prepended, then:
+Any of these operations 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{ED} 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 is a file, the operation may be performed on it, unless it has been excluded as
+    described below.
 \item If the item does not exist, it is ignored.
 \end{compactitem}
 
@@ -798,96 +796,62 @@ pretend it has the value of the \t{ED} 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 is a file, the operation shall not be performed on it.
 \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}
-
-\ChangeWhenAddingAnEAPI{7}
-\begin{centertable}{EAPIs supporting controllable compression}
-    \label{tab:compression-table}
-    \begin{tabular}{lll}
-      \toprule
-      \multicolumn{1}{c}{\textbf{EAPI}} &
-      \multicolumn{1}{c}{\textbf{Supports controllable compression?}} &
-      \multicolumn{1}{c}{\textbf{Supports \t{docompress}?}} \\
-      \midrule
-      0, 1, 2, 3        & No  & No  \\
-      4, 5, 6, 7        & Yes & Yes \\
-      \bottomrule
-    \end{tabular}
-\end{centertable}
-
-\subsection{Commands affecting stripping of symbols}
+The package manager shall take appropriate steps to ensure that any operations that it performs on
+files in the staging area behave sensibly even if an item is listed in the inclusion list multiple
+times or if an item is a symlink.
 
-\featurelabel{dostrip} In EAPIs listed in table~\ref{tab:dostrip} as supporting controllable
-stripping of symbols, the package manager may strip a subset of the files under the \t{ED}
-directory. To control which files may or may not be stripped, the package manager shall maintain
-two lists:
+\featurelabel{docompress} In EAPIs listed in table~\ref{tab:staging-area-commands} as supporting
+controllable compression, the package manager may optionally compress a subset of the files under
+the \t{ED} directory. The package manager shall ensure that its compression mechanisms behave
+sensibly even if a file is already compressed. For compression, the initial values of the two lists
+are as follows:
 
 \begin{compactitem}
-\item An inclusion list. If the \t{RESTRICT} variable described in section~\ref{sec:restrict}
-    enables a \t{strip} token, this list is initially empty; otherwise it initially contains \t{/}
-    (the root path).
-\item An exclusion list, which initially is empty.
+\item The inclusion list contains \t{/usr/share/doc}, \t{/usr/share/info} and \t{/usr/share/man}.
+\item The exclusion list contains \t{/usr/share/doc/\$\{PF\}/html}.
 \end{compactitem}
 
-Stripping of symbols 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{ED} variable prepended, then:
+\featurelabel{dostrip} In EAPIs listed in table~\ref{tab:staging-area-commands} as supporting
+controllable stripping of symbols, the package manager may strip a subset of the files under the
+\t{ED} directory. For stripping of symbols, the initial values of the two lists are as follows:
 
 \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 stripped unless it has been excluded as described below.
-\item If the item does not exist, it is ignored.
+\item If the \t{RESTRICT} variable described in section~\ref{sec:restrict} enables a \t{strip}
+    token, the inclusion list is empty; otherwise it contains \t{/} (the root path).
+\item The exclusion list is empty.
 \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{ED} 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 stripped.
-\item If the item does not exist, it is ignored.
-\end{compactitem}
-
-The package manager shall take appropriate steps to ensure that its stripping mechanisms behave
-sensibly even if an item is listed in the inclusion list multiple times or if an item is a symlink.
-
-The following command may be used in \t{src_install} to alter these lists. It is an error to call
-this function from any other phase.
+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 for compression. Otherwise, add each argument to the respective inclusion list.
+    Only available in EAPIs listed in table~\ref{tab:staging-area-commands} as supporting
+    \t{docompress}.
+
 \item[dostrip] 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:dostrip} as supporting \t{dostrip}.
+    exclusion list for stripping of symbols. Otherwise, add each argument to the respective
+    inclusion list. Only available in EAPIs listed in table~\ref{tab:staging-area-commands} as
+    supporting \t{dostrip}.
 \end{description}
 
 \ChangeWhenAddingAnEAPI{7}
-\begin{centertable}{EAPIs supporting controllable stripping}
-    \label{tab:dostrip}
+\begin{centertable}{Commands controlling manipulation of files in the staging area in EAPIs}
+    \label{tab:staging-area-commands}
     \begin{tabular}{lll}
       \toprule
       \multicolumn{1}{c}{\textbf{EAPI}} &
-      \multicolumn{1}{c}{\textbf{Supports controllable stripping?}} &
-      \multicolumn{1}{c}{\textbf{Supports \t{dostrip}?}} \\
+      \multicolumn{1}{P{13.5em}}{\textbf{Supports controllable compression and \t{docompress}?}} &
+      \multicolumn{1}{P{10.5em}}{\textbf{Supports controllable stripping and \t{dostrip}?}} \\
       \midrule
-      0, 1, 2, 3, 4, 5, 6 & No  & No  \\
-      7                   & Yes & Yes \\
+      0, 1, 2, 3        & No  & No  \\
+      4, 5, 6           & Yes & No  \\
+      7                 & Yes & Yes \\
       \bottomrule
     \end{tabular}
 \end{centertable}