Re: [PATCH 1/2] doc: add an option to have Asciidoctor build man pages directly

Bagas Sanjaya wrote:

On 12/05/21 09.11, brian m. carlson wrote:

quoted

From: Felipe Contreras <redacted>

Asciidoctor contains a converter to generate man pages.  In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.

I have concern: I currently generate manpages with Asciidoctor+xmlto. Does
this change affects people using xmlto?

His proposed change: no, but mine does.

quoted

We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
by the GNU_ROFF option.  This option for the DocBook toolchain, as well
as newer versions of Asciidoctor, makes groff output an ASCII apostrophe
instead of a Unicode apostrophe in text, so as to make copy and pasting
commands easier.  These newer versions of Asciidoctor detect groff and
do the right thing in all cases, so the GNU_ROFF option is obsolete in
this case.

At what version of Asciidoctor the apostrophe handling is corrected?

I will look into this, but in my opinion it's not worth complicating the
doc toolchain for ancient distributions.

The only time people are going to notice something is when:

 1. They build git with USE_ASCIIDOCTOR=YesPlease
    USE_ASCIIDOCTOR_MANPAGE=YesPlease
 2. They use an ancient distribution
 3. They use the ancient distribution's asciidoctor packages, instead of
    Ruby's asciidoctor gem
 4. They open a manpage generated by this process
 5. They select text that specifically has an apostrophe
 6. They copy this text
 7. They paste this text somewhere else

Then, they *might* see some issue.

Yeah, let's not worry about about this *too much*.

quoted

Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: brian m. carlson <redacted>
---
I've preserved Felipe's authorship on this patch because much of it is
his work.  However, I have made some substantial changes here with which
I suspect he will disagree, in addition to expanding on the commit
message, so if he would prefer, I can reroll with the authorship
changed.  I have no preference myself.

  Documentation/Makefile                  | 10 ++++++++++
  Documentation/asciidoctor-extensions.rb |  2 ++
  Makefile                                |  3 +++
  3 files changed, 15 insertions(+)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 2aae4c9cbb..536d9a5f3d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -196,6 +196,9 @@ ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
  DBLATEX_COMMON =
  XMLTO_EXTRA += --skip-validation
  XMLTO_EXTRA += -x manpage.xsl
+ifdef USE_ASCIIDOCTOR_MANPAGE
+TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage

I think "ASCIIDOCTOR_TO_MAN" would be good alternative name here, since
this command generates manpage from asciidoctor.

All the current TXT_TO_* definitions use asciidoc.

Moreover, I'm currently working on some cleanup patches to make
TXT_TO_MAN work with asciidoc + xmlto, so this is future-proof.

quoted

--- a/Makefile
+++ b/Makefile

@@ -285,6 +285,9 @@ all::
  # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the
  # documentation.
  #
+# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
+# instead of building manual pages from DocBook.
+#

The wording should be "...instead of building manual pages from DocBook with
xmlto".

That's why in my opinion it should be the other way around:
USE_ASCIIDOCTOR_XMLTO=No.

Then the expalantion is not even needed, because you can deduce it from
the name of the configuration variable.

Cheers.

-- 
Felipe Contreras