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

[john at keeping.me.uk (John Keeping)]

Hi Todd,

On Sat, Jun 16, 2018 at 12:32:06PM -0400, Todd Zullinger wrote:
> John Keeping wrote:
> > 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.
> 
> It does, but only if the targets are 'doc-man doc-html'.
> For the default 'doc' target which includes 'doc-pdf', the
> issue is still present.
> 
> As a bonus, the output is much nicer, I think.
> 
> We could perhaps work around the 'doc-pdf' failure by adding a
> dep on '($DOC_MAN5)':
> 
> -- >8 --
> diff --git i/Makefile w/Makefile
> index 70f32a4..4879a5a 100644
> --- i/Makefile
> +++ w/Makefile
> @@ -143,7 +143,7 @@ $(DOC_HTML): %.html : %.txt
>         $(TXT_TO_HTML) -o $@+ $< && \
>         mv $@+ $@
>  
> -$(DOC_PDF): %.pdf : %.txt
> +$(DOC_PDF): %.pdf : $(DOC_MAN5) %.txt
>         a2x -f pdf cgitrc.5.txt
>  
>  clean: clean-doc
> -- >8 --
> 
> That's hackish, no doubt.
> 
> We might also want to drop 'doc-pdf' from the default 'doc'
> target.  The alternative is driving the asciidoc pipeline
> for the pdf generation too.  That looks a little more
> involved than doing it for html, but perhaps it's not as bad
> as I think.

I think we can definitely drop doc-pdf from the default output.

I'm half tempted to say we should just delete the PDF output completely
and see if anyone complains, unless you know of anyone using this?

Otherwise, the dependency on $(DOC_MAN5) seems reasonable to me,
probably accompanied with a comment explaining the clash in a2x's
intermediate files.


Regards,
John