[gentoo-pms] [PATCH v2 1/6] nonfatal: Reword argument handling to be cleaner

[gentoo-pms] [PATCH v2 1/6] nonfatal: Reword argument handling to be cleaner

[Michał Górny]

Reword the description of 'nonfatal' to explicitly indicate that it
takes 1+ args and executes them as a command.  The original 'remainder
of its argument' wording sounds weird, given that there is no earlier
mention of argument processing (-> remainder from what?).  This also
clarifies that calling nonfatal with no argument is not valid.
---
 pkg-mgr-commands.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 506673b..cb704f0 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -17,7 +17,7 @@ table~\ref{tab:commands-die-table}.
 
 The following commands affect this behaviour:
 \begin{description}
-\item[nonfatal] \featurelabel{nonfatal} Executes the remainder of its arguments as a command,
+\item[nonfatal] \featurelabel{nonfatal} Takes one or more arguments and executes them as a command,
     preserving the exit status. If this results in a command being called that would normally abort
     the build process due to a failure, instead a non-zero exit status shall be returned. Only in
     EAPIs listed in table~\ref{tab:commands-die-table} as supporting \t{nonfatal}.
-- 
2.17.0

[gentoo-pms] [PATCH v2 2/6] best_version: Explicitly specify the output format

[Michał Górny]

Explain the format used by best_version command explicitly.  Currently,
the function only lists what gets printed but not in what form or how it
is separated.
---
 pkg-mgr-commands.tex | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index cb704f0..ffa7566 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -104,9 +104,9 @@ are given, \t{-r} is assumed.
 \begin{description}
 \item[has_version] Takes exactly one package dependency specification as an argument. Returns
     true if a package matching the specification is installed, and false otherwise.
-\item[best_version] Takes exactly one package dependency specification as an argument. If a
-    matching package is installed, prints the category, package name and version of the highest
-    matching version; otherwise, prints an empty string. The exit code is unspecified.
+\item[best_version] Takes exactly one package dependency specification as an argument. If a matching
+    package is installed, prints \t{category/package-version} of the highest matching version;
+    otherwise, prints an empty string. The exit code is unspecified.
 \end{description}
 
 \ChangeWhenAddingAnEAPI{7}
-- 
2.17.0

[gentoo-pms] [PATCH v2 3/6] Account for 'Build commands' being run in src_test

[Michał Górny]

---
 pkg-mgr-commands.tex | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index ffa7566..42fdced 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -283,9 +283,9 @@ Ebuilds must not run any of these commands once the current phase function has r
 \end{centertable}
 
 \subsection{Build commands}
-These commands are used during the \t{src_configure}, \t{src_compile}, and \t{src_install}
-phases to run the package's build commands. Ebuilds must not run any of these commands once the
-current phase function has returned.
+These commands are used during the \t{src_configure}, \t{src_compile}, \t{src_test},
+and \t{src_install} phases to run the package's build commands. Ebuilds must not run any of these
+commands once the current phase function has returned.
 
 \begin{description}
 \item[econf] Calls the program's \t{./configure} script. This is designed to work with GNU
-- 
2.17.0

[gentoo-pms] [PATCH v2 4/6] *into, *opts: Reword to use 'as ...' wording from 'do*'

[Michał Górny]

Reword the *into and *opts commands to use the 'As ..., for ...' wording
used in do*/new* commands.  This makes the descriptions a bit shorter,
and makes it possible to extend the information given in original
commands without having to update the wording of derived commands.
---
 pkg-mgr-commands.tex | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 42fdced..058be89 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -721,22 +721,19 @@ has returned.
     if it does not already exist. Failure behaviour is EAPI dependent
     as per section~\ref{sec:failure-behaviour}.
 
-\item[insinto] Sets the value of \t{INSDESTTREE} for future invocations of the above utilities. May
-    create the directory, as specified for \t{into}.
+\item[insinto] As \t{into}, for \t{INSDESTTREE}.
 
-\item[exeinto] Sets the install path for \t{doexe} and \t{newexe}. May create the directory, as specified
-    for \t{into}.
+\item[exeinto] As \t{into}, for install path of \t{doexe} and \t{newexe}.
 
-\item[docinto] Sets the install subdirectory for \t{dodoc} et al. May create the directory, as specified
-    for \t{into}.
+\item[docinto] As \t{into}, for install subdirectory of \t{dodoc} et al.
 
 \item[insopts] Sets the options passed by \t{doins} et al.\ to the \t{install} command.
 
