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

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Jan 5, 2017, 13:49 UTC
Message-ID: <alpine.DEB.2.20.1701051444390.3469@virtualbox>
In-Reply-To: <1D7C66EA-E87A-4154-ACAC-8045D28477D2@gmail.com>

Hi Lars,

On Thu, 5 Jan 2017, Lars Schneider wrote:

Show 21 quoted lines

> > On 04 Jan 2017, at 09:08, Jeff King <peff@peff.net> wrote:
> > 
> > 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@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 am not familiar with both tools but it sounds to me as if
> "asciidoctor" is kind of the "lowest common denominator". Is this true?
> If yes, would it make sense to switch TravisCI [1] to asciidocter if
> this change gets merged?

It is true that asciidoc typically parses whatever asciidoctor parses, but not vice versa.

In that light, I would love to see our Travis runs to switch to asciidoctor.

For the record, this is my local config.mak in the asciidoctor worktree:

-- snip -- ASCIIDOC=asciidoctor ASCIIDOC_HTML=html5 ASCIIDOC_DOCBOOK=docbook45 ASCIIDOC_EXTRA="-alitdd=&\#45;&\#45;" ASCIIDOC_CONF=-I"/mingw64/lib/asciidoctor-extensions" -rman-inline-macro -- snap --

Please note that the extensions are required to build correctly (and we require this patch, too, unfortunately: https://github.com/git-for-windows/MINGW-packages/blob/master/mingw-w64-asciidoctor-extensions/0001-man-inline-macro-enable-linkgit-syntax.patch).

Ciao, Dscho