* [PATCH 0/2] Fix the documentation to build with asciidoctor @ 2017-01-02 16:03 Johannes Schindelin 2017-01-02 16:03 ` [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` Johannes Schindelin 2017-01-02 16:04 ` [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor Johannes Schindelin 0 siblings, 2 replies; 18+ messages in thread From: Johannes Schindelin @ 2017-01-02 16:03 UTC (permalink / raw) To: git; +Cc: Junio C Hamano [-- Attachment #1: Type: text/plain, Size: 2856 bytes --] The first patch in this series has been with Git for Windows for well over a year already, the second one is a replacement for such an old patch. The reason why we use asciidoctor in Git for Windows is easy to see: when building new Git for Windows packages, rendering the documentation dominates the time by far. It takes roughly 75 seconds to compile all the executables from scratch on my main work machine, but it takes roughly 125 seconds to build the documentation from scratch. Out of those 125 seconds, 45 are taken by the HTML documentation. In the Git for Windows project, we realized a long time ago that we could reduce the time dramatically by using asciidoctor: it takes only 15 seconds to build the HTML documentation. Those savings come at a cost, though: asciidoctor was designed to be much less flexible than asciidoc, in favor for maximum speed and minimal size of the code base. And to accomodate those shortcomings, it is unfortunately necessary to change Git's documentation sources. So what is the big deal with those timings? It's only half a minute! This is on a very beefy machine. Internally, I use quite a bit of Continuous Integration to build intermediate Git for Windows versions for testing, and those builds are backed by reasonably-sized VMs. That makes it worth shaving that extra time off. Side note for the curious who wonder why asciidoctor is *so much* faster than asciidoc: my gut feeling is that the primary reason for this is, once again, the POSIX emulation layer: asciidoc runs as a Python script, using a Python interpreter that uses the MSYS2 runtime for path translation and fork emulation (among other things), while asciidoctor runs as a Ruby script, using a pure Windows Ruby interpreter (for those remembering the nomenclature: the Python interpreter is an MSYS2 program while the Ruby interpreter is a MINGW program). But even after that I suspect that asciidoc was just not designed for speed, on a very fundamental level. Now back to the patch series: I *hope* the patches are not too disruptive. I am very open to changing them however needed, I only care about one result in the end: that the documentation builds correctly (and fast) with asciidoctor. Johannes Schindelin (1): giteveryday: unbreak rendering with AsciiDoctor 마누엘 (1): asciidoctor: fix user-manual to be built by `asciidoctor` Documentation/Makefile | 2 +- Documentation/giteveryday.txt | 17 +++++++++-------- Documentation/user-manual.txt | 8 ++++++++ 3 files changed, 18 insertions(+), 9 deletions(-) base-commit: e05806da9ec4aff8adfed142ab2a2b3b02e33c8c Published-As: https://github.com/dscho/git/releases/tag/asciidoctor-fixes-v1 Fetch-It-Via: git fetch https://github.com/dscho/git asciidoctor-fixes-v1 -- 2.11.0.rc3.windows.1 ^ permalink raw reply [flat|nested] 18+ messages in thread
* [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-02 16:03 [PATCH 0/2] Fix the documentation to build with asciidoctor Johannes Schindelin @ 2017-01-02 16:03 ` Johannes Schindelin 2017-01-04 8:08 ` Jeff King 2017-01-02 16:04 ` [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor Johannes Schindelin 1 sibling, 1 reply; 18+ messages in thread From: Johannes Schindelin @ 2017-01-02 16:03 UTC (permalink / raw) To: git; +Cc: 마누엘, Junio C Hamano [-- Attachment #1: Type: text/plain, Size: 1789 bytes --] From: =?UTF-8?q?=EB=A7=88=EB=88=84=EC=97=98?= <nalla@hamal.uberspace.de> The `user-manual.txt` is designed as a `book` but the `Makefile` wants to build it as an `article`. This seems to be a problem when building the documentation with `asciidoctor`. Furthermore the parts *Git Glossary* and *Appendix B* had no subsections which is not allowed when building with `asciidoctor`. So lets add a *dummy* section. Signed-off-by: 마누엘 <nalla@hamal.uberspace.de> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> --- Documentation/Makefile | 2 +- Documentation/user-manual.txt | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index b43d66eae6..a9fb497b83 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -337,7 +337,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in user-manual.xml: user-manual.txt user-manual.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(TXT_TO_XML) -d article -o $@+ $< && \ + $(TXT_TO_XML) -d book -o $@+ $< && \ mv $@+ $@ technical/api-index.txt: technical/api-index-skel.txt \ diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 5e07454572..bc29298678 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -4395,6 +4395,10 @@ itself! Git Glossary ============ +[[git-explained]] +Git explained +------------- + include::glossary-content.txt[] [[git-quick-start]] @@ -4636,6 +4640,10 @@ $ git gc Appendix B: Notes and todo list for this manual =============================================== +[[todo-list]] +Todo list +--------- + This is a work in progress. The basic requirements: -- 2.11.0.rc3.windows.1 ^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-02 16:03 ` [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` Johannes Schindelin @ 2017-01-04 8:08 ` Jeff King 2017-01-05 10:05 ` Lars Schneider 2017-01-07 22:03 ` Junio C Hamano 0 siblings, 2 replies; 18+ messages in thread From: Jeff King @ 2017-01-04 8:08 UTC (permalink / raw) To: Johannes Schindelin; +Cc: git, 마누엘, Junio C Hamano On Mon, Jan 02, 2017 at 05:03:57PM +0100, Johannes Schindelin wrote: > From: =?UTF-8?q?=EB=A7=88=EB=88=84=EC=97=98?= <nalla@hamal.uberspace.de> > > The `user-manual.txt` is designed as a `book` but the `Makefile` wants > to build it as an `article`. This seems to be a problem when building > the documentation with `asciidoctor`. Furthermore the parts *Git > Glossary* and *Appendix B* had no subsections which is not allowed when > building with `asciidoctor`. So lets add a *dummy* section. The git-scm.com site uses asciidoctor, too, and I think I have seen some oddness with the rendering though. So in general I am in favor of making things work under both asciidoc and asciidoctor. I diffed the results of "make user-manual.html" before and after this patch. A lot of "h3" chapter titles get bumped to "h2", which is OK. The chapter titles now say "Chapter 1. Repositories and Branches" rather than just "Repositories and Branches". Likewise, references now say Chapter 1, _Repositories and Branches_ rather than: the section called "Repositories and Branches". which is probably OK, though the whole thing is short enough that calling the sections chapters feels a bit over-important. Chapters now get their own table of contents, too. This is especially silly in one-section chapters like "Git Glossary". So I dunno. I really do think "article" is conceptually the most appropriate style, but I agree that there are some book-like things (like appendices). -Peff ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-04 8:08 ` Jeff King @ 2017-01-05 10:05 ` Lars Schneider 2017-01-05 13:49 ` Johannes Schindelin 2017-01-05 16:45 ` Jeff King 2017-01-07 22:03 ` Junio C Hamano 1 sibling, 2 replies; 18+ messages in thread From: Lars Schneider @ 2017-01-05 10:05 UTC (permalink / raw) To: Jeff King Cc: Johannes Schindelin, git, 마누엘, Junio C Hamano > On 04 Jan 2017, at 09:08, Jeff King <peff@peff.net> wrote: > > On Mon, Jan 02, 2017 at 05:03:57PM +0100, Johannes Schindelin wrote: > >> From: =?UTF-8?q?=EB=A7=88=EB=88=84=EC=97=98?= <nalla@hamal.uberspace.de> >> >> The `user-manual.txt` is designed as a `book` but the `Makefile` wants >> to build it as an `article`. This seems to be a problem when building >> the documentation with `asciidoctor`. Furthermore the parts *Git >> Glossary* and *Appendix B* had no subsections which is not allowed when >> building with `asciidoctor`. So lets add a *dummy* section. > > The git-scm.com site uses asciidoctor, too, and I think I have seen some > oddness with the rendering though. So in general I am in favor of making > things work under both asciidoc and asciidoctor. I am not familiar with both tools but it sounds to me as if "asciidoctor" is kind of the "lowest common denominator". Is this true? If yes, would it make sense to switch TravisCI [1] to asciidocter if this change gets merged? - Lars [1] https://github.com/git/git/blob/master/.travis.yml#L48 ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-05 10:05 ` Lars Schneider @ 2017-01-05 13:49 ` Johannes Schindelin 2017-01-05 16:45 ` Jeff King 1 sibling, 0 replies; 18+ messages in thread From: Johannes Schindelin @ 2017-01-05 13:49 UTC (permalink / raw) To: Lars Schneider; +Cc: Jeff King, git, 마누엘, Junio C Hamano Hi Lars, On Thu, 5 Jan 2017, Lars Schneider wrote: > > On 04 Jan 2017, at 09:08, Jeff King <peff@peff.net> wrote: > > > > On Mon, Jan 02, 2017 at 05:03:57PM +0100, Johannes Schindelin wrote: > > > >> From: =?UTF-8?q?=EB=A7=88=EB=88=84=EC=97=98?= <nalla@hamal.uberspace.de> > >> > >> The `user-manual.txt` is designed as a `book` but the `Makefile` > >> wants to build it as an `article`. This seems to be a problem when > >> building the documentation with `asciidoctor`. Furthermore the parts > >> *Git Glossary* and *Appendix B* had no subsections which is not > >> allowed when building with `asciidoctor`. So lets add a *dummy* > >> section. > > > > The git-scm.com site uses asciidoctor, too, and I think I have seen > > some oddness with the rendering though. So in general I am in favor of > > making things work under both asciidoc and asciidoctor. > > I am not familiar with both tools but it sounds to me as if > "asciidoctor" is kind of the "lowest common denominator". Is this true? > If yes, would it make sense to switch TravisCI [1] to asciidocter if > this change gets merged? It is true that asciidoc typically parses whatever asciidoctor parses, but not vice versa. In that light, I would love to see our Travis runs to switch to asciidoctor. For the record, this is my local config.mak in the asciidoctor worktree: -- snip -- ASCIIDOC=asciidoctor ASCIIDOC_HTML=html5 ASCIIDOC_DOCBOOK=docbook45 ASCIIDOC_EXTRA="-alitdd=&\#45;&\#45;" ASCIIDOC_CONF=-I"/mingw64/lib/asciidoctor-extensions" -rman-inline-macro -- snap -- Please note that the extensions are required to build correctly (and we require this patch, too, unfortunately: https://github.com/git-for-windows/MINGW-packages/blob/master/mingw-w64-asciidoctor-extensions/0001-man-inline-macro-enable-linkgit-syntax.patch). Ciao, Dscho ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-05 10:05 ` Lars Schneider 2017-01-05 13:49 ` Johannes Schindelin @ 2017-01-05 16:45 ` Jeff King 2017-01-07 22:00 ` Junio C Hamano 2017-01-07 22:08 ` brian m. carlson 1 sibling, 2 replies; 18+ messages in thread From: Jeff King @ 2017-01-05 16:45 UTC (permalink / raw) To: Lars Schneider Cc: Johannes Schindelin, git, 마누엘, Junio C Hamano On Thu, Jan 05, 2017 at 11:05:29AM +0100, Lars Schneider wrote: > > The git-scm.com site uses asciidoctor, too, and I think I have seen some > > oddness with the rendering though. So in general I am in favor of making > > things work under both asciidoc and asciidoctor. > > I am not familiar with both tools but it sounds to me as if "asciidoctor" > is kind of the "lowest common denominator". Is this true? If yes, would it > make sense to switch TravisCI [1] to asciidocter if this change gets merged? I don't think that's quite true. The two programs produce different output for certain inputs. We tend to see the cases where asciidoc produces the desired output and asciidoctor doesn't, because traditionally the documentation was written _for_ asciidoc. So whenever asciidoctor diverges, it looks like a bug. If people start developing and checking their work using asciidoctor[1], then we'll see bugs going in the other direction. As far as CI goes, I am not altogether convinced of the usefulness of building the documentation. It's very expensive, and the failure mode is rarely "whoops, running `make doc` failed". It's almost always that the output looks subtly wrong, but that's very hard to check automatically. [1] I think we've also traditionally considered asciidoc to be the definitive toolchain, and people using asciidoctor are free to submit patches to make things work correctly in both places. I'm not opposed to changing that attitude, as it seems like asciidoctor is faster and more actively maintained these days. But I suspect our build chain would need some improvements. Last time I tried building with AsciiDoctor it involved a lot manual tweaking of Makefile variables. It sounds like Dscho is doing it regularly, though. It should probably work out of the box (with something like USE_ASCIIDOCTOR=Yes) if we expect people to actually rely on it. ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-05 16:45 ` Jeff King @ 2017-01-07 22:00 ` Junio C Hamano 2017-01-07 22:08 ` brian m. carlson 1 sibling, 0 replies; 18+ messages in thread From: Junio C Hamano @ 2017-01-07 22:00 UTC (permalink / raw) To: Jeff King Cc: Lars Schneider, Johannes Schindelin, git, 마누엘 Jeff King <peff@peff.net> writes: > As far as CI goes, I am not altogether convinced of the usefulness of > building the documentation. It's very expensive, and the failure mode is > rarely "whoops, running `make doc` failed". It's almost always that the > output looks subtly wrong, but that's very hard to check automatically. I've seen "make doc" break for me when it works for other people, and if CI can check the formatting for various combinations of versions of toolchain components, it would have some value. But otherwise, I agree that "make doc" in CI would not give us as much benefit as we spend electricity on it. If we are to make support for building with AsciiDoctor better, CI that does "make doc" with both AsciiDoc and AsciiDoctor might be of help---a "make it buildable with A" patch may accidentally break B and vice versa. > [1] I think we've also traditionally considered asciidoc to be the > definitive toolchain, and people using asciidoctor are free to > submit patches to make things work correctly in both places. I'm not > opposed to changing that attitude, as it seems like asciidoctor is > faster and more actively maintained these days. But I suspect our > build chain would need some improvements. Last time I tried building > with AsciiDoctor it involved a lot manual tweaking of Makefile > variables. It sounds like Dscho is doing it regularly, though. It > should probably work out of the box (with something like > USE_ASCIIDOCTOR=Yes) if we expect people to actually rely on it. I do not mind getting convinced to declare that we will swap the positions of these two documentation toolchains in some future date, and a good first step for it to happen would be an easier out-of-box experience. Thanks. ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-05 16:45 ` Jeff King 2017-01-07 22:00 ` Junio C Hamano @ 2017-01-07 22:08 ` brian m. carlson 2017-01-10 22:59 ` Junio C Hamano 1 sibling, 1 reply; 18+ messages in thread From: brian m. carlson @ 2017-01-07 22:08 UTC (permalink / raw) To: Jeff King Cc: Lars Schneider, Johannes Schindelin, git, 마누엘, Junio C Hamano [-- Attachment #1: Type: text/plain, Size: 2330 bytes --] On Thu, Jan 05, 2017 at 11:45:57AM -0500, Jeff King wrote: > On Thu, Jan 05, 2017 at 11:05:29AM +0100, Lars Schneider wrote: > > > > The git-scm.com site uses asciidoctor, too, and I think I have seen some > > > oddness with the rendering though. So in general I am in favor of making > > > things work under both asciidoc and asciidoctor. > > > > I am not familiar with both tools but it sounds to me as if "asciidoctor" > > is kind of the "lowest common denominator". Is this true? If yes, would it > > make sense to switch TravisCI [1] to asciidocter if this change gets merged? > > I don't think that's quite true. > > The two programs produce different output for certain inputs. We tend to > see the cases where asciidoc produces the desired output and asciidoctor > doesn't, because traditionally the documentation was written _for_ > asciidoc. So whenever asciidoctor diverges, it looks like a bug. This is indeed the case. Asciidoctor is a bit stricter on some inputs because it provides significant performance improvements, but it also has features that AsciiDoc does not. It also has some bugs that AsciiDoc does not (again, usually due to performance concerns). For example, Debian's reproducible builds project would probably like it if we had better support for Asciidoctor. > [1] I think we've also traditionally considered asciidoc to be the > definitive toolchain, and people using asciidoctor are free to > submit patches to make things work correctly in both places. I'm not > opposed to changing that attitude, as it seems like asciidoctor is > faster and more actively maintained these days. But I suspect our > build chain would need some improvements. Last time I tried building > with AsciiDoctor it involved a lot manual tweaking of Makefile > variables. It sounds like Dscho is doing it regularly, though. It > should probably work out of the box (with something like > USE_ASCIIDOCTOR=Yes) if we expect people to actually rely on it. Yes, that would probably be beneficial. I'll see if I can come up with some patches based on Dscho's work. -- brian m. carlson / brian with sandals: Houston, Texas, US +1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only OpenPGP: https://keybase.io/bk2204 [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 868 bytes --] ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-07 22:08 ` brian m. carlson @ 2017-01-10 22:59 ` Junio C Hamano 0 siblings, 0 replies; 18+ messages in thread From: Junio C Hamano @ 2017-01-10 22:59 UTC (permalink / raw) To: brian m. carlson Cc: Jeff King, Lars Schneider, Johannes Schindelin, git, 마누엘 "brian m. carlson" <sandals@crustytoothpaste.net> writes: >> [1] I think we've also traditionally considered asciidoc to be the >> definitive toolchain, and people using asciidoctor are free to >> submit patches to make things work correctly in both places. I'm not >> opposed to changing that attitude, as it seems like asciidoctor is >> faster and more actively maintained these days. But I suspect our >> build chain would need some improvements. Last time I tried building >> with AsciiDoctor it involved a lot manual tweaking of Makefile >> variables. It sounds like Dscho is doing it regularly, though. It >> should probably work out of the box (with something like >> USE_ASCIIDOCTOR=Yes) if we expect people to actually rely on it. > > Yes, that would probably be beneficial. I'll see if I can come up with > some patches based on Dscho's work. Thanks. ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-04 8:08 ` Jeff King 2017-01-05 10:05 ` Lars Schneider @ 2017-01-07 22:03 ` Junio C Hamano 2017-01-08 3:27 ` Jeff King 1 sibling, 1 reply; 18+ messages in thread From: Junio C Hamano @ 2017-01-07 22:03 UTC (permalink / raw) To: Jeff King; +Cc: Johannes Schindelin, git, 마누엘 Jeff King <peff@peff.net> writes: > On Mon, Jan 02, 2017 at 05:03:57PM +0100, Johannes Schindelin wrote: > >> From: =?UTF-8?q?=EB=A7=88=EB=88=84=EC=97=98?= <nalla@hamal.uberspace.de> >> >> The `user-manual.txt` is designed as a `book` but the `Makefile` wants >> to build it as an `article`. This seems to be a problem when building >> the documentation with `asciidoctor`. Furthermore the parts *Git >> Glossary* and *Appendix B* had no subsections which is not allowed when >> building with `asciidoctor`. So lets add a *dummy* section. > > The git-scm.com site uses asciidoctor, too, and I think I have seen some > oddness with the rendering though. So in general I am in favor of making > things work under both asciidoc and asciidoctor. > > I diffed the results of "make user-manual.html" before and after this > patch. A lot of "h3" chapter titles get bumped to "h2", which is OK. The > chapter titles now say "Chapter 1. Repositories and Branches" rather > than just "Repositories and Branches". Likewise, references now say > > Chapter 1, _Repositories and Branches_ > > rather than: > > the section called "Repositories and Branches". > > which is probably OK, though the whole thing is short enough that > calling the sections chapters feels a bit over-important. Is that a longer way to say that the claim "... is designed as a book" is false? > So I dunno. I really do think "article" is conceptually the most > appropriate style, but I agree that there are some book-like things > (like appendices). ... Yeah, I should have read forward first before starting to insert my comments. ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-07 22:03 ` Junio C Hamano @ 2017-01-08 3:27 ` Jeff King 2017-01-10 23:04 ` Junio C Hamano 0 siblings, 1 reply; 18+ messages in thread From: Jeff King @ 2017-01-08 3:27 UTC (permalink / raw) To: Junio C Hamano; +Cc: Johannes Schindelin, git, 마누엘 On Sat, Jan 07, 2017 at 02:03:30PM -0800, Junio C Hamano wrote: > Is that a longer way to say that the claim "... is designed as a > book" is false? > > > So I dunno. I really do think "article" is conceptually the most > > appropriate style, but I agree that there are some book-like things > > (like appendices). > > ... Yeah, I should have read forward first before starting to insert > my comments. To be honest, I'm not sure whether "book" versus "article" was really considered in the original writing. I think we can call it whichever produces the output we find most pleasing. I was mostly just pointing at there are some tradeoffs in the end result in flipping the type. -Peff ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-08 3:27 ` Jeff King @ 2017-01-10 23:04 ` Junio C Hamano 2017-01-12 11:15 ` Johannes Schindelin 0 siblings, 1 reply; 18+ messages in thread From: Junio C Hamano @ 2017-01-10 23:04 UTC (permalink / raw) To: Jeff King; +Cc: Johannes Schindelin, git, 마누엘 Jeff King <peff@peff.net> writes: > On Sat, Jan 07, 2017 at 02:03:30PM -0800, Junio C Hamano wrote: > >> Is that a longer way to say that the claim "... is designed as a >> book" is false? >> >> > So I dunno. I really do think "article" is conceptually the most >> > appropriate style, but I agree that there are some book-like things >> > (like appendices). >> >> ... Yeah, I should have read forward first before starting to insert >> my comments. > > To be honest, I'm not sure whether "book" versus "article" was really > considered in the original writing. I think we can call it whichever > produces the output we find most pleasing. I was mostly just pointing at > there are some tradeoffs in the end result in flipping the type. I understand. And I tend to agree that the silliness you observed (like a t-o-c for a one-section "chapter") is not quite welcome. For now I queued only 2/2 which looked good. I won't object if somebody else rerolls 1/2 to appease AsciiDoctor, but let's take an obviously good bit first. Thanks. ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-10 23:04 ` Junio C Hamano @ 2017-01-12 11:15 ` Johannes Schindelin 2017-01-12 19:30 ` Junio C Hamano 0 siblings, 1 reply; 18+ messages in thread From: Johannes Schindelin @ 2017-01-12 11:15 UTC (permalink / raw) To: Junio C Hamano; +Cc: Jeff King, git, 마누엘 Hi Junio, On Tue, 10 Jan 2017, Junio C Hamano wrote: > Jeff King <peff@peff.net> writes: > > > On Sat, Jan 07, 2017 at 02:03:30PM -0800, Junio C Hamano wrote: > > > >> Is that a longer way to say that the claim "... is designed as a > >> book" is false? > >> > >> > So I dunno. I really do think "article" is conceptually the most > >> > appropriate style, but I agree that there are some book-like things > >> > (like appendices). > >> > >> ... Yeah, I should have read forward first before starting to insert > >> my comments. > > > > To be honest, I'm not sure whether "book" versus "article" was really > > considered in the original writing. I think we can call it whichever > > produces the output we find most pleasing. I was mostly just pointing at > > there are some tradeoffs in the end result in flipping the type. > > I understand. > > And I tend to agree that the silliness you observed (like a t-o-c > for a one-section "chapter") is not quite welcome. > > For now I queued only 2/2 which looked good. I won't object if > somebody else rerolls 1/2 to appease AsciiDoctor, but let's take an > obviously good bit first. For fun, I just reverted the article->book patch and I was greeted with this: -- snip -- ASCIIDOC user-manual.xml asciidoctor: ERROR: user-manual.txt: line 44: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 477: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 477: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 477: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 2814: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 2814: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 2814: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 2958: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 2958: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 2958: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 3514: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 3514: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 3514: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 3771: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 3771: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 3771: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4147: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4147: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4147: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4395: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4395: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4395: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4401: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4401: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4636: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4636: only book doctypes can contain level 0 sections asciidoctor: ERROR: user-manual.txt: line 4636: only book doctypes can contain level 0 sections -- snap -- It still builds, funnily enough, but the result is definitely worse on the eyes. The page is *really* long, and structuring it into individual parts does help the readability. Compare for yourself: https://dscho.github.io/git/index.html (this will go away at some point in the future, but I do not think there is a way for me to send two 200+kB HTML files to the Git mailing list). Ciao, Dscho P.S.: I also tried to use [glossary] and [appendix] as appropriate, but it seems that AsciiDoc *insists* on level-2 sections in an appendix, while AsciiDoctor *insists* on level-3 sections. In other words, the following diff on top of my patch series yields the warning "asciidoc: WARNING: user-manual.txt: line 4411: section title out of sequence: expect ed level 2, got level 3" with AsciiDoc, while AsciiDoctor is totally happy: commit 900e193f15d5d2ef32285b1db9eb24c10710b7c1 Author: Johannes Schindelin <johannes.schindelin@gmx.de> Date: Thu Jan 12 12:06:16 2017 +0100 fixup! asciidoctor: fix user-manual to be built by `asciidoctor` diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index bc29298678..c1ab6ce453 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -4392,25 +4392,23 @@ You see, Git is actually the best tool to find out about the source of Git itself! [[glossary]] +[glossary] Git Glossary ============ -[[git-explained]] -Git explained -------------- - include::glossary-content.txt[] [[git-quick-start]] -Appendix A: Git Quick Reference -=============================== +[appendix] +Git Quick Reference +=================== This is a quick summary of the major commands; the previous chapters explain how these work in more detail. [[quick-creating-a-new-repository]] Creating a new repository -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ From a tarball: @@ -4432,7 +4430,7 @@ $ cd project [[managing-branches]] Managing branches ------------------ +~~~~~~~~~~~~~~~~~ ----------------------------------------------- $ git branch # list all local branches in this repo @@ -4497,7 +4495,7 @@ $ git branch -r # list all remote branches [[exploring-history]] Exploring history ------------------ +~~~~~~~~~~~~~~~~~ ----------------------------------------------- $ gitk # visualize and browse history @@ -4533,7 +4531,7 @@ $ git bisect bad # if this revision is bad. [[making-changes]] Making changes --------------- +~~~~~~~~~~~~~~ Make sure Git knows who to blame: @@ -4564,7 +4562,7 @@ $ git commit -a # use latest content of all tracked files [[merging]] Merging -------- +~~~~~~~ ----------------------------------------------- $ git merge test # merge branch "test" into the current branch @@ -4575,7 +4573,7 @@ $ git pull . test # equivalent to git merge test [[sharing-your-changes]] Sharing your changes --------------------- +~~~~~~~~~~~~~~~~~~~~ Importing or exporting patches: @@ -4621,7 +4619,7 @@ $ git push example test [[repository-maintenance]] Repository maintenance ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ Check for corruption: @@ -4637,12 +4635,9 @@ $ git gc [[todo]] -Appendix B: Notes and todo list for this manual -=============================================== - -[[todo-list]] -Todo list ---------- +[appendix] +Notes and todo list for this manual +=================================== This is a work in progress. ^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-12 11:15 ` Johannes Schindelin @ 2017-01-12 19:30 ` Junio C Hamano 2017-01-13 18:31 ` Junio C Hamano 0 siblings, 1 reply; 18+ messages in thread From: Junio C Hamano @ 2017-01-12 19:30 UTC (permalink / raw) To: Johannes Schindelin; +Cc: Jeff King, git, 마누엘 Johannes Schindelin <Johannes.Schindelin@gmx.de> writes: >> And I tend to agree that the silliness you observed (like a t-o-c >> for a one-section "chapter") is not quite welcome. >> >> For now I queued only 2/2 which looked good. I won't object if >> somebody else rerolls 1/2 to appease AsciiDoctor, but let's take an >> obviously good bit first. > > For fun, I just reverted the article->book patch and I was greeted with > this: > ... > It still builds, funnily enough, but the result is definitely worse on the > eyes. The page is *really* long, and structuring it into individual parts > does help the readability. > ... > P.S.: I also tried to use [glossary] and [appendix] as appropriate, but it > seems that AsciiDoc *insists* on level-2 sections in an appendix, while > AsciiDoctor *insists* on level-3 sections. So in short, what you are saying is that the support for articles in AsciiDoctor is borked and totally unusable on an article that needs to be taken correctly by AsciiDoc, and your conclusion is that the only way to move forward (other than giving up using AsciiDoctor) is to avoid writing documents as articles, and existing articles need to be adjusted to read as books. If that is the case, then I agree with the conclusion. As I already said, I won't object to a reroll of 1/2 to make the document format well with AsciiDoctor without breaking rendering by AsciiDoc too badly, and your "for fun" experiment illustrated that such a reroll still needs to avoid using article style. Perhaps 1/2 posted as-is is the best we could do within that constraint. Let's queue it on 'pu' and see if somebody else comes up with an update that is more visually pleasing with both backends. Thanks. ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` 2017-01-12 19:30 ` Junio C Hamano @ 2017-01-13 18:31 ` Junio C Hamano 0 siblings, 0 replies; 18+ messages in thread From: Junio C Hamano @ 2017-01-13 18:31 UTC (permalink / raw) To: Johannes Schindelin; +Cc: Jeff King, git, 마누엘 Junio C Hamano <gitster@pobox.com> writes: > ... Perhaps 1/2 posted as-is > is the best we could do within that constraint. > > Let's queue it on 'pu' and see if somebody else comes up with an > update that is more visually pleasing with both backends. ... and I noticed that I didn't get to actually queuing this yesterday, even though I sent the message above. Now I have, and the patch will be part of tonight's pushout. Thanks. ^ permalink raw reply [flat|nested] 18+ messages in thread
* [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor 2017-01-02 16:03 [PATCH 0/2] Fix the documentation to build with asciidoctor Johannes Schindelin 2017-01-02 16:03 ` [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` Johannes Schindelin @ 2017-01-02 16:04 ` Johannes Schindelin 2017-01-04 8:15 ` Jeff King 1 sibling, 1 reply; 18+ messages in thread From: Johannes Schindelin @ 2017-01-02 16:04 UTC (permalink / raw) To: git; +Cc: Junio C Hamano The "giteveryday" document has a callout list that contains a code block. This is not a problem for AsciiDoc, but AsciiDoctor sadly was explicitly designed *not* to render this correctly [*1*]. The symptom is an unhelpful line 322: callout list item index: expected 1 got 12 line 325: no callouts refer to list item 1 line 325: callout list item index: expected 2 got 13 line 327: no callouts refer to list item 2 In Git for Windows, we rely on the speed improvement of AsciiDoctor (on this developer's machine, `make -j15 html` takes roughly 30 seconds with AsciiDoctor, 70 seconds with AsciiDoc), therefore we need a way to render this correctly. The easiest way out is to simplify the callout list, as suggested by AsciiDoctor's author, even while one may very well disagree with him that a code block hath no place in a callout list. *1*: https://github.com/asciidoctor/asciidoctor/issues/1478 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> --- Documentation/giteveryday.txt | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt index 35473ad02f..10c8ff93c0 100644 --- a/Documentation/giteveryday.txt +++ b/Documentation/giteveryday.txt @@ -307,9 +307,16 @@ master or exposed as a part of a stable branch. <9> backport a critical fix. <10> create a signed tag. <11> make sure master was not accidentally rewound beyond that -already pushed out. `ko` shorthand points at the Git maintainer's +already pushed out. +<12> In the output from `git show-branch`, `master` should have +everything `ko/master` has, and `next` should have +everything `ko/next` has, etc. +<13> push out the bleeding edge, together with new tags that point +into the pushed history. + +In this example, the `ko` shorthand points at the Git maintainer's repository at kernel.org, and looks like this: -+ + ------------ (in .git/config) [remote "ko"] @@ -320,12 +327,6 @@ repository at kernel.org, and looks like this: push = +refs/heads/pu push = refs/heads/maint ------------ -+ -<12> In the output from `git show-branch`, `master` should have -everything `ko/master` has, and `next` should have -everything `ko/next` has, etc. -<13> push out the bleeding edge, together with new tags that point -into the pushed history. Repository Administration[[ADMINISTRATION]] -- 2.11.0.rc3.windows.1 ^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor 2017-01-02 16:04 ` [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor Johannes Schindelin @ 2017-01-04 8:15 ` Jeff King 2017-01-07 22:05 ` Junio C Hamano 0 siblings, 1 reply; 18+ messages in thread From: Jeff King @ 2017-01-04 8:15 UTC (permalink / raw) To: Johannes Schindelin; +Cc: git, Junio C Hamano On Mon, Jan 02, 2017 at 05:04:05PM +0100, Johannes Schindelin wrote: > The "giteveryday" document has a callout list that contains a code > block. This is not a problem for AsciiDoc, but AsciiDoctor sadly was > explicitly designed *not* to render this correctly [*1*]. The symptom is > an unhelpful > > line 322: callout list item index: expected 1 got 12 > line 325: no callouts refer to list item 1 > line 325: callout list item index: expected 2 got 13 > line 327: no callouts refer to list item 2 > > In Git for Windows, we rely on the speed improvement of AsciiDoctor (on > this developer's machine, `make -j15 html` takes roughly 30 seconds with > AsciiDoctor, 70 seconds with AsciiDoc), therefore we need a way to > render this correctly. > > The easiest way out is to simplify the callout list, as suggested by > AsciiDoctor's author, even while one may very well disagree with him > that a code block hath no place in a callout list. This looks like a good re-write to avoid the issue while maintaining the meaning and flow of the original. -Peff ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor 2017-01-04 8:15 ` Jeff King @ 2017-01-07 22:05 ` Junio C Hamano 0 siblings, 0 replies; 18+ messages in thread From: Junio C Hamano @ 2017-01-07 22:05 UTC (permalink / raw) To: Jeff King; +Cc: Johannes Schindelin, git Jeff King <peff@peff.net> writes: > On Mon, Jan 02, 2017 at 05:04:05PM +0100, Johannes Schindelin wrote: > >> The "giteveryday" document has a callout list that contains a code >> block. This is not a problem for AsciiDoc, but AsciiDoctor sadly was >> explicitly designed *not* to render this correctly [*1*]. The symptom is >> an unhelpful >> >> line 322: callout list item index: expected 1 got 12 >> line 325: no callouts refer to list item 1 >> line 325: callout list item index: expected 2 got 13 >> line 327: no callouts refer to list item 2 >> >> In Git for Windows, we rely on the speed improvement of AsciiDoctor (on >> this developer's machine, `make -j15 html` takes roughly 30 seconds with >> AsciiDoctor, 70 seconds with AsciiDoc), therefore we need a way to >> render this correctly. >> >> The easiest way out is to simplify the callout list, as suggested by >> AsciiDoctor's author, even while one may very well disagree with him >> that a code block hath no place in a callout list. > > This looks like a good re-write to avoid the issue while maintaining the > meaning and flow of the original. OK. Ack. Thanks. ^ permalink raw reply [flat|nested] 18+ messages in thread
end of thread, other threads:[~2017-01-13 18:32 UTC | newest] Thread overview: 18+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2017-01-02 16:03 [PATCH 0/2] Fix the documentation to build with asciidoctor Johannes Schindelin 2017-01-02 16:03 ` [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` Johannes Schindelin 2017-01-04 8:08 ` Jeff King 2017-01-05 10:05 ` Lars Schneider 2017-01-05 13:49 ` Johannes Schindelin 2017-01-05 16:45 ` Jeff King 2017-01-07 22:00 ` Junio C Hamano 2017-01-07 22:08 ` brian m. carlson 2017-01-10 22:59 ` Junio C Hamano 2017-01-07 22:03 ` Junio C Hamano 2017-01-08 3:27 ` Jeff King 2017-01-10 23:04 ` Junio C Hamano 2017-01-12 11:15 ` Johannes Schindelin 2017-01-12 19:30 ` Junio C Hamano 2017-01-13 18:31 ` Junio C Hamano 2017-01-02 16:04 ` [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor Johannes Schindelin 2017-01-04 8:15 ` Jeff King 2017-01-07 22:05 ` Junio C Hamano
Code repositories for project(s) associated with this public inbox https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).