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

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

[Bagas Sanjaya]

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

 [1]:
https://lore.kernel.org/git/20210512021138.63598-1-sandals@crustytoothpaste.net/

 INSTALL | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/INSTALL b/INSTALL
index 66389ce059..89e31566c3 100644
--- a/INSTALL
+++ b/INSTALL
@@ -184,8 +184,9 @@ Issues of note:
 
    "make doc" builds documentation in man and html formats; there are
    also "make man", "make html" and "make info". Note that "make html"
-   requires asciidoc, but not xmlto. "make man" (and thus make doc)
-   requires both.
+   requires asciidoc, but not xmlto. "make man" requires either
+   Asciidoctor or asciidoc+xmlto. "make doc" requires both asciidoc
+   and xmlto.
 
    "make install-doc" installs documentation in man format only; there
    are also "make install-man", "make install-html" and "make
@@ -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.
+
    There are also "make quick-install-doc", "make quick-install-man"
    and "make quick-install-html" which install preformatted man pages
    and html documentation. To use these build targets, you need to
-- 
2.25.1

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

[Junio C Hamano]

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.
The second hunk makes it quite clear, but the updated text in the
first hunk falls a bit short to convey that and needs a bit more
work to clarify, I would think.

> diff --git a/INSTALL b/INSTALL
> index 66389ce059..89e31566c3 100644
> --- a/INSTALL
> +++ b/INSTALL
> @@ -184,8 +184,9 @@ Issues of note:
>  
>     "make doc" builds documentation in man and html formats; there are
>     also "make man", "make html" and "make info". Note that "make html"
> -   requires asciidoc, but not xmlto. "make man" (and thus make doc)
> -   requires both.
> +   requires asciidoc, but not xmlto. "make man" requires either
> +   Asciidoctor or asciidoc+xmlto. "make doc" requires both asciidoc
> +   and xmlto.

As "make doc" is "make -C Documentaiton all",
   "make html" is "make -C Documentaiton html",
   "make man" is "make -C Documentaiton man",
and 
   "make -C Documentation all" is "make -C Documentation html man"

it seems that those who choose to go xmlto-less route for manpages
should not need xmlto while doing "make doc", so the last part of
the updated text is not quite accurate, no?

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

I actually do not mind, for clarity and brevity's sake, to give
readers a bit of white lie and just say something along the lines of

    If you use Asciidoctor version 2.0 or later, you can choose to
    directly generate manpages with its manpage backend, instaed of
    using xmlto in between, by passing USE_ASCIIDOCTOR_MANPAGE=YesPlease
    to "make man".

to _require_ 2.0 without even hinting that earlier versions might be
usable.

In any case, thanks for a good start.

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

[Felipe Contreras]

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

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

[Martin Ågren]

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

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

[Junio C Hamano]

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

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

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

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

[Felipe Contreras]

Martin Ågren wrote:
> 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].
> [1] https://lore.kernel.org/git/20190325190041.GM4047@pobox.com/

That issue affects only the docbook generation, not direct man pages.

So far nobody has mentioned any issues with USE_ASCIIDOCTOR_MANPAGE=1 in
older asciidoctor, especially not regarding apostrophes.

-- 
Felipe Contreras