git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 0/8] doc: asciidoc cleanups
@ 2021-05-12 22:27 Felipe Contreras
  2021-05-12 22:27 ` [PATCH 1/8] doc: standardize asciidoc calls Felipe Contreras
                   ` (7 more replies)
  0 siblings, 8 replies; 19+ messages in thread
From: Felipe Contreras @ 2021-05-12 22:27 UTC (permalink / raw)
  To: git
  Cc: Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano,
	Felipe Contreras

This patch series is an attempt to cleanup a bit the Makefile regarding asciidoc stuff.

It does not enable asciidoctor direct manpage creation, that's in a separate patch.

Felipe Contreras (8):
  doc: standardize asciidoc calls
  doc: add an asciidoc helper
  doc: disable asciidoc-helper for asciidoctor
  doc: simplify the handling of interruptions
  doc: remove redundant rm
  doc: refactor common dependencies
  doc: improve asciidoc dependencies
  doc: join xml and man rules

 Documentation/Makefile           | 45 +++++++++++++-------------------
 Documentation/asciidoc-helper.sh | 17 ++++++++++++
 2 files changed, 35 insertions(+), 27 deletions(-)
 create mode 100755 Documentation/asciidoc-helper.sh

-- 
2.31.1


^ permalink raw reply	[flat|nested] 19+ messages in thread

* [PATCH 1/8] doc: standardize asciidoc calls
  2021-05-12 22:27 [PATCH 0/8] doc: asciidoc cleanups Felipe Contreras
@ 2021-05-12 22:27 ` Felipe Contreras
  2021-05-12 22:27 ` [PATCH 2/8] doc: add an asciidoc helper Felipe Contreras
                   ` (6 subsequent siblings)
  7 siblings, 0 replies; 19+ messages in thread
From: Felipe Contreras @ 2021-05-12 22:27 UTC (permalink / raw)
  To: git
  Cc: Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano,
	Felipe Contreras

By always specifying the output file it will be possible to refactor all
the calls in a future helper.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 2aae4c9cbb..3d282a2797 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -388,7 +388,7 @@ technical/api-index.txt: technical/api-index-skel.txt \
 technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
 $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
 	asciidoc.conf GIT-ASCIIDOCFLAGS
-	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
+	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
 
 SubmittingPatches.txt: SubmittingPatches
 	$(QUIET_GEN) cp $< $@
@@ -442,7 +442,7 @@ howto-index.txt: howto-index.sh $(HOWTO_TXT)
 	mv $@+ $@
 
 $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
-	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
+	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
 
 WEBDOC_DEST = /pub/software/scm/git/docs
 
@@ -450,7 +450,7 @@ 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) - >$@+ && \
+	$(TXT_TO_HTML) -o $@+ - && \
 	mv $@+ $@
 
 install-webdoc : html
-- 
2.31.1


^ permalink raw reply	[flat|nested] 19+ messages in thread

* [PATCH 2/8] doc: add an asciidoc helper
  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
  2021-05-13 15:17   ` Ævar Arnfjörð Bjarmason
  2021-05-12 22:27 ` [PATCH 3/8] doc: disable asciidoc-helper for asciidoctor Felipe Contreras
                   ` (5 subsequent siblings)
  7 siblings, 1 reply; 19+ messages in thread
From: Felipe Contreras @ 2021-05-12 22:27 UTC (permalink / raw)
  To: git
  Cc: Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano,
	Felipe Contreras

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


^ permalink raw reply	[flat|nested] 19+ messages in thread

* [PATCH 3/8] doc: disable asciidoc-helper for asciidoctor
  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 ` [PATCH 2/8] doc: add an asciidoc helper Felipe Contreras
@ 2021-05-12 22:27 ` Felipe Contreras
  2021-05-12 22:27 ` [PATCH 4/8] doc: simplify the handling of interruptions Felipe Contreras
                   ` (4 subsequent siblings)
  7 siblings, 0 replies; 19+ messages in thread
From: Felipe Contreras @ 2021-05-12 22:27 UTC (permalink / raw)
  To: git
  Cc: Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano,
	Felipe Contreras

asciidoctor handles interruptions correctly, no need for the helper.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 5c2a3df24a..956cfabadd 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -194,6 +194,7 @@ ASCIIDOC_DOCBOOK = docbook5
 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
 ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+ASCIIDOC_BASE = $(ASCIIDOC_COMMON)
 DBLATEX_COMMON =
 XMLTO_EXTRA += --skip-validation
 XMLTO_EXTRA += -x manpage.xsl
-- 
2.31.1


^ permalink raw reply	[flat|nested] 19+ messages in thread

