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

["Martin Ågren" <martin.agren@gmail.com>]

On Wed, 12 May 2021 at 10:13, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
>
> Junio C Hamano wrote:
> > 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.
> > > +
> >
> > Hmph, I wasn't closely following the previous discussion, but is the
> > apostrophes the primary reason why anything below 2.0 is not usable?
>
> "Not usable"?
>
> I haven't been able to reproduce the original supposed problem, but even
> if true, the man pages would be quite usable.

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.
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. I would suggest the commit
message saying something like "I skimmed through the doc-diff between
the asciidoctor-with-xmlto and asciidoctor-without-xmlto (using
asciidoctor v2.x.y) -- there are quite many minor differences, but
nothing particularly jarring stands out".

[1] https://lore.kernel.org/git/20190325190041.GM4047@pobox.com/

Martin