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

[Junio C Hamano <gitster@pobox.com>]

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.