{"thread":{"id":"37717","subject":"[PATCH 4/4] Documentation: implement linkgit macro for Asciidoctor","startedAt":"2014-10-11T23:37:32Z","lastAt":"2014-10-16T22:53:12Z","messageCount":19,"participants":["brian m. carlson","Junio C Hamano","Jakub Narębski","Jeff King","Thomas Braun","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"250515","messageId":"1413070656-241955-1-git-send-email-sandals@crustytoothpaste.net","threadId":"37717","inReplyTo":null,"subject":"[PATCH 0/4] Allow building Git with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-11T23:37:32Z","receivedAt":"2014-10-11T23:37:32Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"This series is designed to implement the changes necessary to build Git\nusing Asciidoctor instead of AsciiDoc.\n\nThe first two patches are bug fixes. Asciidoctor is stricter about\ntitle underline lengths (± 1 character instead of 2) and requires\nmatching delimiter lengths[0]. They're needed regardless of whether the\nother two patches are accepted because git-scm.com uses Asciidoctor to\nrender the documentation, so we might as well render it correctly.\n\nEven with these patches, Asciidoctor warns about everyday.txt and\nuser-manual.txt. I'm not sending patches for these right now because\nI've seen recent series including those and don't want to cause a\nmerge conflict.\n\nThe second two patches implement some basic support for building with\nAsciidoctor. The first of these moves some items into variables due to\nsome differences between the AsciiDoc and Asciidoctor command lines.\nThe user can then override these values when invoking make.\n\nThe final patch adds support for the linkgit macro. Asciidoctor uses\nRuby extensions to implement macro support, unlike AsciiDoc, which uses\na configuration file.\n\nIn order to build the documentation successfully, the patches from [1]\nare required. The current version of Asciidoctor uses the wrong\nelements in some cases and is lacking elements in others when generating\nmanpage (refentry) output in DocBook format. The need for these patches\nis also the reason I didn't implement a configuration macro for\nAsciidoctor, as almost nobody will be able to use it at the moment.\n\nWith these patches and the ones for Asciidoctor, it's possible to build\nthe documentation with the following command line:\n\n make doc ASCIIDOC=asciidoctor ASCIIDOC_DOCBOOK=docbook45 ASCIIDOC_HTML=html5 ASCIIDOC_CONF='-I. -rasciidoctor/extensions -rextensions'\n\nbrian m. carlson (4):\n Documentation: adjust document title underlining\n Documentation: fix mismatched delimiters in git-imap-send\n Documentation: move some AsciiDoc parameters into variables\n Documentation: implement linkgit macro for Asciidoctor\n\n Documentation/Makefile | 18 +++++++++++-------\n Documentation/extensions.rb | 39 ++++++++++++++++++++++++++++++++++++++\n Documentation/git-imap-send.txt | 4 ++--\n Documentation/git-prune-packed.txt | 2 +-\n Documentation/git-quiltimport.txt | 2 +-\n Documentation/git-stage.txt | 2 +-\n 6 files changed, 55 insertions(+), 12 deletions(-)\n create mode 100644 Documentation/extensions.rb\n\n[0] http://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/\n[1] https://github.com/asciidoctor/asciidoctor/pull/1142\n-- \n2.1.1\n"},{"id":"250518","messageId":"1413070656-241955-2-git-send-email-sandals@crustytoothpaste.net","threadId":"37717","inReplyTo":"1413070656-241955-1-git-send-email-sandals@crustytoothpaste.net","subject":"[PATCH 1/4] Documentation: adjust document title underlining","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-11T23:37:33Z","receivedAt":"2014-10-11T23:37:33Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"AsciiDoc specification states that in two-line titles, the title\nunderline has to be the same length as the title text, plus or minus two\ncharacters. Asciidoctor, however, requires that this must be plus or\nminus one character. Adjust the underlines to be the same length as the\ntitle text to improve compatibility.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/git-prune-packed.txt | 2 +-\n Documentation/git-quiltimport.txt | 2 +-\n Documentation/git-stage.txt | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt\nindex 6738055..9fed59a 100644\n--- a/Documentation/git-prune-packed.txt\n+++ b/Documentation/git-prune-packed.txt\n@@ -1,5 +1,5 @@\n git-prune-packed(1)\n-=====================\n+===================\n \n NAME\n ----\ndiff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt\nindex a356196..d64388c 100644\n--- a/Documentation/git-quiltimport.txt\n+++ b/Documentation/git-quiltimport.txt\n@@ -1,5 +1,5 @@\n git-quiltimport(1)\n-================\n+==================\n \n NAME\n ----\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex ba3fe0d..25bcda9 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -1,5 +1,5 @@\n git-stage(1)\n-==============\n+============\n \n NAME\n ----\n-- \n2.1.1\n"},{"id":"250517","messageId":"1413070656-241955-3-git-send-email-sandals@crustytoothpaste.net","threadId":"37717","inReplyTo":"1413070656-241955-1-git-send-email-sandals@crustytoothpaste.net","subject":"[PATCH 2/4] Documentation: fix mismatched delimiters in git-imap-send","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-11T23:37:34Z","receivedAt":"2014-10-11T23:37:34Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"The documentation for git-imap-send uses block delimiters with\nmismatched lengths, which Asciidoctor doesn't support. As a result, the\npage is misrendered. Adjust the delimiters so that they are of the same\nlength.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/git-imap-send.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt\nindex 7d991d9..c7c0d21 100644\n--- a/Documentation/git-imap-send.txt\n+++ b/Documentation/git-imap-send.txt\n@@ -97,7 +97,7 @@ Using direct mode:\n host = imap://imap.example.com\n user = bob\n pass = p4ssw0rd\n-..........................\n+.........................\n \n Using direct mode with SSL:\n \n@@ -109,7 +109,7 @@ Using direct mode with SSL:\n pass = p4ssw0rd\n port = 123\n sslverify = false\n-..........................\n+.........................\n \n \n EXAMPLE\n-- \n2.1.1\n"},{"id":"250516","messageId":"1413070656-241955-4-git-send-email-sandals@crustytoothpaste.net","threadId":"37717","inReplyTo":"1413070656-241955-1-git-send-email-sandals@crustytoothpaste.net","subject":"[PATCH 3/4] Documentation: move some AsciiDoc parameters into variables","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-11T23:37:35Z","receivedAt":"2014-10-11T23:37:35Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Asciidoctor takes slightly different arguments from AsciiDoc in some\ncases. It has a different name for the HTML backend and the \"docbook\"\nbackend produces DocBook 5, not DocBook 4.5. Also, Asciidoctor does not\naccept the -f option. Move these values into variables so that they can\nbe overridden by users wishing to use Asciidoctor instead of Asciidoc.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/Makefile | 18 +++++++++++-------\n 1 file changed, 11 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex cea0e7a..00c50bf 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -97,6 +97,9 @@ man7dir = $(mandir)/man7\n \n ASCIIDOC = asciidoc\n ASCIIDOC_EXTRA =\n+ASCIIDOC_HTML = xhtml11\n+ASCIIDOC_DOCBOOK = docbook\n+ASCIIDOC_CONF = -f asciidoc.conf\n MANPAGE_XSL = manpage-normal.xsl\n XMLTO = xmlto\n XMLTO_EXTRA =\n@@ -304,13 +307,13 @@ clean:\n \n $(MAN_HTML): %.html : %.txt asciidoc.conf\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \\\n+\t$(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage $(ASCIIDOC_CONF) \\\n \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \\\n \tmv $@+ $@\n \n $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \\\n+\t$(ASCIIDOC) -b $(ASCIIDOC_HTML) $(ASCIIDOC_CONF) \\\n \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \\\n \tmv $@+ $@\n \n@@ -323,13 +326,13 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n \n %.xml : %.txt asciidoc.conf\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \\\n+\t$(ASCIIDOC) -b $(ASCIIDOC_DOCBOOK) -d manpage $(ASCIIDOC_CONF) \\\n \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \\\n \tmv $@+ $@\n \n user-manual.xml: user-manual.txt user-manual.conf\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d article -o $@+ $< && \\\n+\t$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b $(ASCIIDOC_DOCBOOK) -d article -o $@+ $< && \\\n \tmv $@+ $@\n \n technical/api-index.txt: technical/api-index-skel.txt \\\n@@ -338,7 +341,7 @@ technical/api-index.txt: technical/api-index-skel.txt \\\n \n technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf\n-\t$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \\\n+\t$(QUIET_ASCIIDOC)$(ASCIIDOC) -b $(ASCIIDOC_HTML) $(ASCIIDOC_CONF) \\\n \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt\n \n XSLT = docbook.xsl\n@@ -386,14 +389,15 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n \tmv $@+ $@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n-\t$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt\n+\t$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b $(ASCIIDOC_HTML) $*.txt\n \n WEBDOC_DEST = /pub/software/scm/git/docs\n \n howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\tsed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \\\n+\tsed -e '1,/^$$/d' $< | \\\n+\t$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b $(ASCIIDOC_HTML) - >$@+ && \\\n \tmv $@+ $@\n \n install-webdoc : html\n-- \n2.1.1\n"},{"id":"250514","messageId":"1413070656-241955-5-git-send-email-sandals@crustytoothpaste.net","threadId":"37717","inReplyTo":"1413070656-241955-1-git-send-email-sandals@crustytoothpaste.net","subject":"[PATCH 4/4] Documentation: implement linkgit macro for Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-11T23:37:36Z","receivedAt":"2014-10-11T23:37:36Z","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.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/extensions.rb | 39 +++++++++++++++++++++++++++++++++++++++\n 1 file changed, 39 insertions(+)\n create mode 100644 Documentation/extensions.rb\n\ndiff --git a/Documentation/extensions.rb b/Documentation/extensions.rb\nnew file mode 100644\nindex 0000000..c33a50d\n--- /dev/null\n+++ b/Documentation/extensions.rb\n@@ -0,0 +1,39 @@\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+ generate_html(parent, target, attrs)\n+ elsif parent.document.basebackend? 'docbook'\n+ generate_docbook(parent, target, attrs)\n+ end\n+ end\n+\n+ private\n+\n+ def generate_html(parent, target, attrs)\n+ section = attrs.has_key?(1) ? \"(#{attrs[1]})\" : ''\n+ prefix = parent.document.attr('git-relative-html-prefix') || ''\n+ %(#{target}#{section}\\n)\n+ end\n+\n+ def generate_docbook(parent, target, attrs)\n+ %(\n+#{target}#{attrs[1]}\n+\n+)\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.1.1\n"},{"id":"250574","messageId":"xmqqy4sj1ze9.fsf@gitster.dls.corp.google.com","threadId":"37717","inReplyTo":"1413070656-241955-2-git-send-email-sandals@crustytoothpaste.net","subject":"Re: [PATCH 1/4] Documentation: adjust document title underlining","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-13T20:35:26Z","receivedAt":"2014-10-13T20:35:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thanks, obviously correct.\n"},{"id":"250575","messageId":"xmqqtx371z44.fsf@gitster.dls.corp.google.com","threadId":"37717","inReplyTo":"1413070656-241955-1-git-send-email-sandals@crustytoothpaste.net","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-13T20:41:31Z","receivedAt":"2014-10-13T20:41:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n> This series is designed to implement the changes necessary to build Git\n> using Asciidoctor instead of AsciiDoc.\n>\n> The first two patches are bug fixes. Asciidoctor is stricter about\n> title underline lengths (± 1 character instead of 2) and requires\n> matching delimiter lengths[0]. They're needed regardless of whether the\n> other two patches are accepted because git-scm.com uses Asciidoctor to\n> render the documentation, so we might as well render it correctly.\n>\n> Even with these patches, Asciidoctor warns about everyday.txt and\n> user-manual.txt. I'm not sending patches for these right now because\n> I've seen recent series including those and don't want to cause a\n> merge conflict.\n\nSounds good.\n\n> The second two patches implement some basic support for building with\n> Asciidoctor. The first of these moves some items into variables due to\n> some differences between the AsciiDoc and Asciidoctor command lines.\n> The user can then override these values when invoking make.\n>\n> The final patch adds support for the linkgit macro. Asciidoctor uses\n> Ruby extensions to implement macro support, unlike AsciiDoc, which uses\n> a configuration file.\n\nWhat I do not understand is that 3/4 lets you drop inclusion of\nasciidoc.conf which contains a lot more than just linkgit:\ndefinition.\n\nFor now I'll queue only the first two, which unquestionably take us\nin the right direction.\n\nThanks.\n"},{"id":"250593","messageId":"20141014003451.GA7041@vauxhall.crustytoothpaste.net","threadId":"37717","inReplyTo":"xmqqtx371z44.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-14T00:34:51Z","receivedAt":"2014-10-14T00:34:51Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Mon, Oct 13, 2014 at 01:41:31PM -0700, Junio C Hamano wrote:\n> \"brian m. carlson\" writes:\n> \n> > The second two patches implement some basic support for building with\n> > Asciidoctor. The first of these moves some items into variables due to\n> > some differences between the AsciiDoc and Asciidoctor command lines.\n> > The user can then override these values when invoking make.\n> >\n> > The final patch adds support for the linkgit macro. Asciidoctor uses\n> > Ruby extensions to implement macro support, unlike AsciiDoc, which uses\n> > a configuration file.\n> \n> What I do not understand is that 3/4 lets you drop inclusion of\n> asciidoc.conf which contains a lot more than just linkgit:\n> definition.\n\nAsciidoctor just doesn't understand the -f argument, so trying to pass\nit is going to fail. For Asciidoctor, you're going to want to do\nsomething like \"-I. -rasciidoctor/extensions -rextensions\" there\ninstead.\n\nAs for the rest of the asciidoc.conf file, the DocBook manpage header\ndeclarations are implemented automatically by Asciidoctor after my\nrecent patches. The paragraph hacks do not appear to be necessary with\nAsciidoctor, so they've been omitted.\n\nThat leaves the attributes. All but litdd are built-in to Asciidoctor,\nand I can reroll with a modification to extensions.rb that implements\nthat one.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187\n"},{"id":"250608","messageId":"20141014095119.GC16686@peff.net","threadId":"37717","inReplyTo":"1413070656-241955-1-git-send-email-sandals@crustytoothpaste.net","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2014-10-14T09:51:19Z","receivedAt":"2014-10-14T09:51:19Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Oct 11, 2014 at 11:37:32PM +0000, brian m. carlson wrote:\n\n> This series is designed to implement the changes necessary to build Git\n> using Asciidoctor instead of AsciiDoc.\n\nThanks. I had always taken the attitude that we wrote for the original\nPython AsciiDoc, and that using AsciiDoctor was a choice that\ngit-scm.com made, and something they would have to deal with as far as\ncompatibility (AFAIK, AsciiDoctor grew out of git-scm.com's home-grown\nasciidoc parser).\n\nWhat's the status on AsciiDoc versus AsciiDoctor? The latter seems more\nactively developed these days, but perhaps that is just my perception.\nThe incompatibilities seem fairly minimal (if those first two patches\nare the extent of it, I have no problem at all trying to remain\ncompatible with both). Would it ever make sense to switch to AsciiDoctor\nas our official command-line build program? I know it is supposed to be\nmuch faster (though a lot of the slowness in our build chain is due to\ndocbook, not asciidoc itself).\n\nSpecifically I'm not excited about getting into a state where we have to\nmaintain both an asciidoc.conf file _and_ ruby extensions for\nasciidoctor. I don't mind if somebody wants to step up and keep the\nasciidoctor bits in sync with the asciidoc.conf, but I feel like one of\nthem needs to be considered the \"master\".\n\n-Peff\n"},{"id":"250601","messageId":"543CF5F7.5060704@gmail.com","threadId":"37717","inReplyTo":"20141014003451.GA7041@vauxhall.crustytoothpaste.net","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2014-10-14T10:07:51Z","receivedAt":"2014-10-14T10:07:51Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"brian m. carlson wrote:\n> On Mon, Oct 13, 2014 at 01:41:31PM -0700, Junio C Hamano wrote:\n>> \"brian m. carlson\" writes:\n>>\n>>> The second two patches implement some basic support for building with\n>>> Asciidoctor. The first of these moves some items into variables due to\n>>> some differences between the AsciiDoc and Asciidoctor command lines.\n>>> The user can then override these values when invoking make.\n>>>\n>>> The final patch adds support for the linkgit macro. Asciidoctor uses\n>>> Ruby extensions to implement macro support, unlike AsciiDoc, which uses\n>>> a configuration file.\n>>\n>> What I do not understand is that 3/4 lets you drop inclusion of\n>> asciidoc.conf which contains a lot more than just linkgit:\n>> definition.\n>\n> Asciidoctor just doesn't understand the -f argument, so trying to pass\n> it is going to fail. For Asciidoctor, you're going to want to do\n> something like \"-I. -rasciidoctor/extensions -rextensions\" there\n> instead.\n>\n> As for the rest of the asciidoc.conf file, the DocBook manpage header\n> declarations are implemented automatically by Asciidoctor after my\n> recent patches. The paragraph hacks do not appear to be necessary with\n> Asciidoctor, so they've been omitted.\n>\n> That leaves the attributes. All but litdd are built-in to Asciidoctor,\n> and I can reroll with a modification to extensions.rb that implements\n> that one.\n\nWould it be possible to automatically convert asciidoc.conf file to \nAsciidoctor extension?\n\n-- \nJakub Narębski\n"},{"id":"250603","messageId":"20141014112642.GB7041@vauxhall.crustytoothpaste.net","threadId":"37717","inReplyTo":"543CF5F7.5060704@gmail.com","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-14T11:26:42Z","receivedAt":"2014-10-14T11:26:42Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Tue, Oct 14, 2014 at 12:07:51PM +0200, Jakub Narębski wrote:\n> brian m. carlson wrote:\n> >On Mon, Oct 13, 2014 at 01:41:31PM -0700, Junio C Hamano wrote:\n> >>\n> >>What I do not understand is that 3/4 lets you drop inclusion of\n> >>asciidoc.conf which contains a lot more than just linkgit:\n> >>definition.\n> >\n> >Asciidoctor just doesn't understand the -f argument, so trying to pass\n> >it is going to fail. For Asciidoctor, you're going to want to do\n> >something like \"-I. -rasciidoctor/extensions -rextensions\" there\n> >instead.\n> >\n> >As for the rest of the asciidoc.conf file, the DocBook manpage header\n> >declarations are implemented automatically by Asciidoctor after my\n> >recent patches. The paragraph hacks do not appear to be necessary with\n> >Asciidoctor, so they've been omitted.\n> >\n> >That leaves the attributes. All but litdd are built-in to Asciidoctor,\n> >and I can reroll with a modification to extensions.rb that implements\n> >that one.\n> \n> Would it be possible to automatically convert asciidoc.conf file to\n> Asciidoctor extension?\n\nIt is in theory possible, but it's going to result in a lot of messy\ncode. I'm also not sure that Junio wants more than the minimal amount\nof Ruby possible, since the goal has been to move away from scripting\nlanguages and to C.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187\n"},{"id":"250614","messageId":"xmqqsiiqziik.fsf@gitster.dls.corp.google.com","threadId":"37717","inReplyTo":"20141014095119.GC16686@peff.net","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-14T17:08:19Z","receivedAt":"2014-10-14T17:08:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Sat, Oct 11, 2014 at 11:37:32PM +0000, brian m. carlson wrote:\n>\n> Specifically I'm not excited about getting into a state where we have to\n> maintain both an asciidoc.conf file _and_ ruby extensions for\n> asciidoctor. I don't mind if somebody wants to step up and keep the\n> asciidoctor bits in sync with the asciidoc.conf, but I feel like one of\n> them needs to be considered the \"master\".\n\nMy so-far-unstated inclination, since seeing the patch to fix the\nunbalanced example block separators from Brian (which was outside\nand before this four-patch series), has been to keep our Makefile in\nDocumentation/ aware only of AsciiDoc while maintaining *.txt files\nin a state so that AsciiDoctor could also be used to process them,\nif people want to futz with their copies of Documentation/Makefile.\n\nI do not mind to have the machinery to run AsciiDoctor too much in\nmy tree. It may make it easier for those who use it to spot places\nin *.txt that need (in)compatibility workarounds between the two\nformatters than keeping it outside.\n\nBut somebody needs to maintain that machinery and that will not be\nme.\n\nThanks.\n"},{"id":"250659","messageId":"20141015011754.GA131351@vauxhall.crustytoothpaste.net","threadId":"37717","inReplyTo":"xmqqsiiqziik.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-15T01:17:54Z","receivedAt":"2014-10-15T01:17:54Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Tue, Oct 14, 2014 at 10:08:19AM -0700, Junio C Hamano wrote:\n> Jeff King writes:\n> \n> > On Sat, Oct 11, 2014 at 11:37:32PM +0000, brian m. carlson wrote:\n> >\n> > Specifically I'm not excited about getting into a state where we have to\n> > maintain both an asciidoc.conf file _and_ ruby extensions for\n> > asciidoctor. I don't mind if somebody wants to step up and keep the\n> > asciidoctor bits in sync with the asciidoc.conf, but I feel like one of\n> > them needs to be considered the \"master\".\n> \n> My so-far-unstated inclination, since seeing the patch to fix the\n> unbalanced example block separators from Brian (which was outside\n> and before this four-patch series), has been to keep our Makefile in\n> Documentation/ aware only of AsciiDoc while maintaining *.txt files\n> in a state so that AsciiDoctor could also be used to process them,\n> if people want to futz with their copies of Documentation/Makefile.\n> \n> I do not mind to have the machinery to run AsciiDoctor too much in\n> my tree. It may make it easier for those who use it to spot places\n> in *.txt that need (in)compatibility workarounds between the two\n> formatters than keeping it outside.\n\nI'd be happy if you simply picked up patch 3 and left out patch 4. It\ngets us most of the way there, which is good enough for most things.\nIt's even possible to handle the litdd attribute on the command line, so\nthe only thing we'd really lose is the linkgit links.\n\nAlternately, I'm happy to be responsible for maintaining the\nextensions.rb file. The asciidoc.conf file has not had a substantive\n(non-comment) change since 2012, and it has not had a change that would\nrequire an update to the extensions since 2010. I don't anticipate that\nkeeping it up-to-date will require a significant amount of work. We can\neven drop it into contrib if you think that's a better place.\n\nIt's really up to you which you'd prefer.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187\n"},{"id":"250673","messageId":"543E5966.80400@virtuell-zuhause.de","threadId":"37717","inReplyTo":"20141014095119.GC16686@peff.net","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"Thomas Braun","fromEmail":"thomas.braun@virtuell-zuhause.de","sentAt":"2014-10-15T11:24:22Z","receivedAt":"2014-10-15T11:24:22Z","isPatch":true,"sender":{"key":"thomas.braun@virtuell-zuhause.de","avatar":"https://avatars.githubusercontent.com/u/1185677?v=4"},"body":"Am 14.10.2014 um 11:51 schrieb Jeff King:\n> What's the status on AsciiDoc versus AsciiDoctor? The latter seems more\n> actively developed these days, but perhaps that is just my perception.\n> The incompatibilities seem fairly minimal (if those first two patches\n> are the extent of it, I have no problem at all trying to remain\n> compatible with both). Would it ever make sense to switch to AsciiDoctor\n> as our official command-line build program? I know it is supposed to be\n> much faster (though a lot of the slowness in our build chain is due to\n> docbook, not asciidoc itself).\n\nJust recently we added the AsciiDoc toolchain to our git-for-windows/sdk\n(formerly known as msysgit). So I'm not really fond of switching now to\nsomething different again.\n\nRemaining compatible with both would therefore be my choice.\n\nThomas\n"},{"id":"250693","messageId":"xmqqsiipw7ne.fsf@gitster.dls.corp.google.com","threadId":"37717","inReplyTo":"20141015011754.GA131351@vauxhall.crustytoothpaste.net","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-15T17:43:33Z","receivedAt":"2014-10-15T17:43:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n> On Tue, Oct 14, 2014 at 10:08:19AM -0700, Junio C Hamano wrote:\n>> Jeff King writes:\n>> \n>> > On Sat, Oct 11, 2014 at 11:37:32PM +0000, brian m. carlson wrote:\n>> >\n>> > Specifically I'm not excited about getting into a state where we have to\n>> > maintain both an asciidoc.conf file _and_ ruby extensions for\n>> > asciidoctor. I don't mind if somebody wants to step up and keep the\n>> > asciidoctor bits in sync with the asciidoc.conf, but I feel like one of\n>> > them needs to be considered the \"master\".\n>> \n>> I do not mind to have the machinery to run AsciiDoctor too much in\n>> my tree. It may make it easier for those who use it to spot places\n>> in *.txt that need (in)compatibility workarounds between the two\n>> formatters than keeping it outside.\n>\n> Alternately, I'm happy to be responsible for maintaining the\n> extensions.rb file.\n\nLet's see how well the patches 3 and 4 work for other people with\nAsciiDoctor and then decide to go in that direction.\n\nI do not forsee that changes to allow our *.txt to be used with\nAsciiDoctor interfere with what GitHub folks do with their own\ndocumentation toolchain, but I am not sure how the AsciiDoctor\nspecific alternative build infrastructure we would eventually ship\nwould interact with them---maybe they are not affected at all, or\nmaybe they can even take advantage of it.\n\nThanks.\n"},{"id":"250703","messageId":"xmqq61flvzay.fsf@gitster.dls.corp.google.com","threadId":"37717","inReplyTo":"1413070656-241955-4-git-send-email-sandals@crustytoothpaste.net","subject":"Re: [PATCH 3/4] Documentation: move some AsciiDoc parameters into variables","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-15T20:43:49Z","receivedAt":"2014-10-15T20:43:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n> Asciidoctor takes slightly different arguments from AsciiDoc in some\n> cases. It has a different name for the HTML backend and the \"docbook\"\n> backend produces DocBook 5, not DocBook 4.5. Also, Asciidoctor does not\n> accept the -f option. Move these values into variables so that they can\n> be overridden by users wishing to use Asciidoctor instead of Asciidoc.\n>\n> Signed-off-by: brian m. carlson \n> ---\n\nI think it makes sense to make these customizable, but I wonder if\nit makes the result easier to maintain if we make units of logical\ndefinitions larger, e.g.\n\n\tASCIIDOC = asciidoc\n TXT_TO_MANHTML = $(ASCIIDOC) -b xhtml11 -d manpage $(ASCIIDOC_CONF)\n TXT_TO_ARTICLE = $(ASCIIDOC) -b docbook -d article\n\t...\n\nASCIIDOC_EXTRA may want to apply all of them, even though I see that\nwe do not feed it to OBSOLETE_HTML right now. It may also be that\n$(ASCIIDOC_CONF) and -agit_version=$(GIT_VERSION) could be shared\namong the ones that currently do not have.\n\nThen the above would become something like:\n\n\tASCIIDOC = asciidoc\n\tASCIIDOC_COMMON = $(ASCIIDOC) \\\n \t$(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) -agit_version=$(GIT_VERSION)\n TXT_TO_MANHTML = $(ASCIIDOC_COMMON) -b xhtml11 -d manpage\n ...\n\nand would further simplify this part\n\n> $(MAN_HTML): %.html : %.txt asciidoc.conf\n> \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> -\t$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \\\n> +\t$(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage $(ASCIIDOC_CONF) \\\n> \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \\\n\ninto just\n\n\t$(TXT_TO_MANHTML) -o $@+ $<\n\nAfter all, our output formats are fairly limited, I would think.\nAre there too many different variants and exceptions to make such an\napproach infeasible?\n"},{"id":"250738","messageId":"20141015235237.GB146788@vauxhall.crustytoothpaste.net","threadId":"37717","inReplyTo":"543E5966.80400@virtuell-zuhause.de","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-15T23:52:38Z","receivedAt":"2014-10-15T23:52:38Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Wed, Oct 15, 2014 at 01:24:22PM +0200, Thomas Braun wrote:\n> Am 14.10.2014 um 11:51 schrieb Jeff King:\n> > What's the status on AsciiDoc versus AsciiDoctor? The latter seems more\n> > actively developed these days, but perhaps that is just my perception.\n> > The incompatibilities seem fairly minimal (if those first two patches\n> > are the extent of it, I have no problem at all trying to remain\n> > compatible with both). Would it ever make sense to switch to AsciiDoctor\n> > as our official command-line build program? I know it is supposed to be\n> > much faster (though a lot of the slowness in our build chain is due to\n> > docbook, not asciidoc itself).\n\nI don't think there's a lot of benefit for us to switch, and I say that\nbeing a contributor to Asciidoctor. It's useful to be able to build Git\nwith both simply to find incompatibilities that we're going to need to\nfix anyway, due to the fact that Asciidoctor is used for the website.\n\nAnd yes, those first two patches are it, as far as I'm aware.\n\n> Just recently we added the AsciiDoc toolchain to our git-for-windows/sdk\n> (formerly known as msysgit). So I'm not really fond of switching now to\n> something different again.\n> \n> Remaining compatible with both would therefore be my choice.\n\nThat's my goal. I simply wanted the ability to support both AsciiDoc\nand Asciidoctor without making major changes to the codebase. Hence,\nmoving the calls into variables.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187\n"},{"id":"250741","messageId":"20141016015253.GC146788@vauxhall.crustytoothpaste.net","threadId":"37717","inReplyTo":"xmqq61flvzay.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 3/4] Documentation: move some AsciiDoc parameters into variables","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-16T01:52:53Z","receivedAt":"2014-10-16T01:52:53Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Wed, Oct 15, 2014 at 01:43:49PM -0700, Junio C Hamano wrote:\n> I think it makes sense to make these customizable, but I wonder if\n> it makes the result easier to maintain if we make units of logical\n> definitions larger, e.g.\n> \n> \tASCIIDOC = asciidoc\n> TXT_TO_MANHTML = $(ASCIIDOC) -b xhtml11 -d manpage $(ASCIIDOC_CONF)\n> TXT_TO_ARTICLE = $(ASCIIDOC) -b docbook -d article\n\nLooking at the code, it seems the most reusable unit is something like\nthe following:\n\n TXT_TO_HTML = $(ASCIIDOC) -b xhtml11 $(ASCIIDOC_CONF)\n TXT_TO_XML = $(ASCIIDOC) -b docbook $(ASCIIDOC_CONF)\n\nthat is, omitting the -d argument from the variable. Using -d would\nmean we'd have to have a variable for each of the seven locations we\ncall $(ASCIIDOC).\n\n> Then the above would become something like:\n> \n> \tASCIIDOC = asciidoc\n> \tASCIIDOC_COMMON = $(ASCIIDOC) \\\n> \t$(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) -agit_version=$(GIT_VERSION)\n> TXT_TO_MANHTML = $(ASCIIDOC_COMMON) -b xhtml11 -d manpage\n> ...\n> \n> and would further simplify this part\n> \n> > $(MAN_HTML): %.html : %.txt asciidoc.conf\n> > \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> > -\t$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \\\n> > +\t$(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage $(ASCIIDOC_CONF) \\\n> > \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \\\n> \n> into just\n> \n> \t$(TXT_TO_MANHTML) -o $@+ $<\n> \n> After all, our output formats are fairly limited, I would think.\n> Are there too many different variants and exceptions to make such an\n> approach infeasible?\n\nI'm on board with the $(ASCIIDOC_COMMON) idea, but to minimize the\nnumber of variables, I think we should leave the -d out of the macro\nitself. I'll re-roll over the next couple of days.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187\n"},{"id":"250780","messageId":"0F6BE26CD2B44C37A1E1BB0239655AC5@PhilipOakley","threadId":"37717","inReplyTo":"1413070656-241955-1-git-send-email-sandals@crustytoothpaste.net","subject":"Re: [PATCH 0/4] Allow building Git with Asciidoctor","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-16T22:53:12Z","receivedAt":"2014-10-16T22:53:12Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"brian m. carlson\" \n> This series is designed to implement the changes necessary to build \n> Git\n> using Asciidoctor instead of AsciiDoc.\n[..]\n> Even with these patches, Asciidoctor warns about everyday.txt and\n> user-manual.txt. I'm not sending patches for these right now because\n> I've seen recent series including those and don't want to cause a\n> merge conflict.\n>\nDoes the new version for giteveryday.txt and everyday.txt which \ngraduated to master, 1cb3324 (Merge branch 'po/everyday-doc', \n2014-10-16) format OK?\n\ni.e. does 'git help everyday' now correct the Asciidoctor warnings.\n\nI don't have access to Asciidoctor (on MsysGit), but did make sure the \nheader underlines were updated.\n--\nPhilip \n"}]}