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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 12, 2017, 19:30 UTC
Message-ID: <xmqq37gokrdj.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <alpine.DEB.2.20.1701121130190.3469@virtualbox>

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Show 17 quoted lines

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