[PATCH 0/2] Fix the documentation to build with asciidoctor

[PATCH 0/2] Fix the documentation to build with asciidoctor

[Johannes Schindelin]

[-- 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

[PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Johannes Schindelin]

[-- 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

[PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor

[Johannes Schindelin]

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

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Jeff King]

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

Re: [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor

[Jeff King]

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

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Lars Schneider]

> 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

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Johannes Schindelin]

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

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Jeff King]

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.

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Junio C Hamano]

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.

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Junio C Hamano]

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.

Re: [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor

[Junio C Hamano]

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.

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[brian m. carlson]

[-- 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 --]

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Jeff King]

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

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Junio C Hamano]

"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.

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Junio C Hamano]

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.

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Johannes Schindelin]

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.
 

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Junio C Hamano]

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.

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

[Junio C Hamano]

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.