On Wed, 12 May 2021 at 10:13, Felipe Contreras <felipe.contreras@xxxxxxxxx> wrote: > > Junio C Hamano wrote: > > Bagas Sanjaya <bagasdotme@xxxxxxxxx> 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@xxxxxxxxx/ Martin
