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.
>
> 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@xxxxxxxxx>
> Signed-off-by: Felipe Contreras <felipe.contreras@xxxxxxxxx>
> Signed-off-by: brian m. carlson <sandals@xxxxxxxxxxxxxxxxxxxx>
Commit-message-by: brian m. carlson <sandals@xxxxxxxxxxxxxxxxxxxx>
I certainly would not want to pretend to have written the text above.
> ---
> 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.
Hard to tell in this frankenstein commit. I'd be fine with a
Commit-message-by line.
> 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
I'd do:
ifndef USE_ASCIIDOCTOR_XMLTO
(the other way around)
> +TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
> +endif
> endif
>
> SHELL_PATH ?= $(SHELL)
> 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].
3. Doesn't work on my machine without my original \e; I see
"\fBgittutorial\fR(7)".
I don't see any way this is an improvement.
Cheers.
[1] https://git.kernel.org/pub/scm/git/git-manpages.git/tree/man1/git.1
--
Felipe Contreras
