{"thread":{"id":"44935","subject":"[PATCH v2 1/7] Documentation: fix warning in cat-texi.perl","startedAt":"2017-01-22T02:42:13Z","lastAt":"2017-01-31T20:20:55Z","messageCount":24,"participants":["brian m. carlson","Øyvind A. Holm","Junio C Hamano","Johannes Schindelin","Jeff King","Eric Wong"],"isPatch":true,"patchVersion":2,"patchTotal":7},"messages":[{"id":"309915","messageId":"20170122024156.284180-2-sandals@crustytoothpaste.net","threadId":"44935","inReplyTo":"20170122024156.284180-1-sandals@crustytoothpaste.net","subject":"[PATCH v2 1/7] Documentation: fix warning in cat-texi.perl","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-22T02:41:50Z","receivedAt":"2017-01-22T02:42:13Z","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 \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 () {\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":"309916","messageId":"20170122024156.284180-1-sandals@crustytoothpaste.net","threadId":"44935","inReplyTo":null,"subject":"[PATCH v2 0/7] Macros for Asciidoctor support","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-22T02:41:49Z","receivedAt":"2017-01-22T02:42:17Z","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\nChanges from v1:\n* Fix a brown-paper-bag bug.\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":"309917","messageId":"20170122024156.284180-5-sandals@crustytoothpaste.net","threadId":"44935","inReplyTo":"20170122024156.284180-1-sandals@crustytoothpaste.net","subject":"[PATCH v2 4/7] Documentation: sort sources for gitman.texi","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-22T02:41:53Z","receivedAt":"2017-01-22T02:42:20Z","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 \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":"309918","messageId":"20170122024156.284180-4-sandals@crustytoothpaste.net","threadId":"44935","inReplyTo":"20170122024156.284180-1-sandals@crustytoothpaste.net","subject":"[PATCH v2 3/7] Documentation: remove unneeded argument in cat-texi.perl","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-22T02:41:52Z","receivedAt":"2017-01-22T02:42:25Z","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 \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 () {\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":"309919","messageId":"20170122024156.284180-3-sandals@crustytoothpaste.net","threadId":"44935","inReplyTo":"20170122024156.284180-1-sandals@crustytoothpaste.net","subject":"[PATCH v2 2/7] Documentation: modernize cat-texi.perl","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-22T02:41:51Z","receivedAt":"2017-01-22T02:42:26Z","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 \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 () {\n \tnext if (/^\\\\input texinfo/../\\@node Top/);\n@@ -13,9 +16,9 @@ while () {\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 () {\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":"309920","messageId":"20170122024156.284180-7-sandals@crustytoothpaste.net","threadId":"44935","inReplyTo":"20170122024156.284180-1-sandals@crustytoothpaste.net","subject":"[PATCH v2 6/7] Documentation: move dblatex arguments into variable","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-22T02:41:55Z","receivedAt":"2017-01-22T02:42:29Z","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 \n---\n Documentation/Makefile | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 76be7017c..d95002e62 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":"309921","messageId":"20170122024156.284180-8-sandals@crustytoothpaste.net","threadId":"44935","inReplyTo":"20170122024156.284180-1-sandals@crustytoothpaste.net","subject":"[PATCH v2 7/7] Makefile: add a knob to enable the use of Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-22T02:41:56Z","receivedAt":"2017-01-22T02:42:30Z","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 \n---\n Documentation/Makefile | 12 ++++++++++++\n Makefile | 6 ++++++\n 2 files changed, 18 insertions(+)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex d95002e62..19c42eb60 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":"309922","messageId":"20170122024156.284180-6-sandals@crustytoothpaste.net","threadId":"44935","inReplyTo":"20170122024156.284180-1-sandals@crustytoothpaste.net","subject":"[PATCH v2 5/7] Documentation: add XSLT to fix DocBook for Texinfo","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-22T02:41:54Z","receivedAt":"2017-01-22T02:42:33Z","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 \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+\n+\n+\n+\n+\n+\n+\trefsect\n+\t\n+\t\t\n+\t\n+\n+\n+\n+\n+\t\n+\t\t\n+\t\n+\n+\n+\n"},{"id":"309968","messageId":"20170123025712.o52hgkdu26h6lrm2@sunbase.org","threadId":"44935","inReplyTo":"20170122024156.284180-8-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 7/7] Makefile: add a knob to enable the use of Asciidoctor","fromName":"Øyvind A. Holm","fromEmail":"sunny@sunbase.org","sentAt":"2017-01-23T02:57:13Z","receivedAt":"2017-01-23T02:57:20Z","isPatch":true,"sender":{"key":"sunny@sunbase.org","avatar":"https://avatars.githubusercontent.com/u/113445?v=4"},"body":"On 2017-01-22 02:41:56, brian m. carlson wrote:\n> While Git has traditionally built its documentation using AsciiDoc, some\n> people wish to use Asciidoctor for speed or other reasons. Add a\n> Makefile knob, USE_ASCIIDOCTOR, that sets various options in order to\n> produce acceptable output. For HTML output, XHTML5 was chosen, since\n> the AsciiDoc options also produce XHTML, albeit XHTML 1.1.\n\nI applied and tested the patches on the current master, commit \n787f75f0567a (\"Sixth batch for 2.12\"), and \"make doc\" with \nUSE_ASCIIDOCTOR fails:\n\n $ git clean -fxd && make doc USE_ASCIIDOCTOR=1\n Removing Documentation/cmd-list.made\n Removing Documentation/cmds-ancillaryinterrogators.txt\n Removing Documentation/cmds-ancillarymanipulators.txt\n Removing Documentation/cmds-foreignscminterface.txt\n Removing Documentation/cmds-mainporcelain.txt\n Removing Documentation/cmds-plumbinginterrogators.txt\n Removing Documentation/cmds-plumbingmanipulators.txt\n Removing Documentation/cmds-purehelpers.txt\n Removing Documentation/cmds-synchelpers.txt\n Removing Documentation/cmds-synchingrepositories.txt\n Removing Documentation/doc.dep\n Removing Documentation/mergetools-diff.txt\n Removing Documentation/mergetools-list.made\n Removing Documentation/mergetools-merge.txt\n Removing GIT-VERSION-FILE\n GIT_VERSION = 2.11.0.460.g218feb5a0e89\n make -C Documentation all\n make[1]: Entering directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'\n GEN mergetools-list.made\n GEN cmd-list.made\n GEN doc.dep\n make[2]: Entering directory '/home/sunny/src/git/src-other/devel/git/git'\n make[2]: 'GIT-VERSION-FILE' is up to date.\n make[2]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git'\n make[2]: Entering directory '/home/sunny/src/git/src-other/devel/git/git'\n make[2]: 'GIT-VERSION-FILE' is up to date.\n make[2]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git'\n ASCIIDOC git-init-db.html\n Couldn't find a view in @views for document\n Use --trace for backtrace\n Makefile:330: recipe for target 'git-init-db.html' failed\n make[1]: *** [git-init-db.html] Error 1\n make[1]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'\n Makefile:2091: recipe for target 'doc' failed\n make: *** [doc] Error 2\n 2017-01-23 03:50:05 sunny@sunbase:~/src/git/src-other/devel/git/git (tp-bmc-asciidoctor)\n\n $ lsb_release -d\n Description: Debian GNU/Linux 8.7 (jessie)\n\n $ asciidoctor --version\n Asciidoctor 0.1.4 [http://asciidoctor.org]\n\nI installed Asciidoctor with a standard \"apt-get install asciidoctor\", \ndo I need to install more packages?\n\nThe build is broken by patch #7 (\"Makefile: add a knob to enable the use \nof Asciidoctor\"), the other commits seems to work, though I haven't \ntested them all individually yet. Standard \"make doc\" works.\n\nRegards,\nØyvind\n\n+-| Øyvind A. Holm - 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+------------| 60bceb4e-e116-11e6-8fac-db5caa6d21d3 |-------------+\n"},{"id":"309969","messageId":"20170123040917.lrd6ic6wb6nxulzf@genre.crustytoothpaste.net","threadId":"44935","inReplyTo":"20170123025712.o52hgkdu26h6lrm2@sunbase.org","subject":"Re: [PATCH v2 7/7] Makefile: add a knob to enable the use of Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-23T04:09:17Z","receivedAt":"2017-01-23T04:09:30Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Mon, Jan 23, 2017 at 03:57:13AM +0100, Øyvind A. Holm wrote:\n> On 2017-01-22 02:41:56, brian m. carlson wrote:\n> > While Git has traditionally built its documentation using AsciiDoc, some\n> > people wish to use Asciidoctor for speed or other reasons. Add a\n> > Makefile knob, USE_ASCIIDOCTOR, that sets various options in order to\n> > produce acceptable output. For HTML output, XHTML5 was chosen, since\n> > the AsciiDoc options also produce XHTML, albeit XHTML 1.1.\n> \n> I applied and tested the patches on the current master, commit \n> 787f75f0567a (\"Sixth batch for 2.12\"), and \"make doc\" with \n> USE_ASCIIDOCTOR fails:\n> \n> $ git clean -fxd && make doc USE_ASCIIDOCTOR=1\n> Removing Documentation/cmd-list.made\n> Removing Documentation/cmds-ancillaryinterrogators.txt\n> Removing Documentation/cmds-ancillarymanipulators.txt\n> Removing Documentation/cmds-foreignscminterface.txt\n> Removing Documentation/cmds-mainporcelain.txt\n> Removing Documentation/cmds-plumbinginterrogators.txt\n> Removing Documentation/cmds-plumbingmanipulators.txt\n> Removing Documentation/cmds-purehelpers.txt\n> Removing Documentation/cmds-synchelpers.txt\n> Removing Documentation/cmds-synchingrepositories.txt\n> Removing Documentation/doc.dep\n> Removing Documentation/mergetools-diff.txt\n> Removing Documentation/mergetools-list.made\n> Removing Documentation/mergetools-merge.txt\n> Removing GIT-VERSION-FILE\n> GIT_VERSION = 2.11.0.460.g218feb5a0e89\n> make -C Documentation all\n> make[1]: Entering directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'\n> GEN mergetools-list.made\n> GEN cmd-list.made\n> GEN doc.dep\n> make[2]: Entering directory '/home/sunny/src/git/src-other/devel/git/git'\n> make[2]: 'GIT-VERSION-FILE' is up to date.\n> make[2]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git'\n> make[2]: Entering directory '/home/sunny/src/git/src-other/devel/git/git'\n> make[2]: 'GIT-VERSION-FILE' is up to date.\n> make[2]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git'\n> ASCIIDOC git-init-db.html\n> Couldn't find a view in @views for document\n> Use --trace for backtrace\n> Makefile:330: recipe for target 'git-init-db.html' failed\n> make[1]: *** [git-init-db.html] Error 1\n> make[1]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'\n> Makefile:2091: recipe for target 'doc' failed\n> make: *** [doc] Error 2\n> 2017-01-23 03:50:05 sunny@sunbase:~/src/git/src-other/devel/git/git (tp-bmc-asciidoctor)\n> \n> $ lsb_release -d\n> Description: Debian GNU/Linux 8.7 (jessie)\n> \n> $ asciidoctor --version\n> Asciidoctor 0.1.4 [http://asciidoctor.org]\n> \n> I installed Asciidoctor with a standard \"apt-get install asciidoctor\", \n> do I need to install more packages?\n> \n> The build is broken by patch #7 (\"Makefile: add a knob to enable the use \n> of Asciidoctor\"), the other commits seems to work, though I haven't \n> tested them all individually yet. Standard \"make doc\" works.\n\nI think you need a newer version of Asciidoctor. I fixed one or two\nissues upstream in 1.5.2, I think, that made it work properly.\n\nYou could try to do the build with the \"html5\" target instead of\n\"xhtml5\" and see if that works. If so, we could switch to that instead\nif we want to support older Asciidoctor versions.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"310000","messageId":"xmqqa8ahsiuq.fsf@gitster.mtv.corp.google.com","threadId":"44935","inReplyTo":"20170122024156.284180-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 0/7] Macros for Asciidoctor support","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-23T18:59:25Z","receivedAt":"2017-01-23T18:59:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n> There are two major processors of AsciiDoc: AsciiDoc itself, and Asciidoctor.\n> Both have advantages and disadvantages, but traditionally the documentation has\n> been built with AsciiDoc, leading to some surprising breakage when building with\n> Asciidoctor. Partially, this is due to the need to specify a significant number\n> of macros on the command line when building with Asciidoctor.\n>\n> This series cleans up some issues building the documentation with Asciidoctor\n> and provides two knobs, USE_ASCIIDOCTOR, which controls building with\n> Asciidoctor, and ASCIIDOCTOR_EXTENSIONS_LAB, which controls the location of the\n> Asciidoctor Extensions Lab, which is necessary to expand the linkgit macro.\n>\n> The need for the extensions could be replaced with a small amount of Ruby code,\n> if that's considered desirable. Previous opinions on doing so were negative,\n> however.\n>\n> In the process, I found several issues with cat-texi.perl, which have been\n> fixed. It has also been modernized to use strict, warnings, and lexical file\n> handles. I also made an attempt to produce more diffable texi files; I may\n> follow up with additional series along this line to make the documentation build\n> reproducibly.\n\nThanks. We'd probably want INSTALL to talk about Asciidoctor once\nthis matures, as it is very simple requirement for the builder to\nhave to just set USE_ASCIIDOCTOR, but the version requirement and\nstuff might be still confusing.\n"},{"id":"310135","messageId":"20170125022628.dyqokkdfxasfxjrl@sunbase.org","threadId":"44935","inReplyTo":"20170123040917.lrd6ic6wb6nxulzf@genre.crustytoothpaste.net","subject":"Re: [PATCH v2 7/7] Makefile: add a knob to enable the use of Asciidoctor","fromName":"Øyvind A. Holm","fromEmail":"sunny@sunbase.org","sentAt":"2017-01-25T02:26:30Z","receivedAt":"2017-01-25T02:26:40Z","isPatch":true,"sender":{"key":"sunny@sunbase.org","avatar":"https://avatars.githubusercontent.com/u/113445?v=4"},"body":"On 2017-01-23 04:09:17, brian m. carlson wrote:\n> On Mon, Jan 23, 2017 at 03:57:13AM +0100, Øyvind A. Holm wrote:\n> > On 2017-01-22 02:41:56, brian m. carlson wrote:\n> > > While Git has traditionally built its documentation using \n> > > AsciiDoc, some people wish to use Asciidoctor for speed or other \n> > > reasons. Add a Makefile knob, USE_ASCIIDOCTOR, that sets various \n> > > options in order to produce acceptable output. For HTML output, \n> > > XHTML5 was chosen, since the AsciiDoc options also produce XHTML, \n> > > albeit XHTML 1.1.\n> >\n> > I applied and tested the patches on the current master, commit \n> > 787f75f0567a (\"Sixth batch for 2.12\"), and \"make doc\" with \n> > USE_ASCIIDOCTOR fails:\n> >\n> > [...]\n> >\n> > $ asciidoctor --version\n> > Asciidoctor 0.1.4 [http://asciidoctor.org]\n>\n> I think you need a newer version of Asciidoctor. I fixed one or two \n> issues upstream in 1.5.2, I think, that made it work properly.\n\nI've tried on Linux Mint 18 with Asciidoctor 1.5.4 now, and it works \nthere, so the version is probably too old, yes.\n\n> You could try to do the build with the \"html5\" target instead of \n> \"xhtml5\" and see if that works. If so, we could switch to that \n> instead if we want to support older Asciidoctor versions.\n\nIt went a little better, but after a while it died with\n\n $ make doc USE_ASCIIDOCTOR=1\n [Cut 249 lines]\n GEN technical/api-index.txt\n ASCIIDOC technical/api-index.html\n ASCIIDOC git-init-db.xml\n sed \"s|@@MAN_BASE_URL@@|file:///home/sunny/share/doc/git-doc/|\" manpage-base-url.xsl.in > manpage-base-url.xsl\n XMLTO git-init-db.1\n xmlto: /home/sunny/src/git/src-other/devel/git/git/Documentation/git-init-db.xml does not validate (status 3)\n xmlto: Fix document syntax or use --skip-validation option\n /home/sunny/src/git/src-other/devel/git/git/Documentation/git-init-db.xml:5: element article: validity error : root and DTD name do not match 'article' and 'manpage'\n Document /home/sunny/src/git/src-other/devel/git/git/Documentation/git-init-db.xml does not validate\n Makefile:343: recipe for target 'git-init-db.1' failed\n make[1]: *** [git-init-db.1] Error 13\n make[1]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'\n Makefile:2091: recipe for target 'doc' failed\n make: *** [doc] Error 2\n $\n\nand that's fair enough, since the generated html isn't well-formed. \nAdding --skip-validation to XMLTO_EXTRA gave a slightly different \nresult:\n\n GEN technical/api-index.txt\n ASCIIDOC technical/api-index.html\n ASCIIDOC git-init-db.xml\n sed \"s|@@MAN_BASE_URL@@|file:///home/sunny/share/doc/git-doc/|\" manpage-base-url.xsl.in > manpage-base-url.xsl\n XMLTO git-init-db.1\n Note: namesp. cut : stripped namespace before processing git-init-db(1)\n Note: namesp. cut : processing stripped document git-init-db(1)\n Erro: no refentry: No refentry elements found in \"git-init-db(1) git-init-db(1)\n Makefile:343: recipe for target 'git-init-db.1' failed\n make[1]: *** [git-init-db.1] Error 1\n make[1]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'\n Makefile:2091: recipe for target 'doc' failed\n make: *** [doc] Error 2\n $\n\nBut frankly, this probably isn't a showstopper. Even though this is the \nnewest stable version of Debian, Asciidoctor 0.1.4 was released \n2013-09-05, 3y5m ago. USE_ASCIIDOCTOR isn't the default, so people can \nbuild the docs with asciidoc, and that works in Debian 8.7.\n\nRegards,\nØyvind\n\n+-| Øyvind A. Holm - 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+------------| 1698e7f6-e257-11e6-bfa0-db5caa6d21d3 |-------------+\n"},{"id":"310160","messageId":"alpine.DEB.2.20.1701251425080.3469@virtualbox","threadId":"44935","inReplyTo":"20170122024156.284180-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 0/7] Macros for Asciidoctor support","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2017-01-25T13:28:55Z","receivedAt":"2017-01-25T13:29:34Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Brian,\n\nOn Sun, 22 Jan 2017, brian m. carlson wrote:\n\n> There are two major processors of AsciiDoc: AsciiDoc itself, and\n> Asciidoctor. Both have advantages and disadvantages, but traditionally\n> the documentation has been built with AsciiDoc, leading to some\n> surprising breakage when building with Asciidoctor. Partially, this is\n> due to the need to specify a significant number of macros on the command\n> line when building with Asciidoctor.\n> \n> This series cleans up some issues building the documentation with\n> Asciidoctor and provides two knobs, USE_ASCIIDOCTOR, which controls\n> building with Asciidoctor, and ASCIIDOCTOR_EXTENSIONS_LAB, which\n> controls the location of the Asciidoctor Extensions Lab, which is\n> necessary to expand the linkgit macro.\n\nI like it.\n\nI reviewed all the patches and think they are good (except the XSLT patch,\nwhich made me just feel incompetent because I do not know enough to have\nan opinion about it).\n\n> The need for the extensions could be replaced with a small amount of\n> Ruby code, if that's considered desirable. Previous opinions on doing\n> so were negative, however.\n\nQuite frankly, it is annoying to be forced to install the extensions. I\nwould much rather have the small amount of Ruby code in Git's repository.\n\nThanks,\nJohannes\n"},{"id":"310214","messageId":"20170125213544.eelk4pjhrhshi6zh@sigill.intra.peff.net","threadId":"44935","inReplyTo":"alpine.DEB.2.20.1701251425080.3469@virtualbox","subject":"Re: [PATCH v2 0/7] Macros for Asciidoctor support","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-01-25T21:35:44Z","receivedAt":"2017-01-25T21:35:54Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jan 25, 2017 at 02:28:55PM +0100, Johannes Schindelin wrote:\n\n> > The need for the extensions could be replaced with a small amount of\n> > Ruby code, if that's considered desirable. Previous opinions on doing\n> > so were negative, however.\n> \n> Quite frankly, it is annoying to be forced to install the extensions. I\n> would much rather have the small amount of Ruby code in Git's repository.\n\nMe too. Dependencies can be a big annoyance. I'd reserve judgement until\nI saw the actual Ruby code, though. :)\n\n-Peff\n"},{"id":"310256","messageId":"20170125231926.usufhlugjotjw5zw@genre.crustytoothpaste.net","threadId":"44935","inReplyTo":"20170125213544.eelk4pjhrhshi6zh@sigill.intra.peff.net","subject":"Re: [PATCH v2 0/7] Macros for Asciidoctor support","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-25T23:19:26Z","receivedAt":"2017-01-25T23:19:37Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Wed, Jan 25, 2017 at 04:35:44PM -0500, Jeff King wrote:\n> On Wed, Jan 25, 2017 at 02:28:55PM +0100, Johannes Schindelin wrote:\n> \n> > > The need for the extensions could be replaced with a small amount of\n> > > Ruby code, if that's considered desirable. Previous opinions on doing\n> > > so were negative, however.\n> > \n> > Quite frankly, it is annoying to be forced to install the extensions. I\n> > would much rather have the small amount of Ruby code in Git's repository.\n> \n> Me too. Dependencies can be a big annoyance. I'd reserve judgement until\n> I saw the actual Ruby code, though. :)\n\nI've sent the patch before, but I can send it again. It's relatively\nsmall and self-contained. I'm also happy to be responsible for\nmaintaining it.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"310262","messageId":"20170125232959.zdbf3n3ey7qtnv7j@sigill.intra.peff.net","threadId":"44935","inReplyTo":"20170125231926.usufhlugjotjw5zw@genre.crustytoothpaste.net","subject":"Re: [PATCH v2 0/7] Macros for Asciidoctor support","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-01-25T23:30:00Z","receivedAt":"2017-01-25T23:30:11Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jan 25, 2017 at 11:19:26PM +0000, brian m. carlson wrote:\n\n> On Wed, Jan 25, 2017 at 04:35:44PM -0500, Jeff King wrote:\n> > On Wed, Jan 25, 2017 at 02:28:55PM +0100, Johannes Schindelin wrote:\n> > \n> > > > The need for the extensions could be replaced with a small amount of\n> > > > Ruby code, if that's considered desirable. Previous opinions on doing\n> > > > so were negative, however.\n> > > \n> > > Quite frankly, it is annoying to be forced to install the extensions. I\n> > > would much rather have the small amount of Ruby code in Git's repository.\n> > \n> > Me too. Dependencies can be a big annoyance. I'd reserve judgement until\n> > I saw the actual Ruby code, though. :)\n> \n> I've sent the patch before, but I can send it again. It's relatively\n> small and self-contained. I'm also happy to be responsible for\n> maintaining it.\n\nAh, it's:\n\n http://public-inbox.org/git/1413070656-241955-5-git-send-email-sandals@crustytoothpaste.net/\n\n(and note there is some surrounding discussion there).\n\nThe code is not _too_ bad. The main thing is that it would have to be\nkept up to date with changes to asciidoc.conf's version of the linkgit\nmacro. But it's not like that changes frequently.\n\n-Peff\n"},{"id":"310266","messageId":"20170125234101.n2pzrp77df4zycv7@genre.crustytoothpaste.net","threadId":"44935","inReplyTo":"20170125232959.zdbf3n3ey7qtnv7j@sigill.intra.peff.net","subject":"Re: [PATCH v2 0/7] Macros for Asciidoctor support","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-25T23:41:01Z","receivedAt":"2017-01-25T23:41:10Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Wed, Jan 25, 2017 at 06:30:00PM -0500, Jeff King wrote:\n> On Wed, Jan 25, 2017 at 11:19:26PM +0000, brian m. carlson wrote:\n> \n> > On Wed, Jan 25, 2017 at 04:35:44PM -0500, Jeff King wrote:\n> > > On Wed, Jan 25, 2017 at 02:28:55PM +0100, Johannes Schindelin wrote:\n> > > \n> > > > > The need for the extensions could be replaced with a small amount of\n> > > > > Ruby code, if that's considered desirable. Previous opinions on doing\n> > > > > so were negative, however.\n> > > > \n> > > > Quite frankly, it is annoying to be forced to install the extensions. I\n> > > > would much rather have the small amount of Ruby code in Git's repository.\n> > > \n> > > Me too. Dependencies can be a big annoyance. I'd reserve judgement until\n> > > I saw the actual Ruby code, though. :)\n> > \n> > I've sent the patch before, but I can send it again. It's relatively\n> > small and self-contained. I'm also happy to be responsible for\n> > maintaining it.\n> \n> Ah, it's:\n> \n> http://public-inbox.org/git/1413070656-241955-5-git-send-email-sandals@crustytoothpaste.net/\n> \n> (and note there is some surrounding discussion there).\n> \n> The code is not _too_ bad. The main thing is that it would have to be\n> kept up to date with changes to asciidoc.conf's version of the linkgit\n> macro. But it's not like that changes frequently.\n\nYes. I think I can actually simplify it some more, since we always seem\nto use the argument to linkgit, so I'll send out a simplified patch in a\nfew minutes.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"310272","messageId":"20170126001344.445534-1-sandals@crustytoothpaste.net","threadId":"44935","inReplyTo":"20170125234101.n2pzrp77df4zycv7@genre.crustytoothpaste.net","subject":"[PATCH] Documentation: implement linkgit macro for Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-26T00:13:44Z","receivedAt":"2017-01-26T00:13:57Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"AsciiDoc uses a configuration file to implement macros like linkgit,\nwhile Asciidoctor uses Ruby extensions. Implement a Ruby extension that\nimplements the linkgit macro for Asciidoctor in the same way that\nasciidoc.conf does for AsciiDoc. Adjust the Makefile to use it by\ndefault.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/Makefile | 5 +----\n Documentation/asciidoctor-extensions.rb | 28 ++++++++++++++++++++++++++++\n 2 files changed, 29 insertions(+), 4 deletions(-)\n create mode 100644 Documentation/asciidoctor-extensions.rb\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 19c42eb60..d1b7a6865 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -179,10 +179,7 @@ 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+ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions -alitdd='&\\#x2d;&\\#x2d;'\n DBLATEX_COMMON =\n endif\n \ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nnew file mode 100644\nindex 000000000..09f7088ee\n--- /dev/null\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -0,0 +1,28 @@\n+require 'asciidoctor'\n+require 'asciidoctor/extensions'\n+\n+module Git\n+ module Documentation\n+ class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor\n+ use_dsl\n+\n+ named :chrome\n+\n+ def process(parent, target, attrs)\n+ if parent.document.basebackend? 'html'\n+ prefix = parent.document.attr('git-relative-html-prefix')\n+ %(#{target}(#{attrs[1]})\\n)\n+ elsif parent.document.basebackend? 'docbook'\n+ %(\n+#{target}#{attrs[1]}\n+\n+)\n+ end\n+ end\n+ end\n+ end\n+end\n+\n+Asciidoctor::Extensions.register do\n+ inline_macro Git::Documentation::LinkGitProcessor, :linkgit\n+end\n-- \n2.11.0\n\n"},{"id":"310287","messageId":"20170126034655.fwzow2mgkjj5dpek@sigill.intra.peff.net","threadId":"44935","inReplyTo":"20170126001344.445534-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-01-26T03:46:56Z","receivedAt":"2017-01-26T03:47:03Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Jan 26, 2017 at 12:13:44AM +0000, brian m. carlson wrote:\n\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 19c42eb60..d1b7a6865 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -179,10 +179,7 @@ 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> +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions -alitdd='&\\#x2d;&\\#x2d;'\n\nMight be more readable to just leave the litdd part on its own line.\n\n> diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\n> new file mode 100644\n> index 000000000..09f7088ee\n> --- /dev/null\n> +++ b/Documentation/asciidoctor-extensions.rb\n> @@ -0,0 +1,28 @@\n> +require 'asciidoctor'\n> +require 'asciidoctor/extensions'\n> +\n> +module Git\n> + module Documentation\n> + class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor\n> + use_dsl\n> +\n> + named :chrome\n> +\n> + def process(parent, target, attrs)\n> + if parent.document.basebackend? 'html'\n> + prefix = parent.document.attr('git-relative-html-prefix')\n> + %(#{target}(#{attrs[1]})\\n)\n> + elsif parent.document.basebackend? 'docbook'\n> + %(\n> +#{target}#{attrs[1]}\n> +\n> +)\n> + end\n> + end\n> + end\n> + end\n> +end\n\nI think this looks reasonable. There's some boilerplate, but even as\nsomebody not familiar with asciidoctor, it's all quite obvious.\n\nThe multi-line string is kind of ugly because of the indentation.\nApparently Ruby has here-docs that will eat leading whitespace, but the\nsyntax was not introduce until Ruby 2.3, which is probably more recent\nthan we should count on.\n\nI think you could write:\n\n %(\n #{target}#{attrs[1]}\n \n\t ).gsub(/^\\s*/, \"\")\n\nI don't know if that's too clever or not.\n\nBut either way, I like this better than introducing an extra dependency.\n\n-Peff\n"},{"id":"310296","messageId":"20170126074304.GA26530@starla","threadId":"44935","inReplyTo":"20170126034655.fwzow2mgkjj5dpek@sigill.intra.peff.net","subject":"Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor","fromName":"Eric Wong","fromEmail":"e@80x24.org","sentAt":"2017-01-26T07:43:04Z","receivedAt":"2017-01-26T07:43:10Z","isPatch":true,"sender":{"key":"e@80x24.org","avatar":null},"body":"Jeff King wrote:\n> On Thu, Jan 26, 2017 at 12:13:44AM +0000, brian m. carlson wrote:\n> > +\n> > + def process(parent, target, attrs)\n> > + if parent.document.basebackend? 'html'\n> > + prefix = parent.document.attr('git-relative-html-prefix')\n> > + %(#{target}(#{attrs[1]})\\n)\n> > + elsif parent.document.basebackend? 'docbook'\n> > + %(\n> > +#{target}#{attrs[1]}\n> > +\n> > +)\n\n\n\n> The multi-line string is kind of ugly because of the indentation.\n> Apparently Ruby has here-docs that will eat leading whitespace, but the\n> syntax was not introduce until Ruby 2.3, which is probably more recent\n> than we should count on.\n\nYou can use '\\' to continue long lines with any Ruby version:\n\n \"\" \\\n \"#{target}\" \\\n \"#{attrs[1]}\" \\\n \"\"\n\nThe above happens during the parse phase, so there's no garbage\nor method call overhead compared to the more-frequently seen '+'\nor '<<' method calls to combine strings.\n\n> I think you could write:\n> \n> %(\n> #{target}#{attrs[1]}\n> \n> \t ).gsub(/^\\s*/, \"\")\n> \n> I don't know if that's too clever or not.\n\nIck...\n\n> But either way, I like this better than introducing an extra dependency.\n\nAgreed.\n"},{"id":"310305","messageId":"alpine.DEB.2.20.1701261242430.3469@virtualbox","threadId":"44935","inReplyTo":"20170126001344.445534-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2017-01-26T11:43:04Z","receivedAt":"2017-01-26T11:50:34Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Brian,\n\nOn Thu, 26 Jan 2017, brian m. carlson wrote:\n\n> AsciiDoc uses a configuration file to implement macros like linkgit,\n> while Asciidoctor uses Ruby extensions. Implement a Ruby extension that\n> implements the linkgit macro for Asciidoctor in the same way that\n> asciidoc.conf does for AsciiDoc. Adjust the Makefile to use it by\n> default.\n\nI like it.\n\nThank you,\nJohannes\n"},{"id":"310351","messageId":"20170126191841.GA6060@dcvr.yhbt.net","threadId":"44935","inReplyTo":"xmqq1svp7lcs.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor","fromName":"Eric Wong","fromEmail":"e@80x24.org","sentAt":"2017-01-26T19:18:41Z","receivedAt":"2017-01-26T19:19:26Z","isPatch":true,"sender":{"key":"e@80x24.org","avatar":null},"body":"> Eric Wong writes:\n> > You can use '\\' to continue long lines with any Ruby version:\n> >\n> > \"\" \\\n> > \"#{target}\" \\\n> > \"#{attrs[1]}\" \\\n> > \"\"\n\nJunio C Hamano wrote:\n> + \"\\n\"\n> + \"#{target}\"\n> + \"#{attrs[1]}\\n\"\n> + \"\\n\"\n> end\n\nYou need the '\\' at the end of those strings, it's not like C\nsince Ruby doesn't require semi-colons to terminate lines.\nIn other words, that should be:\n\n \"\\n\" \\\n \"#{target}\" \\\n \"#{attrs[1]}\\n\" \\\n \"\\n\"\n"},{"id":"310379","messageId":"20170127004050.23jrq5iqwfxcwmik@genre.crustytoothpaste.net","threadId":"44935","inReplyTo":"20170126191841.GA6060@dcvr.yhbt.net","subject":"Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-27T00:40:50Z","receivedAt":"2017-01-27T00:42:20Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Thu, Jan 26, 2017 at 07:18:41PM +0000, Eric Wong wrote:\n> > Eric Wong writes:\n> Junio C Hamano wrote:\n> > + \"\\n\"\n> > + \"#{target}\"\n> > + \"#{attrs[1]}\\n\"\n> > + \"\\n\"\n> > end\n> \n> You need the '\\' at the end of those strings, it's not like C\n> since Ruby doesn't require semi-colons to terminate lines.\n> In other words, that should be:\n> \n> \"\\n\" \\\n> \"#{target}\" \\\n> \"#{attrs[1]}\\n\" \\\n> \"\\n\"\n> \n\nThis change is fine with me.\n\nFor the record, I don't have a strong opinion one way or the other.\nSince this code is related to Asciidoctor and Git has no existing Ruby\nstyle standards, I picked the Asciidoctor house style, which uses\nmulti-line %(). We could pick [0] as an option, or just argue it out\nwhen someone cares, like here.\n\n[0] https://github.com/bbatsov/ruby-style-guide\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"310614","messageId":"xmqqtw8fq8vv.fsf@gitster.mtv.corp.google.com","threadId":"44935","inReplyTo":"20170127004050.23jrq5iqwfxcwmik@genre.crustytoothpaste.net","subject":"Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-31T20:20:20Z","receivedAt":"2017-01-31T20:20:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n> On Thu, Jan 26, 2017 at 07:18:41PM +0000, Eric Wong wrote:\n>> > Eric Wong writes:\n>> Junio C Hamano wrote:\n>> > + \"\\n\"\n>> > + \"#{target}\"\n>> > + \"#{attrs[1]}\\n\"\n>> > + \"\\n\"\n>> > end\n>> \n>> You need the '\\' at the end of those strings, it's not like C\n>> since Ruby doesn't require semi-colons to terminate lines.\n>> In other words, that should be:\n>> \n>> \"\\n\" \\\n>> \"#{target}\" \\\n>> \"#{attrs[1]}\\n\" \\\n>> \"\\n\"\n>> \n>\n> This change is fine with me.\n\nOK, I just squashed the final one in. Will merge to 'next' shortly.\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 11f76506b6..b21e5808b1 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -179,7 +179,8 @@ ASCIIDOC = asciidoctor\n ASCIIDOC_CONF =\n ASCIIDOC_HTML = xhtml5\n ASCIIDOC_DOCBOOK = docbook45\n-ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions -alitdd='&\\#x2d;&\\#x2d;'\n+ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n+ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n DBLATEX_COMMON =\n endif\n \ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 09f7088eea..ec83b4959e 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -13,10 +13,10 @@ module Git\n prefix = parent.document.attr('git-relative-html-prefix')\n %(#{target}(#{attrs[1]})\\n)\n elsif parent.document.basebackend? 'docbook'\n- %(\n-#{target}#{attrs[1]}\n-\n-)\n+ \"\\n\" \\\n+ \"#{target}\" \\\n+ \"#{attrs[1]}\\n\" \\\n+ \"\\n\"\n end\n end\n end\n"}]}