From f7bf8feaf504767d1c147cc8cd03d7df2539ba47 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Sun, 22 Jan 2017 02:41:50 +0000 Subject: Documentation: fix warning in cat-texi.perl Newer versions of Perl produce the warning "Unescaped left brace in regex is deprecated, passed through in regex" when an unescaped left brace occurs in a regex. Escape the brace to avoid this warning. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/cat-texi.perl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl index 87437f8a95..b1fe52e8b9 100755 --- a/Documentation/cat-texi.perl +++ b/Documentation/cat-texi.perl @@ -11,7 +11,7 @@ while () { if (s/^\@top (.*)/\@node $1,,,Top/) { push @menu, $1; } - s/\(\@pxref{\[(URLS|REMOTES)\]}\)//; + s/\(\@pxref\{\[(URLS|REMOTES)\]}\)//; s/\@anchor\{[^{}]*\}//g; print TMP; } -- cgit v1.2.3 From b56867c9866bede78bed30373a193d9c7f2ce2d3 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Sun, 22 Jan 2017 02:41:51 +0000 Subject: Documentation: modernize cat-texi.perl Good style for Perl includes using the strict and warnings pragmas, and preferring lexical file handles over bareword file handles. Using lexical file handles necessitates being explicit when $_ is printed, so that Perl does not get confused and instead print the glob ref. The benefit of this modernization is that a formerly obscured bug is now visible, which will be fixed in a followup patch. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/cat-texi.perl | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl index b1fe52e8b9..1bc84d3c7c 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 () { next if (/^\\input texinfo/../\@node Top/); @@ -13,9 +16,9 @@ while () { } s/\(\@pxref\{\[(URLS|REMOTES)\]}\)//; s/\@anchor\{[^{}]*\}//g; - print TMP; + print $tmp $_; } -close TMP; +close $tmp; printf '\input texinfo @setfilename gitman.info @@ -34,10 +37,10 @@ for (@menu) { print "* ${_}::\n"; } print "\@end menu\n"; -open TMP, '<', "$output.tmp"; -while () { +open $tmp, '<', "$output.tmp"; +while (<$tmp>) { print; } -close TMP; +close $tmp; print "\@bye\n"; unlink "$output.tmp"; -- cgit v1.2.3 From a7e1b15c5492c0d5da1187ed6d7a81270a1ec339 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Sun, 22 Jan 2017 02:41:52 +0000 Subject: Documentation: remove unneeded argument in cat-texi.perl The newly-added use of the warnings pragma exposes that the $menu[0] argument to printf has long been silently ignored, since there is no format specifier for it. It doesn't appear that the argument is actually needed, either: there is no reason to insert the name of one particular documentation page anywhere in the header that's being generated. Remove the unused argument, and since the format specification functionality is no longer needed, convert the printf to a simple print. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/cat-texi.perl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl index 1bc84d3c7c..14d2f83415 100755 --- a/Documentation/cat-texi.perl +++ b/Documentation/cat-texi.perl @@ -20,7 +20,7 @@ while () { } close $tmp; -printf '\input texinfo +print '\input texinfo @setfilename gitman.info @documentencoding UTF-8 @dircategory Development @@ -31,7 +31,7 @@ printf '\input texinfo @top Git Manual Pages @documentlanguage en @menu -', $menu[0]; +'; for (@menu) { print "* ${_}::\n"; -- cgit v1.2.3 From c4abba43554228a8c6e3082e7da7f0993c2d6b4b Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Sun, 22 Jan 2017 02:41:53 +0000 Subject: Documentation: sort sources for gitman.texi Sorting the sources makes it easier to compare the output using diff. In addition, it aids groups creating reproducible builds, as the order of the files is no longer dependent on the file system or other irrelevant factors. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index b43d66eae6..5e32bbe913 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -373,7 +373,7 @@ user-manual.pdf: user-manual.xml gitman.texi: $(MAN_XML) cat-texi.perl $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ - ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \ + ($(foreach xml,$(sort $(MAN_XML)),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \ --to-stdout $(xml) &&) true) > $@++ && \ $(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \ rm $@++ && \ -- cgit v1.2.3 From 95e5efc6dcf5941637bf9ead0f78861017c3aa85 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Sun, 22 Jan 2017 02:41:54 +0000 Subject: Documentation: add XSLT to fix DocBook for Texinfo There are two ways to create a section in a reference document (i.e., manpage) in DocBook 4: refsection elements and refsect, refsect2, and refsect3 elements. Either form is acceptable as of DocBook 4.2, but they cannot be mixed. Prior to DocBook 4.2, only the numbered forms were acceptable. docbook2texi only accepts the numbered forms, and this has not generally been a problem, since AsciiDoc produces the numbered forms. Asciidoctor, on the other hand, uses a shared backend for DocBook 4 and 5, and uses the unnumbered refsection elements instead. If we don't convert the unnumbered form to the numbered form, docbook2texi omits section headings, which is undesirable. Add an XSLT stylesheet to transform the unnumbered forms to the numbered forms automatically, and preprocess the DocBook XML as part of the transformation to Texinfo format. Note that this transformation is only necessary for Texinfo, since docbook2texi provides its own stylesheets. The DocBook stylesheets, which we use for other formats, provide the full range of DocBook 4 and 5 compatibility, and don't have this issue. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/Makefile | 7 ++++--- Documentation/texi.xsl | 26 ++++++++++++++++++++++++++ 2 files changed, 30 insertions(+), 3 deletions(-) create mode 100644 Documentation/texi.xsl diff --git a/Documentation/Makefile b/Documentation/Makefile index 5e32bbe913..eecc27aba2 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -371,10 +371,11 @@ user-manual.pdf: user-manual.xml $(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \ mv $@+ $@ -gitman.texi: $(MAN_XML) cat-texi.perl +gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ - ($(foreach xml,$(sort $(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/texi.xsl b/Documentation/texi.xsl new file mode 100644 index 0000000000..0f8ff07eca --- /dev/null +++ b/Documentation/texi.xsl @@ -0,0 +1,26 @@ + + + + + + + refsect + + + + + + + + + + + + + -- cgit v1.2.3 From ae4e3e8d449a8e1fbe8d5a3fe5e69f1154f97f3f Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Sun, 22 Jan 2017 02:41:55 +0000 Subject: Documentation: move dblatex arguments into variable Our dblatex invocation uses several style components from the AsciiDoc distribution, but those components are not available when building with Asciidoctor. Move the command line arguments into a variable so it can be overridden by the user or makefile configuration options. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index eecc27aba2..3e317b8c1c 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 @@ -368,7 +369,7 @@ 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 texi.xsl -- cgit v1.2.3 From ec3366eb52caad29e4cfb0a0afb605c450ad5a39 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Sun, 22 Jan 2017 02:41:56 +0000 Subject: Makefile: add a knob to enable the use of Asciidoctor While Git has traditionally built its documentation using AsciiDoc, some people wish to use Asciidoctor for speed or other reasons. Add a Makefile knob, USE_ASCIIDOCTOR, that sets various options in order to produce acceptable output. For HTML output, XHTML5 was chosen, since the AsciiDoc options also produce XHTML, albeit XHTML 1.1. Asciidoctor does not have built-in support for the linkgit macro, but it is available using the Asciidoctor Extensions Lab. Add a macro to enable the use of this extension if it is available. Without it, the linkgit macros are emitted into the output. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/Makefile | 12 ++++++++++++ Makefile | 6 ++++++ 2 files changed, 18 insertions(+) diff --git a/Documentation/Makefile b/Documentation/Makefile index 3e317b8c1c..2057a35363 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -174,6 +174,18 @@ ifdef GNU_ROFF XMLTO_EXTRA += -m manpage-quote-apos.xsl endif +ifdef USE_ASCIIDOCTOR +ASCIIDOC = asciidoctor +ASCIIDOC_CONF = +ASCIIDOC_HTML = xhtml5 +ASCIIDOC_DOCBOOK = docbook45 +ifdef ASCIIDOCTOR_EXTENSIONS_LAB +ASCIIDOC_EXTRA = -I$(ASCIIDOCTOR_EXTENSIONS_LAB) -rasciidoctor/extensions -rman-inline-macro +endif +ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' +DBLATEX_COMMON = +endif + SHELL_PATH ?= $(SHELL) # Shell quote; SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) diff --git a/Makefile b/Makefile index f53fcc90d7..24e35dd74f 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 -- cgit v1.2.3 From 55d2d812e49aece049b73682ad5980ea84e23839 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Thu, 26 Jan 2017 00:13:44 +0000 Subject: Documentation: implement linkgit macro for Asciidoctor AsciiDoc uses a configuration file to implement macros like linkgit, while Asciidoctor uses Ruby extensions. Implement a Ruby extension that implements the linkgit macro for Asciidoctor in the same way that asciidoc.conf does for AsciiDoc. Adjust the Makefile to use it by default. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/Makefile | 4 +--- Documentation/asciidoctor-extensions.rb | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 3 deletions(-) create mode 100644 Documentation/asciidoctor-extensions.rb diff --git a/Documentation/Makefile b/Documentation/Makefile index 2057a35363..b21e5808b1 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -179,9 +179,7 @@ ASCIIDOC = asciidoctor ASCIIDOC_CONF = ASCIIDOC_HTML = xhtml5 ASCIIDOC_DOCBOOK = docbook45 -ifdef ASCIIDOCTOR_EXTENSIONS_LAB -ASCIIDOC_EXTRA = -I$(ASCIIDOCTOR_EXTENSIONS_LAB) -rasciidoctor/extensions -rman-inline-macro -endif +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' DBLATEX_COMMON = endif 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') + %(#{target}(#{attrs[1]})\n) + elsif parent.document.basebackend? 'docbook' + "\n" \ + "#{target}" \ + "#{attrs[1]}\n" \ + "\n" + end + end + end + end +end + +Asciidoctor::Extensions.register do + inline_macro Git::Documentation::LinkGitProcessor, :linkgit +end -- cgit v1.2.3