{"thread":{"id":"59591","subject":"[RFC PATCH 00/12] doc: add tests and reimplement xmlto","startedAt":"2023-04-13T11:57:51Z","lastAt":"2023-04-13T11:58:28Z","messageCount":13,"participants":["Felipe Contreras"],"isPatch":true,"patchVersion":1,"patchTotal":12},"messages":[{"id":"475285","messageId":"20230413115745.116063-1-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":null,"subject":"[RFC PATCH 00/12] doc: add tests and reimplement xmlto","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:33Z","receivedAt":"2023-04-13T11:57:51Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"It's never clear what a single change does in the myriad of\n{asciidoc.py,asciidoctor}{docbook45,docbook5,manpage} tools, not to mention\nxmlto and docbook-xsl.\n\nSo I decided to create a very simple test to generate a manpage in different\ntools, and the result is that nothing works correctly.\n\nOnce the test was running correctly I decided to investigate why xmlto wasn't\nable to verify docbook5 documents, and it turns out it's just not supported,\nand neither it is in xmllint.\n\nWhile doing so I realized xmlto doesn't do anything for us, so I wrote a simple\nscript that does the same thing.\n\nMoving all the old hacks to this gen-stylesheet script, I realized a hack from\n2006 is not necessary anymore, and DocBook Stylesheets already generate much\nbetter output.\n\nGetting rid of this generates nice aligment for callouts:\n\n $ git diff (1)\n $ git diff --cached (2)\n $ git diff HEAD (3)\n\n 1. Changes in the working tree not yet staged for the next\n commit.\n 2. Changes between the index and your last commit; what you\n would be committing if you run git commit without -a\n option.\n 3. Changes in the working tree since your last commit; what\n you would be committing if you run git commit -a\n\nThere's a lot of changes not explored in detail, so this is only an RFC but I\nthink it's clear something like this is the direction to go.\n\nFelipe Contreras (12):\n doc: add test for doc tools output\n doc: add missing manpage docinfo\n doc: remove unnecessary hack for asciidoctor\n test: doc: add test for docbook5\n doc: fix support for multiple docbook backends\n doc: add gen-stylesheet helper\n doc: get rid of xmlto dependency\n test: doc: use temporary stylesheet\n doc: remove references to xmlto\n doc: stylesheet: move all the xslt templates\n test: doc: add check for callouts\n doc: manpage: remove callout hack\n\n Documentation/.gitignore | 1 +\n Documentation/Makefile | 19 ++--\n Documentation/asciidoc.conf | 15 +--\n Documentation/gen-stylesheet | 28 +++++\n Documentation/manpage-bold-literal.xsl | 16 ---\n Documentation/manpage-normal.xsl | 26 -----\n Documentation/manpage.xsl | 3 -\n INSTALL | 4 +-\n ci/install-dependencies.sh | 2 +-\n shared.mak | 3 +-\n t/t0600-doc-tools.sh | 135 +++++++++++++++++++++++++\n 11 files changed, 184 insertions(+), 68 deletions(-)\n create mode 100755 Documentation/gen-stylesheet\n delete mode 100644 Documentation/manpage-bold-literal.xsl\n delete mode 100644 Documentation/manpage-normal.xsl\n delete mode 100644 Documentation/manpage.xsl\n create mode 100755 t/t0600-doc-tools.sh\n\n-- \n2.40.0+fc1\n\n"},{"id":"475286","messageId":"20230413115745.116063-2-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 01/12] doc: add test for doc tools output","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:34Z","receivedAt":"2023-04-13T11:57:52Z","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 t/t0600-doc-tools.sh | 91 ++++++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 91 insertions(+)\n create mode 100755 t/t0600-doc-tools.sh\n\ndiff --git a/t/t0600-doc-tools.sh b/t/t0600-doc-tools.sh\nnew file mode 100755\nindex 0000000000..0f9a4053a9\n--- /dev/null\n+++ b/t/t0600-doc-tools.sh\n@@ -0,0 +1,91 @@\n+#!/bin/sh\n+\n+test_description='Check the output of documentation tools'\n+\n+. ./test-lib.sh\n+\n+doc_dir=\"$GIT_BUILD_DIR/Documentation\"\n+\n+command -v asciidoc >/dev/null && test_set_prereq ASCIIDOC\n+command -v asciidoctor >/dev/null && test_set_prereq ASCIIDOCTOR\n+\n+cat >git-foo.txt <]\n+\n+DESCRIPTION\n+-----------\n+description\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\n+EOF\n+\n+cat >git-foo.1.expected <]\n+.fi\n+.sp\n+.SH \"DESCRIPTION\"\n+.sp\n+description\n+.SH \"GIT\"\n+.sp\n+Part of the \\fBgit\\fR(1) suite\n+EOF\n+\n+xmltoman() {\n+\tbase=\"$1\"\n+\tshift\n+\txmlto --skip-validation -m \"$doc_dir/manpage-normal.xsl\" -m \"$doc_dir/manpage-bold-literal.xsl\" \"$@\" man \"$base.xml\"\n+}\n+\n+build_asciidoc_py() {\n+\tasciidoc -f \"$doc_dir/asciidoc.conf\" -amanmanual='Git Manual' -amansource='Git 1.0.0' -arevdate='2005-01-01' -b docbook -d manpage \\\n+\t\t-o \"$1.xml\" \"$1.txt\" &&\n+\txmltoman \"$1\"\n+}\n+\n+build_asciidoctor() {\n+\tasciidoctor -acompat-mode -atabsize=8 -I \"$doc_dir\" -rasciidoctor-extensions -alitdd='--' \\\n+\t\t-amanmanual='Git Manual' -amansource='Git 1.0.0' -arevdate='2005-01-01' -b docbook5 -d manpage \\\n+\t\t-o \"$1.xml\" \"$1.txt\" &&\n+\txmltoman \"$1\" -x \"$doc_dir\"/manpage.xsl\n+}\n+\n+check_manpage() {\n+\tsed -e '/^\\.\\\\\"/d' -e '/^$/d' \"$1.1\" >\"$1.1.actual\" &&\n+\ttest_cmp \"$1.1.expected\" \"$1.1.actual\"\n+}\n+\n+test_expect_failure ASCIIDOC 'legacy asciidoc.py' '\n+\tbuild_asciidoc_py \"git-foo\" &&\n+\tcheck_manpage \"git-foo\"\n+'\n+\n+test_expect_failure ASCIIDOCTOR 'modern asciidoctor (docbook5)' '\n+\tbuild_asciidoctor \"git-foo\" &&\n+\tcheck_manpage \"git-foo\"\n+'\n+\n+test_done\n-- \n2.40.0+fc1\n\n"},{"id":"475287","messageId":"20230413115745.116063-3-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 02/12] doc: add missing manpage docinfo","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:35Z","receivedAt":"2023-04-13T11:57:55Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"We can remove the whole hack, since asciidoc.py already does that\ncorrectly since 2008.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoc.conf | 3 +++\n t/t0600-doc-tools.sh | 2 +-\n 2 files changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 3e4c13971b..303d45dc34 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -56,6 +56,9 @@ ifdef::backend-docbook[]\n [header]\n template::[header-declarations]\n \n+\n+template::[docinfo]\n+\n \n {mantitle}\n {manvolnum}\ndiff --git a/t/t0600-doc-tools.sh b/t/t0600-doc-tools.sh\nindex 0f9a4053a9..db77db72e5 100755\n--- a/t/t0600-doc-tools.sh\n+++ b/t/t0600-doc-tools.sh\n@@ -78,7 +78,7 @@ check_manpage() {\n \ttest_cmp \"$1.1.expected\" \"$1.1.actual\"\n }\n \n-test_expect_failure ASCIIDOC 'legacy asciidoc.py' '\n+test_expect_success ASCIIDOC 'legacy asciidoc.py' '\n \tbuild_asciidoc_py \"git-foo\" &&\n \tcheck_manpage \"git-foo\"\n '\n-- \n2.40.0+fc1\n\n"},{"id":"475288","messageId":"20230413115745.116063-4-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 03/12] doc: remove unnecessary hack for asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:36Z","receivedAt":"2023-04-13T11:57:57Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"It was added in f6461b82b9 (Documentation: fix build with Asciidoctor 2,\n2019-09-15) to avoid newlines, but they don't matter.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 1 -\n Documentation/manpage.xsl | 3 ---\n t/t0600-doc-tools.sh | 4 ++--\n 3 files changed, 2 insertions(+), 6 deletions(-)\n delete mode 100644 Documentation/manpage.xsl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 5cd35df61c..3fab7ce9cd 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -202,7 +202,6 @@ ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\n-XMLTO_EXTRA += -x manpage.xsl\n endif\n \n SHELL_PATH ?= $(SHELL)\ndiff --git a/Documentation/manpage.xsl b/Documentation/manpage.xsl\ndeleted file mode 100644\nindex ef64bab17a..0000000000\n--- a/Documentation/manpage.xsl\n+++ /dev/null\n@@ -1,3 +0,0 @@\n-\n-\t\n-\ndiff --git a/t/t0600-doc-tools.sh b/t/t0600-doc-tools.sh\nindex db77db72e5..a80cd32cd6 100755\n--- a/t/t0600-doc-tools.sh\n+++ b/t/t0600-doc-tools.sh\n@@ -70,7 +70,7 @@ build_asciidoctor() {\n \tasciidoctor -acompat-mode -atabsize=8 -I \"$doc_dir\" -rasciidoctor-extensions -alitdd='--' \\\n \t\t-amanmanual='Git Manual' -amansource='Git 1.0.0' -arevdate='2005-01-01' -b docbook5 -d manpage \\\n \t\t-o \"$1.xml\" \"$1.txt\" &&\n-\txmltoman \"$1\" -x \"$doc_dir\"/manpage.xsl\n+\txmltoman \"$1\"\n }\n \n check_manpage() {\n@@ -83,7 +83,7 @@ test_expect_success ASCIIDOC 'legacy asciidoc.py' '\n \tcheck_manpage \"git-foo\"\n '\n \n-test_expect_failure ASCIIDOCTOR 'modern asciidoctor (docbook5)' '\n+test_expect_success ASCIIDOCTOR 'modern asciidoctor (docbook5)' '\n \tbuild_asciidoctor \"git-foo\" &&\n \tcheck_manpage \"git-foo\"\n '\n-- \n2.40.0+fc1\n\n"},{"id":"475289","messageId":"20230413115745.116063-5-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 04/12] test: doc: add test for docbook5","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:37Z","receivedAt":"2023-04-13T11:58:03Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"It was released 13 years ago and we still don't support it.\n\nSigned-off-by: Felipe Contreras \n---\n t/t0600-doc-tools.sh | 8 +++++++-\n 1 file changed, 7 insertions(+), 1 deletion(-)\n\ndiff --git a/t/t0600-doc-tools.sh b/t/t0600-doc-tools.sh\nindex a80cd32cd6..e4388a54c6 100755\n--- a/t/t0600-doc-tools.sh\n+++ b/t/t0600-doc-tools.sh\n@@ -61,7 +61,8 @@ xmltoman() {\n }\n \n build_asciidoc_py() {\n-\tasciidoc -f \"$doc_dir/asciidoc.conf\" -amanmanual='Git Manual' -amansource='Git 1.0.0' -arevdate='2005-01-01' -b docbook -d manpage \\\n+\tbackend=${2-docbook}\n+\tasciidoc -f \"$doc_dir/asciidoc.conf\" -amanmanual='Git Manual' -amansource='Git 1.0.0' -arevdate='2005-01-01' -b \"$backend\" -d manpage \\\n \t\t-o \"$1.xml\" \"$1.txt\" &&\n \txmltoman \"$1\"\n }\n@@ -83,6 +84,11 @@ test_expect_success ASCIIDOC 'legacy asciidoc.py' '\n \tcheck_manpage \"git-foo\"\n '\n \n+test_expect_failure ASCIIDOC 'legacy asciidoc.py (docbook5)' '\n+\tbuild_asciidoc_py \"git-foo\" docbook5 &&\n+\tcheck_manpage \"git-foo\"\n+'\n+\n test_expect_success ASCIIDOCTOR 'modern asciidoctor (docbook5)' '\n \tbuild_asciidoctor \"git-foo\" &&\n \tcheck_manpage \"git-foo\"\n-- \n2.40.0+fc1\n\n"},{"id":"475290","messageId":"20230413115745.116063-6-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 05/12] doc: fix support for multiple docbook backends","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:38Z","receivedAt":"2023-04-13T11:58:04Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"docbook isn't a backend, but a famliy of backends.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoc.conf | 12 ++++++------\n t/t0600-doc-tools.sh | 2 +-\n 2 files changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 303d45dc34..356b131870 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -22,15 +22,15 @@ apostrophe='\n backtick=`\n litdd=--\n \n-ifdef::backend-docbook[]\n+ifdef::basebackend-docbook[]\n [linkgit-inlinemacro]\n {0%{target}}\n {0#}\n {0#{target}{0}}\n {0#}\n-endif::backend-docbook[]\n+endif::basebackend-docbook[]\n \n-ifdef::backend-docbook[]\n+ifdef::basebackend-docbook[]\n ifdef::doctype-manpage[]\n # The following two small workarounds insert a simple paragraph after screen\n [listingblock]\n@@ -49,10 +49,10 @@ ifdef::doctype-manpage[]\n {title#}\n {title%}\n endif::doctype-manpage[]\n-endif::backend-docbook[]\n+endif::basebackend-docbook[]\n \n ifdef::doctype-manpage[]\n-ifdef::backend-docbook[]\n+ifdef::basebackend-docbook[]\n [header]\n template::[header-declarations]\n \n@@ -70,7 +70,7 @@ template::[docinfo]\n {manname}\n {manpurpose}\n \n-endif::backend-docbook[]\n+endif::basebackend-docbook[]\n endif::doctype-manpage[]\n \n ifdef::backend-xhtml11[]\ndiff --git a/t/t0600-doc-tools.sh b/t/t0600-doc-tools.sh\nindex e4388a54c6..2552b0d376 100755\n--- a/t/t0600-doc-tools.sh\n+++ b/t/t0600-doc-tools.sh\n@@ -84,7 +84,7 @@ test_expect_success ASCIIDOC 'legacy asciidoc.py' '\n \tcheck_manpage \"git-foo\"\n '\n \n-test_expect_failure ASCIIDOC 'legacy asciidoc.py (docbook5)' '\n+test_expect_success ASCIIDOC 'legacy asciidoc.py (docbook5)' '\n \tbuild_asciidoc_py \"git-foo\" docbook5 &&\n \tcheck_manpage \"git-foo\"\n '\n-- \n2.40.0+fc1\n\n"},{"id":"475291","messageId":"20230413115745.116063-7-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 06/12] doc: add gen-stylesheet helper","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:39Z","receivedAt":"2023-04-13T11:58:11Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Move most of the logic of xmlto into a simple script that generates a\nsingle stylesheet.\n\nThere should be no functional changes.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/.gitignore | 1 +\n Documentation/Makefile | 12 +++++-------\n Documentation/gen-stylesheet | 17 +++++++++++++++++\n t/t0600-doc-tools.sh | 4 +++-\n 4 files changed, 26 insertions(+), 8 deletions(-)\n create mode 100755 Documentation/gen-stylesheet\n\ndiff --git a/Documentation/.gitignore b/Documentation/.gitignore\nindex a48448de32..afec7e7f19 100644\n--- a/Documentation/.gitignore\n+++ b/Documentation/.gitignore\n@@ -15,3 +15,4 @@ tmp-doc-diff/\n GIT-ASCIIDOCFLAGS\n /.build/\n /GIT-EXCLUDED-PROGRAMS\n+/manpage.xsl\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3fab7ce9cd..96d3f52c60 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -155,7 +155,6 @@ ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS\n TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)\n TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)\n-MANPAGE_XSL = manpage-normal.xsl\n XMLTO = xmlto\n XMLTO_EXTRA =\n INSTALL ?= install\n@@ -176,10 +175,6 @@ endif\n -include ../config.mak.autogen\n -include ../config.mak\n \n-ifndef NO_MAN_BOLD_LITERAL\n-XMLTO_EXTRA += -m manpage-bold-literal.xsl\n-endif\n-\n # Newer DocBook stylesheet emits warning cruft in the output when\n # this is not set, and if set it shows an absolute link. Older\n # stylesheets simply ignore this parameter.\n@@ -338,8 +333,11 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n \n-manpage-prereqs := $(wildcard manpage*.xsl)\n-manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n+manpage-prereqs := manpage.xsl $(wildcard manpage*.xsl)\n+manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -x manpage.xsl $(XMLTO_EXTRA) man $<\n+\n+manpage.xsl: gen-stylesheet\n+\t./gen-stylesheet >\"$@\"\n \n %.1 : %.xml $(manpage-prereqs)\n \t$(manpage-cmd)\ndiff --git a/Documentation/gen-stylesheet b/Documentation/gen-stylesheet\nnew file mode 100755\nindex 0000000000..c006a85c39\n--- /dev/null\n+++ b/Documentation/gen-stylesheet\n@@ -0,0 +1,17 @@\n+#!/bin/sh\n+\n+includes='manpage-normal.xsl'\n+test -z \"$NO_MAN_BOLD_LITERAL\" && includes=\"$includes manpage-bold-literal.xsl\"\n+\n+cat <\n+\n+\n+EOF\n+\n+for x in $includes\n+do\n+\tprintf '\\n' \"$x\"\n+done\n+\n+echo \"\"\ndiff --git a/t/t0600-doc-tools.sh b/t/t0600-doc-tools.sh\nindex 2552b0d376..a003686c2f 100755\n--- a/t/t0600-doc-tools.sh\n+++ b/t/t0600-doc-tools.sh\n@@ -54,10 +54,12 @@ description\n Part of the \\fBgit\\fR(1) suite\n EOF\n \n+\"$doc_dir\"/gen-stylesheet >\"$doc_dir\"/manpage.xsl\n+\n xmltoman() {\n \tbase=\"$1\"\n \tshift\n-\txmlto --skip-validation -m \"$doc_dir/manpage-normal.xsl\" -m \"$doc_dir/manpage-bold-literal.xsl\" \"$@\" man \"$base.xml\"\n+\txmlto --skip-validation -x \"$doc_dir\"/manpage.xsl man \"$base.xml\"\n }\n \n build_asciidoc_py() {\n-- \n2.40.0+fc1\n\n"},{"id":"475292","messageId":"20230413115745.116063-8-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 07/12] doc: get rid of xmlto dependency","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:40Z","receivedAt":"2023-04-13T11:58:13Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"We don't use any of its functionality, so all it's doing for us is\ngenerate a stylesheet, which we are doing by ourselves now.\n\nUse `xsltproc` directly.\n\nThis gets rid of some annoying warnings because my system doesn't use\ndebian's libpaper:\n\n (null): unknown option '-n'\n (null): unknown option '-mh'\n (null): unknown option '-mw'\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 6 ++----\n t/t0600-doc-tools.sh | 4 +---\n 2 files changed, 3 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 96d3f52c60..3e2cbef306 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -155,7 +155,6 @@ ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS\n TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)\n TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)\n-XMLTO = xmlto\n XMLTO_EXTRA =\n INSTALL ?= install\n RM ?= rm -f\n@@ -184,7 +183,7 @@ endif\n ifndef MAN_BASE_URL\n MAN_BASE_URL = file://$(htmldir)/\n endif\n-XMLTO_EXTRA += --stringparam man.base.url.for.relative.links='$(MAN_BASE_URL)'\n+XMLTO_EXTRA += --stringparam man.base.url.for.relative.links '$(MAN_BASE_URL)'\n \n ifdef USE_ASCIIDOCTOR\n ASCIIDOC = asciidoctor\n@@ -196,7 +195,6 @@ ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n DBLATEX_COMMON =\n-XMLTO_EXTRA += --skip-validation\n endif\n \n SHELL_PATH ?= $(SHELL)\n@@ -334,7 +332,7 @@ $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n \n manpage-prereqs := manpage.xsl $(wildcard manpage*.xsl)\n-manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -x manpage.xsl $(XMLTO_EXTRA) man $<\n+manpage-cmd = $(QUIET_XMLTO)xsltproc --nonet $(XMLTO_EXTRA) -o $@ manpage.xsl $<\n \n manpage.xsl: gen-stylesheet\n \t./gen-stylesheet >\"$@\"\ndiff --git a/t/t0600-doc-tools.sh b/t/t0600-doc-tools.sh\nindex a003686c2f..0af431941d 100755\n--- a/t/t0600-doc-tools.sh\n+++ b/t/t0600-doc-tools.sh\n@@ -57,9 +57,7 @@ EOF\n \"$doc_dir\"/gen-stylesheet >\"$doc_dir\"/manpage.xsl\n \n xmltoman() {\n-\tbase=\"$1\"\n-\tshift\n-\txmlto --skip-validation -x \"$doc_dir\"/manpage.xsl man \"$base.xml\"\n+\txsltproc --nonet -o \"$1.1\" \"$doc_dir/manpage.xsl\" \"$1.xml\"\n }\n \n build_asciidoc_py() {\n-- \n2.40.0+fc1\n\n"},{"id":"475293","messageId":"20230413115745.116063-9-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 08/12] test: doc: use temporary stylesheet","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:41Z","receivedAt":"2023-04-13T11:58:14Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"xsltproc doesn't have a problem with a our trash directory.\n\nSigned-off-by: Felipe Contreras \n---\n t/t0600-doc-tools.sh | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/t/t0600-doc-tools.sh b/t/t0600-doc-tools.sh\nindex 0af431941d..cd88027514 100755\n--- a/t/t0600-doc-tools.sh\n+++ b/t/t0600-doc-tools.sh\n@@ -54,10 +54,10 @@ description\n Part of the \\fBgit\\fR(1) suite\n EOF\n \n-\"$doc_dir\"/gen-stylesheet >\"$doc_dir\"/manpage.xsl\n+\"$doc_dir\"/gen-stylesheet >manpage.xsl\n \n xmltoman() {\n-\txsltproc --nonet -o \"$1.1\" \"$doc_dir/manpage.xsl\" \"$1.xml\"\n+\txsltproc --nonet -o \"$1.1\" manpage.xsl \"$1.xml\"\n }\n \n build_asciidoc_py() {\n-- \n2.40.0+fc1\n\n"},{"id":"475294","messageId":"20230413115745.116063-10-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 09/12] doc: remove references to xmlto","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:42Z","receivedAt":"2023-04-13T11:58:22Z","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 | 6 +++---\n Documentation/manpage-normal.xsl | 2 +-\n INSTALL | 4 ++--\n ci/install-dependencies.sh | 2 +-\n shared.mak | 3 +--\n 5 files changed, 8 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3e2cbef306..a85f60f766 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -155,7 +155,7 @@ ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS\n TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)\n TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)\n-XMLTO_EXTRA =\n+XSLTPROC_EXTRA =\n INSTALL ?= install\n RM ?= rm -f\n MAN_REPO = ../../git-manpages\n@@ -183,7 +183,7 @@ endif\n ifndef MAN_BASE_URL\n MAN_BASE_URL = file://$(htmldir)/\n endif\n-XMLTO_EXTRA += --stringparam man.base.url.for.relative.links '$(MAN_BASE_URL)'\n+XSLTPROC_EXTRA += --stringparam man.base.url.for.relative.links '$(MAN_BASE_URL)'\n \n ifdef USE_ASCIIDOCTOR\n ASCIIDOC = asciidoctor\n@@ -332,7 +332,7 @@ $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n \n manpage-prereqs := manpage.xsl $(wildcard manpage*.xsl)\n-manpage-cmd = $(QUIET_XMLTO)xsltproc --nonet $(XMLTO_EXTRA) -o $@ manpage.xsl $<\n+manpage-cmd = $(QUIET_XSLTPROC)xsltproc --nonet $(XSLTPROC_EXTRA) -o $@ manpage.xsl $<\n \n manpage.xsl: gen-stylesheet\n \t./gen-stylesheet >\"$@\"\ndiff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl\nindex a9c7ec69f4..3fb044a8a7 100644\n--- a/Documentation/manpage-normal.xsl\n+++ b/Documentation/manpage-normal.xsl\n@@ -4,7 +4,7 @@\n \t\tversion=\"1.0\">\n \n \n-\n+\n \n \n \ndiff --git a/INSTALL b/INSTALL\nindex 4b42288882..48c126b3be 100644\n--- a/INSTALL\n+++ b/INSTALL\n@@ -176,13 +176,13 @@ Issues of note:\n the name is reserved for local settings.\n \n - To build and install documentation suite, you need to have\n- the asciidoc/xmlto toolchain. Because not many people are\n+ the asciidoc/xsltproc toolchain. Because not many people are\n inclined to install the tools, the default build target\n (\"make all\") does _not_ build them.\n \n \"make doc\" builds documentation in man and html formats; there are\n also \"make man\", \"make html\" and \"make info\". Note that \"make html\"\n- requires asciidoc, but not xmlto. \"make man\" (and thus make doc)\n+ requires asciidoc, but not xsltproc. \"make man\" (and thus make doc)\n requires both.\n \n \"make install-doc\" installs documentation in man format only; there\ndiff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\nindex 4f407530d3..fe72525f1f 100755\n--- a/ci/install-dependencies.sh\n+++ b/ci/install-dependencies.sh\n@@ -69,7 +69,7 @@ sparse)\n \t;;\n Documentation)\n \tsudo apt-get -q update\n-\tsudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make\n+\tsudo apt-get -q -y install asciidoc xsltproc docbook-xsl-ns make\n \n \ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n \tsudo gem install --version 1.5.8 asciidoctor\ndiff --git a/shared.mak b/shared.mak\nindex aeb80fc4d5..52fbc8ec6f 100644\n--- a/shared.mak\n+++ b/shared.mak\n@@ -78,11 +78,10 @@ ifndef V\n \n ## Used in \"Documentation/Makefile\"\n \tQUIET_ASCIIDOC\t= @echo ' ' ASCIIDOC $@;\n-\tQUIET_XMLTO\t= @echo ' ' XMLTO $@;\n+\tQUIET_XSLTPROC\t= @echo ' ' XSLTPROC $@;\n \tQUIET_DB2TEXI\t= @echo ' ' DB2TEXI $@;\n \tQUIET_MAKEINFO\t= @echo ' ' MAKEINFO $@;\n \tQUIET_DBLATEX\t= @echo ' ' DBLATEX $@;\n-\tQUIET_XSLTPROC\t= @echo ' ' XSLTPROC $@;\n \tQUIET_GEN\t= @echo ' ' GEN $@;\n \tQUIET_STDERR\t= 2> /dev/null\n \n-- \n2.40.0+fc1\n\n"},{"id":"475295","messageId":"20230413115745.116063-11-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 10/12] doc: stylesheet: move all the xslt templates","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:43Z","receivedAt":"2023-04-13T11:58:25Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"There's no need to have them scattered everywhere.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/gen-stylesheet | 42 +++++++++++++++++++++-----\n Documentation/manpage-bold-literal.xsl | 16 ----------\n Documentation/manpage-normal.xsl | 26 ----------------\n 3 files changed, 35 insertions(+), 49 deletions(-)\n delete mode 100644 Documentation/manpage-bold-literal.xsl\n delete mode 100644 Documentation/manpage-normal.xsl\n\ndiff --git a/Documentation/gen-stylesheet b/Documentation/gen-stylesheet\nindex c006a85c39..7d1839fcab 100755\n--- a/Documentation/gen-stylesheet\n+++ b/Documentation/gen-stylesheet\n@@ -1,17 +1,45 @@\n #!/bin/sh\n \n-includes='manpage-normal.xsl'\n-test -z \"$NO_MAN_BOLD_LITERAL\" && includes=\"$includes manpage-bold-literal.xsl\"\n-\n cat <\n \n \n EOF\n \n-for x in $includes\n-do\n-\tprintf '\\n' \"$x\"\n-done\n+# these params silence some output from xsltproc\n+cat <\n+\n+EOF\n+\n+# convert asciidoc callouts to man page format\n+cat <\n+\t\n+\n+\n+\t.sp \n+\t\n+\t \n+\n+\n+\t\n+\t\n+\t.br \n+\n+EOF\n+\n+if [[ -z \"$NO_MAN_BOLD_LITERAL\" ]]\n+then\n+\t# render literal text as bold (instead of plain or monospace); this makes\n+\t# literal text easier to distinguish in manpages viewed on a tty\n+\tcat <<-EOF\n+\t\n+\t\t\\fB\n+\t\t\n+\t\t\\fR\n+\t\n+\tEOF\n+fi\n \n echo \"\"\ndiff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl\ndeleted file mode 100644\nindex e13db85693..0000000000\n--- a/Documentation/manpage-bold-literal.xsl\n+++ /dev/null\n@@ -1,16 +0,0 @@\n-\n-\n-\n-\n-\n-\t\\fB\n-\t\n-\t\\fR\n-\n-\n-\ndiff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl\ndeleted file mode 100644\nindex 3fb044a8a7..0000000000\n--- a/Documentation/manpage-normal.xsl\n+++ /dev/null\n@@ -1,26 +0,0 @@\n-\n-\n-\n-\n-\n-\n-\n-\n-\n-\n-\t\n-\n-\n-\t.sp \n-\t\n-\t \n-\n-\n-\t\n-\t\n-\t.br \n-\n-\n-\n-- \n2.40.0+fc1\n\n"},{"id":"475296","messageId":"20230413115745.116063-12-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 11/12] test: doc: add check for callouts","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:44Z","receivedAt":"2023-04-13T11:58:26Z","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 t/t0600-doc-tools.sh | 36 ++++++++++++++++++++++++++++++++++--\n 1 file changed, 34 insertions(+), 2 deletions(-)\n\ndiff --git a/t/t0600-doc-tools.sh b/t/t0600-doc-tools.sh\nindex cd88027514..545fb0e199 100755\n--- a/t/t0600-doc-tools.sh\n+++ b/t/t0600-doc-tools.sh\n@@ -26,6 +26,17 @@ DESCRIPTION\n -----------\n description\n \n+CALLOUTS\n+--------\n+----\n+$ git diff <1>\n+$ git diff --cached <2>\n+$ git diff @ <3>\n+----\n+<1> Callout 1\n+<2> Callout 2\n+<3> Callout 3\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n@@ -49,6 +60,27 @@ git-foo \\- Test command\n .SH \"DESCRIPTION\"\n .sp\n description\n+.SH \"CALLOUTS\"\n+.sp\n+.if n \\{\\\\\n+.RS 4\n+.\\}\n+.nf\n+$ git diff \\fB(1)\\fR\n+$ git diff \\-\\-cached \\fB(2)\\fR\n+$ git diff @ \\fB(3)\\fR\n+.fi\n+.if n \\{\\\\\n+.RE\n+.\\}\n+.sp\n+.sp\n+\\fB1. \\fRCallout 1\n+.br\n+\\fB2. \\fRCallout 2\n+.br\n+\\fB3. \\fRCallout 3\n+.br\n .SH \"GIT\"\n .sp\n Part of the \\fBgit\\fR(1) suite\n@@ -84,12 +116,12 @@ test_expect_success ASCIIDOC 'legacy asciidoc.py' '\n \tcheck_manpage \"git-foo\"\n '\n \n-test_expect_success ASCIIDOC 'legacy asciidoc.py (docbook5)' '\n+test_expect_failure ASCIIDOC 'legacy asciidoc.py (docbook5)' '\n \tbuild_asciidoc_py \"git-foo\" docbook5 &&\n \tcheck_manpage \"git-foo\"\n '\n \n-test_expect_success ASCIIDOCTOR 'modern asciidoctor (docbook5)' '\n+test_expect_failure ASCIIDOCTOR 'modern asciidoctor (docbook5)' '\n \tbuild_asciidoctor \"git-foo\" &&\n \tcheck_manpage \"git-foo\"\n '\n-- \n2.40.0+fc1\n\n"},{"id":"475297","messageId":"20230413115745.116063-13-felipe.contreras@gmail.com","threadId":"59591","inReplyTo":"20230413115745.116063-1-felipe.contreras@gmail.com","subject":"[RFC PATCH 12/12] doc: manpage: remove callout hack","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-13T11:57:45Z","receivedAt":"2023-04-13T11:58:28Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"DocBook Stylesheets already have much better support for callouts.\n\nThis:\n\n $ git diff (1)\n $ git diff --cached (2)\n $ git diff HEAD (3)\n\n 1. Changes in the working tree not yet staged for the next\n commit.\n 2. Changes between the index and your last commit; what you\n would be committing if you run git commit without -a\n option.\n 3. Changes in the working tree since your last commit; what\n you would be committing if you run git commit -a\n\nLooks much better than this:\n\n $ git diff (1)\n $ git diff --cached (2)\n $ git diff HEAD (3)\n\n 1. Changes in the working tree not yet staged for the next commit.\n 2. Changes between the index and your last commit; what you would\n be committing if you run git commit without -a option.\n 3. Changes in the working tree since your last commit; what you\n would be committing if you run git commit -a\n\nThis implementation goes back to 2006: 776e994af5 (Properly render\nasciidoc \"callouts\" in git man pages., 2006-04-28). It probably wasn't\nneeded since a long time ago.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/gen-stylesheet | 17 -----------------\n t/t0600-doc-tools.sh | 24 +++++++++++++++---------\n 2 files changed, 15 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/gen-stylesheet b/Documentation/gen-stylesheet\nindex 7d1839fcab..53c3dfca17 100755\n--- a/Documentation/gen-stylesheet\n+++ b/Documentation/gen-stylesheet\n@@ -12,23 +12,6 @@ cat <\n EOF\n \n-# convert asciidoc callouts to man page format\n-cat <\n-\t\n-\n-\n-\t.sp \n-\t\n-\t \n-\n-\n-\t\n-\t\n-\t.br \n-\n-EOF\n-\n if [[ -z \"$NO_MAN_BOLD_LITERAL\" ]]\n then\n \t# render literal text as bold (instead of plain or monospace); this makes\ndiff --git a/t/t0600-doc-tools.sh b/t/t0600-doc-tools.sh\nindex 545fb0e199..10a472e1e6 100755\n--- a/t/t0600-doc-tools.sh\n+++ b/t/t0600-doc-tools.sh\n@@ -74,13 +74,19 @@ $ git diff @ \\fB(3)\\fR\n .RE\n .\\}\n .sp\n-.sp\n-\\fB1. \\fRCallout 1\n-.br\n-\\fB2. \\fRCallout 2\n-.br\n-\\fB3. \\fRCallout 3\n-.br\n+.TS\n+tab(:);\n+r lw(\\n(.lu*75u/100u).\n+\\fB1.\\fR\\h'-2n':T{\n+Callout 1\n+T}\n+\\fB2.\\fR\\h'-2n':T{\n+Callout 2\n+T}\n+\\fB3.\\fR\\h'-2n':T{\n+Callout 3\n+T}\n+.TE\n .SH \"GIT\"\n .sp\n Part of the \\fBgit\\fR(1) suite\n@@ -116,12 +122,12 @@ test_expect_success ASCIIDOC 'legacy asciidoc.py' '\n \tcheck_manpage \"git-foo\"\n '\n \n-test_expect_failure ASCIIDOC 'legacy asciidoc.py (docbook5)' '\n+test_expect_success ASCIIDOC 'legacy asciidoc.py (docbook5)' '\n \tbuild_asciidoc_py \"git-foo\" docbook5 &&\n \tcheck_manpage \"git-foo\"\n '\n \n-test_expect_failure ASCIIDOCTOR 'modern asciidoctor (docbook5)' '\n+test_expect_success ASCIIDOCTOR 'modern asciidoctor (docbook5)' '\n \tbuild_asciidoctor \"git-foo\" &&\n \tcheck_manpage \"git-foo\"\n '\n-- \n2.40.0+fc1\n\n"}]}