Jeff King <peff@xxxxxxxx> 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@xxxxxxxxxxxxxxxxxx> >> >> 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.