From 7682e76de5e0c8d12867fc95a92150c1318775b8 Mon Sep 17 00:00:00 2001
From: Thomas Haller <thaller@redhat.com>
Date: Tue, 2 Jun 2020 17:47:30 +0200
Subject: [PATCH] docs: fix dependency of "nm-settings*xml" to "common.ent"

"man/nm-settings%.xml" really should depend on "common.ent".
The reason is that XSL files like "man/nm-settings.xsl" include
"common.ent".
The previous code already tried to express that, but for some
reasons this dependency was not honored. Fix that.

However, that uncovers another problem with gtk-doc.make. If we do
that without the workaround for "docs/api/Makefile.am", then

  $ ./autogen.sh && make V=1 SHELL='sh -x' distcheck

breaks.

The reason is not clear to me. The new dependency leads to rebuild
"man/nm-settings-keyfile.xml". But that is worse, somehow the file
"$(top_srcdir)/man/nm-settings-keyfile.xml" ends up being read-only.
Afterwards, gtk-doc.make does

    setup-build.stamp:
        -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ;
        then \
          files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \
          if test "x$$files" != "x" ; then \
            for file in $$files ; do \
              destdir=`dirname $(abs_builddir)/$$file`; \
              test -d "$$destdir" || mkdir -p "$$destdir"; \
              test -f $(abs_srcdir)/$$file && \
                cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true;
                \
            done; \
          fi; \
        fi
        $(AM_V_at)touch setup-build.stamp

so that the files in build dir are also read-only. Then, make distcheck
goes ahead and builds the files once again, which fails.

You are welcome to understand why this workaround is necessary. Please
then create a better fix.
---
 Makefile.am          |  6 ++----
 docs/api/Makefile.am | 21 ++++++++++++++++++++-
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/Makefile.am b/Makefile.am
index 97b9708231..8406a5af62 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -4970,10 +4970,8 @@ man_nm_settings_xml = \
 
 if HAVE_INTROSPECTION
 
-man/nm-setting%.xml: man/common.ent
-
-man/nm-setting%.xml: man/nm-setting%.xsl libnm/nm-setting%-docs.xml
-	$(AM_V_GEN) $(XSLTPROC) --output $@ $(xsltproc_flags) $^
+man/nm-setting%.xml: man/nm-setting%.xsl libnm/nm-setting%-docs.xml man/common.ent
+	$(AM_V_GEN) $(XSLTPROC) --output $@ $(xsltproc_flags) $< $(word 2,$^)
 
 CLEANFILES += $(man_nm_settings_xml)
 
diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am
index 44933bc980..376cf613a0 100644
--- a/docs/api/Makefile.am
+++ b/docs/api/Makefile.am
@@ -8,7 +8,7 @@ GENERATED_FILES =
 if BUILD_DOCS
 
 settings-spec.xml: settings-spec.xsl $(top_builddir)/libnm/nm-settings-docs.xml
-	$(AM_V_GEN) xsltproc --output $@ $^
+	$(AM_V_GEN) (! test -f $@ || chmod u+w $@) && xsltproc --output $@ $^
 
 # Top-level SGML file includes (depends on) settings-spec.xml
 $(DOC_MAIN_SGML_FILE): settings-spec.xml
@@ -104,6 +104,25 @@ endif
 
 include $(top_srcdir)/gtk-doc.make
 
+# workaround setup-build.stamp from gtk-doc.make, which copies
+# the file as read-only. That breaks later build steps, as the
+# file can no longer be written. Instead, copy the file with `cp -f`
+# only.
+setup-build.stamp:
+	-$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
+	  files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \
+	  if test "x$$files" != "x" ; then \
+	    for file in $$files ; do \
+	      destdir=`dirname $(abs_builddir)/$$file`; \
+	      test -d "$$destdir" || mkdir -p "$$destdir"; \
+	      test -f $(abs_srcdir)/$$file && \
+	        ( cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file ; \
+	        chmod u+w $(abs_builddir)/$$file ) || true; \
+	    done; \
+	  fi; \
+	fi
+	$(AM_V_at)touch setup-build.stamp
+
 ####################################
 
 EXTRA_DIST += version.xml.in settings-spec.xsl meson.build $(GENERATED_FILES)