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

On 2021-05-12 at 02:48:59, 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?

This change adds an option to allow not using xmlto at all but instead
using just Asciidoctor to generate manual pages.  If you do nothing,
you'll continue to use xmlto as before.

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?

The first released version is 1.5.3.

quoted

We also need to update the code that tells Asciidoctor how to format our
linkgit macros so that it can output proper code for man pages.  Be
careful to reset the font to the previous after the change.  In order to
do so, we must reset to the previous after each font change so the
previous state at the end is the state before our inserted text, since
troff only remembers one previous font.

Because Asciidoctor versions before 2.0 had a few problems with man page
output, let's default this to off for now, since some common distros are
still on 1.5.  If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.

Maybe when distros upgraded shipped Asciidoctor version to 2.0, we can
bump the version requirement.

My general policy, which need not be Git's policy (but I think is
reasonable), is that I will support the previous version of Debian and
Ubuntu LTS for a year after the new one comes out.  Under that policy,
we'd wait until a year after Debian 11 (bullseye) is released.

quoted

diff --git a/Makefile b/Makefile
index 93664d6714..cb75dec314 100644
--- 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".

I can make that change.  We're not using DocBook either way, with xmlto
or other tooling (e.g., a plain xsltproc), so what we have here is
accurate.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US