{"thread":{"id":"44934","subject":"[PATCH 0/7] Macro for Asciidoctor support","startedAt":"2017-01-21T21:59:47Z","lastAt":"2017-01-22T01:35:43Z","messageCount":9,"participants":["brian m. carlson","Øyvind A. Holm"],"isPatch":true,"patchVersion":1,"patchTotal":7},"messages":[{"id":"309904","messageId":"20170121215912.246691-1-sandals@crustytoothpaste.net","threadId":"44934","inReplyTo":null,"subject":"[PATCH 0/7] Macro for Asciidoctor support","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-21T21:59:05Z","receivedAt":"2017-01-21T21:59:47Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"There are two major processors of AsciiDoc: AsciiDoc itself, and Asciidoctor.\nBoth have advantages and disadvantages, but traditionally the documentation has\nbeen built with AsciiDoc, leading to some surprising breakage when building with\nAsciidoctor.  Partially, this is due to the need to specify a significant number\nof macros on the command line when building with Asciidoctor.\n\nThis series cleans up some issues building the documentation with Asciidoctor\nand provides two knobs, USE_ASCIIDOCTOR, which controls building with\nAsciidoctor, and ASCIIDOCTOR_EXTENSIONS_LAB, which controls the location of the\nAsciidoctor Extensions Lab, which is necessary to expand the linkgit macro.\n\nThe need for the extensions could be replaced with a small amount of Ruby code,\nif that's considered desirable.  Previous opinions on doing so were negative,\nhowever.\n\nIn the process, I found several issues with cat-texi.perl, which have been\nfixed.  It has also been modernized to use strict, warnings, and lexical file\nhandles.  I also made an attempt to produce more diffable texi files; I may\nfollow up with additional series along this line to make the documentation build\nreproducibly.\n\nbrian m. carlson (7):\n  Documentation: fix warning in cat-texi.perl\n  Documentation: modernize cat-texi.perl\n  Documentation: remove unneeded argument in cat-texi.perl\n  Documentation: sort sources for gitman.texi\n  Documentation: add XSLT to fix DocBook for Texinfo\n  Documentation: move dblatex arguments into variable\n  Makefile: add a knob to enable the use of Asciidoctor\n\n Documentation/Makefile      | 22 ++++++++++++++++++----\n Documentation/cat-texi.perl | 21 ++++++++++++---------\n Documentation/texi.xsl      | 26 ++++++++++++++++++++++++++\n Makefile                    |  6 ++++++\n 4 files changed, 62 insertions(+), 13 deletions(-)\n create mode 100644 Documentation/texi.xsl\n\n"},{"id":"309905","messageId":"20170121215912.246691-4-sandals@crustytoothpaste.net","threadId":"44934","inReplyTo":"20170121215912.246691-1-sandals@crustytoothpaste.net","subject":"[PATCH 3/7] Documentation: remove unneeded argument in cat-texi.perl","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-21T21:59:08Z","receivedAt":"2017-01-21T21:59:53Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"The newly-added use of the warnings pragma exposes that the $menu[0]\nargument to printf has long been silently ignored, since there is no\nformat specifier for it.  It doesn't appear that the argument is\nactually needed, either: there is no reason to insert the name of one\nparticular documentation page anywhere in the header that's being\ngenerated.\n\nRemove the unused argument, and since the format specification\nfunctionality is no longer needed, convert the printf to a simple print.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/cat-texi.perl | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl\nindex 1bc84d3c7..14d2f8341 100755\n--- a/Documentation/cat-texi.perl\n+++ b/Documentation/cat-texi.perl\n@@ -20,7 +20,7 @@ while (<STDIN>) {\n }\n close $tmp;\n \n-printf '\\input texinfo\n+print '\\input texinfo\n @setfilename gitman.info\n @documentencoding UTF-8\n @dircategory Development\n@@ -31,7 +31,7 @@ printf '\\input texinfo\n @top Git Manual Pages\n @documentlanguage en\n @menu\n-', $menu[0];\n+';\n \n for (@menu) {\n \tprint \"* ${_}::\\n\";\n"},{"id":"309906","messageId":"20170121215912.246691-3-sandals@crustytoothpaste.net","threadId":"44934","inReplyTo":"20170121215912.246691-1-sandals@crustytoothpaste.net","subject":"[PATCH 2/7] Documentation: modernize cat-texi.perl","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-21T21:59:07Z","receivedAt":"2017-01-21T21:59:54Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Good style for Perl includes using the strict and warnings pragmas, and\npreferring lexical file handles over bareword file handles.  Using\nlexical file handles necessitates being explicit when $_ is printed, so\nthat Perl does not get confused and instead print the glob ref.\n\nThe benefit of this modernization is that a formerly obscured bug is now\nvisible, which will be fixed in a followup patch.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/cat-texi.perl | 15 +++++++++------\n 1 file changed, 9 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl\nindex b1fe52e8b..1bc84d3c7 100755\n--- a/Documentation/cat-texi.perl\n+++ b/Documentation/cat-texi.perl\n@@ -1,9 +1,12 @@\n #!/usr/bin/perl -w\n \n+use strict;\n+use warnings;\n+\n my @menu = ();\n my $output = $ARGV[0];\n \n-open TMP, '>', \"$output.tmp\";\n+open my $tmp, '>', \"$output.tmp\";\n \n while (<STDIN>) {\n \tnext if (/^\\\\input texinfo/../\\@node Top/);\n@@ -13,9 +16,9 @@ while (<STDIN>) {\n \t}\n \ts/\\(\\@pxref\\{\\[(URLS|REMOTES)\\]}\\)//;\n \ts/\\@anchor\\{[^{}]*\\}//g;\n-\tprint TMP;\n+\tprint $tmp $_;\n }\n-close TMP;\n+close $tmp;\n \n printf '\\input texinfo\n @setfilename gitman.info\n@@ -34,10 +37,10 @@ for (@menu) {\n \tprint \"* ${_}::\\n\";\n }\n print \"\\@end menu\\n\";\n-open TMP, '<', \"$output.tmp\";\n-while (<TMP>) {\n+open $tmp, '<', \"$output.tmp\";\n+while (<$tmp>) {\n \tprint;\n }\n-close TMP;\n+close $tmp;\n print \"\\@bye\\n\";\n unlink \"$output.tmp\";\n"},{"id":"309907","messageId":"20170121215912.246691-2-sandals@crustytoothpaste.net","threadId":"44934","inReplyTo":"20170121215912.246691-1-sandals@crustytoothpaste.net","subject":"[PATCH 1/7] Documentation: fix warning in cat-texi.perl","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-21T21:59:06Z","receivedAt":"2017-01-21T21:59:57Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Newer versions of Perl produce the warning \"Unescaped left brace in\nregex is deprecated, passed through in regex\" when an unescaped left\nbrace occurs in a regex.  Escape the brace to avoid this warning.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/cat-texi.perl | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl\nindex 87437f8a9..b1fe52e8b 100755\n--- a/Documentation/cat-texi.perl\n+++ b/Documentation/cat-texi.perl\n@@ -11,7 +11,7 @@ while (<STDIN>) {\n \tif (s/^\\@top (.*)/\\@node $1,,,Top/) {\n \t\tpush @menu, $1;\n \t}\n-\ts/\\(\\@pxref{\\[(URLS|REMOTES)\\]}\\)//;\n+\ts/\\(\\@pxref\\{\\[(URLS|REMOTES)\\]}\\)//;\n \ts/\\@anchor\\{[^{}]*\\}//g;\n \tprint TMP;\n }\n"},{"id":"309908","messageId":"20170121215912.246691-5-sandals@crustytoothpaste.net","threadId":"44934","inReplyTo":"20170121215912.246691-1-sandals@crustytoothpaste.net","subject":"[PATCH 4/7] Documentation: sort sources for gitman.texi","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-21T21:59:09Z","receivedAt":"2017-01-21T21:59:58Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Sorting the sources makes it easier to compare the output using diff.\nIn addition, it aids groups creating reproducible builds, as the order\nof the files is no longer dependent on the file system or other\nirrelevant factors.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/Makefile | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex a9fb497b8..6e6c82409 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -373,7 +373,7 @@ user-manual.pdf: user-manual.xml\n \n gitman.texi: $(MAN_XML) cat-texi.perl\n \t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n-\t($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \\\n+\t($(foreach xml,$(sort $(MAN_XML)),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \\\n \t\t--to-stdout $(xml) &&) true) > $@++ && \\\n \t$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \\\n \trm $@++ && \\\n"},{"id":"309909","messageId":"20170121215912.246691-8-sandals@crustytoothpaste.net","threadId":"44934","inReplyTo":"20170121215912.246691-1-sandals@crustytoothpaste.net","subject":"[PATCH 7/7] Makefile: add a knob to enable the use of Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-21T21:59:12Z","receivedAt":"2017-01-21T22:00:00Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"While Git has traditionally built its documentation using AsciiDoc, some\npeople wish to use Asciidoctor for speed or other reasons.  Add a\nMakefile knob, USE_ASCIIDOCTOR, that sets various options in order to\nproduce acceptable output.  For HTML output, XHTML5 was chosen, since\nthe AsciiDoc options also produce XHTML, albeit XHTML 1.1.\n\nAsciidoctor does not have built-in support for the linkgit macro, but it\nis available using the Asciidoctor Extensions Lab.  Add a macro to\nenable the use of this extension if it is available.  Without it, the\nlinkgit macros are emitted into the output.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/Makefile | 12 ++++++++++++\n Makefile               |  6 ++++++\n 2 files changed, 18 insertions(+)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 0f4db48eb..5cbecfa99 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -174,6 +174,18 @@ ifdef GNU_ROFF\n XMLTO_EXTRA += -m manpage-quote-apos.xsl\n endif\n \n+ifdef USE_ASCIIDOCTOR\n+ASCIIDOC = asciidoctor\n+ASCIIDOC_CONF =\n+ASCIIDOC_HTML = xhtml5\n+ASCIIDOC_DOCBOOK = docbook45\n+ifdef ASCIIDOCTOR_EXTENSIONS_LAB\n+ASCIIDOC_EXTRA = -I$(ASCIIDOCTOR_EXTENSIONS_LAB) -rasciidoctor/extensions -rman-inline-macro\n+endif\n+ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n+DBLATEX_COMMON =\n+endif\n+\n SHELL_PATH ?= $(SHELL)\n # Shell quote;\n SHELL_PATH_SQ = $(subst ','\\'',$(SHELL_PATH))\ndiff --git a/Makefile b/Makefile\nindex 27afd0f37..7ed9d4d4b 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -250,6 +250,12 @@ all::\n # apostrophes to be ASCII so that cut&pasting examples to the shell\n # will work.\n #\n+# Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the\n+# documentation.\n+#\n+# Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor\n+# Extensions Lab if you have it available.\n+#\n # Define PERL_PATH to the path of your Perl binary (usually /usr/bin/perl).\n #\n # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's\n"},{"id":"309910","messageId":"20170121215912.246691-6-sandals@crustytoothpaste.net","threadId":"44934","inReplyTo":"20170121215912.246691-1-sandals@crustytoothpaste.net","subject":"[PATCH 5/7] Documentation: add XSLT to fix DocBook for Texinfo","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-21T21:59:10Z","receivedAt":"2017-01-21T22:00:06Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"There are two ways to create a section in a reference document (i.e.,\nmanpage) in DocBook 4: refsection elements and refsect, refsect2, and\nrefsect3 elements.  Either form is acceptable as of DocBook 4.2, but\nthey cannot be mixed.  Prior to DocBook 4.2, only the numbered forms\nwere acceptable.\n\ndocbook2texi only accepts the numbered forms, and this has not generally\nbeen a problem, since AsciiDoc produces the numbered forms.\nAsciidoctor, on the other hand, uses a shared backend for DocBook 4 and\n5, and uses the unnumbered refsection elements instead.\n\nIf we don't convert the unnumbered form to the numbered form,\ndocbook2texi omits section headings, which is undesirable.  Add an XSLT\nstylesheet to transform the unnumbered forms to the numbered forms\nautomatically, and preprocess the DocBook XML as part of the\ntransformation to Texinfo format.\n\nNote that this transformation is only necessary for Texinfo, since\ndocbook2texi provides its own stylesheets.  The DocBook stylesheets,\nwhich we use for other formats, provide the full range of DocBook 4 and\n5 compatibility, and don't have this issue.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/Makefile |  7 ++++---\n Documentation/texi.xsl | 26 ++++++++++++++++++++++++++\n 2 files changed, 30 insertions(+), 3 deletions(-)\n create mode 100644 Documentation/texi.xsl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 6e6c82409..76be7017c 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -371,10 +371,11 @@ user-manual.pdf: user-manual.xml\n \t$(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \\\n \tmv $@+ $@\n \n-gitman.texi: $(MAN_XML) cat-texi.perl\n+gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl\n \t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n-\t($(foreach xml,$(sort $(MAN_XML)),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \\\n-\t\t--to-stdout $(xml) &&) true) > $@++ && \\\n+\t($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \\\n+\t\t$(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \\\n+\t\trm $(xml)+ &&) true) > $@++ && \\\n \t$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \\\n \trm $@++ && \\\n \tmv $@+ $@\ndiff --git a/Documentation/texi.xsl b/Documentation/texi.xsl\nnew file mode 100644\nindex 000000000..0f8ff07ec\n--- /dev/null\n+++ b/Documentation/texi.xsl\n@@ -0,0 +1,26 @@\n+<!-- texi.xsl:\n+     convert refsection elements into refsect elements that docbook2texi can\n+     understand -->\n+<xsl:stylesheet xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\"\n+\t\tversion=\"1.0\">\n+\n+<xsl:output method=\"xml\"\n+\t    encoding=\"UTF-8\"\n+\t    doctype-public=\"-//OASIS//DTD DocBook XML V4.5//EN\"\n+\t    doctype-system=\"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\" />\n+\n+<xsl:template match=\"//refsection\">\n+\t<xsl:variable name=\"element\">refsect<xsl:value-of select=\"count(ancestor-or-self::refsection)\" /></xsl:variable>\n+\t<xsl:element name=\"{$element}\">\n+\t\t<xsl:apply-templates select=\"@*|node()\" />\n+\t</xsl:element>\n+</xsl:template>\n+\n+<!-- Copy all other nodes through. -->\n+<xsl:template match=\"node()|@*\">\n+\t<xsl:copy>\n+\t\t<xsl:apply-templates select=\"@*|node()\" />\n+\t</xsl:copy>\n+</xsl:template>\n+\n+</xsl:stylesheet>\n"},{"id":"309911","messageId":"20170121215912.246691-7-sandals@crustytoothpaste.net","threadId":"44934","inReplyTo":"20170121215912.246691-1-sandals@crustytoothpaste.net","subject":"[PATCH 6/7] Documentation: move dblatex arguments into variable","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-21T21:59:11Z","receivedAt":"2017-01-21T22:00:08Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Our dblatex invocation uses several style components from the AsciiDoc\ndistribution, but those components are not available when building with\nAsciidoctor.  Move the command line arguments into a variable so it can\nbe overridden by the user or makefile configuration options.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/Makefile | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 76be7017c..0f4db48eb 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -120,6 +120,7 @@ INSTALL_INFO = install-info\n DOCBOOK2X_TEXI = docbook2x-texi\n DBLATEX = dblatex\n ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex\n+DBLATEX_COMMON = -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty\n ifndef PERL_PATH\n \tPERL_PATH = /usr/bin/perl\n endif\n@@ -368,7 +369,7 @@ user-manual.texi: user-manual.xml\n \n user-manual.pdf: user-manual.xml\n \t$(QUIET_DBLATEX)$(RM) $@+ $@ && \\\n-\t$(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \\\n+\t$(DBLATEX) $-o $@+ (DBLATEX_COMMON) $< && \\\n \tmv $@+ $@\n \n gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl\n"},{"id":"309914","messageId":"20170122010346.iywz4rqqzewfmhkn@sunbase.org","threadId":"44934","inReplyTo":"20170121215912.246691-7-sandals@crustytoothpaste.net","subject":"Re: [PATCH 6/7] Documentation: move dblatex arguments into variable","fromName":"Øyvind A. Holm","fromEmail":"sunny@sunbase.org","sentAt":"2017-01-22T01:03:47Z","receivedAt":"2017-01-22T01:35:43Z","isPatch":true,"sender":{"key":"sunny@sunbase.org","avatar":"https://avatars.githubusercontent.com/u/113445?v=4"},"body":"On 2017-01-21 21:59:11, brian m. carlson wrote:\n> Our dblatex invocation uses several style components from the AsciiDoc\n> distribution, but those components are not available when building with\n> Asciidoctor.  Move the command line arguments into a variable so it can\n> be overridden by the user or makefile configuration options.\n> [...]\n> -\t$(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \\\n> +\t$(DBLATEX) $-o $@+ (DBLATEX_COMMON) $< && \\\n\nIt looks as the dollar sign is in the wrong place, should be in front of \n(DBLATEX_COMMON).\n\nRegards,\nØyvind\n\n+-| Øyvind A. Holm <sunny@sunbase.org> - N 60.37604° E 5.33339° |-+\n| OpenPGP: 0xFB0CBEE894A506E5 - http://www.sunbase.org/pubkey.asc |\n| Fingerprint: A006 05D6 E676 B319 55E2  E77E FB0C BEE8 94A5 06E5 |\n+------------| 61815930-e03e-11e6-b4f4-db5caa6d21d3 |-------------+\n"}]}