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

> 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.
> > 
> > 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,
> 
> > 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`).

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

> > 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>
> 
> Commit-message-by: brian m. carlson <sandals@crustytoothpaste.net>
> 
> I certainly would not want to pretend to have written the text above.

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