RE: [RFC/NOPATCHv3 1/4] doc: add an option to have Asciidoctor build man pages directly

From

Felipe Contreras <felipe.contreras@gmail.com>

Date

Jun 18, 2021, 20:57 UTC

Message-ID

<60cd08a716873_c0ff9208c4@natae.notmuch>

In-Reply-To

<20210618203057.790320-2-felipe.contreras@gmail.com>

Felipe Contreras wrote:

> From: "brian m. carlson" <sandals@crustytoothpaste.net>
> 
> 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.

This suffices:

  There's no need to use xmlto to build the man pages when modern
  asciidoctor can do it by itself.

> 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 isn't true. There's no difference from 1.5, 1.5.3, 2.0.0 or even 2.0.15.

> 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 (1.5.3 and above)
> detect groff and do the right thing in all cases, so the GNU_ROFF option
> is obsolete in this case.

> 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.

What are these "few problems"?

Cheers.

-- 
Felipe Contreras