| Message ID | 20210512222803.508446-3-felipe.contreras@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | doc: asciidoc cleanups | expand |
On Wed, May 12 2021, Felipe Contreras wrote: > 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. Both this and your first patch could just be made to use the .DELETE_ON_ERROR flag instead, although that's a bigger change. I had this and a related series for that recently: https://lore.kernel.org/git/patch-4.6-2ff6359c273-20210329T161723Z-avarab@gmail.com/ I don't think anyone had an objection to using that, I didn't pursue it because I was trying to make (among other things) AIX development less annoying, but Junio didn't like the -o $@+ && mv $@+ $@ pattern for object files, so I gave up on pursuing it. But if you're trying to address this "maybe it errors" issue then .DELETE_ON_ERROR is a better solution. I think if we use that we should also undo your changes to use "-o file" and instead pipe to the file ourselves, otherwise we'll probably have cases where the program that fails and GNU make will race to delete the file (but I haven't tested that case).
Ævar Arnfjörð Bjarmason wrote: > > On Wed, May 12 2021, Felipe Contreras wrote: > > > 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. > > Both this and your first patch could just be made to use the > .DELETE_ON_ERROR flag instead, although that's a bigger change. > > I had this and a related series for that recently: > > https://lore.kernel.org/git/patch-4.6-2ff6359c273-20210329T161723Z-avarab@gmail.com/ It may be a bigger change on the general Makefile, but I don't think that's the case for the documentation Makefile. > I don't think anyone had an objection to using that, I didn't pursue it > because I was trying to make (among other things) AIX development less > annoying, but Junio didn't like the -o $@+ && mv $@+ $@ pattern for > object files, so I gave up on pursuing it. I really don't see what's the point of scattering all those rm mv all over the place. If the command is interrupted (ctrl+C), then make will remove the file anyway (regardless of .DELETE_ON_ERROR). It's only a problem if the command fails for some other reason, in which case the command itself should remove the file, or it's trapping the SIGINT signal incorrectly (as is the case with asciidoc). > But if you're trying to address this "maybe it errors" issue then > .DELETE_ON_ERROR is a better solution. Indeed, it seems so. Thanks. > I think if we use that we should also undo your changes to use "-o file" > and instead pipe to the file ourselves, otherwise we'll probably have > cases where the program that fails and GNU make will race to delete the > file (but I haven't tested that case). Yes, although I would prefer to investigate what happens in that case, and I bet no race happens (doing `rm -f` twice is not an issue). Cheers.
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > But if you're trying to address this "maybe it errors" issue then > .DELETE_ON_ERROR is a better solution. Yeah, I forgot about that, but I agree that .DELETE_ON_ERROR is a good thing to use, as we depend on GNU make anyway. Thanks for bringing it up.
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"
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