Bagas Sanjaya wrote:
> On 12/05/21 09.11, brian m. carlson wrote:
> > From: Felipe Contreras <felipe.contreras@xxxxxxxxx>
> >
> > 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.
> > 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*.
> > Suggested-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
> > Signed-off-by: Felipe Contreras <felipe.contreras@xxxxxxxxx>
> > Signed-off-by: brian m. carlson <sandals@xxxxxxxxxxxxxxxxxxxx>
> > ---
> > 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.
> > --- 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