* [PATCH 4/8] doc: simplify the handling of interruptions
  2021-05-12 22:27 [PATCH 0/8] doc: asciidoc cleanups Felipe Contreras
                   ` (2 preceding siblings ...)
  2021-05-12 22:27 ` [PATCH 3/8] doc: disable asciidoc-helper for asciidoctor Felipe Contreras
@ 2021-05-12 22:27 ` Felipe Contreras
  2021-05-13  5:19   ` Junio C Hamano
  2021-05-12 22:28 ` [PATCH 5/8] doc: remove redundant rm Felipe Contreras
                   ` (3 subsequent siblings)
  7 siblings, 1 reply; 19+ messages in thread
From: Felipe Contreras @ 2021-05-12 22:27 UTC (permalink / raw)
  To: git
  Cc: Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano,
	Felipe Contreras

There's no need to have an intermediary file.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoc-helper.sh | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/asciidoc-helper.sh b/Documentation/asciidoc-helper.sh
index ae16cf9288..8dbe4fc372 100755
--- a/Documentation/asciidoc-helper.sh
+++ b/Documentation/asciidoc-helper.sh
@@ -13,6 +13,5 @@ while [ $# -gt 1 ]; do
 	shift
 done
 
-rm -f "$out+" "$out" &&
-"${args[@]}" -o "$out+" "$1" &&
-mv "$out+" "$out"
+"${args[@]}" -o "$out" "$1" ||
+{ rm -f "$out"; false; }
-- 
2.31.1


^ permalink raw reply	[flat|nested] 19+ messages in thread

* [PATCH 5/8] doc: remove redundant rm
  2021-05-12 22:27 [PATCH 0/8] doc: asciidoc cleanups Felipe Contreras
                   ` (3 preceding siblings ...)
  2021-05-12 22:27 ` [PATCH 4/8] doc: simplify the handling of interruptions Felipe Contreras
@ 2021-05-12 22:28 ` Felipe Contreras
  2021-05-13 15:22   ` Ævar Arnfjörð Bjarmason
  2021-05-12 22:28 ` [PATCH 6/8] doc: refactor common dependencies Felipe Contreras
                   ` (2 subsequent siblings)
  7 siblings, 1 reply; 19+ messages in thread
From: Felipe Contreras @ 2021-05-12 22:28 UTC (permalink / raw)
  To: git
  Cc: Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano,
	Felipe Contreras

It's not clear what it was supposed to achieve.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 956cfabadd..d02bd848e8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -366,8 +366,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
 	$(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
 
 %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
-	$(QUIET_XMLTO)$(RM) $@ && \
-	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+	$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 
 %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
-- 
2.31.1


^ permalink raw reply	[flat|nested] 19+ messages in thread

* [PATCH 6/8] doc: refactor common dependencies
  2021-05-12 22:27 [PATCH 0/8] doc: asciidoc cleanups Felipe Contreras
                   ` (4 preceding siblings ...)
  2021-05-12 22:28 ` [PATCH 5/8] doc: remove redundant rm Felipe Contreras
@ 2021-05-12 22:28 ` Felipe Contreras
  2021-05-12 22:28 ` [PATCH 7/8] doc: improve asciidoc dependencies Felipe Contreras
  2021-05-12 22:28 ` [PATCH 8/8] doc: join xml and man rules Felipe Contreras
  7 siblings, 0 replies; 19+ messages in thread
From: Felipe Contreras @ 2021-05-12 22:28 UTC (permalink / raw)
  To: git
  Cc: Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano,
	Felipe Contreras

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index d02bd848e8..f846bb91ee 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -140,6 +140,7 @@ ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
 		-amanversion=$(GIT_VERSION) \
 		-amanmanual='Git Manual' -amansource='Git'
 ASCIIDOC_BASE = '$(SHELL_PATH_SQ)' ./asciidoc-helper.sh $(ASCIIDOC_COMMON)
+ASCIIDOC_DEPS = asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 TXT_TO_HTML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_HTML)
 TXT_TO_XML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_DOCBOOK)
 MANPAGE_XSL = manpage-normal.xsl
@@ -356,10 +357,10 @@ clean:
 	$(RM) manpage-base-url.xsl
 	$(RM) GIT-ASCIIDOCFLAGS
 
-$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
+$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<
 
-$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
+$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
 
 manpage-base-url.xsl: manpage-base-url.xsl.in
@@ -368,7 +369,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
 %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
 	$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 
-%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
+%.xml : %.txt $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
 
 user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
-- 
2.31.1


^ permalink raw reply	[flat|nested] 19+ messages in thread

* [PATCH 7/8] doc: improve asciidoc dependencies
  2021-05-12 22:27 [PATCH 0/8] doc: asciidoc cleanups Felipe Contreras
                   ` (5 preceding siblings ...)
  2021-05-12 22:28 ` [PATCH 6/8] doc: refactor common dependencies Felipe Contreras
@ 2021-05-12 22:28 ` 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
  7 siblings, 1 reply; 19+ messages in thread
From: Felipe Contreras @ 2021-05-12 22:28 UTC (permalink / raw)
  To: git
  Cc: Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano,
	Felipe Contreras

asciidoc needs asciidoc.conf, asciidoctor asciidoctor-extensions.rb.

Neither needs the other.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index f846bb91ee..ba0c947d0d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -140,7 +140,7 @@ ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
 		-amanversion=$(GIT_VERSION) \
 		-amanmanual='Git Manual' -amansource='Git'
 ASCIIDOC_BASE = '$(SHELL_PATH_SQ)' ./asciidoc-helper.sh $(ASCIIDOC_COMMON)
-ASCIIDOC_DEPS = asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
+ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
 TXT_TO_HTML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_HTML)
 TXT_TO_XML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_DOCBOOK)
 MANPAGE_XSL = manpage-normal.xsl
