[PATCH 2/8] doc: add an asciidoc helper
- From
Felipe Contreras <felipe.contreras@gmail.com>
- Date
- May 12, 2021, 22:27 UTC
- Message-ID
- <20210512222803.508446-3-felipe.contreras@gmail.com>
- In-Reply-To
- <20210512222803.508446-1-felipe.contreras@gmail.com>
The hacks to deal with interrupted builds is scattered throughout the Makefile, but not everywhere (it's not done for techical/ and articles).
It originally comes from f9dae0d3e6 (Documentation/Makefile: fix interrupted builds of user-manual.xml, 2010-04-21), however, that description is not correct.
asciidoc does actually remove the output file in case of an exception, but there was a bug that handled keyboard interruptions through a different path, and thus in that particular case the file is not removed[1].
We shouldn't overly complicate the Makefile due to bugs in asciidoc.
In order to keep the Makefile clean this commit creates an asciidoc wrapper that does the job of tracking the intermediary output.
Once asciidoc is fixed this helper can be safely removed and there would be minimal changes elsewhere.
It's written for bash, but could easily be modified for something more portable.
[1] https://github.com/asciidoc-py/asciidoc-py/pull/195
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/Makefile | 27 +++++++++------------------ Documentation/asciidoc-helper.sh | 18 ++++++++++++++++++ 2 files changed, 27 insertions(+), 18 deletions(-) create mode 100755 Documentation/asciidoc-helper.sh
diff --git a/Documentation/Makefile b/Documentation/Makefile index 3d282a2797..5c2a3df24a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -139,8 +139,9 @@ ASCIIDOC_CONF = -f asciidoc.conf ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ -amanversion=$(GIT_VERSION) \ -amanmanual='Git Manual' -amansource='Git' -TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) -TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) +ASCIIDOC_BASE = '$(SHELL_PATH_SQ)' ./asciidoc-helper.sh $(ASCIIDOC_COMMON) +TXT_TO_HTML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_HTML) +TXT_TO_XML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_DOCBOOK) MANPAGE_XSL = manpage-normal.xsl XMLTO = xmlto XMLTO_EXTRA = @@ -355,14 +356,10 @@ clean: $(RM) GIT-ASCIIDOCFLAGS $(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(TXT_TO_HTML) -d manpage -o $@+ $< && \ - mv $@+ $@ + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $< $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(TXT_TO_HTML) -o $@+ $< && \ - mv $@+ $@ + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $< manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ @@ -372,14 +369,10 @@ manpage-base-url.xsl: manpage-base-url.xsl.in $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(TXT_TO_XML) -d manpage -o $@+ $< && \ - mv $@+ $@ + $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $< user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(TXT_TO_XML) -d book -o $@+ $< && \ - mv $@+ $@ + $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $< technical/api-index.txt: technical/api-index-skel.txt \ technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) @@ -448,10 +441,8 @@ WEBDOC_DEST = /pub/software/scm/git/docs howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - sed -e '1,/^$$/d' $< | \ - $(TXT_TO_HTML) -o $@+ - && \ - mv $@+ $@ + $(QUIET_ASCIIDOC)sed -e '1,/^$$/d' $< | \ + $(TXT_TO_HTML) -o $@ - install-webdoc : html '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST) diff --git a/Documentation/asciidoc-helper.sh b/Documentation/asciidoc-helper.sh new file mode 100755 index 0000000000..ae16cf9288 --- /dev/null +++ b/Documentation/asciidoc-helper.sh @@ -0,0 +1,18 @@ +#!/bin/bash + +# This helper is a workaround for an interruption bug in asciidoc: +# https://github.com/asciidoc-py/asciidoc-py/pull/195 + +args=() + +while [ $# -gt 1 ]; do + case $1 in + -o) shift; out="$1" ;; + *) args+=("$1") + esac + shift +done + +rm -f "$out+" "$out" && +"${args[@]}" -o "$out+" "$1" && +mv "$out+" "$out"
-- 2.31.1