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

brian m. carlson wrote:

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.

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

I don't see what that paragraph has to do with the patch below.

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.

Yes, but why shove it in this patch? Now this is is doing *two*
logically-independent changes.

Be careful to reset the font to the previous after the change.

This is a third change, since the current man pages already don't do
this:

  % zcat /usr/share/man/man1/git-add.1.gz | grep '\fB'
  you must use the \fBadd\fR command

We insert \e before each font-change backslash so Asciidoctor doesn't
convert them into \*(rs, the reverse solidus character, and instead
leaves them as we wanted them.

Right. So my patch was correct: it is neecessary.

Additionally, we don't want to use XML-style escapes for the litdd and
plus macros, so let's only use the XML-style escapes in HTML and XML and
use something different for our man pages.

That's a fourth change now, and one that complicates the Makefile even
more, when I've been trying to simplify it.

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.

Can you point what problems are those? I did a doc-diff with my patches
on asciidoctor 1.5.8 and I did not see any major problems.

If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.

What rendering issues?

Also, the many should not suffer because of the few.

If a few people doing USE_ASCIIDOCTOR=YesPlease have issues (because of
ancient packages in their distribution, and their reluctance to type
`gem install`), then *they* can disable USE_ASCIIDOCTOR_MANPAGE (or just
disable USE_ASCIIDOCTOR altogether). Most people doing
USE_ASCIIDOCTOR=YesPlease should not suffer because of a
minority.

Signed-off-by: Felipe Contreras <redacted>

I most definitely do not sign off this.

-- 
Felipe Contreras