From 33b4fe4adfa4c22fe822d843aa2a17943903f534 Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <mjo@gentoo.org>
Date: Wed, 24 Apr 2019 20:39:30 -0400
Subject: [PATCH 1/1] 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@gmail.com>
Signed-off-by: Michael Orlitzky <mjo@gentoo.org>
---
 function-reference/install-functions/text.xml | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/function-reference/install-functions/text.xml b/function-reference/install-functions/text.xml
index 2b0cbf2..3bd74a2 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,16 @@ 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. Portage, for example, accomplishes this by installing a
+      hidden file prefixed with <c>.keep_</c> to the directory in
+      question.
     </ti>
   </tr>
   <tr>
-- 
2.23.0