Bagas Sanjaya [off-list ref] 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 <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.
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.
quoted hunk
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?
quoted hunk
@@ -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 [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
On Wed, 12 May 2021 at 10:13, Felipe Contreras
[off-list ref] wrote:
Junio C Hamano wrote:
quoted
Bagas Sanjaya [off-list ref] writes:
quoted
+ 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 wrote:
On Wed, 12 May 2021 at 10:13, Felipe Contreras
[off-list ref] wrote:
quoted
Junio C Hamano wrote:
quoted
Bagas Sanjaya [off-list ref] writes:
quoted
+ 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