| Message ID | 20210512064128.15411-1-bagasdotme@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | INSTALL: note about make man with Asciidoctor backend | expand |
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.
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.
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
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.
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.
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
"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(-)