-\item[diropts] Sets the options passed by \t{dodir} et al.\ to the \t{install} command.
+\item[diropts] As \t{insopts}, for \t{dodir} et al.
 
-\item[exeopts] Sets the options passed by \t{doexe} et al.\ to the \t{install} command.
+\item[exeopts] As \t{insopts}, for \t{doexe} et al.
 
-\item[libopts] Sets the options passed by \t{dolib} et al.\ to the \t{install} command.
+\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
     per section~\ref{sec:banned-commands}.
 
-- 
2.17.0

[gentoo-pms] [PATCH v2 5/6] *into, *opts: Clarify the number of arguments

[Michał Górny]

Clarify the number of arguments taken by *into and *opts.  The former
always takes a single argument, so clarify that calling it without
arguments is invalid.  The latter may take 0+ arguments (with 0
resetting the list), so clarify that the correct way is to pass multiple
arguments rather than a single quoted argument.
---
 pkg-mgr-commands.tex | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 058be89..6397a4b 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -714,12 +714,11 @@ has returned.
 
 \begin{description}
 
-\item[into] Sets the value of \t{DESTTREE} for future invocations
-    of the above utilities. Creates the directory under \t{\$\{ED\}}
-    in offset-prefix aware EAPIs or under \t{\$\{D\}} in offset-prefix
-    agnostic EAPIs, using \t{install -d} with no additional options,
-    if it does not already exist. Failure behaviour is EAPI dependent
-    as per section~\ref{sec:failure-behaviour}.
+\item[into] Takes exactly one argument, and sets the value of \t{DESTTREE} for future invocations of
+    the above utilities to it.  Creates the directory under \t{\$\{ED\}} in offset-prefix aware
+    EAPIs or under \t{\$\{D\}} in offset-prefix agnostic EAPIs, using \t{install -d} with no
+    additional options, if it does not already exist. Failure behaviour is EAPI dependent as per
+    section~\ref{sec:failure-behaviour}.
 
 \item[insinto] As \t{into}, for \t{INSDESTTREE}.
 
@@ -727,7 +726,9 @@ has returned.
 
 \item[docinto] As \t{into}, for install subdirectory of \t{dodoc} et al.
 
-\item[insopts] Sets the options passed by \t{doins} et al.\ to the \t{install} command.
+\item[insopts] Takes zero or more arguments, and sets the options passed by \t{doins} et al.
+    to the \t{install} command to them. When called with no arguments, resets the option list
+    to empty.
 
 \item[diropts] As \t{insopts}, for \t{dodir} et al.
 
-- 
2.17.0

[gentoo-pms] [PATCH v2 6/6] *into, *opts: Remove redundant offset-prefix sentence from heading

[Michał Górny]

Remove the offset-prefix reference from heading to 'Commands affecting
install destinations'.  The offset-prefix situation is explained
in 'into' already, and it applies only to the *into commands.
---
 pkg-mgr-commands.tex | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 6397a4b..908f3f4 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -706,8 +706,7 @@ the current phase function has returned.
 \end{centertable}
 
 \subsection{Commands affecting install destinations}
-The following commands are used to set the various destination trees, all relative to \t{\$\{ED\}} in
-offset-prefix aware EAPIs and relative to \t{\$\{D\}} in offset-prefix agnostic EAPIs, used by the
+The following commands are used to set the various destination trees and options used by the
 above installation commands. They must be shell functions or aliases, due to the need to set variables
 read by the above commands. Ebuilds must not run any of these commands once the current phase function
 has returned.
-- 
2.17.0

Re: [gentoo-pms] [PATCH v2 5/6] *into, *opts: Clarify the number of arguments

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 522 bytes --]

>>>>> On Tue, 1 May 2018, Michał Górny wrote:
 
> -\item[insopts] Sets the options passed by \t{doins} et al.\ to the \t{install} command.
> +\item[insopts] Takes zero or more arguments, and sets the options passed by \t{doins} et al.

Don't remove the control space after "et al.", as the dot doesn't mark
a sentence end.

> +    to the \t{install} command to them. When called with no arguments, resets the option list
> +    to empty.

Whole patch series pushed, with one other whitespace change.

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]