@@ -196,6 +196,7 @@ ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
 ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
 ASCIIDOC_BASE = $(ASCIIDOC_COMMON)
+ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 DBLATEX_COMMON =
 XMLTO_EXTRA += --skip-validation
 XMLTO_EXTRA += -x manpage.xsl
-- 
2.31.1


^ permalink raw reply	[flat|nested] 19+ messages in thread

* [PATCH 8/8] doc: join xml and man rules
  2021-05-12 22:27 [PATCH 0/8] doc: asciidoc cleanups Felipe Contreras
                   ` (6 preceding siblings ...)
  2021-05-12 22:28 ` [PATCH 7/8] doc: improve asciidoc dependencies Felipe Contreras
@ 2021-05-12 22:28 ` Felipe Contreras
  2021-05-13 11:02   ` Martin Ågren
  7 siblings, 1 reply; 19+ messages in thread
From: Felipe Contreras @ 2021-05-12 22:28 UTC (permalink / raw)
  To: git
  Cc: Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano,
	Felipe Contreras

Will be useful later with asciidoctor that can do both at the same time.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index ba0c947d0d..d5ea05295d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -367,11 +367,9 @@ $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
 manpage-base-url.xsl: manpage-base-url.xsl.in
 	$(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
 
-%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
-	$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
-
-%.xml : %.txt $(ASCIIDOC_DEPS)
-	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
+%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS) manpage-base-url.xsl $(wildcard manpage*.xsl)
+	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $*.xml $< && \
+	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $*.xml
 
 user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<
-- 
2.31.1


^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH 4/8] doc: simplify the handling of interruptions
  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
  0 siblings, 1 reply; 19+ messages in thread
From: Junio C Hamano @ 2021-05-13  5:19 UTC (permalink / raw)
  To: Felipe Contreras; +Cc: git, Jeff King, Martin Ågren, brian m . carlson

Felipe Contreras <felipe.contreras@gmail.com> writes:

> +"${args[@]}" -o "$out" "$1" ||
> +{ rm -f "$out"; false; }

It would be so nice if this worked, but here is what I saw in a
quick-and-dirty experiment:

    $ f () { echo foo >"$1" && sleep 20 && echo bar >>"$1"; }
    $ f hoi ;# wait sufficiently long
    $ cat hoi
    foo
    bar
    $ f hoi ;# wait a bit and hit ^C
    ^C
    $ cat hoi
    foo
    $ rm hoi
    $ f hoi || rm hoi ;# wait a bit and hit ^C
    ^C
    $ cat hoi
    foo

So, I suspect it unfortunately may not work well.

We need to get 2/8 redone without bash-ism, but it would not affect
the correctness of this step, I would think, whether this is done in
bash or implemented in a plain vanilla POSIX shell.

Thanks.

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH 4/8] doc: simplify the handling of interruptions
  2021-05-13  5:19   ` Junio C Hamano
@ 2021-05-13  6:10     ` Felipe Contreras
  0 siblings, 0 replies; 19+ messages in thread
From: Felipe Contreras @ 2021-05-13  6:10 UTC (permalink / raw)
  To: Junio C Hamano, Felipe Contreras
  Cc: git, Jeff King, Martin Ågren, brian m . carlson

Junio C Hamano wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > +"${args[@]}" -o "$out" "$1" ||
> > +{ rm -f "$out"; false; }
> 
> It would be so nice if this worked, but here is what I saw in a
> quick-and-dirty experiment:
> 
>     $ f hoi || rm hoi ;# wait a bit and hit ^C
> 
> So, I suspect it unfortunately may not work well.

