summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2017-02-02 13:36:57 -0800
committerJunio C Hamano <gitster@pobox.com>2017-02-02 13:36:57 -0800
commita77fe4a976dadea6ae0549a78a004665dbefdc7a (patch)
treeb221de2b9615d79827797071544544c7758caa13
parentbe6de6ecf99f8390fb09fef12cf4d739263b5124 (diff)
parent55d2d812e49aece049b73682ad5980ea84e23839 (diff)
downloadgit-a77fe4a976dadea6ae0549a78a004665dbefdc7a.tar.gz
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
-rw-r--r--Documentation/Makefile20
-rw-r--r--Documentation/asciidoctor-extensions.rb28
-rwxr-xr-xDocumentation/cat-texi.perl21
-rw-r--r--Documentation/texi.xsl26
-rw-r--r--Makefile6
5 files changed, 88 insertions, 13 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile
index a9fb497b83..b5be2e2d3f 100644
--- 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
index 0000000000..ec83b4959e
--- /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 87437f8a95..14d2f83415 100755
--- 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 @@ while (<STDIN>) {
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 @@ printf '\input texinfo
@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
index 0000000000..0f8ff07eca
--- /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 108d3731fc..8e4081e061 100644
--- 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