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(-) (limited to 'Documentation/Makefile') diff --git a/Documentation/Makefile b/Documentation/Makefile index b43d66eae..5e32bbe91 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.1 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 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'Documentation/Makefile') diff --git a/Documentation/Makefile b/Documentation/Makefile index 5e32bbe91..eecc27aba 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 $@+ $@ -- cgit v1.2.1 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(-) (limited to 'Documentation/Makefile') diff --git a/Documentation/Makefile b/Documentation/Makefile index eecc27aba..3e317b8c1 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.1 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 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'Documentation/Makefile') diff --git a/Documentation/Makefile b/Documentation/Makefile index 3e317b8c1..2057a3536 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)) -- cgit v1.2.1 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 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'Documentation/Makefile') diff --git a/Documentation/Makefile b/Documentation/Makefile index 2057a3536..b21e5808b 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 -- cgit v1.2.1