[gentoo-pms] [PATCH] doins, dodoc: Clarify how directories are created.

[Ulrich Müller]

With the -r option, it was unspecified what the mode of any created
directories is. Clarify that doins -r will create them as if dodir was
called (i.e., respect diropts), and that dodoc -r will create them as
if plain install -d was used.

For doins, this agrees with package manager implementations.

For dodoc, this agrees with historic Paludis behaviour. Portage
behaviour has changed in the past, when dodoc was changed from a
standalone helper to reusing parts of doins. Usage in the Gentoo
repository indicates that no ebuilds call diropts specifically for
installing of documentation. However, for several ebuilds dodoc -r is
affected by diropts called previously for another directory, which
looks like an unwanted side effect.

Signed-off-by: Ulrich Müller <ulm@g.o>
---
 pkg-mgr-commands.tex | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 9aacc70..00ae3a7 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -448,7 +448,8 @@ the current phase function has returned.
     directory \t{/usr/share/doc/\$\{PF\}/}. For EAPIs listed in table~\ref{tab:dodoc-table}
     as supporting \t{-r}, if the first argument is \t{-r}, any subsequent arguments that are
     directories are installed recursively to the appropriate location; in any other case, it is
-    an error for a directory to be specified. Failure behaviour is EAPI dependent as per
+    an error for a directory to be specified. Any directories that don't already exist are created
+    using \t{install -d} with no additional options. Failure behaviour is EAPI dependent as per
     section~\ref{sec:failure-behaviour}.
 
 \item[doenvd] Installs the given environment files into \t{/etc/env.d/}, by default with file mode
@@ -509,10 +510,10 @@ the current phase function has returned.
 \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
     the most recent \t{insopts} call. If the first argument is \t{-r}, then operates recursively,
-    descending into any directories given. For EAPIs listed in table~\ref{tab:doins-table},
-    \t{doins} must install symlinks as symlinks; for other EAPIs, behaviour is undefined if any
-    symlink is encountered. Failure behaviour is EAPI dependent as per
-    section~\ref{sec:failure-behaviour}.
+    descending into any directories given. Any directories are created as if \t{dodir} was called.
+    For EAPIs listed in table~\ref{tab:doins-table}, \t{doins} must install symlinks as symlinks;
+    for other EAPIs, behaviour is undefined if any symlink is encountered. Failure behaviour is
+    EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
 \item[dolib.a] For each argument, installs it into the appropriate library subdirectory under
     \t{DESTTREE}, as determined by algorithm~\ref{alg:ebuild-libdir}. Files are installed with file
-- 
2.23.0