{"thread":{"id":"37762","subject":"[PATCH v2 1/3] Documentation: adjust document title underlining","startedAt":"2014-10-20T00:20:35Z","lastAt":"2014-10-20T19:08:33Z","messageCount":6,"participants":["brian m. carlson","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":3},"messages":[{"id":"250841","messageId":"1413764438-297386-1-git-send-email-sandals@crustytoothpaste.net","threadId":"37762","inReplyTo":null,"subject":"[PATCH v2 0/3] Allow building Git with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-20T00:20:35Z","receivedAt":"2014-10-20T00:20:35Z","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, and are unchanged from v1.\nAsciidoctor is stricter about some aspects of formatting, and these\npatches are required to make the documentation build correctly.\n\nThe third patch moves several pieces of the documentation makefile into\nvariables.  Some of these changes were suggested by Junio, and some of\nthem were required to simply build correctly.\n\nIn this patch, I have maintained the ASCIIDOC_HTML and ASCIIDOC_DOCBOOK\nvariables, because otherwise there is no way to override the backends\neasily, which is required to build.  For Asciidoctor, there is no\nxhtml11 backend and the docbook backend produces DocBook 5, which xmlto\ndoesn't like.\n\nThe fourth patch in the previous series has been dropped, as Dan Allen\nof the Asciidoctor project has pointed me to a backend-agnostic\nimplementation of the linkgit macro which is included in the Asciidoctor\nproject.  The litdd attribute, the only other missing piece, can be\nmoved to the command line, so the patch became unnecessary.\n\nI've successfully built the documentation with Asciidoctor using the\nfollowing command line:\n\n  make doc ASCIIDOC=asciidoctor ASCIIDOC_HTML=html5 \\\n  ASCIIDOC_DOCBOOK=docbook45 ASCIIDOC_EXTRA=\"'-alitdd=&#45;&#45;'\" \\\n  ASCIIDOC_CONF=\n\nThis resulted in a total build time (documentation only) of 3:17 versus\n5:43 for AsciiDoc (a 42% improvement).\n\nbrian m. carlson (3):\n  Documentation: adjust document title underlining\n  Documentation: fix mismatched delimiters in git-imap-send\n  Documentation: move some AsciiDoc parameters into variables\n\n Documentation/Makefile             | 26 +++++++++++++++-----------\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 5 files changed, 20 insertions(+), 16 deletions(-)\n\n-- \n2.1.1\n"},{"id":"250838","messageId":"1413764438-297386-2-git-send-email-sandals@crustytoothpaste.net","threadId":"37762","inReplyTo":"1413764438-297386-1-git-send-email-sandals@crustytoothpaste.net","subject":"[PATCH v2 1/3] Documentation: adjust document title underlining","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-20T00:20:36Z","receivedAt":"2014-10-20T00:20:36Z","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 <sandals@crustytoothpaste.net>\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":"250840","messageId":"1413764438-297386-3-git-send-email-sandals@crustytoothpaste.net","threadId":"37762","inReplyTo":"1413764438-297386-1-git-send-email-sandals@crustytoothpaste.net","subject":"[PATCH v2 2/3] Documentation: fix mismatched delimiters in git-imap-send","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-20T00:20:37Z","receivedAt":"2014-10-20T00:20:37Z","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 <sandals@crustytoothpaste.net>\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":"250839","messageId":"1413764438-297386-4-git-send-email-sandals@crustytoothpaste.net","threadId":"37762","inReplyTo":"1413764438-297386-1-git-send-email-sandals@crustytoothpaste.net","subject":"[PATCH v2 3/3] Documentation: move some AsciiDoc parameters into variables","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2014-10-20T00:20:38Z","receivedAt":"2014-10-20T00:20:38Z","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,\nand simplify several redundant rules.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/Makefile | 26 +++++++++++++++-----------\n 1 file changed, 15 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex cea0e7a..5952cc2 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -97,6 +97,13 @@ 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+ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n+\t\t-agit-version=$(GIT_VERSION)\n+TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)\n+TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)\n MANPAGE_XSL = manpage-normal.xsl\n XMLTO = xmlto\n XMLTO_EXTRA =\n@@ -304,14 +311,12 @@ 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\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \\\n+\t$(TXT_TO_HTML) -d manpage -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\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \\\n+\t$(TXT_TO_HTML) -o $@+ $< && \\\n \tmv $@+ $@\n \n manpage-base-url.xsl: manpage-base-url.xsl.in\n@@ -323,13 +328,12 @@ 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\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \\\n+\t$(TXT_TO_XML) -d manpage -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$(TXT_TO_XML) -d article -o $@+ $< && \\\n \tmv $@+ $@\n \n technical/api-index.txt: technical/api-index-skel.txt \\\n@@ -338,8 +342,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\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt\n \n XSLT = docbook.xsl\n XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\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)$(TXT_TO_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$(TXT_TO_HTML) - >$@+ && \\\n \tmv $@+ $@\n \n install-webdoc : html\n-- \n2.1.1\n"},{"id":"250849","messageId":"20141020092425.GD12913@peff.net","threadId":"37762","inReplyTo":"1413764438-297386-1-git-send-email-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 0/3] Allow building Git with Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2014-10-20T09:24:25Z","receivedAt":"2014-10-20T09:24:25Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Oct 20, 2014 at 12:20:35AM +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\nThese all looked sane to me from my cursory read (I haven't played with\nAsciiDoctor myself yet, but it looks from your results like you have).\n\n> I've successfully built the documentation with Asciidoctor using the\n> following command line:\n> \n>   make doc ASCIIDOC=asciidoctor ASCIIDOC_HTML=html5 \\\n>   ASCIIDOC_DOCBOOK=docbook45 ASCIIDOC_EXTRA=\"'-alitdd=&#45;&#45;'\" \\\n>   ASCIIDOC_CONF=\n\nThat incantation is getting a bit hairy. Is it worth adding a meta-macro\nlike USE_ASCIIDOCTOR that encompasses it all? That might encourage other\npeople to play around with it.\n\n-Peff\n"},{"id":"250869","messageId":"xmqqbnp636fi.fsf@gitster.dls.corp.google.com","threadId":"37762","inReplyTo":"1413764438-297386-1-git-send-email-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 0/3] Allow building Git with Asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-20T19:08:33Z","receivedAt":"2014-10-20T19:08:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Too late that the original is already in 'next'.  Care to reroll as\nan incremental, plaese?\n\nThanks.\n"}]}