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

From: Jeff King <peff@peff.net>
Date: Jan 4, 2017, 08:08 UTC
Message-ID: <20170104080852.bmlmtzxhjx4qt74f@sigill.intra.peff.net>
In-Reply-To: <3c160f81a88cf8697f2459bb7f2a3e27fb3e469c.1483373021.git.johannes.schindelin@gmx.de>

On Mon, Jan 02, 2017 at 05:03:57PM +0100, Johannes Schindelin wrote:

Show 7 quoted lines

> 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