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

[John Keeping]

On Sat, Jun 16, 2018 at 01:38:31AM -0400, Todd Zullinger wrote:
> 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. :)

How about the patch below instead?  It's a bigger change to the output
format for HTML, but as a side effect it fixes the parallel build.

I considered removing a2x for the manpage output as well, but Asciidoc
can't generate that directly so we'd have to build the documentation
pipeline ourselves.  Git does that, but I don't think it's worth the
effort here because we don't need to customise the process.

-- >8 --
Subject: [PATCH] Makefile: drive asciidoc directly for HTML output

This is mostly taken from Git's doc/Makefile, although simplified for
our use.  The output now uses Asciidoc's default CSS which I think looks
a bit nicer than the Docbook formatting; as a result of this we no
longer need our custom .css file.

A side effect of this change is that temporary files generated from the
HTML output no longer conflict with the manpage output format (because
any temporary HTML output files use names derived from the output
filename which includes .html).
---
 Makefile     | 9 ++++++++-
 cgit-doc.css | 3 ---
 2 files changed, 8 insertions(+), 4 deletions(-)
 delete mode 100644 cgit-doc.css

diff --git a/Makefile b/Makefile
index 687069f..70f32a4 100644
--- a/Makefile
+++ b/Makefile
@@ -24,6 +24,12 @@ DOC_MAN5 = $(patsubst %.txt,%,$(MAN5_TXT))
 DOC_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
 DOC_PDF  = $(patsubst %.txt,%.pdf,$(MAN_TXT))
 
+ASCIIDOC = asciidoc
+ASCIIDOC_EXTRA =
+ASCIIDOC_HTML = xhtml11
+ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA)
+TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
+
 # Define NO_C99_FORMAT if your formatted IO functions (printf/scanf et.al.)
 # do not support the 'size specifiers' introduced by C99, namely ll, hh,
 # j, z, t. (representing long long int, char, intmax_t, size_t, ptrdiff_t).
@@ -134,7 +140,8 @@ doc-pdf: $(DOC_PDF)
 	a2x -f manpage $<
 
 $(DOC_HTML): %.html : %.txt
-	a2x -f xhtml --stylesheet=cgit-doc.css --xsltproc-opts="--param generate.consistent.ids 1" $<
+	$(TXT_TO_HTML) -o $@+ $< && \
+	mv $@+ $@
 
 $(DOC_PDF): %.pdf : %.txt
 	a2x -f pdf cgitrc.5.txt
diff --git a/cgit-doc.css b/cgit-doc.css
deleted file mode 100644
index 5a399b6..0000000
--- a/cgit-doc.css
+++ /dev/null
@@ -1,3 +0,0 @@
-div.variablelist dt {
-	margin-top: 1em;
-}
-- 
2.17.1