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

[Felipe Contreras <felipe.contreras@gmail.com>]

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 <felipe.contreras@gmail.com>

I most definitely do not sign off this.

-- 
Felipe Contreras