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

Johannes Schindelin [off-list ref] writes:

quoted

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.