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

From: Junio C Hamano <gitster@pobox.com>
Date: May 13, 2021, 20:23 UTC
Message-ID: <xmqqwns29ydw.fsf@gitster.g>
In-Reply-To: <CAN0heSrNzxSpq=trPvOHAYx_yT1W=WuN1XstzTRjHdZko-i+DA@mail.gmail.com>

Martin Ågren <martin.agren@gmail.com> writes:

Show 12 quoted lines

>> > Bagas Sanjaya <bagasdotme@gmail.com> 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.

Show 7 quoted lines

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