threads / patch / 32533

patchDocumentation: fix man page dependency on asciidoc.conf

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

## tl;dr

6 messages between Jan 5, 2013 and Jan 6, 2013. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

John Keeping· Jan 5, 2013, 16:00 UTC · lore

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.

Signed-off-by: John Keeping <john@keeping.me.uk>
---
 Documentation/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to Documentation/Makefile +1 −1
diff --git a/Documentation/Makefile b/Documentation/Makefile
index e53d333..71d2b4a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -178,7 +178,7 @@ all: html man
 
 html: $(DOC_HTML)
 
-$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7): asciidoc.conf
+$(DOC_HTML) $(MAN_XML): asciidoc.conf
 
 man: man1 man5 man7
 man1: $(DOC_MAN1)

-- 
1.8.0.2
Jonathan Nieder· Jan 5, 2013, 23:28 UTC · re: John Keeping · lore

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

John Keeping wrote:
Show 6 quoted lines
> 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?

Show changes to diff +4 −6
diff --git i/Documentation/Makefile w/Documentation/Makefile
index e53d333e..971977b8 100644
--- i/Documentation/Makefile
+++ w/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
 
diff --git i/t/test-terminal.perl w/t/test-terminal.perl
index 10172aee..1fb373f2 100755
--- i/t/test-terminal.perl
+++ w/t/test-terminal.perl
@@ -31,7 +31,7 @@ sub finish_child {
 	} elsif ($? & 127) {
 		my $code = $? & 127;
 		warn "died of signal $code";
-		return $code - 128;
+		return $code + 128;
 	} else {
 		return $? >> 8;
 	}
Junio C Hamano· Jan 6, 2013, 06:51 UTC · re: Jonathan Nieder · lore

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

Jonathan Nieder <jrnieder@gmail.com> writes:
Show 14 quoted lines
> John Keeping 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 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.
Show 53 quoted lines
> diff --git i/Documentation/Makefile w/Documentation/Makefile
> index e53d333e..971977b8 100644
> --- i/Documentation/Makefile
> +++ w/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
>  
> diff --git i/t/test-terminal.perl w/t/test-terminal.perl
> index 10172aee..1fb373f2 100755
> --- i/t/test-terminal.perl
> +++ w/t/test-terminal.perl
> @@ -31,7 +31,7 @@ sub finish_child {
>  	} elsif ($? & 127) {
>  		my $code = $? & 127;
>  		warn "died of signal $code";
> -		return $code - 128;
> +		return $code + 128;
>  	} else {
>  		return $? >> 8;
>  	}
Jonathan Nieder· Jan 6, 2013, 12:01 UTC · re: Junio C Hamano · lore

[PATCH] docs: manpage XML depends on asciidoc.conf

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 <john@keeping.me.uk>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Junio C Hamano wrote:
> Care to do a real patch?
Here you go.
 Documentation/Makefile | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)
Show changes to Documentation/Makefile +3 −5
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
John Keeping· Jan 6, 2013, 12:33 UTC · re: Jonathan Nieder · lore

Re: [PATCH] docs: manpage XML depends on asciidoc.conf

On Sun, Jan 06, 2013 at 04:01:53AM -0800, Jonathan Nieder wrote:
Show 12 quoted lines
> 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 <john@keeping.me.uk>
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> ---

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

Tested-by: John Keeping <john@keeping.me.uk>

← back to recent threads