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

On 2021-05-12 at 04:41:41, Felipe Contreras wrote:

brian m. carlson wrote:

quoted

From: Felipe Contreras <redacted>

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

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.  Be
careful to reset the font to the previous after the change.  In order to
do so, we must reset to the previous after each font change so the
previous state at the end is the state before our inserted text, since
troff only remembers one previous font.

Because Asciidoctor versions before 2.0 had a few problems with man page
output, let's default this to off for now,

quoted

since some common distros are > still on 1.5.

Are "some common distros" namely Debian stable *exclusively*?

If so, I would consider flipping the default the other way around,
espececially since it's only te default shipped by the Debian stable
packages (easily fixed by `gem install asciidoctor`).

CentOS 7 and Ubuntu 18.04 also ship 1.5.  CentOS 8 does not appear to
ship Asciidoctor at all.

quoted

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

The other way around: if users are using an ancient distribution they
can disable the option.

Debian stable is not ancient.  It is less than two years old, which for
a Linux distro or any operating system distribution, is not at all
considered even reasonably old.

I am not going to propose or give my approval to a change that causes
problems building Git with the distro packages on Debian stable or the
latest Ubuntu LTS, in any way, shape, or form.  People should be able to
use the distro packages if that's most convenient.

quoted

Suggested-by: Bagas Sanjaya <redacted>
Signed-off-by: Felipe Contreras <redacted>
Signed-off-by: brian m. carlson <redacted>

Commit-message-by: brian m. carlson [off-list ref]

I certainly would not want to pretend to have written the text above.

I'll reroll with the author reset.

quoted

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a00803..40fa87b121 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb

@@ -15,6 +15,8 @@ module Git
           "#{target}(#{attrs[1]})</ulink>"
         elsif parent.document.basebackend? 'html'
           %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
+        elsif parent.document.basebackend? 'manpage'
+          %(\\fB#{target}\\fP\\fR(#{attrs[1]})\\fP)

I still prefer my original version, especially since:

 1. I suspect most git developers are familiar with printf directives:
    %s.
 2. Where is that \\fP coming from? I don't see that with xmlto, nor the
    publicly genrated man pages[1].

That's coming from my knowledge of troff, having used it extensively
over the years, and my general hesitance to affect global state.

 3. Doesn't work on my machine without my original \e; I see
    "\fBgittutorial\fR(7)".

Works just fine on my system using Asciidoctor 2.0.12.  The \e would
insert an additional escape character and shouldn't be needed unless
we're in copy mode (which we should not be here).
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US