That's because the interrupt signal is not caught.

This works:

  sh -c 'echo foo >"$1" && trap "exit 1" INT && sleep 20' test hoi || rm hoi

And so does this:

  #!/bin/sh

  ruby - hoi <<EOF || rm hoi
  File.write(ARGV[0], 'foo')
  begin
    sleep(10)
  rescue Exception
    exit(1)
  end
  EOF

Both asciidoc and asciidoctor trap the signal.

> We need to get 2/8 redone without bash-ism,

Yes, if we agree this approach is indeed desirable I can do that.

Cheers.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH 8/8] doc: join xml and man rules
  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
  0 siblings, 1 reply; 19+ messages in thread
From: Martin Ågren @ 2021-05-13 11:02 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: Git Mailing List, Jeff King, brian m . carlson, Junio C Hamano

On Thu, 13 May 2021 at 00:28, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
>
> Will be useful later with asciidoctor that can do both at the same time.

> -%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
> -       $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
> -
> -%.xml : %.txt $(ASCIIDOC_DEPS)
> -       $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
> +%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS) manpage-base-url.xsl $(wildcard manpage*.xsl)
> +       $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $*.xml $< && \
> +       $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $*.xml

It does mean that if manpage-base-url.xsl changes, we'll regenerate all
the xml files. Before this change, we would just rerun the xmlto step.

Also, this will break `make info`. It will either find xml files that
"happen" to be there, e.g., because you just built the manpages (or
maybe you did so several weeks ago), or it won't find them and error
out.

(If you're wondering if anyone is actually using `make info`, there's
some discussion at [1]. I don't think anyone would be too sad to see it
go. Once `make info` is the only reason we need to generate the xml
files, I think it's a given we should try to drop that stuff.)

I think we should keep the separate xml targets as long as "asciidoctor
without xmlto" isn't the only way we support building the manpages. If
the only benefit here is "later", I think we should do this patch later.
I could also imagine that the xml target will just go away once all the
"old" ways of building the manpages are gone and `make info` is gone,
i.e., when we simply don't need any of these generated xml files.

[1] https://lore.kernel.org/git/20200402004533.GA6369@camp.crustytoothpaste.net/

Martin

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH 8/8] doc: join xml and man rules
  2021-05-13 11:02   ` Martin Ågren
@ 2021-05-13 11:15     ` Felipe Contreras
  0 siblings, 0 replies; 19+ messages in thread
From: Felipe Contreras @ 2021-05-13 11:15 UTC (permalink / raw)
  To: Martin Ågren, Felipe Contreras
  Cc: Git Mailing List, Jeff King, brian m . carlson, Junio C Hamano

Martin Ågren wrote:
> On Thu, 13 May 2021 at 00:28, Felipe Contreras
> <felipe.contreras@gmail.com> wrote:
> >
> > Will be useful later with asciidoctor that can do both at the same time.
> 
> > -%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
> > -       $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
> > -
> > -%.xml : %.txt $(ASCIIDOC_DEPS)
> > -       $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
> > +%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS) manpage-base-url.xsl $(wildcard manpage*.xsl)
> > +       $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $*.xml $< && \
> > +       $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $*.xml
> 
> It does mean that if manpage-base-url.xsl changes, we'll regenerate all
> the xml files. Before this change, we would just rerun the xmlto step.

True.

> Also, this will break `make info`.

Ahh, I didn't see that dependency on MAN_XML.

> (If you're wondering if anyone is actually using `make info`, there's
> some discussion at [1]. I don't think anyone would be too sad to see it
> go. Once `make info` is the only reason we need to generate the xml
> files, I think it's a given we should try to drop that stuff.)

Perhaps, but not in this patch series.

> I think we should keep the separate xml targets as long as "asciidoctor
> without xmlto" isn't the only way we support building the manpages. If
> the only benefit here is "later", I think we should do this patch later.
> I could also imagine that the xml target will just go away once all the
> "old" ways of building the manpages are gone and `make info` is gone,
> i.e., when we simply don't need any of these generated xml files.

Agreed. I will drop this in the next version.

Cheers.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH 2/8] doc: add an asciidoc helper
  2021-05-12 22:27 ` [PATCH 2/8] doc: add an asciidoc helper Felipe Contreras
@ 2021-05-13 15:17   ` Ævar Arnfjörð Bjarmason
  2021-05-13 19:33     ` Felipe Contreras
  2021-05-13 21:43     ` Junio C Hamano
  0 siblings, 2 replies; 19+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-05-13 15:17 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: git, Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano


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).

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH 5/8] doc: remove redundant rm
  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
  0 siblings, 1 reply; 19+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-05-13 15:22 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: git, Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano


On Wed, May 12 2021, Felipe Contreras wrote:

> It's not clear what it was supposed to achieve.

It seems this used to make sense around 7b8a74f39cb (Documentation:
Replace @@GIT_VERSION@@ in documentation, 2007-03-25), but at some point
(I didn't look further) we refactored that and kept the "rm".

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH 7/8] doc: improve asciidoc dependencies
  2021-05-12 22:28 ` [PATCH 7/8] doc: improve asciidoc dependencies Felipe Contreras
@ 2021-05-13 17:43   ` Martin Ågren
  0 siblings, 0 replies; 19+ messages in thread
From: Martin Ågren @ 2021-05-13 17:43 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: Git Mailing List, Jeff King, brian m . carlson, Junio C Hamano

On Thu, 13 May 2021 at 00:28, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
>
> asciidoc needs asciidoc.conf, asciidoctor asciidoctor-extensions.rb.
>
> Neither needs the other.

> -ASCIIDOC_DEPS = asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
> +ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS

> +ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS

Thanks. I was a bit lazy in a15ef383e7 ("Documentation/Makefile: add
missing dependency on asciidoctor-extensions", 2019-02-27).

We end up with some duplication. We could pull GIT-ASCIIDOCFLAGS into
some ASCIIDOC_DEPS_COMMON. But with just one such common dependency, it
seems unnecessary and overly complicated. We can pull out the common
dependencies when we actually gain something from it.

Martin

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH 5/8] doc: remove redundant rm
  2021-05-13 15:22   ` Ævar Arnfjörð Bjarmason
@ 2021-05-13 18:58     ` Felipe Contreras
  0 siblings, 0 replies; 19+ messages in thread
From: Felipe Contreras @ 2021-05-13 18:58 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, Felipe Contreras
  Cc: git, Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano

Ævar Arnfjörð Bjarmason wrote:
> On Wed, May 12 2021, Felipe Contreras wrote:
> 
> > It's not clear what it was supposed to achieve.
> 
> It seems this used to make sense around 7b8a74f39cb (Documentation:
> Replace @@GIT_VERSION@@ in documentation, 2007-03-25), but at some point
> (I didn't look further) we refactored that and kept the "rm".

Actually it came later: 50cff52f1a (When generating manpages, delete
outdated targets first., 2007-08-02).

I'm not sure we should complicate the Makefile just because somebody
made the mistake of doing 'sudo make doc' a long time. Especially since
other rules don't have this.

  sudo make doc
  touch GIT-ASCIIDOCFLAGS
  make doc

Fails here already.

  asciidoc: FAILED: api-merge.txt: line 2: unexpected error:
  asciidoc: ------------------------------------------------------------
  Traceback (most recent call last):
    File "/usr/bin/asciidoc", line 6247, in asciidoc
      writer.open(outfile, reader.bom)
    File "/usr/bin/asciidoc", line 4633, in open
      self.f = open(fname, 'w+', encoding='utf-8', newline="")
  PermissionError: [Errno 13] Permission denied: '.../Documentation/technical/api-merge.html'

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH 2/8] doc: add an asciidoc helper
  2021-05-13 15:17   ` Ævar Arnfjörð Bjarmason
@ 2021-05-13 19:33     ` Felipe Contreras
  2021-05-13 21:43     ` Junio C Hamano
  1 sibling, 0 replies; 19+ messages in thread
From: Felipe Contreras @ 2021-05-13 19:33 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason, Felipe Contreras
  Cc: git, Jeff King, Martin Ågren, brian m . carlson, Junio C Hamano

Æ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.

-- 
Felipe Contreras

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH 2/8] doc: add an asciidoc helper
  2021-05-13 15:17   ` Ævar Arnfjörð Bjarmason
  2021-05-13 19:33     ` Felipe Contreras
@ 2021-05-13 21:43     ` Junio C Hamano
  1 sibling, 0 replies; 19+ messages in thread
From: Junio C Hamano @ 2021-05-13 21:43 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason
  Cc: Felipe Contreras, git, Jeff King, Martin Ågren, brian m . carlson

Æ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.

^ permalink raw reply	[flat|nested] 19+ messages in thread

end of thread, other threads:[~2021-05-13 21:43 UTC | newest]

Thread overview: 19+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
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 ` [PATCH 2/8] doc: add an asciidoc helper Felipe Contreras
2021-05-13 15:17   ` Æ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

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).