Re: [PATCH] Documentation: fix man page dependency on asciidoc.conf

Jonathan Nieder [off-list ref] writes:

John Keeping wrote:

quoted

When building manual pages, the source text is transformed to XML with
AsciiDoc before the man pages are generated from the XML with xmlto.

Fix the dependency in the Makefile so that the XML files are rebuilt
when asciidoc.conf changes and not just the manual pages from unchanged
XML.

Good catch, thanks.

Would something like the following make sense, to make it more obvious
how the dependency needs to be adjusted if we change the $(ASCIIDOC)
command line for some reason?

I think such a more explicit approach is easier to understand, than
a separate "By the way, I do not define any rule to build these
targets using asciidoc.conf, but I know they depend on it" rule.

Care to do a real patch?

Thanks.

When building manual pages, the source text is transformed to XML with
AsciiDoc before the man pages are generated from the XML with xmlto.

Fix the dependencies in the Makefile so that the XML files are rebuilt
when asciidoc.conf changes and not just the manual pages from
unchanged XML, and move the dependencies from a recipeless rule to the
rules with commands that use asciidoc.conf to make the dependencies
easier to understand and maintain.

Reported-by: John Keeping <redacted>
Signed-off-by: Jonathan Nieder <redacted>
---
Junio C Hamano wrote:

Care to do a real patch?

Here you go.

 Documentation/Makefile | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e53d333e..971977b8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -178,8 +178,6 @@ all: html man
 
 html: $(DOC_HTML)
 
-$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7): asciidoc.conf
-
 man: man1 man5 man7
 man1: $(DOC_MAN1)
 man5: $(DOC_MAN5)

@@ -257,7 +255,7 @@ clean:
 	$(RM) $(cmds_txt) *.made
 	$(RM) manpage-base-url.xsl
 
-$(MAN_HTML): %.html : %.txt
+$(MAN_HTML): %.html : %.txt asciidoc.conf
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
 		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \

@@ -270,7 +268,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
 	$(QUIET_XMLTO)$(RM) $@ && \
 	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 
-%.xml : %.txt
+%.xml : %.txt asciidoc.conf
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
 		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \

@@ -286,7 +284,7 @@ technical/api-index.txt: technical/api-index-skel.txt \
 	$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
 
 technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
-$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt
+$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf
 	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
 		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
 

-- 
1.8.1

On Sun, Jan 06, 2013 at 04:01:53AM -0800, Jonathan Nieder wrote:

When building manual pages, the source text is transformed to XML with
AsciiDoc before the man pages are generated from the XML with xmlto.

Fix the dependencies in the Makefile so that the XML files are rebuilt
when asciidoc.conf changes and not just the manual pages from
unchanged XML, and move the dependencies from a recipeless rule to the
rules with commands that use asciidoc.conf to make the dependencies
easier to understand and maintain.

Reported-by: John Keeping <redacted>
Signed-off-by: Jonathan Nieder <redacted>
---

This fixes the problem I wanted to fix (as well as being clearer for the
future), so FWIW:

Tested-by: John Keeping <redacted>

Thanks.