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

[Felipe Contreras <felipe.contreras@gmail.com>]

Junio C Hamano wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
> > "make man" can now be also done with Asciidoctor's manpage backend
> > instead of asciidoc+xmlto.
> >
> > Update INSTALL to reflect that.
> >
> > Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> > ---
> >
> >  This patch is based on  "doc: add an option to have Asciidoctor build
> >  man pages directly" series by brian m. carlson [1]. It can be added
> >  to that series.
> 
> It's not like "can be"; it would not make any sense to queue this
> patch before queuing those two patches below it ;-)
> 
> Not everybody with Asciidoctor can do the "man" without xmlto; they
> must have recent enough vintage of Asciidoctor, or they need xmlto.

This is something yet to be determined (I will investigate).

It's likely that they *can* do `make man` without xmlto, but perhaps
they wouldn't have a perfect output (yet to be determined).

> > @@ -201,6 +202,11 @@ Issues of note:
> >     use Asciidoctor (requires Ruby) by passing USE_ASCIIDOCTOR=YesPlease
> >     to make. You need at least Asciidoctor version 1.5.
> >  
> > +   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.

(not beeing able to copy-paste chunks of code from a man page with
apostrophes can't be hardly considered "unusable").


Either way, more work is needed to figure out what's going on.

Cheers.

-- 
Felipe Contreras