{"thread":{"id":"44807","subject":"[PATCH 0/2] Fix the documentation to build with asciidoctor","startedAt":"2017-01-02T16:04:05Z","lastAt":"2017-01-13T18:33:01Z","messageCount":18,"participants":["Johannes Schindelin","Jeff King","Lars Schneider","Junio C Hamano","brian m. carlson"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"308670","messageId":"cover.1483373021.git.johannes.schindelin@gmx.de","threadId":"44807","inReplyTo":null,"subject":"[PATCH 0/2] Fix the documentation to build with asciidoctor","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2017-01-02T16:03:53Z","receivedAt":"2017-01-02T16:04:05Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"The first patch in this series has been with Git for Windows for well\nover a year already, the second one is a replacement for such an old\npatch.\n\nThe reason why we use asciidoctor in Git for Windows is easy to see:\nwhen building new Git for Windows packages, rendering the documentation\ndominates the time by far. It takes roughly 75 seconds to compile all\nthe executables from scratch on my main work machine, but it takes\nroughly 125 seconds to build the documentation from scratch.\n\nOut of those 125 seconds, 45 are taken by the HTML documentation.\n\nIn the Git for Windows project, we realized a long time ago that we\ncould reduce the time dramatically by using asciidoctor: it takes only\n15 seconds to build the HTML documentation.\n\nThose savings come at a cost, though: asciidoctor was designed to be\nmuch less flexible than asciidoc, in favor for maximum speed and minimal\nsize of the code base. And to accomodate those shortcomings, it is\nunfortunately necessary to change Git's documentation sources.\n\nSo what is the big deal with those timings? It's only half a minute!\n\nThis is on a very beefy machine. Internally, I use quite a bit of\nContinuous Integration to build intermediate Git for Windows versions\nfor testing, and those builds are backed by reasonably-sized VMs. That\nmakes it worth shaving that extra time off.\n\nSide note for the curious who wonder why asciidoctor is *so much* faster\nthan asciidoc: my gut feeling is that the primary reason for this is,\nonce again, the POSIX emulation layer: asciidoc runs as a Python script,\nusing a Python interpreter that uses the MSYS2 runtime for path\ntranslation and fork emulation (among other things), while asciidoctor\nruns as a Ruby script, using a pure Windows Ruby interpreter (for those\nremembering the nomenclature: the Python interpreter is an MSYS2 program\nwhile the Ruby interpreter is a MINGW program). But even after that I\nsuspect that asciidoc was just not designed for speed, on a very\nfundamental level.\n\nNow back to the patch series: I *hope* the patches are not too\ndisruptive. I am very open to changing them however needed, I only care\nabout one result in the end: that the documentation builds correctly\n(and fast) with asciidoctor.\n\n\nJohannes Schindelin (1):\n giteveryday: unbreak rendering with AsciiDoctor\n\n마누엘 (1):\n asciidoctor: fix user-manual to be built by `asciidoctor`\n\n Documentation/Makefile | 2 +-\n Documentation/giteveryday.txt | 17 +++++++++--------\n Documentation/user-manual.txt | 8 ++++++++\n 3 files changed, 18 insertions(+), 9 deletions(-)\n\n\nbase-commit: e05806da9ec4aff8adfed142ab2a2b3b02e33c8c\nPublished-As: https://github.com/dscho/git/releases/tag/asciidoctor-fixes-v1\nFetch-It-Via: git fetch https://github.com/dscho/git asciidoctor-fixes-v1\n\n-- \n2.11.0.rc3.windows.1\n"},{"id":"308671","messageId":"3c160f81a88cf8697f2459bb7f2a3e27fb3e469c.1483373021.git.johannes.schindelin@gmx.de","threadId":"44807","inReplyTo":"cover.1483373021.git.johannes.schindelin@gmx.de","subject":"[PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2017-01-02T16:03:57Z","receivedAt":"2017-01-02T16:04:14Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: =?UTF-8?q?=EB=A7=88=EB=88=84=EC=97=98?= \n\nThe `user-manual.txt` is designed as a `book` but the `Makefile` wants\nto build it as an `article`. This seems to be a problem when building\nthe documentation with `asciidoctor`. Furthermore the parts *Git\nGlossary* and *Appendix B* had no subsections which is not allowed when\nbuilding with `asciidoctor`. So lets add a *dummy* section.\n\nSigned-off-by: 마누엘 \nSigned-off-by: Johannes Schindelin \n---\n Documentation/Makefile | 2 +-\n Documentation/user-manual.txt | 8 ++++++++\n 2 files changed, 9 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex b43d66eae6..a9fb497b83 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -337,7 +337,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n \n user-manual.xml: user-manual.txt user-manual.conf\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(TXT_TO_XML) -d article -o $@+ $< && \\\n+\t$(TXT_TO_XML) -d book -o $@+ $< && \\\n \tmv $@+ $@\n \n technical/api-index.txt: technical/api-index-skel.txt \\\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 5e07454572..bc29298678 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -4395,6 +4395,10 @@ itself!\n Git Glossary\n ============\n \n+[[git-explained]]\n+Git explained\n+-------------\n+\n include::glossary-content.txt[]\n \n [[git-quick-start]]\n@@ -4636,6 +4640,10 @@ $ git gc\n Appendix B: Notes and todo list for this manual\n ===============================================\n \n+[[todo-list]]\n+Todo list\n+---------\n+\n This is a work in progress.\n \n The basic requirements:\n-- \n2.11.0.rc3.windows.1\n\n"},{"id":"308672","messageId":"c3b21bbec96408c4d6698129fd336c24c9e2f0f0.1483373021.git.johannes.schindelin@gmx.de","threadId":"44807","inReplyTo":"cover.1483373021.git.johannes.schindelin@gmx.de","subject":"[PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2017-01-02T16:04:05Z","receivedAt":"2017-01-02T16:04:20Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"The \"giteveryday\" document has a callout list that contains a code\nblock. This is not a problem for AsciiDoc, but AsciiDoctor sadly was\nexplicitly designed *not* to render this correctly [*1*]. The symptom is\nan unhelpful\n\n\tline 322: callout list item index: expected 1 got 12\n\tline 325: no callouts refer to list item 1\n\tline 325: callout list item index: expected 2 got 13\n\tline 327: no callouts refer to list item 2\n\nIn Git for Windows, we rely on the speed improvement of AsciiDoctor (on\nthis developer's machine, `make -j15 html` takes roughly 30 seconds with\nAsciiDoctor, 70 seconds with AsciiDoc), therefore we need a way to\nrender this correctly.\n\nThe easiest way out is to simplify the callout list, as suggested by\nAsciiDoctor's author, even while one may very well disagree with him\nthat a code block hath no place in a callout list.\n\n*1*: https://github.com/asciidoctor/asciidoctor/issues/1478\n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/giteveryday.txt | 17 +++++++++--------\n 1 file changed, 9 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt\nindex 35473ad02f..10c8ff93c0 100644\n--- a/Documentation/giteveryday.txt\n+++ b/Documentation/giteveryday.txt\n@@ -307,9 +307,16 @@ master or exposed as a part of a stable branch.\n <9> backport a critical fix.\n <10> create a signed tag.\n <11> make sure master was not accidentally rewound beyond that\n-already pushed out. `ko` shorthand points at the Git maintainer's\n+already pushed out.\n+<12> In the output from `git show-branch`, `master` should have\n+everything `ko/master` has, and `next` should have\n+everything `ko/next` has, etc.\n+<13> push out the bleeding edge, together with new tags that point\n+into the pushed history.\n+\n+In this example, the `ko` shorthand points at the Git maintainer's\n repository at kernel.org, and looks like this:\n-+\n+\n ------------\n (in .git/config)\n [remote \"ko\"]\n@@ -320,12 +327,6 @@ repository at kernel.org, and looks like this:\n \tpush = +refs/heads/pu\n \tpush = refs/heads/maint\n ------------\n-+\n-<12> In the output from `git show-branch`, `master` should have\n-everything `ko/master` has, and `next` should have\n-everything `ko/next` has, etc.\n-<13> push out the bleeding edge, together with new tags that point\n-into the pushed history.\n \n \n Repository Administration[[ADMINISTRATION]]\n-- \n2.11.0.rc3.windows.1\n"},{"id":"308764","messageId":"20170104080852.bmlmtzxhjx4qt74f@sigill.intra.peff.net","threadId":"44807","inReplyTo":"3c160f81a88cf8697f2459bb7f2a3e27fb3e469c.1483373021.git.johannes.schindelin@gmx.de","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-01-04T08:08:52Z","receivedAt":"2017-01-04T08:09:01Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jan 02, 2017 at 05:03:57PM +0100, Johannes Schindelin wrote:\n\n> From: =?UTF-8?q?=EB=A7=88=EB=88=84=EC=97=98?= \n> \n> The `user-manual.txt` is designed as a `book` but the `Makefile` wants\n> to build it as an `article`. This seems to be a problem when building\n> the documentation with `asciidoctor`. Furthermore the parts *Git\n> Glossary* and *Appendix B* had no subsections which is not allowed when\n> building with `asciidoctor`. So lets add a *dummy* section.\n\nThe git-scm.com site uses asciidoctor, too, and I think I have seen some\noddness with the rendering though. So in general I am in favor of making\nthings work under both asciidoc and asciidoctor.\n\nI diffed the results of \"make user-manual.html\" before and after this\npatch. A lot of \"h3\" chapter titles get bumped to \"h2\", which is OK. The\nchapter titles now say \"Chapter 1. Repositories and Branches\" rather\nthan just \"Repositories and Branches\". Likewise, references now say\n\n Chapter 1, _Repositories and Branches_\n\nrather than:\n\n the section called \"Repositories and Branches\".\n\nwhich is probably OK, though the whole thing is short enough that\ncalling the sections chapters feels a bit over-important. Chapters now\nget their own table of contents, too. This is especially silly in\none-section chapters like \"Git Glossary\".\n\nSo I dunno. I really do think \"article\" is conceptually the most\nappropriate style, but I agree that there are some book-like things\n(like appendices).\n\n-Peff\n"},{"id":"308765","messageId":"20170104081544.5htofa3zpgkvty7x@sigill.intra.peff.net","threadId":"44807","inReplyTo":"c3b21bbec96408c4d6698129fd336c24c9e2f0f0.1483373021.git.johannes.schindelin@gmx.de","subject":"Re: [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-01-04T08:15:44Z","receivedAt":"2017-01-04T08:16:32Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jan 02, 2017 at 05:04:05PM +0100, Johannes Schindelin wrote:\n\n> The \"giteveryday\" document has a callout list that contains a code\n> block. This is not a problem for AsciiDoc, but AsciiDoctor sadly was\n> explicitly designed *not* to render this correctly [*1*]. The symptom is\n> an unhelpful\n> \n> \tline 322: callout list item index: expected 1 got 12\n> \tline 325: no callouts refer to list item 1\n> \tline 325: callout list item index: expected 2 got 13\n> \tline 327: no callouts refer to list item 2\n> \n> In Git for Windows, we rely on the speed improvement of AsciiDoctor (on\n> this developer's machine, `make -j15 html` takes roughly 30 seconds with\n> AsciiDoctor, 70 seconds with AsciiDoc), therefore we need a way to\n> render this correctly.\n> \n> The easiest way out is to simplify the callout list, as suggested by\n> AsciiDoctor's author, even while one may very well disagree with him\n> that a code block hath no place in a callout list.\n\nThis looks like a good re-write to avoid the issue while maintaining the\nmeaning and flow of the original.\n\n-Peff\n"},{"id":"308814","messageId":"1D7C66EA-E87A-4154-ACAC-8045D28477D2@gmail.com","threadId":"44807","inReplyTo":"20170104080852.bmlmtzxhjx4qt74f@sigill.intra.peff.net","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2017-01-05T10:05:29Z","receivedAt":"2017-01-05T10:06:43Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\n> On 04 Jan 2017, at 09:08, Jeff King wrote:\n> \n> On Mon, Jan 02, 2017 at 05:03:57PM +0100, Johannes Schindelin wrote:\n> \n>> From: =?UTF-8?q?=EB=A7=88=EB=88=84=EC=97=98?= \n>> \n>> The `user-manual.txt` is designed as a `book` but the `Makefile` wants\n>> to build it as an `article`. This seems to be a problem when building\n>> the documentation with `asciidoctor`. Furthermore the parts *Git\n>> Glossary* and *Appendix B* had no subsections which is not allowed when\n>> building with `asciidoctor`. So lets add a *dummy* section.\n> \n> The git-scm.com site uses asciidoctor, too, and I think I have seen some\n> oddness with the rendering though. So in general I am in favor of making\n> things work under both asciidoc and asciidoctor.\n\nI am not familiar with both tools but it sounds to me as if \"asciidoctor\"\nis kind of the \"lowest common denominator\". Is this true? If yes, would it\nmake sense to switch TravisCI [1] to asciidocter if this change gets merged?\n\n- Lars\n\n[1] https://github.com/git/git/blob/master/.travis.yml#L48\n\n"},{"id":"308819","messageId":"alpine.DEB.2.20.1701051444390.3469@virtualbox","threadId":"44807","inReplyTo":"1D7C66EA-E87A-4154-ACAC-8045D28477D2@gmail.com","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2017-01-05T13:49:35Z","receivedAt":"2017-01-05T13:50:05Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Lars,\n\nOn Thu, 5 Jan 2017, Lars Schneider wrote:\n\n> > On 04 Jan 2017, at 09:08, Jeff King wrote:\n> > \n> > On Mon, Jan 02, 2017 at 05:03:57PM +0100, Johannes Schindelin wrote:\n> > \n> >> From: =?UTF-8?q?=EB=A7=88=EB=88=84=EC=97=98?= \n> >> \n> >> The `user-manual.txt` is designed as a `book` but the `Makefile`\n> >> wants to build it as an `article`. This seems to be a problem when\n> >> building the documentation with `asciidoctor`. Furthermore the parts\n> >> *Git Glossary* and *Appendix B* had no subsections which is not\n> >> allowed when building with `asciidoctor`. So lets add a *dummy*\n> >> section.\n> > \n> > The git-scm.com site uses asciidoctor, too, and I think I have seen\n> > some oddness with the rendering though. So in general I am in favor of\n> > making things work under both asciidoc and asciidoctor.\n> \n> I am not familiar with both tools but it sounds to me as if\n> \"asciidoctor\" is kind of the \"lowest common denominator\". Is this true?\n> If yes, would it make sense to switch TravisCI [1] to asciidocter if\n> this change gets merged?\n\nIt is true that asciidoc typically parses whatever asciidoctor parses,\nbut not vice versa.\n\nIn that light, I would love to see our Travis runs to switch to\nasciidoctor.\n\nFor the record, this is my local config.mak in the asciidoctor worktree:\n\n-- snip --\nASCIIDOC=asciidoctor\nASCIIDOC_HTML=html5\nASCIIDOC_DOCBOOK=docbook45\nASCIIDOC_EXTRA=\"-alitdd=&\\#45;&\\#45;\"\nASCIIDOC_CONF=-I\"/mingw64/lib/asciidoctor-extensions\" -rman-inline-macro\n-- snap --\n\nPlease note that the extensions are required to build correctly (and we\nrequire this patch, too, unfortunately:\nhttps://github.com/git-for-windows/MINGW-packages/blob/master/mingw-w64-asciidoctor-extensions/0001-man-inline-macro-enable-linkgit-syntax.patch).\n\nCiao,\nDscho\n"},{"id":"308828","messageId":"20170105164556.b3bzeqqzx4pvni4z@sigill.intra.peff.net","threadId":"44807","inReplyTo":"1D7C66EA-E87A-4154-ACAC-8045D28477D2@gmail.com","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-01-05T16:45:57Z","receivedAt":"2017-01-05T19:16:55Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Jan 05, 2017 at 11:05:29AM +0100, Lars Schneider wrote:\n\n> > The git-scm.com site uses asciidoctor, too, and I think I have seen some\n> > oddness with the rendering though. So in general I am in favor of making\n> > things work under both asciidoc and asciidoctor.\n> \n> I am not familiar with both tools but it sounds to me as if \"asciidoctor\"\n> is kind of the \"lowest common denominator\". Is this true? If yes, would it\n> make sense to switch TravisCI [1] to asciidocter if this change gets merged?\n\nI don't think that's quite true.\n\nThe two programs produce different output for certain inputs. We tend to\nsee the cases where asciidoc produces the desired output and asciidoctor\ndoesn't, because traditionally the documentation was written _for_\nasciidoc. So whenever asciidoctor diverges, it looks like a bug.\n\nIf people start developing and checking their work using asciidoctor[1],\nthen we'll see bugs going in the other direction.\n\nAs far as CI goes, I am not altogether convinced of the usefulness of\nbuilding the documentation. It's very expensive, and the failure mode is\nrarely \"whoops, running `make doc` failed\". It's almost always that the\noutput looks subtly wrong, but that's very hard to check automatically.\n\n[1] I think we've also traditionally considered asciidoc to be the\n definitive toolchain, and people using asciidoctor are free to\n submit patches to make things work correctly in both places. I'm not\n opposed to changing that attitude, as it seems like asciidoctor is\n faster and more actively maintained these days. But I suspect our\n build chain would need some improvements. Last time I tried building\n with AsciiDoctor it involved a lot manual tweaking of Makefile\n variables. It sounds like Dscho is doing it regularly, though. It\n should probably work out of the box (with something like\n USE_ASCIIDOCTOR=Yes) if we expect people to actually rely on it.\n"},{"id":"308937","messageId":"xmqqfuku3504.fsf@gitster.mtv.corp.google.com","threadId":"44807","inReplyTo":"20170105164556.b3bzeqqzx4pvni4z@sigill.intra.peff.net","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-07T22:00:11Z","receivedAt":"2017-01-07T22:00:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> As far as CI goes, I am not altogether convinced of the usefulness of\n> building the documentation. It's very expensive, and the failure mode is\n> rarely \"whoops, running `make doc` failed\". It's almost always that the\n> output looks subtly wrong, but that's very hard to check automatically.\n\nI've seen \"make doc\" break for me when it works for other people,\nand if CI can check the formatting for various combinations of\nversions of toolchain components, it would have some value. But\notherwise, I agree that \"make doc\" in CI would not give us as much\nbenefit as we spend electricity on it.\n\nIf we are to make support for building with AsciiDoctor better, CI\nthat does \"make doc\" with both AsciiDoc and AsciiDoctor might be of\nhelp---a \"make it buildable with A\" patch may accidentally break B\nand vice versa.\n\n> [1] I think we've also traditionally considered asciidoc to be the\n> definitive toolchain, and people using asciidoctor are free to\n> submit patches to make things work correctly in both places. I'm not\n> opposed to changing that attitude, as it seems like asciidoctor is\n> faster and more actively maintained these days. But I suspect our\n> build chain would need some improvements. Last time I tried building\n> with AsciiDoctor it involved a lot manual tweaking of Makefile\n> variables. It sounds like Dscho is doing it regularly, though. It\n> should probably work out of the box (with something like\n> USE_ASCIIDOCTOR=Yes) if we expect people to actually rely on it.\n\nI do not mind getting convinced to declare that we will swap the\npositions of these two documentation toolchains in some future date,\nand a good first step for it to happen would be an easier out-of-box\nexperience.\n\nThanks.\n"},{"id":"308938","messageId":"xmqqbmvi34ul.fsf@gitster.mtv.corp.google.com","threadId":"44807","inReplyTo":"20170104080852.bmlmtzxhjx4qt74f@sigill.intra.peff.net","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-07T22:03:30Z","receivedAt":"2017-01-07T22:03:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Mon, Jan 02, 2017 at 05:03:57PM +0100, Johannes Schindelin wrote:\n>\n>> From: =?UTF-8?q?=EB=A7=88=EB=88=84=EC=97=98?= \n>> \n>> The `user-manual.txt` is designed as a `book` but the `Makefile` wants\n>> to build it as an `article`. This seems to be a problem when building\n>> the documentation with `asciidoctor`. Furthermore the parts *Git\n>> Glossary* and *Appendix B* had no subsections which is not allowed when\n>> building with `asciidoctor`. So lets add a *dummy* section.\n>\n> The git-scm.com site uses asciidoctor, too, and I think I have seen some\n> oddness with the rendering though. So in general I am in favor of making\n> things work under both asciidoc and asciidoctor.\n>\n> I diffed the results of \"make user-manual.html\" before and after this\n> patch. A lot of \"h3\" chapter titles get bumped to \"h2\", which is OK. The\n> chapter titles now say \"Chapter 1. Repositories and Branches\" rather\n> than just \"Repositories and Branches\". Likewise, references now say\n>\n> Chapter 1, _Repositories and Branches_\n>\n> rather than:\n>\n> the section called \"Repositories and Branches\".\n>\n> which is probably OK, though the whole thing is short enough that\n> calling the sections chapters feels a bit over-important.\n\nIs that a longer way to say that the claim \"... is designed as a\nbook\" is false?\n\n> So I dunno. I really do think \"article\" is conceptually the most\n> appropriate style, but I agree that there are some book-like things\n> (like appendices).\n\n... Yeah, I should have read forward first before starting to insert\nmy comments.\n"},{"id":"308939","messageId":"xmqq7f6634rp.fsf@gitster.mtv.corp.google.com","threadId":"44807","inReplyTo":"20170104081544.5htofa3zpgkvty7x@sigill.intra.peff.net","subject":"Re: [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-07T22:05:14Z","receivedAt":"2017-01-07T22:05:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Mon, Jan 02, 2017 at 05:04:05PM +0100, Johannes Schindelin wrote:\n>\n>> The \"giteveryday\" document has a callout list that contains a code\n>> block. This is not a problem for AsciiDoc, but AsciiDoctor sadly was\n>> explicitly designed *not* to render this correctly [*1*]. The symptom is\n>> an unhelpful\n>> \n>> \tline 322: callout list item index: expected 1 got 12\n>> \tline 325: no callouts refer to list item 1\n>> \tline 325: callout list item index: expected 2 got 13\n>> \tline 327: no callouts refer to list item 2\n>> \n>> In Git for Windows, we rely on the speed improvement of AsciiDoctor (on\n>> this developer's machine, `make -j15 html` takes roughly 30 seconds with\n>> AsciiDoctor, 70 seconds with AsciiDoc), therefore we need a way to\n>> render this correctly.\n>> \n>> The easiest way out is to simplify the callout list, as suggested by\n>> AsciiDoctor's author, even while one may very well disagree with him\n>> that a code block hath no place in a callout list.\n>\n> This looks like a good re-write to avoid the issue while maintaining the\n> meaning and flow of the original.\n\nOK. Ack.\n\nThanks.\n"},{"id":"308940","messageId":"20170107220834.uge5ksdr66asw27q@genre.crustytoothpaste.net","threadId":"44807","inReplyTo":"20170105164556.b3bzeqqzx4pvni4z@sigill.intra.peff.net","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-01-07T22:08:34Z","receivedAt":"2017-01-07T22:09:02Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Thu, Jan 05, 2017 at 11:45:57AM -0500, Jeff King wrote:\n> On Thu, Jan 05, 2017 at 11:05:29AM +0100, Lars Schneider wrote:\n> \n> > > The git-scm.com site uses asciidoctor, too, and I think I have seen some\n> > > oddness with the rendering though. So in general I am in favor of making\n> > > things work under both asciidoc and asciidoctor.\n> > \n> > I am not familiar with both tools but it sounds to me as if \"asciidoctor\"\n> > is kind of the \"lowest common denominator\". Is this true? If yes, would it\n> > make sense to switch TravisCI [1] to asciidocter if this change gets merged?\n> \n> I don't think that's quite true.\n> \n> The two programs produce different output for certain inputs. We tend to\n> see the cases where asciidoc produces the desired output and asciidoctor\n> doesn't, because traditionally the documentation was written _for_\n> asciidoc. So whenever asciidoctor diverges, it looks like a bug.\n\nThis is indeed the case. Asciidoctor is a bit stricter on some inputs\nbecause it provides significant performance improvements, but it also\nhas features that AsciiDoc does not. It also has some bugs that\nAsciiDoc does not (again, usually due to performance concerns).\n\nFor example, Debian's reproducible builds project would probably like it\nif we had better support for Asciidoctor.\n\n> [1] I think we've also traditionally considered asciidoc to be the\n> definitive toolchain, and people using asciidoctor are free to\n> submit patches to make things work correctly in both places. I'm not\n> opposed to changing that attitude, as it seems like asciidoctor is\n> faster and more actively maintained these days. But I suspect our\n> build chain would need some improvements. Last time I tried building\n> with AsciiDoctor it involved a lot manual tweaking of Makefile\n> variables. It sounds like Dscho is doing it regularly, though. It\n> should probably work out of the box (with something like\n> USE_ASCIIDOCTOR=Yes) if we expect people to actually rely on it.\n\nYes, that would probably be beneficial. I'll see if I can come up with\nsome patches based on Dscho's work.\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":"308948","messageId":"20170108032709.k43zmej5lxmcoj4o@sigill.intra.peff.net","threadId":"44807","inReplyTo":"xmqqbmvi34ul.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-01-08T03:27:09Z","receivedAt":"2017-01-08T03:27:17Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Jan 07, 2017 at 02:03:30PM -0800, Junio C Hamano wrote:\n\n> Is that a longer way to say that the claim \"... is designed as a\n> book\" is false?\n> \n> > So I dunno. I really do think \"article\" is conceptually the most\n> > appropriate style, but I agree that there are some book-like things\n> > (like appendices).\n> \n> ... Yeah, I should have read forward first before starting to insert\n> my comments.\n\nTo be honest, I'm not sure whether \"book\" versus \"article\" was really\nconsidered in the original writing. I think we can call it whichever\nproduces the output we find most pleasing. I was mostly just pointing at\nthere are some tradeoffs in the end result in flipping the type.\n\n-Peff\n"},{"id":"309188","messageId":"xmqqmveyplln.fsf@gitster.mtv.corp.google.com","threadId":"44807","inReplyTo":"20170107220834.uge5ksdr66asw27q@genre.crustytoothpaste.net","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-10T22:59:48Z","receivedAt":"2017-01-10T22:59:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n>> [1] I think we've also traditionally considered asciidoc to be the\n>> definitive toolchain, and people using asciidoctor are free to\n>> submit patches to make things work correctly in both places. I'm not\n>> opposed to changing that attitude, as it seems like asciidoctor is\n>> faster and more actively maintained these days. But I suspect our\n>> build chain would need some improvements. Last time I tried building\n>> with AsciiDoctor it involved a lot manual tweaking of Makefile\n>> variables. It sounds like Dscho is doing it regularly, though. It\n>> should probably work out of the box (with something like\n>> USE_ASCIIDOCTOR=Yes) if we expect people to actually rely on it.\n>\n> Yes, that would probably be beneficial. I'll see if I can come up with\n> some patches based on Dscho's work.\n\nThanks.\n"},{"id":"309189","messageId":"xmqqinpmpld0.fsf@gitster.mtv.corp.google.com","threadId":"44807","inReplyTo":"20170108032709.k43zmej5lxmcoj4o@sigill.intra.peff.net","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-10T23:04:59Z","receivedAt":"2017-01-10T23:05:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Sat, Jan 07, 2017 at 02:03:30PM -0800, Junio C Hamano wrote:\n>\n>> Is that a longer way to say that the claim \"... is designed as a\n>> book\" is false?\n>> \n>> > So I dunno. I really do think \"article\" is conceptually the most\n>> > appropriate style, but I agree that there are some book-like things\n>> > (like appendices).\n>> \n>> ... Yeah, I should have read forward first before starting to insert\n>> my comments.\n>\n> To be honest, I'm not sure whether \"book\" versus \"article\" was really\n> considered in the original writing. I think we can call it whichever\n> produces the output we find most pleasing. I was mostly just pointing at\n> there are some tradeoffs in the end result in flipping the type.\n\nI understand. \n\nAnd I tend to agree that the silliness you observed (like a t-o-c\nfor a one-section \"chapter\") is not quite welcome.\n\nFor now I queued only 2/2 which looked good. I won't object if\nsomebody else rerolls 1/2 to appease AsciiDoctor, but let's take an\nobviously good bit first.\n\nThanks.\n"},{"id":"309268","messageId":"alpine.DEB.2.20.1701121130190.3469@virtualbox","threadId":"44807","inReplyTo":"xmqqinpmpld0.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2017-01-12T11:15:08Z","receivedAt":"2017-01-12T11:15:34Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Junio,\n\nOn Tue, 10 Jan 2017, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > On Sat, Jan 07, 2017 at 02:03:30PM -0800, Junio C Hamano wrote:\n> >\n> >> Is that a longer way to say that the claim \"... is designed as a\n> >> book\" is false?\n> >> \n> >> > So I dunno. I really do think \"article\" is conceptually the most\n> >> > appropriate style, but I agree that there are some book-like things\n> >> > (like appendices).\n> >> \n> >> ... Yeah, I should have read forward first before starting to insert\n> >> my comments.\n> >\n> > To be honest, I'm not sure whether \"book\" versus \"article\" was really\n> > considered in the original writing. I think we can call it whichever\n> > produces the output we find most pleasing. I was mostly just pointing at\n> > there are some tradeoffs in the end result in flipping the type.\n> \n> I understand. \n> \n> And I tend to agree that the silliness you observed (like a t-o-c\n> for a one-section \"chapter\") is not quite welcome.\n> \n> For now I queued only 2/2 which looked good. I won't object if\n> somebody else rerolls 1/2 to appease AsciiDoctor, but let's take an\n> obviously good bit first.\n\nFor fun, I just reverted the article->book patch and I was greeted with\nthis:\n\n-- snip --\n ASCIIDOC user-manual.xml\nasciidoctor: ERROR: user-manual.txt: line 44: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 477: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 477: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 477: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 2814: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 2814: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 2814: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 2958: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 2958: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 2958: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 3514: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 3514: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 3514: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 3771: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 3771: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 3771: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4147: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4147: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4147: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4395: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4395: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4395: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4401: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4401: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4636: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4636: only book doctypes can\ncontain level 0 sections\nasciidoctor: ERROR: user-manual.txt: line 4636: only book doctypes can\ncontain level 0 sections\n-- snap --\n\nIt still builds, funnily enough, but the result is definitely worse on the\neyes. The page is *really* long, and structuring it into individual parts\ndoes help the readability.\n\nCompare for yourself: https://dscho.github.io/git/index.html (this will go\naway at some point in the future, but I do not think there is a way for me\nto send two 200+kB HTML files to the Git mailing list).\n\nCiao,\nDscho\n\nP.S.: I also tried to use [glossary] and [appendix] as appropriate, but it\nseems that AsciiDoc *insists* on level-2 sections in an appendix, while\nAsciiDoctor *insists* on level-3 sections. In other words, the following\ndiff on top of my patch series yields the warning \"asciidoc: WARNING:\nuser-manual.txt: line 4411: section title out of sequence: expect\ned level 2, got level 3\" with AsciiDoc, while AsciiDoctor is totally\nhappy:\n\ncommit 900e193f15d5d2ef32285b1db9eb24c10710b7c1\nAuthor: Johannes Schindelin \nDate: Thu Jan 12 12:06:16 2017 +0100\n\n fixup! asciidoctor: fix user-manual to be built by `asciidoctor`\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex bc29298678..c1ab6ce453 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -4392,25 +4392,23 @@ You see, Git is actually the best tool to find out\nabout the source of Git\n itself!\n \n [[glossary]]\n+[glossary]\n Git Glossary\n ============\n \n-[[git-explained]]\n-Git explained\n--------------\n-\n include::glossary-content.txt[]\n \n [[git-quick-start]]\n-Appendix A: Git Quick Reference\n-===============================\n+[appendix]\n+Git Quick Reference\n+===================\n \n This is a quick summary of the major commands; the previous chapters\n explain how these work in more detail.\n \n [[quick-creating-a-new-repository]]\n Creating a new repository\n--------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~\n \n From a tarball:\n \n@@ -4432,7 +4430,7 @@ $ cd project\n \n [[managing-branches]]\n Managing branches\n------------------\n+~~~~~~~~~~~~~~~~~\n \n -----------------------------------------------\n $ git branch\t # list all local branches in this repo\n@@ -4497,7 +4495,7 @@ $ git branch -r\t\t\t# list all remote\nbranches\n \n [[exploring-history]]\n Exploring history\n------------------\n+~~~~~~~~~~~~~~~~~\n \n -----------------------------------------------\n $ gitk\t\t\t # visualize and browse history\n@@ -4533,7 +4531,7 @@ $ git bisect bad\t\t# if this revision is bad.\n \n [[making-changes]]\n Making changes\n---------------\n+~~~~~~~~~~~~~~\n \n Make sure Git knows who to blame:\n \n@@ -4564,7 +4562,7 @@ $ git commit -a\t # use latest content of all\ntracked files\n \n [[merging]]\n Merging\n--------\n+~~~~~~~\n \n -----------------------------------------------\n $ git merge test # merge branch \"test\" into the current branch\n@@ -4575,7 +4573,7 @@ $ git pull . test # equivalent to git merge test\n \n [[sharing-your-changes]]\n Sharing your changes\n---------------------\n+~~~~~~~~~~~~~~~~~~~~\n \n Importing or exporting patches:\n \n@@ -4621,7 +4619,7 @@ $ git push example test\n \n [[repository-maintenance]]\n Repository maintenance\n-----------------------\n+~~~~~~~~~~~~~~~~~~~~~~\n \n Check for corruption:\n \n@@ -4637,12 +4635,9 @@ $ git gc\n \n \n [[todo]]\n-Appendix B: Notes and todo list for this manual\n-===============================================\n-\n-[[todo-list]]\n-Todo list\n----------\n+[appendix]\n+Notes and todo list for this manual\n+===================================\n \n This is a work in progress.\n \n\n"},{"id":"309284","messageId":"xmqq37gokrdj.fsf@gitster.mtv.corp.google.com","threadId":"44807","inReplyTo":"alpine.DEB.2.20.1701121130190.3469@virtualbox","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-12T19:30:48Z","receivedAt":"2017-01-12T19:31:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin writes:\n\n>> And I tend to agree that the silliness you observed (like a t-o-c\n>> for a one-section \"chapter\") is not quite welcome.\n>> \n>> For now I queued only 2/2 which looked good. I won't object if\n>> somebody else rerolls 1/2 to appease AsciiDoctor, but let's take an\n>> obviously good bit first.\n>\n> For fun, I just reverted the article->book patch and I was greeted with\n> this:\n> ...\n> It still builds, funnily enough, but the result is definitely worse on the\n> eyes. The page is *really* long, and structuring it into individual parts\n> does help the readability.\n> ...\n> P.S.: I also tried to use [glossary] and [appendix] as appropriate, but it\n> seems that AsciiDoc *insists* on level-2 sections in an appendix, while\n> AsciiDoctor *insists* on level-3 sections.\n\nSo in short, what you are saying is that the support for articles in\nAsciiDoctor is borked and totally unusable on an article that needs\nto be taken correctly by AsciiDoc, and your conclusion is that the\nonly way to move forward (other than giving up using AsciiDoctor) is\nto avoid writing documents as articles, and existing articles need\nto be adjusted to read as books.\n\nIf that is the case, then I agree with the conclusion. As I already\nsaid, I won't object to a reroll of 1/2 to make the document format\nwell with AsciiDoctor without breaking rendering by AsciiDoc too\nbadly, and your \"for fun\" experiment illustrated that such a reroll\nstill needs to avoid using article style. Perhaps 1/2 posted as-is\nis the best we could do within that constraint.\n\nLet's queue it on 'pu' and see if somebody else comes up with an\nupdate that is more visually pleasing with both backends.\n\nThanks.\n\n\n\n"},{"id":"309380","messageId":"xmqqziiuhkvz.fsf@gitster.mtv.corp.google.com","threadId":"44807","inReplyTo":"xmqq37gokrdj.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-13T18:31:28Z","receivedAt":"2017-01-13T18:33:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> ... Perhaps 1/2 posted as-is\n> is the best we could do within that constraint.\n>\n> Let's queue it on 'pu' and see if somebody else comes up with an\n> update that is more visually pleasing with both backends.\n\n... and I noticed that I didn't get to actually queuing this\nyesterday, even though I sent the message above.\n\nNow I have, and the patch will be part of tonight's pushout.\n\nThanks.\n"}]}