git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH] INSTALL: note about make man with Asciidoctor backend
@ 2021-05-12  6:41 Bagas Sanjaya
  2021-05-12  7:00 ` Junio C Hamano
  0 siblings, 1 reply; 6+ messages in thread
From: Bagas Sanjaya @ 2021-05-12  6:41 UTC (permalink / raw)
  To: git
  Cc: brian m . carlson, Felipe Contreras, Martin Ågren,
	Jeff King, 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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH] INSTALL: note about make man with Asciidoctor backend
  2021-05-12  6:41 [PATCH] INSTALL: note about make man with Asciidoctor backend Bagas Sanjaya
@ 2021-05-12  7:00 ` Junio C Hamano
  2021-05-12  8:13   ` Felipe Contreras
  0 siblings, 1 reply; 6+ messages in thread
From: Junio C Hamano @ 2021-05-12  7:00 UTC (permalink / raw)
  To: Bagas Sanjaya
  Cc: git, brian m . carlson, Felipe Contreras, Martin Ågren, Jeff King

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.

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH] INSTALL: note about make man with Asciidoctor backend
  2021-05-12  7:00 ` Junio C Hamano
@ 2021-05-12  8:13   ` Felipe Contreras
  2021-05-13 13:41     ` Martin Ågren
  0 siblings, 1 reply; 6+ messages in thread
From: Felipe Contreras @ 2021-05-12  8:13 UTC (permalink / raw)
  To: Junio C Hamano, Bagas Sanjaya
  Cc: git, brian m . carlson, Felipe Contreras, Martin Ågren, Jeff King

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

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH] INSTALL: note about make man with Asciidoctor backend
  2021-05-12  8:13   ` Felipe Contreras
@ 2021-05-13 13:41     ` Martin Ågren
  2021-05-13 20:23       ` Junio C Hamano
  2021-06-02 20:07       ` Felipe Contreras
  0 siblings, 2 replies; 6+ messages in thread
From: Martin Ågren @ 2021-05-13 13:41 UTC (permalink / raw)
  To: Felipe Contreras
  Cc: Junio C Hamano, Bagas Sanjaya, Git Mailing List,
	brian m . carlson, Jeff King

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

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH] INSTALL: note about make man with Asciidoctor backend
  2021-05-13 13:41     ` Martin Ågren
@ 2021-05-13 20:23       ` Junio C Hamano
  2021-06-02 20:07       ` Felipe Contreras
  1 sibling, 0 replies; 6+ messages in thread
From: Junio C Hamano @ 2021-05-13 20:23 UTC (permalink / raw)
  To: Martin Ågren
  Cc: Felipe Contreras, Bagas Sanjaya, Git Mailing List,
	brian m . carlson, Jeff King

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.


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH] INSTALL: note about make man with Asciidoctor backend
  2021-05-13 13:41     ` Martin Ågren
  2021-05-13 20:23       ` Junio C Hamano
@ 2021-06-02 20:07       ` Felipe Contreras
  1 sibling, 0 replies; 6+ messages in thread
From: Felipe Contreras @ 2021-06-02 20:07 UTC (permalink / raw)
  To: Martin Ågren, Felipe Contreras
  Cc: Junio C Hamano, Bagas Sanjaya, Git Mailing List,
	brian m . carlson, Jeff King

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

^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2021-06-02 20:08 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-12  6:41 [PATCH] INSTALL: note about make man with Asciidoctor backend Bagas Sanjaya
2021-05-12  7:00 ` Junio C Hamano
2021-05-12  8:13   ` Felipe Contreras
2021-05-13 13:41     ` Martin Ågren
2021-05-13 20:23       ` Junio C Hamano
2021-06-02 20:07       ` Felipe Contreras

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).