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.  Instead, use "find ..." to find all
directories and files in the generated _built/html tree and use the
Automake-provided installer macros to create the target directories
and install the target files with desireable permissions.

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 <jsquyres@cisco.com>

Author: jsquyres

docs/Makefile.am

@@ -889,11 +889,32 @@ 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 a
+# "find ..." to copy the entire generated tree to the target
+# directory.
+#
+# Note: we do not use "cp -r ..." because if the source directory is
+# write-protected (e.g., during "make distcheck"), then the cp -r will
+# also write-protect the target directory.  Instead, use the
+# Automake-provided install macros to set desirable permissions on the
+# target directories and files.
+#
+# Since this might be a VPATH build, first check to see if _build/html
+# exists in the source tree.  If not, do the find+install from the
+# build tree.
 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 {} \;
+	if test -d $(srcdir)/_build/html; then \
+	    topdir=$(srcdir)/_build; \
+	else \
+	    topdir=_build; \
+	fi; \
+	cd $$topdir; \
+	find html -type d -exec $(mkinstalldirs) $(DESTDIR)$(docdir)/{} \; ; \
+	find html -type f -exec $(INSTALL_DATA) {} $(DESTDIR)$(docdir)/{} \;
 
 uninstall-hook:
 	rm -rf $(DESTDIR)$(docdir)