[gentoo-pms] [PATCH 19/21] EAPI 8: insopts and exeopts affect only doins and doexe

[Ulrich Müller]

Bug: https://bugs.gentoo.org/657580
Signed-off-by: Ulrich Müller <ulm@g.o>
---
 eapi-differences.tex |  8 ++++++
 pkg-mgr-commands.tex | 64 +++++++++++++++++++++++++++++++++++---------
 2 files changed, 60 insertions(+), 12 deletions(-)

diff --git a/eapi-differences.tex b/eapi-differences.tex
index 8cfc442..d263cbc 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -299,6 +299,12 @@ Output commands use stdout & \compactfeatureref{output-no-stdout} &
 \t{new*} support stdin & \compactfeatureref{newfoo-stdin} &
     No & Yes & Yes & Yes & Yes \\
 
+\t{insopts} affects misc.\ commands & \compactfeatureref{insopts} &
+    Yes & Yes & Yes & Yes & No \\
+
+\t{exeopts} affects \t{doinitd} & \compactfeatureref{exeopts} &
+    Yes & Yes & Yes & Yes & No \\
+
 Controllable compression & \compactfeatureref{docompress} &
     * & Yes & Yes & Yes & Yes \\
 
@@ -521,6 +527,8 @@ EAPI 8 is EAPI 7 with the following changes:
 \item \t{econf} adds \t{-{}-datarootdir}, \featureref{econf-options}.
 \item \t{econf} adds \t{-{}-disable-static}, \featureref{econf-options}.
 \item \t{dosym} can create relative paths, \featureref{dosym-relative}.
+\item \t{insopts} no longer affects \t{doconfd}, \t{doenvd} and \t{doheader}, \featureref{insopts}.
+\item \t{exeopts} no longer affects \t{doinitd}, \featureref{exeopts}.
 \end{compactitem}
 
 \ChangeWhenAddingAnEAPI{8}
diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index dd286a6..58254fa 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -460,8 +460,9 @@ the current phase function has returned.
     \t{joe:users}. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
 \item[doconfd] Installs the given config files into \t{/etc/conf.d/}, by default with file mode
-    \t{0644}, or with the \t{install} options set by the most recent \t{insopts} call.
-    Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
+    \t{0644}. For EAPIs listed in table~\ref{tab:insopts-commands} as respecting \t{insopts}
+    in \t{doconfd}, the \t{install} options set by the most recent \t{insopts} call override
+    the default. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
 \item[dodir] Creates the given directories, by default with file mode \t{0755}, or with the
     \t{install} options set by the most recent \t{diropts} call. Failure behaviour is EAPI
@@ -478,8 +479,9 @@ the current phase function has returned.
     section~\ref{sec:failure-behaviour}.
 
 \item[doenvd] Installs the given environment files into \t{/etc/env.d/}, by default with file mode
-    \t{0644}, or with the \t{install} options set by the most recent \t{insopts} call.
-    Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
+    \t{0644}. For EAPIs listed in table~\ref{tab:insopts-commands} as respecting \t{insopts}
+    in \t{doenvd}, the \t{install} options set by the most recent \t{insopts} call override
+    the default. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
 \item[doexe] Installs the given files into the directory specified by the most recent \t{exeinto}
     call. If \t{exeinto} has not yet been called, behaviour is undefined. Files are installed by
@@ -494,9 +496,10 @@ the current phase function has returned.
     section~\ref{sec:banned-commands}.
 
 \item[doheader] \featurelabel{doheader} Installs the given header files into \t{/usr/include/},
-    by default with file mode \t{0644}, or with the \t{install} options set by the most recent
-    \t{insopts} call. If the first argument is \t{-r}, then operates recursively, descending
-    into any directories given.
+    by default with file mode \t{0644}. For EAPIs listed in table~\ref{tab:insopts-commands}
+    as respecting \t{insopts} in \t{doheader}, the \t{install} options set by the most recent
+    \t{insopts} call override the default. If the first argument is \t{-r}, then operates
+    recursively, descending into any directories given.
     Only available in EAPIs listed in table~\ref{tab:doheader-table} as supporting \t{doheader}.
     Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
@@ -529,8 +532,9 @@ the current phase function has returned.
     \t{0644}. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
 \item[doinitd] Installs the given initscript files into \t{/etc/init.d}, by default with file mode
-    \t{0755}, or with the \t{install} options set by the most recent \t{exeopts} call.
-    Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
+    \t{0755}. For EAPIs listed in table~\ref{tab:insopts-commands} as respecting \t{insopts}
+    in \t{doinitd}, the \t{install} options set by the most recent \t{exeopts} call override
+    the default. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
 \item[doins] \featurelabel{doins} Takes one or more files as arguments and installs them into
     \t{INSDESTTREE}, by default with file mode \t{0644}, or with the \t{install} options set by
@@ -782,12 +786,16 @@ function has returned.
 
 \item[docinto] As \t{into}, for install subdirectory of \t{dodoc} et al.
 
-\item[insopts] Takes one or more arguments, and sets the options passed by \t{doins} et al.\
-    to the \t{install} command to them. Behaviour upon encountering empty arguments is undefined.
+\item[insopts] \featurelabel{insopts} Takes one or more arguments, and sets the options passed by
+    \t{doins} et al.\ to the \t{install} command to them. Behaviour upon encountering empty
+    arguments is undefined. Depending on EAPI, affects only those commands that are specified
+    by table~\ref{tab:insopts-commands} as respecting \t{insopts}.
 
 \item[diropts] As \t{insopts}, for \t{dodir} et al.
 
-\item[exeopts] As \t{insopts}, for \t{doexe} et al.
+\item[exeopts] \featurelabel{exeopts} As \t{insopts}, for \t{doexe} et al. Depending on EAPI,
+    affects only those commands that are specified by table~\ref{tab:exeopts-commands}
+    as respecting \t{exeopts}.
 
 \item[libopts] As \t{insopts}, for \t{dolib} et al.
     In EAPIs listed in table~\ref{tab:banned-commands-table}, this command is banned as
@@ -795,6 +803,38 @@ function has returned.
 
 \end{description}
 
+\ChangeWhenAddingAnEAPI{8}
+\begin{centertable}{Commands respecting \t{insopts} for EAPIs}
+    \label{tab:insopts-commands}
+    \begin{tabular}{lllll}
+      \toprule
+      \multicolumn{1}{c}{\textbf{EAPI}} &
+      \multicolumn{1}{c}{\textbf{\t{doins}?}} &
+      \multicolumn{1}{c}{\textbf{\t{doconfd}?}} &
+      \multicolumn{1}{c}{\textbf{\t{doenvd}?}} &
+      \multicolumn{1}{c}{\textbf{\t{doheader}?}} \\
+      \midrule
+      0, 1, 2, 3, 4, 5, 6, 7  & Yes & Yes & Yes & Yes \\
+      8                       & Yes & No  & No  & No  \\
+      \bottomrule
+    \end{tabular}
+\end{centertable}
+
+\ChangeWhenAddingAnEAPI{8}
+\begin{centertable}{Commands respecting \t{exeopts} for EAPIs}
+    \label{tab:exeopts-commands}
+    \begin{tabular}{lll}
+      \toprule
+      \multicolumn{1}{c}{\textbf{EAPI}} &
+      \multicolumn{1}{c}{\textbf{\t{doexe}?}} &
+      \multicolumn{1}{c}{\textbf{\t{doinitd}?}} \\
+      \midrule
+      0, 1, 2, 3, 4, 5, 6, 7  & Yes & Yes \\
+      8                       & Yes & No  \\
+      \bottomrule
+    \end{tabular}
+\end{centertable}
+
 \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
-- 
2.31.1