Subject: Re: [PATCH] INSTALL: note about make man with Asciidoctor backend

From: Junio C Hamano <[email-masked]>
Date: Fri, 14 May 2021 05:23:07 +0900

Martin Ågren <[email-masked]> writes:

>> > Bagas Sanjaya <[email-masked]> writes:
>> >
>> > > +   You can also do "make man" using Asciidoctor's manpage backend in
>> > > +   place of xmlto by passing USE_ASCIIDOCTOR_MANPAGE=YesPlease. Version
>> > > +   2.0 or later is highly recommended, as these version properly handle
>> > > +   apostrophes.
>> ...
>
> Even early 2.0.x had some issues [1]. It's always debatable whether they're
> significant or not, i.e., is a significant speed-up worth it if the
> result is just-as-informative-but-a-bit-ugly-here-and-there? We should
> provide some rough background here to help people and distros decide.

What does "properly handle apostrophes" refer to exactly?  I got an
impression that it was the pretty-quoting that breaks cut-and-paste,
which is a usability issue for manpages.

> Maybe something like
>
>   "This can be quite a bit faster and requires fewer dependencies, but
>    please note that this is early work: there are some typographical
>    issues we know of, and there might be others."
>
> but hopefully phrased better than that.

That looks like a good starting point.