Merge branch 'bc/use-asciidoctor-opt'

Asciidoctor, an alternative reimplementation of AsciiDoc, still
needs some changes to work with documents meant to be formatted
with AsciiDoc.  "make USE_ASCIIDOCTOR=YesPlease" to use it out of
the box to document our pages is getting closer to reality.

* bc/use-asciidoctor-opt:
Documentation: implement linkgit macro for Asciidoctor
Makefile: add a knob to enable the use of Asciidoctor
Documentation: move dblatex arguments into variable
Documentation: add XSLT to fix DocBook for Texinfo
Documentation: sort sources for gitman.texi
Documentation: remove unneeded argument in cat-texi.perl
Documentation: modernize cat-texi.perl
Documentation: fix warning in cat-texi.perl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index a9fb497b837dd39673ab7105774ad61ecbf67a6f..b5be2e2d3f5c8ade04fa81ddb5b24a8747838cdc 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -120,6 +120,7 @@ INSTALL_INFO = install-info
 DOCBOOK2X_TEXI = docbook2x-texi
 DBLATEX = dblatex
 ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex
+DBLATEX_COMMON = -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty
 ifndef PERL_PATH
        PERL_PATH = /usr/bin/perl
 endif
@@ -173,6 +174,16 @@ ifdef GNU_ROFF
 XMLTO_EXTRA += -m manpage-quote-apos.xsl
 endif
 
+ifdef USE_ASCIIDOCTOR
+ASCIIDOC = asciidoctor
+ASCIIDOC_CONF =
+ASCIIDOC_HTML = xhtml5
+ASCIIDOC_DOCBOOK = docbook45
+ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
+ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+DBLATEX_COMMON =
+endif
+
 SHELL_PATH ?= $(SHELL)
 # Shell quote;
 SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
@@ -368,13 +379,14 @@ user-manual.texi: user-manual.xml
 
 user-manual.pdf: user-manual.xml
        $(QUIET_DBLATEX)$(RM) $@+ $@ && \
-       $(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
+       $(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \
        mv $@+ $@
 
-gitman.texi: $(MAN_XML) cat-texi.perl
+gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
        $(QUIET_DB2TEXI)$(RM) $@+ $@ && \
-       ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
-               --to-stdout $(xml) &&) true) > $@++ && \
+       ($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \
+               $(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \
+               rm $(xml)+ &&) true) > $@++ && \
        $(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
        rm $@++ && \
        mv $@+ $@

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
new file mode 100644 (file)
index 0000000..ec83b49
--- /dev/null
+++ b/Documentation/asciidoctor-extensions.rb
@@ -0,0 +1,28 @@
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+module Git
+  module Documentation
+    class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor
+      use_dsl
+
+      named :chrome
+
+      def process(parent, target, attrs)
+        if parent.document.basebackend? 'html'
+          prefix = parent.document.attr('git-relative-html-prefix')
+          %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n)
+        elsif parent.document.basebackend? 'docbook'
+          "<citerefentry>\n" \
+            "<refentrytitle>#{target}</refentrytitle>" \
+            "<manvolnum>#{attrs[1]}</manvolnum>\n" \
+          "</citerefentry>\n"
+        end
+      end
+    end
+  end
+end
+
+Asciidoctor::Extensions.register do
+  inline_macro Git::Documentation::LinkGitProcessor, :linkgit
+end

diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index 87437f8a95768595e040b8c4c1d48e5c29ada087..14d2f834151712fa84e13209a65f0f7121b49dd7 100755 (executable)
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl
@@ -1,9 +1,12 @@
 #!/usr/bin/perl -w
 
+use strict;
+use warnings;
+
 my @menu = ();
 my $output = $ARGV[0];
 
-open TMP, '>', "$output.tmp";
+open my $tmp, '>', "$output.tmp";
 
 while (<STDIN>) {
        next if (/^\\input texinfo/../\@node Top/);
@@ -11,13 +14,13 @@
        if (s/^\@top (.*)/\@node $1,,,Top/) {
                push @menu, $1;
        }
-       s/\(\@pxref{\[(URLS|REMOTES)\]}\)//;
+       s/\(\@pxref\{\[(URLS|REMOTES)\]}\)//;
        s/\@anchor\{[^{}]*\}//g;
-       print TMP;
+       print $tmp $_;
 }
-close TMP;
+close $tmp;
 
-printf '\input texinfo
+print '\input texinfo
 @setfilename gitman.info
 @documentencoding UTF-8
 @dircategory Development
@@ -28,16 +31,16 @@
 @top Git Manual Pages
 @documentlanguage en
 @menu
-', $menu[0];
+';
 
 for (@menu) {
        print "* ${_}::\n";
 }
 print "\@end menu\n";
-open TMP, '<', "$output.tmp";
-while (<TMP>) {
+open $tmp, '<', "$output.tmp";
+while (<$tmp>) {
        print;
 }
-close TMP;
+close $tmp;
 print "\@bye\n";
 unlink "$output.tmp";

diff --git a/Documentation/texi.xsl b/Documentation/texi.xsl
new file mode 100644 (file)
index 0000000..0f8ff07
--- /dev/null
+++ b/Documentation/texi.xsl
@@ -0,0 +1,26 @@
+<!-- texi.xsl:
+     convert refsection elements into refsect elements that docbook2texi can
+     understand -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+               version="1.0">
+
+<xsl:output method="xml"
+           encoding="UTF-8"
+           doctype-public="-//OASIS//DTD DocBook XML V4.5//EN"
+           doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" />
+
+<xsl:template match="//refsection">
+       <xsl:variable name="element">refsect<xsl:value-of select="count(ancestor-or-self::refsection)" /></xsl:variable>
+       <xsl:element name="{$element}">
+               <xsl:apply-templates select="@*|node()" />
+       </xsl:element>
+</xsl:template>
+
+<!-- Copy all other nodes through. -->
+<xsl:template match="node()|@*">
+       <xsl:copy>
+               <xsl:apply-templates select="@*|node()" />
+       </xsl:copy>
+</xsl:template>
+
+</xsl:stylesheet>

diff --git a/Makefile b/Makefile
index 108d3731fcefc2abb0f593704794b95fd2c09c5c..8e4081e0619f8a9927a3a4c544048f576a194fd0 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -250,6 +250,12 @@ all::
 # apostrophes to be ASCII so that cut&pasting examples to the shell
 # will work.
 #
+# Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the
+# documentation.
+#
+# Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor
+# Extensions Lab if you have it available.
+#
 # Define PERL_PATH to the path of your Perl binary (usually /usr/bin/perl).
 #
 # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's