git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Felipe Contreras <felipe.contreras@gmail.com>
To: git@vger.kernel.org
Cc: "Jeff King" <peff@peff.net>,
	"Martin Ågren" <martin.agren@gmail.com>,
	"brian m . carlson" <sandals@crustytoothpaste.net>,
	"Junio C Hamano" <gitster@pobox.com>,
	"Felipe Contreras" <felipe.contreras@gmail.com>
Subject: [PATCH 2/8] doc: add an asciidoc helper
Date: Wed, 12 May 2021 17:27:57 -0500	[thread overview]
Message-ID: <20210512222803.508446-3-felipe.contreras@gmail.com> (raw)
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


  parent reply	other threads:[~2021-05-12 23:35 UTC|newest]

Thread overview: 19+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-12 22:27 [PATCH 0/8] doc: asciidoc cleanups Felipe Contreras
2021-05-12 22:27 ` [PATCH 1/8] doc: standardize asciidoc calls Felipe Contreras
2021-05-12 22:27 ` Felipe Contreras [this message]
2021-05-13 15:17   ` [PATCH 2/8] doc: add an asciidoc helper Ævar Arnfjörð Bjarmason
2021-05-13 19:33     ` Felipe Contreras
2021-05-13 21:43     ` Junio C Hamano
2021-05-12 22:27 ` [PATCH 3/8] doc: disable asciidoc-helper for asciidoctor Felipe Contreras
2021-05-12 22:27 ` [PATCH 4/8] doc: simplify the handling of interruptions Felipe Contreras
2021-05-13  5:19   ` Junio C Hamano
2021-05-13  6:10     ` Felipe Contreras
2021-05-12 22:28 ` [PATCH 5/8] doc: remove redundant rm Felipe Contreras
2021-05-13 15:22   ` Ævar Arnfjörð Bjarmason
2021-05-13 18:58     ` Felipe Contreras
2021-05-12 22:28 ` [PATCH 6/8] doc: refactor common dependencies Felipe Contreras
2021-05-12 22:28 ` [PATCH 7/8] doc: improve asciidoc dependencies Felipe Contreras
2021-05-13 17:43   ` Martin Ågren
2021-05-12 22:28 ` [PATCH 8/8] doc: join xml and man rules Felipe Contreras
2021-05-13 11:02   ` Martin Ågren
2021-05-13 11:15     ` Felipe Contreras

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210512222803.508446-3-felipe.contreras@gmail.com \
    --to=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=martin.agren@gmail.com \
    --cc=peff@peff.net \
    --cc=sandals@crustytoothpaste.net \
    --subject='Re: [PATCH 2/8] doc: add an asciidoc helper' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.version-control.git
	nntp://ie5yzdi7fg72h7s4sdcztq5evakq23rdt33mfyfcddc5u3ndnw24ogqd.onion/inbox.comp.version-control.git
	nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git