[RFC PATCH] Makefile: work around parallel make issues in docs

[Todd Zullinger]

When make is run with multiple jobs, doc-man and doc-html fail.  The a2x
command tries to write %.5.xml for each invocation, overwriting each
other.

Work around this by copying %.5 to %.5+ in doc-man.  This is a rather
gross hack, but nothing better came to mind.  Using --asciidoc-opts to
pass the '--out-file' did not affect the temporary .xml file at issue.

Signed-off-by: Todd Zullinger <tmz at pobox.com>
---
I ran into this in the Fedora/EPEL package builds long ago and set -j1 for the
doc build at the time. I finally got around to looking a little deeper.

I'm not happy with this patch, but as I said above, nothing better came to
mind.  I'm hoping that submitting this will spur some discussion about a better
way to handle this.  Though maybe the best way to handle it will be "don't
build the docs in parallel, you're not saving any time for the single file that
is built." :)

That's effectively what I've done for ages, a separate 'make -j1 doc-man
doc-html' invocation.

Reproduction should be simple: make -j2 doc-man doc-html

Each a2x process tries to create cgitrc.5.xml in the process of generating the
man and html files, clobbering each other and causing xmllint to fail.

This is still broken when calling 'make -j2 doc' as I only added the rename
work-around to doc-man, so if doc-man, doc-html, and doc-pdf are all run, the
two without the work-around will cause the same issue.

I consider this more of a demonstration of the issue than a fix.  I hope that
by sending it, someone will respond with the obvious, elegant, and correct
solution.  Or maybe moments after I send it, that solution will come to me.
Things often work out that way. :)

Thanks,

Todd

 Makefile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 687069f..da36872 100644
--- a/Makefile
+++ b/Makefile
@@ -131,7 +131,9 @@ doc-html: $(DOC_HTML)
 doc-pdf: $(DOC_PDF)
 
 %.5 : %.5.txt
-	a2x -f manpage $<
+	cp -a $@.txt $@+.txt && \
+	a2x -f manpage $@+.txt && \
+	rm -f $@+.txt
 
 $(DOC_HTML): %.html : %.txt
 	a2x -f xhtml --stylesheet=cgit-doc.css --xsltproc-opts="--param generate.consistent.ids 1" $<