docs: do not set HTML install tree to 0755 perms

Follow on to 8ffe33f: do not set the dirs in the installed HTML
files tree to have 0755 permissions because Automake doesn't do that
when it creates directories.

Additionally, add a comment explaining why the install-data-hook rule
exists, and why we are doing what we are doing in it.

Signed-off-by: Jeff Squyres <[email protected]>

Author: jsquyres

docs/Makefile.am

@@ -1,4 +1,4 @@
-#
+>#
 # Copyright (c) 2022 Cisco Systems, Inc.  All rights reserved.
 #
 # $COPYRIGHT$
@@ -889,10 +889,23 @@ man1_MANS += \
 man3_MANS += $(OSHMEM_MAN3_BUILT)
 endif
 
+# We do not know the names of all the generated HTML files: we only
+# know that the generated tree will of files be in _build/html/.
+# Unfortunately, Automake's installation process only handles
+# individual files -- not entire trees of files.  Hence, we use "cp -r
+# ..." to copy the entire generated tree to the target directory.
+#
+# Ensure to set the permissions of each file in that target tree to
+# 0644, mimicing what Automake's installation process does for
+# individual files.
+#
+# Note, however, that we specifically do *not* set directory
+# permissions because Automake simply uses MKDIR_P to make directories
+# and solely relies on the user's umask for the resulting permissions
+# on that directory.
 install-data-hook:
 	$(MKDIR_P) $(DESTDIR)$(docdir)
 	cp -r $(srcdir)/_build/html $(DESTDIR)$(docdir)
-	find $(DESTDIR)$(docdir) -type d -exec chmod 0755 {} \;
 	find $(DESTDIR)$(docdir) -type f -exec chmod 0644 {} \;
 
 uninstall-hook: