{"thread":{"id":"55676","subject":"[PATCH 0/8] doc: asciidoc cleanups","startedAt":"2021-05-12T23:21:27Z","lastAt":"2021-05-13T21:43:26Z","messageCount":19,"participants":["Felipe Contreras","Junio C Hamano","Martin Ågren","Ævar Arnfjörð Bjarmason"],"isPatch":true,"patchVersion":1,"patchTotal":8},"messages":[{"id":"424380","messageId":"20210512222803.508446-1-felipe.contreras@gmail.com","threadId":"55676","inReplyTo":null,"subject":"[PATCH 0/8] doc: asciidoc cleanups","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T22:27:55Z","receivedAt":"2021-05-12T23:21:27Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This patch series is an attempt to cleanup a bit the Makefile regarding asciidoc stuff.\n\nIt does not enable asciidoctor direct manpage creation, that's in a separate patch.\n\nFelipe Contreras (8):\n doc: standardize asciidoc calls\n doc: add an asciidoc helper\n doc: disable asciidoc-helper for asciidoctor\n doc: simplify the handling of interruptions\n doc: remove redundant rm\n doc: refactor common dependencies\n doc: improve asciidoc dependencies\n doc: join xml and man rules\n\n Documentation/Makefile | 45 +++++++++++++-------------------\n Documentation/asciidoc-helper.sh | 17 ++++++++++++\n 2 files changed, 35 insertions(+), 27 deletions(-)\n create mode 100755 Documentation/asciidoc-helper.sh\n\n-- \n2.31.1\n\n"},{"id":"424381","messageId":"20210512222803.508446-4-felipe.contreras@gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-1-felipe.contreras@gmail.com","subject":"[PATCH 3/8] doc: disable asciidoc-helper for asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T22:27:58Z","receivedAt":"2021-05-12T23:22:01Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"asciidoctor handles interruptions correctly, no need for the helper.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 5c2a3df24a..956cfabadd 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -194,6 +194,7 @@ ASCIIDOC_DOCBOOK = docbook5\n ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n+ASCIIDOC_BASE = $(ASCIIDOC_COMMON)\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\n XMLTO_EXTRA += -x manpage.xsl\n-- \n2.31.1\n\n"},{"id":"424382","messageId":"20210512222803.508446-3-felipe.contreras@gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-1-felipe.contreras@gmail.com","subject":"[PATCH 2/8] doc: add an asciidoc helper","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T22:27:57Z","receivedAt":"2021-05-12T23:22:10Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"The hacks to deal with interrupted builds is scattered throughout the\nMakefile, but not everywhere (it's not done for techical/ and articles).\n\nIt originally comes from f9dae0d3e6 (Documentation/Makefile: fix\ninterrupted builds of user-manual.xml, 2010-04-21), however, that\ndescription is not correct.\n\nasciidoc does actually remove the output file in case of an exception,\nbut there was a bug that handled keyboard interruptions through a\ndifferent path, and thus in that particular case the file is not\nremoved[1].\n\nWe shouldn't overly complicate the Makefile due to bugs in asciidoc.\n\nIn order to keep the Makefile clean this commit creates an asciidoc\nwrapper that does the job of tracking the intermediary output.\n\nOnce asciidoc is fixed this helper can be safely removed and there would\nbe minimal changes elsewhere.\n\nIt's written for bash, but could easily be modified for something more\nportable.\n\n[1] https://github.com/asciidoc-py/asciidoc-py/pull/195\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 27 +++++++++------------------\n Documentation/asciidoc-helper.sh | 18 ++++++++++++++++++\n 2 files changed, 27 insertions(+), 18 deletions(-)\n create mode 100755 Documentation/asciidoc-helper.sh\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3d282a2797..5c2a3df24a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -139,8 +139,9 @@ ASCIIDOC_CONF = -f asciidoc.conf\n ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n \t\t-amanversion=$(GIT_VERSION) \\\n \t\t-amanmanual='Git Manual' -amansource='Git'\n-TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)\n-TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)\n+ASCIIDOC_BASE = '$(SHELL_PATH_SQ)' ./asciidoc-helper.sh $(ASCIIDOC_COMMON)\n+TXT_TO_HTML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_HTML)\n+TXT_TO_XML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_DOCBOOK)\n MANPAGE_XSL = manpage-normal.xsl\n XMLTO = xmlto\n XMLTO_EXTRA =\n@@ -355,14 +356,10 @@ clean:\n \t$(RM) GIT-ASCIIDOCFLAGS\n \n $(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(TXT_TO_HTML) -d manpage -o $@+ $< && \\\n-\tmv $@+ $@\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<\n \n $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(TXT_TO_HTML) -o $@+ $< && \\\n-\tmv $@+ $@\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n \n manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_GEN)sed \"s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|\" $< > $@\n@@ -372,14 +369,10 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n \n %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n-\tmv $@+ $@\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\n \n user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(TXT_TO_XML) -d book -o $@+ $< && \\\n-\tmv $@+ $@\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<\n \n technical/api-index.txt: technical/api-index-skel.txt \\\n \ttechnical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n@@ -448,10 +441,8 @@ WEBDOC_DEST = /pub/software/scm/git/docs\n \n howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\tsed -e '1,/^$$/d' $< | \\\n-\t$(TXT_TO_HTML) -o $@+ - && \\\n-\tmv $@+ $@\n+\t$(QUIET_ASCIIDOC)sed -e '1,/^$$/d' $< | \\\n+\t$(TXT_TO_HTML) -o $@ -\n \n install-webdoc : html\n \t'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST)\ndiff --git a/Documentation/asciidoc-helper.sh b/Documentation/asciidoc-helper.sh\nnew file mode 100755\nindex 0000000000..ae16cf9288\n--- /dev/null\n+++ b/Documentation/asciidoc-helper.sh\n@@ -0,0 +1,18 @@\n+#!/bin/bash\n+\n+# This helper is a workaround for an interruption bug in asciidoc:\n+# https://github.com/asciidoc-py/asciidoc-py/pull/195\n+\n+args=()\n+\n+while [ $# -gt 1 ]; do\n+\tcase $1 in\n+\t-o) shift; out=\"$1\" ;;\n+\t*) args+=(\"$1\")\n+\tesac\n+\tshift\n+done\n+\n+rm -f \"$out+\" \"$out\" &&\n+\"${args[@]}\" -o \"$out+\" \"$1\" &&\n+mv \"$out+\" \"$out\"\n-- \n2.31.1\n\n"},{"id":"424383","messageId":"20210512222803.508446-2-felipe.contreras@gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-1-felipe.contreras@gmail.com","subject":"[PATCH 1/8] doc: standardize asciidoc calls","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T22:27:56Z","receivedAt":"2021-05-12T23:22:46Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"By always specifying the output file it will be possible to refactor all\nthe calls in a future helper.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 2aae4c9cbb..3d282a2797 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -388,7 +388,7 @@ technical/api-index.txt: technical/api-index-skel.txt \\\n technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \\\n \tasciidoc.conf GIT-ASCIIDOCFLAGS\n-\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n \n SubmittingPatches.txt: SubmittingPatches\n \t$(QUIET_GEN) cp $< $@\n@@ -442,7 +442,7 @@ howto-index.txt: howto-index.sh $(HOWTO_TXT)\n \tmv $@+ $@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n-\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n \n WEBDOC_DEST = /pub/software/scm/git/docs\n \n@@ -450,7 +450,7 @@ howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \tsed -e '1,/^$$/d' $< | \\\n-\t$(TXT_TO_HTML) - >$@+ && \\\n+\t$(TXT_TO_HTML) -o $@+ - && \\\n \tmv $@+ $@\n \n install-webdoc : html\n-- \n2.31.1\n\n"},{"id":"424384","messageId":"20210512222803.508446-5-felipe.contreras@gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-1-felipe.contreras@gmail.com","subject":"[PATCH 4/8] doc: simplify the handling of interruptions","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T22:27:59Z","receivedAt":"2021-05-12T23:27:53Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"There's no need to have an intermediary file.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoc-helper.sh | 5 ++---\n 1 file changed, 2 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/asciidoc-helper.sh b/Documentation/asciidoc-helper.sh\nindex ae16cf9288..8dbe4fc372 100755\n--- a/Documentation/asciidoc-helper.sh\n+++ b/Documentation/asciidoc-helper.sh\n@@ -13,6 +13,5 @@ while [ $# -gt 1 ]; do\n \tshift\n done\n \n-rm -f \"$out+\" \"$out\" &&\n-\"${args[@]}\" -o \"$out+\" \"$1\" &&\n-mv \"$out+\" \"$out\"\n+\"${args[@]}\" -o \"$out\" \"$1\" ||\n+{ rm -f \"$out\"; false; }\n-- \n2.31.1\n\n"},{"id":"424385","messageId":"20210512222803.508446-6-felipe.contreras@gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-1-felipe.contreras@gmail.com","subject":"[PATCH 5/8] doc: remove redundant rm","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T22:28:00Z","receivedAt":"2021-05-12T23:27:55Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"It's not clear what it was supposed to achieve.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 3 +--\n 1 file changed, 1 insertion(+), 2 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 956cfabadd..d02bd848e8 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -366,8 +366,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_GEN)sed \"s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|\" $< > $@\n \n %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n-\t$(QUIET_XMLTO)$(RM) $@ && \\\n-\t$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n+\t$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n \n %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\n-- \n2.31.1\n\n"},{"id":"424386","messageId":"20210512222803.508446-9-felipe.contreras@gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-1-felipe.contreras@gmail.com","subject":"[PATCH 8/8] doc: join xml and man rules","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T22:28:03Z","receivedAt":"2021-05-12T23:27:55Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Will be useful later with asciidoctor that can do both at the same time.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 8 +++-----\n 1 file changed, 3 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex ba0c947d0d..d5ea05295d 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -367,11 +367,9 @@ $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_GEN)sed \"s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|\" $< > $@\n \n-%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n-\t$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n-\n-%.xml : %.txt $(ASCIIDOC_DEPS)\n-\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\n+%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS) manpage-base-url.xsl $(wildcard manpage*.xsl)\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $*.xml $< && \\\n+\t$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $*.xml\n \n user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<\n-- \n2.31.1\n\n"},{"id":"424387","messageId":"20210512222803.508446-8-felipe.contreras@gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-1-felipe.contreras@gmail.com","subject":"[PATCH 7/8] doc: improve asciidoc dependencies","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T22:28:02Z","receivedAt":"2021-05-12T23:27:57Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"asciidoc needs asciidoc.conf, asciidoctor asciidoctor-extensions.rb.\n\nNeither needs the other.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f846bb91ee..ba0c947d0d 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -140,7 +140,7 @@ ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n \t\t-amanversion=$(GIT_VERSION) \\\n \t\t-amanmanual='Git Manual' -amansource='Git'\n ASCIIDOC_BASE = '$(SHELL_PATH_SQ)' ./asciidoc-helper.sh $(ASCIIDOC_COMMON)\n-ASCIIDOC_DEPS = asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n+ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS\n TXT_TO_HTML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_HTML)\n TXT_TO_XML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_DOCBOOK)\n MANPAGE_XSL = manpage-normal.xsl\n@@ -196,6 +196,7 @@ ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n ASCIIDOC_BASE = $(ASCIIDOC_COMMON)\n+ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\n XMLTO_EXTRA += -x manpage.xsl\n-- \n2.31.1\n\n"},{"id":"424388","messageId":"20210512222803.508446-7-felipe.contreras@gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-1-felipe.contreras@gmail.com","subject":"[PATCH 6/8] doc: refactor common dependencies","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T22:28:01Z","receivedAt":"2021-05-12T23:27:57Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras \n---\n Documentation/Makefile | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex d02bd848e8..f846bb91ee 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -140,6 +140,7 @@ ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n \t\t-amanversion=$(GIT_VERSION) \\\n \t\t-amanmanual='Git Manual' -amansource='Git'\n ASCIIDOC_BASE = '$(SHELL_PATH_SQ)' ./asciidoc-helper.sh $(ASCIIDOC_COMMON)\n+ASCIIDOC_DEPS = asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n TXT_TO_HTML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_HTML)\n TXT_TO_XML = $(ASCIIDOC_BASE) -b $(ASCIIDOC_DOCBOOK)\n MANPAGE_XSL = manpage-normal.xsl\n@@ -356,10 +357,10 @@ clean:\n \t$(RM) manpage-base-url.xsl\n \t$(RM) GIT-ASCIIDOCFLAGS\n \n-$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n+$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<\n \n-$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n+$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n \n manpage-base-url.xsl: manpage-base-url.xsl.in\n@@ -368,7 +369,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n \t$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n \n-%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n+%.xml : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\n \n user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n-- \n2.31.1\n\n"},{"id":"424419","messageId":"xmqqmtszb47p.fsf@gitster.g","threadId":"55676","inReplyTo":"20210512222803.508446-5-felipe.contreras@gmail.com","subject":"Re: [PATCH 4/8] doc: simplify the handling of interruptions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-13T05:19:38Z","receivedAt":"2021-05-13T05:20:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> +\"${args[@]}\" -o \"$out\" \"$1\" ||\n> +{ rm -f \"$out\"; false; }\n\nIt would be so nice if this worked, but here is what I saw in a\nquick-and-dirty experiment:\n\n $ f () { echo foo >\"$1\" && sleep 20 && echo bar >>\"$1\"; }\n $ f hoi ;# wait sufficiently long\n $ cat hoi\n foo\n bar\n $ f hoi ;# wait a bit and hit ^C\n ^C\n $ cat hoi\n foo\n $ rm hoi\n $ f hoi || rm hoi ;# wait a bit and hit ^C\n ^C\n $ cat hoi\n foo\n\nSo, I suspect it unfortunately may not work well.\n\nWe need to get 2/8 redone without bash-ism, but it would not affect\nthe correctness of this step, I would think, whether this is done in\nbash or implemented in a plain vanilla POSIX shell.\n\nThanks.\n"},{"id":"424420","messageId":"609cc2ca7cf26_1e7820868@natae.notmuch","threadId":"55676","inReplyTo":"xmqqmtszb47p.fsf@gitster.g","subject":"Re: [PATCH 4/8] doc: simplify the handling of interruptions","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-13T06:10:18Z","receivedAt":"2021-05-13T06:10:39Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Felipe Contreras writes:\n> \n> > +\"${args[@]}\" -o \"$out\" \"$1\" ||\n> > +{ rm -f \"$out\"; false; }\n> \n> It would be so nice if this worked, but here is what I saw in a\n> quick-and-dirty experiment:\n> \n> $ f hoi || rm hoi ;# wait a bit and hit ^C\n> \n> So, I suspect it unfortunately may not work well.\n\nThat's because the interrupt signal is not caught.\n\nThis works:\n\n sh -c 'echo foo >\"$1\" && trap \"exit 1\" INT && sleep 20' test hoi || rm hoi\n\nAnd so does this:\n\n #!/bin/sh\n\n ruby - hoi < We need to get 2/8 redone without bash-ism,\n\nYes, if we agree this approach is indeed desirable I can do that.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424459","messageId":"CAN0heSrWu462h9Ch5K-aMHUgjB-BGqRp9YpWa=vPi_V+MiUwBg@mail.gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-9-felipe.contreras@gmail.com","subject":"Re: [PATCH 8/8] doc: join xml and man rules","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T11:02:47Z","receivedAt":"2021-05-13T11:04:21Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 13 May 2021 at 00:28, Felipe Contreras\n wrote:\n>\n> Will be useful later with asciidoctor that can do both at the same time.\n\n> -%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n> - $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n> -\n> -%.xml : %.txt $(ASCIIDOC_DEPS)\n> - $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\n> +%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS) manpage-base-url.xsl $(wildcard manpage*.xsl)\n> + $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $*.xml $< && \\\n> + $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $*.xml\n\nIt does mean that if manpage-base-url.xsl changes, we'll regenerate all\nthe xml files. Before this change, we would just rerun the xmlto step.\n\nAlso, this will break `make info`. It will either find xml files that\n\"happen\" to be there, e.g., because you just built the manpages (or\nmaybe you did so several weeks ago), or it won't find them and error\nout.\n\n(If you're wondering if anyone is actually using `make info`, there's\nsome discussion at [1]. I don't think anyone would be too sad to see it\ngo. Once `make info` is the only reason we need to generate the xml\nfiles, I think it's a given we should try to drop that stuff.)\n\nI think we should keep the separate xml targets as long as \"asciidoctor\nwithout xmlto\" isn't the only way we support building the manpages. If\nthe only benefit here is \"later\", I think we should do this patch later.\nI could also imagine that the xml target will just go away once all the\n\"old\" ways of building the manpages are gone and `make info` is gone,\ni.e., when we simply don't need any of these generated xml files.\n\n[1] https://lore.kernel.org/git/20200402004533.GA6369@camp.crustytoothpaste.net/\n\nMartin\n"},{"id":"424461","messageId":"609d0a684ece6_271c20831@natae.notmuch","threadId":"55676","inReplyTo":"CAN0heSrWu462h9Ch5K-aMHUgjB-BGqRp9YpWa=vPi_V+MiUwBg@mail.gmail.com","subject":"Re: [PATCH 8/8] doc: join xml and man rules","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-13T11:15:52Z","receivedAt":"2021-05-13T11:16:06Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin Ågren wrote:\n> On Thu, 13 May 2021 at 00:28, Felipe Contreras\n> wrote:\n> >\n> > Will be useful later with asciidoctor that can do both at the same time.\n> \n> > -%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n> > - $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n> > -\n> > -%.xml : %.txt $(ASCIIDOC_DEPS)\n> > - $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\n> > +%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS) manpage-base-url.xsl $(wildcard manpage*.xsl)\n> > + $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $*.xml $< && \\\n> > + $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $*.xml\n> \n> It does mean that if manpage-base-url.xsl changes, we'll regenerate all\n> the xml files. Before this change, we would just rerun the xmlto step.\n\nTrue.\n\n> Also, this will break `make info`.\n\nAhh, I didn't see that dependency on MAN_XML.\n\n> (If you're wondering if anyone is actually using `make info`, there's\n> some discussion at [1]. I don't think anyone would be too sad to see it\n> go. Once `make info` is the only reason we need to generate the xml\n> files, I think it's a given we should try to drop that stuff.)\n\nPerhaps, but not in this patch series.\n\n> I think we should keep the separate xml targets as long as \"asciidoctor\n> without xmlto\" isn't the only way we support building the manpages. If\n> the only benefit here is \"later\", I think we should do this patch later.\n> I could also imagine that the xml target will just go away once all the\n> \"old\" ways of building the manpages are gone and `make info` is gone,\n> i.e., when we simply don't need any of these generated xml files.\n\nAgreed. I will drop this in the next version.\n\nCheers.\n\n-- \nFelipe Contreras"},{"id":"424480","messageId":"87bl9esls8.fsf@evledraar.gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-3-felipe.contreras@gmail.com","subject":"Re: [PATCH 2/8] doc: add an asciidoc helper","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-05-13T15:17:33Z","receivedAt":"2021-05-13T15:20:42Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, May 12 2021, Felipe Contreras wrote:\n\n> The hacks to deal with interrupted builds is scattered throughout the\n> Makefile, but not everywhere (it's not done for techical/ and articles).\n>\n> It originally comes from f9dae0d3e6 (Documentation/Makefile: fix\n> interrupted builds of user-manual.xml, 2010-04-21), however, that\n> description is not correct.\n>\n> asciidoc does actually remove the output file in case of an exception,\n> but there was a bug that handled keyboard interruptions through a\n> different path, and thus in that particular case the file is not\n> removed[1].\n>\n> We shouldn't overly complicate the Makefile due to bugs in asciidoc.\n>\n> In order to keep the Makefile clean this commit creates an asciidoc\n> wrapper that does the job of tracking the intermediary output.\n>\n> Once asciidoc is fixed this helper can be safely removed and there would\n> be minimal changes elsewhere.\n>\n> It's written for bash, but could easily be modified for something more\n> portable.\n\nBoth this and your first patch could just be made to use the\n.DELETE_ON_ERROR flag instead, although that's a bigger change.\n\nI had this and a related series for that recently:\n\nhttps://lore.kernel.org/git/patch-4.6-2ff6359c273-20210329T161723Z-avarab@gmail.com/\n\nI don't think anyone had an objection to using that, I didn't pursue it\nbecause I was trying to make (among other things) AIX development less\nannoying, but Junio didn't like the -o $@+ && mv $@+ $@ pattern for\nobject files, so I gave up on pursuing it.\n\nBut if you're trying to address this \"maybe it errors\" issue then\n.DELETE_ON_ERROR is a better solution.\n\nI think if we use that we should also undo your changes to use \"-o file\"\nand instead pipe to the file ourselves, otherwise we'll probably have\ncases where the program that fails and GNU make will race to delete the\nfile (but I haven't tested that case).\n"},{"id":"424482","messageId":"878s4islld.fsf@evledraar.gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-6-felipe.contreras@gmail.com","subject":"Re: [PATCH 5/8] doc: remove redundant rm","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-05-13T15:22:37Z","receivedAt":"2021-05-13T15:24:44Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, May 12 2021, Felipe Contreras wrote:\n\n> It's not clear what it was supposed to achieve.\n\nIt seems this used to make sense around 7b8a74f39cb (Documentation:\nReplace @@GIT_VERSION@@ in documentation, 2007-03-25), but at some point\n(I didn't look further) we refactored that and kept the \"rm\".\n"},{"id":"424486","messageId":"CAN0heSoWPUvc+kQO2oXx1XnpOp7=jesGJ80XZm6EjTe15RxQLQ@mail.gmail.com","threadId":"55676","inReplyTo":"20210512222803.508446-8-felipe.contreras@gmail.com","subject":"Re: [PATCH 7/8] doc: improve asciidoc dependencies","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T17:43:26Z","receivedAt":"2021-05-13T17:43:52Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 13 May 2021 at 00:28, Felipe Contreras\n wrote:\n>\n> asciidoc needs asciidoc.conf, asciidoctor asciidoctor-extensions.rb.\n>\n> Neither needs the other.\n\n> -ASCIIDOC_DEPS = asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n> +ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS\n\n> +ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n\nThanks. I was a bit lazy in a15ef383e7 (\"Documentation/Makefile: add\nmissing dependency on asciidoctor-extensions\", 2019-02-27).\n\nWe end up with some duplication. We could pull GIT-ASCIIDOCFLAGS into\nsome ASCIIDOC_DEPS_COMMON. But with just one such common dependency, it\nseems unnecessary and overly complicated. We can pull out the common\ndependencies when we actually gain something from it.\n\nMartin\n"},{"id":"424495","messageId":"609d76e1ae327_42a0208bd@natae.notmuch","threadId":"55676","inReplyTo":"878s4islld.fsf@evledraar.gmail.com","subject":"Re: [PATCH 5/8] doc: remove redundant rm","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-13T18:58:41Z","receivedAt":"2021-05-13T18:58:45Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n> On Wed, May 12 2021, Felipe Contreras wrote:\n> \n> > It's not clear what it was supposed to achieve.\n> \n> It seems this used to make sense around 7b8a74f39cb (Documentation:\n> Replace @@GIT_VERSION@@ in documentation, 2007-03-25), but at some point\n> (I didn't look further) we refactored that and kept the \"rm\".\n\nActually it came later: 50cff52f1a (When generating manpages, delete\noutdated targets first., 2007-08-02).\n\nI'm not sure we should complicate the Makefile just because somebody\nmade the mistake of doing 'sudo make doc' a long time. Especially since\nother rules don't have this.\n\n sudo make doc\n touch GIT-ASCIIDOCFLAGS\n make doc\n\nFails here already.\n\n asciidoc: FAILED: api-merge.txt: line 2: unexpected error:\n asciidoc: ------------------------------------------------------------\n Traceback (most recent call last):\n File \"/usr/bin/asciidoc\", line 6247, in asciidoc\n writer.open(outfile, reader.bom)\n File \"/usr/bin/asciidoc\", line 4633, in open\n self.f = open(fname, 'w+', encoding='utf-8', newline=\"\")\n PermissionError: [Errno 13] Permission denied: '.../Documentation/technical/api-merge.html'\n\n-- \nFelipe Contreras"},{"id":"424497","messageId":"609d7efa79732_42a0208d@natae.notmuch","threadId":"55676","inReplyTo":"87bl9esls8.fsf@evledraar.gmail.com","subject":"Re: [PATCH 2/8] doc: add an asciidoc helper","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-13T19:33:14Z","receivedAt":"2021-05-13T19:33:23Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n> \n> On Wed, May 12 2021, Felipe Contreras wrote:\n> \n> > The hacks to deal with interrupted builds is scattered throughout the\n> > Makefile, but not everywhere (it's not done for techical/ and articles).\n> >\n> > It originally comes from f9dae0d3e6 (Documentation/Makefile: fix\n> > interrupted builds of user-manual.xml, 2010-04-21), however, that\n> > description is not correct.\n> >\n> > asciidoc does actually remove the output file in case of an exception,\n> > but there was a bug that handled keyboard interruptions through a\n> > different path, and thus in that particular case the file is not\n> > removed[1].\n> >\n> > We shouldn't overly complicate the Makefile due to bugs in asciidoc.\n> >\n> > In order to keep the Makefile clean this commit creates an asciidoc\n> > wrapper that does the job of tracking the intermediary output.\n> >\n> > Once asciidoc is fixed this helper can be safely removed and there would\n> > be minimal changes elsewhere.\n> >\n> > It's written for bash, but could easily be modified for something more\n> > portable.\n> \n> Both this and your first patch could just be made to use the\n> .DELETE_ON_ERROR flag instead, although that's a bigger change.\n> \n> I had this and a related series for that recently:\n> \n> https://lore.kernel.org/git/patch-4.6-2ff6359c273-20210329T161723Z-avarab@gmail.com/\n\nIt may be a bigger change on the general Makefile, but I don't think\nthat's the case for the documentation Makefile.\n\n> I don't think anyone had an objection to using that, I didn't pursue it\n> because I was trying to make (among other things) AIX development less\n> annoying, but Junio didn't like the -o $@+ && mv $@+ $@ pattern for\n> object files, so I gave up on pursuing it.\n\nI really don't see what's the point of scattering all those rm mv all\nover the place. If the command is interrupted (ctrl+C), then make will\nremove the file anyway (regardless of .DELETE_ON_ERROR).\n\nIt's only a problem if the command fails for some other reason, in which\ncase the command itself should remove the file, or it's trapping the\nSIGINT signal incorrectly (as is the case with asciidoc).\n\n> But if you're trying to address this \"maybe it errors\" issue then\n> .DELETE_ON_ERROR is a better solution.\n\nIndeed, it seems so. Thanks.\n\n> I think if we use that we should also undo your changes to use \"-o file\"\n> and instead pipe to the file ourselves, otherwise we'll probably have\n> cases where the program that fails and GNU make will race to delete the\n> file (but I haven't tested that case).\n\nYes, although I would prefer to investigate what happens in that case,\nand I bet no race happens (doing `rm -f` twice is not an issue).\n\nCheers.\n\n-- \nFelipe Contreras"},{"id":"424519","messageId":"xmqq4kf69uoa.fsf@gitster.g","threadId":"55676","inReplyTo":"87bl9esls8.fsf@evledraar.gmail.com","subject":"Re: [PATCH 2/8] doc: add an asciidoc helper","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-13T21:43:17Z","receivedAt":"2021-05-13T21:43:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> But if you're trying to address this \"maybe it errors\" issue then\n> .DELETE_ON_ERROR is a better solution.\n\nYeah, I forgot about that, but I agree that .DELETE_ON_ERROR is a\ngood thing to use, as we depend on GNU make anyway.\n\nThanks for bringing it up.\n"}]}