[gentoo-commits] proj/devmanual:master commit in: function-reference/install-functions/

["Michael Orlitzky" <mjo@gentoo.org>]

commit:     401ad3ebcf88837618fa559c5cea7666a4b30435
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Thu Apr 25 00:39:30 2019 +0000
Commit:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
CommitDate: Fri Nov 22 13:31:16 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=401ad3eb

function-reference/install-functions: clarify dodir/keepdir usage.

The existing "Install Functions Reference" documentation on dodir()
and keepdir() is a bit wishy-washy. What developers really want to
know is, when do I use one, and when do I use the other?

This commit updates the descriptions of those two functions to provide
that information. If the directory will be non-empty, dodir() is fine.
Otherwise, keepdir() should be used. Some rationale for the existence
of the keepdir() function is also provided for the skeptical developer
who might otherwise find it superfluous.

This change mirrors an update to the ebuild(5) man page in portage.

Closes: https://bugs.gentoo.org/451472
Reported-by: Matthew Schultz <mattsch <AT> gmail.com>
Signed-off-by: Michael Orlitzky <mjo <AT> gentoo.org>

 function-reference/install-functions/text.xml | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/function-reference/install-functions/text.xml b/function-reference/install-functions/text.xml
index 2b0cbf2..06bc241 100644
--- a/function-reference/install-functions/text.xml
+++ b/function-reference/install-functions/text.xml
@@ -117,7 +117,9 @@ the first is the source name, the second the name to use when installing.
       <c>dodir</c>
     </ti>
     <ti>
-      Install a directory
+      Install a directory that will be non-empty when the package is
+      merged. For directories that will be empty, please use
+      <c>keepdir</c> instead.
     </ti>
   </tr>
   <tr>
@@ -288,9 +290,15 @@ the first is the source name, the second the name to use when installing.
       <c>keepdir</c>
     </ti>
     <ti>
-      Create a directory which will be preserved by the package
-      manager (This is typically accomplished by inserting an empty
-      <c>.keep_${CATEGORY}_${PN}-${SLOT%/*}</c> file in the directory)
+      Install a directory that will be empty when the package is
+      merged. This is like <c>dodir</c>, but for empty directories
+      instead. <uri
+      link="https://projects.gentoo.org/pms/7/pms.html#x1-14200013.2.2">The
+      handling of empty directories is undefined by the package
+      manager specification</uri>, and the <c>keepdir</c> function
+      exists to ensure that the (otherwise empty) directory is
+      tracked. This is accomplished by installing a hidden file
+      prefixed with <c>.keep</c> to the directory in question.
     </ti>
   </tr>
   <tr>