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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 12, 2021, 05:03 UTC
Message-ID: <609b618e663bd_678ff208ec@natae.notmuch>
In-Reply-To: <6d56412a-cc67-22fc-717f-9fa218264b40@gmail.com>

Bagas Sanjaya wrote:

Show 12 quoted lines

> On 12/05/21 09.11, brian m. carlson wrote:
> > From: Felipe Contreras <felipe.contreras@gmail.com>
> > 
> > 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.

Show 10 quoted lines

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

Show 27 quoted lines

> > Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
> > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> > Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> > ---
> > 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.

Show 11 quoted lines

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