[gentoo-pms] Re: [PATCH] Installation commands must be called with at least one parameter.

[Ulrich Mueller]

>>>>> On Tue, 20 Aug 2013, Ulrich Mueller wrote:

> The wording of PMS is somewhat unclear here. However, doins and
> friends are implemented in all package managers with a check for
> at least one parameter. The patch included below clarifies this.
> See also <https://bugs.gentoo.org/show_bug.cgi?id=481664#c15>.

Updated version. Differences to previous patch:
- The introductory paragraph now says "filename parameter" instead
  of "parameter" to account for things like the -r option.
- doins takes "one or more" files as arguments, not "any number"
  of files.

Ulrich


From ec8b2e97b3fbc56d838e0e2982ad2b070f237fd7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ulrich=20M=C3=BCller?= <ulm@g.o>
Date: Tue, 20 Aug 2013 14:40:41 +0200
Subject: [PATCH] Installation commands must be called with at least one parameter.

Also adjust the wording for doinfo, doman, and domo, in order to
clarify that multiple file name parameters are allowed.
---
 pkg-mgr-commands.tex | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index bafa748..acf71ac 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -249,8 +249,9 @@ install} target cannot be used or does not install all needed files. Except wher
 all filenames created or modified are relative to the staging directory including the offset-prefix
 \t{ED} in offset-prefix aware EAPIs, or just the staging directory \t{D} in offset-prefix agnostic
 EAPIs. Existing destination files are overwritten. These commands must all be external programs and
-not bash functions or aliases---that is, they must be callable from \t{xargs}. Ebuilds must not run
-any of these commands once the current phase function has returned.
+not bash functions or aliases---that is, they must be callable from \t{xargs}. Calling any of these
+commands without a filename parameter is an error. Ebuilds must not run any of these commands once
+the current phase function has returned.
 
 \begin{description}
 \item[dobin] Installs the given files into \t{DESTTREE/bin}, where
@@ -320,14 +321,14 @@ can be extended or reduced (see below). The options that can be passed to \t{doh
     It is undefined whether a failure shall occur if \t{-r} is not specified and a directory is
     encountered. Ebuilds must not rely upon any particular behaviour.
 
-\item[doinfo] Installs a GNU Info file into the \t{/usr/share/info} area with file mode \t{0644}.
-    Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
+\item[doinfo] Installs the given GNU Info files into the \t{/usr/share/info} area with file mode
+    \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}. This can be overridden by setting \t{EXEOPTIONS} with the \t{exeopts} function.
     Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
-\item[doins] \featurelabel{doins} Takes any number of files as arguments and installs them into
+\item[doins] \featurelabel{doins} Takes one or more files as arguments and installs them into
     \t{INSDESTTREE}, by default with file mode \t{0644}. This can be overridden by setting
     \t{INSOPTIONS} with the \t{insopts} function. If the first argument is \t{-r}, then operates
     recursively, descending into any directories given. For EAPIs listed in
@@ -367,9 +368,9 @@ can be extended or reduced (see below). The options that can be passed to \t{doh
 \end{algorithmic}
 \end{algorithm}
 
-\item[doman] Installs a man page into the appropriate subdirectory of \t{/usr/share/man} depending
-    upon its apparent section suffix (e.\,g.\ \t{foo.1} goes to \t{/usr/share/man/man1/foo.1}) with
-    file mode \t{0644}.
+\item[doman] Installs the given man pages into the appropriate subdirectory of \t{/usr/share/man}
+    depending upon its apparent section suffix (e.\,g.\ \t{foo.1} goes to
+    \t{/usr/share/man/man1/foo.1}) with file mode \t{0644}.
 
     \featurelabel{doman-langs} In EAPIs listed in table~\ref{tab:doman-table} as supporting
     language detection by filename, a man page with name of the form \t{foo.}\i{lang}\t{.1} shall
@@ -383,10 +384,10 @@ can be extended or reduced (see below). The options that can be passed to \t{doh
     the empty string. In EAPIs specified by table~\ref{tab:doman-table}, the \t{-i18n} option takes
     precedence over the language code in the filename.
 
-\item[domo] Installs a \t{.mo} file with file mode \t{0644} into the appropriate subdirectory of
-    \t{DESTTREE\slash share\slash locale}, generated by taking the basename of the file, removing
-    the \t{.*} suffix, and appending \t{/LC\_MESSAGES}. The name of the installed files is the
-    package name with \t{.mo} appended. Failure behaviour is EAPI dependent as per
+\item[domo] Installs the given \t{.mo} files with file mode \t{0644} into the appropriate
+    subdirectory of \t{DESTTREE\slash share\slash locale}, generated by taking the basename of the
+    file, removing the \t{.*} suffix, and appending \t{/LC\_MESSAGES}. The name of the installed
+    files is the package name with \t{.mo} appended. Failure behaviour is EAPI dependent as per
     section~\ref{sec:failure-behaviour}.
 
 \item[dosbin] As \t{dobin}, but installs to \t{DESTTREE/sbin}.
-- 
1.8.3.2