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

Junio C Hamano wrote:

Bagas Sanjaya [off-list ref] writes:

quoted

"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 <redacted>
---

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

quoted

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