From 7d61547db85df0bb16683ee191805b3646920e00 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Sat, 11 Oct 2014 23:37:35 +0000 Subject: Documentation: move some AsciiDoc parameters into variables Asciidoctor takes slightly different arguments from AsciiDoc in some cases. It has a different name for the HTML backend and the "docbook" backend produces DocBook 5, not DocBook 4.5. Also, Asciidoctor does not accept the -f option. Move these values into variables so that they can be overridden by users wishing to use Asciidoctor instead of Asciidoc. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/Makefile | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index cea0e7ae3d..00c50bf49f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -97,6 +97,9 @@ man7dir = $(mandir)/man7 ASCIIDOC = asciidoc ASCIIDOC_EXTRA = +ASCIIDOC_HTML = xhtml11 +ASCIIDOC_DOCBOOK = docbook +ASCIIDOC_CONF = -f asciidoc.conf MANPAGE_XSL = manpage-normal.xsl XMLTO = xmlto XMLTO_EXTRA = @@ -304,13 +307,13 @@ clean: $(MAN_HTML): %.html : %.txt asciidoc.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ + $(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage $(ASCIIDOC_CONF) \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ mv $@+ $@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ + $(ASCIIDOC) -b $(ASCIIDOC_HTML) $(ASCIIDOC_CONF) \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ mv $@+ $@ @@ -323,13 +326,13 @@ manpage-base-url.xsl: manpage-base-url.xsl.in %.xml : %.txt asciidoc.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ + $(ASCIIDOC) -b $(ASCIIDOC_DOCBOOK) -d manpage $(ASCIIDOC_CONF) \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d article -o $@+ $< && \ + $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b $(ASCIIDOC_DOCBOOK) -d article -o $@+ $< && \ mv $@+ $@ technical/api-index.txt: technical/api-index-skel.txt \ @@ -338,7 +341,7 @@ technical/api-index.txt: technical/api-index-skel.txt \ technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf - $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ + $(QUIET_ASCIIDOC)$(ASCIIDOC) -b $(ASCIIDOC_HTML) $(ASCIIDOC_CONF) \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt XSLT = docbook.xsl @@ -386,14 +389,15 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt) mv $@+ $@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt - $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt + $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b $(ASCIIDOC_HTML) $*.txt WEBDOC_DEST = /pub/software/scm/git/docs howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - sed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \ + sed -e '1,/^$$/d' $< | \ + $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b $(ASCIIDOC_HTML) - >$@+ && \ mv $@+ $@ install-webdoc : html -- cgit v1.2.1 From 773ee47c2b9c691d9758b2bea6cac10e3f0c4e12 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Sat, 11 Oct 2014 23:37:36 +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. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/extensions.rb | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 Documentation/extensions.rb diff --git a/Documentation/extensions.rb b/Documentation/extensions.rb new file mode 100644 index 0000000000..c33a50dce5 --- /dev/null +++ b/Documentation/extensions.rb @@ -0,0 +1,39 @@ +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' + generate_html(parent, target, attrs) + elsif parent.document.basebackend? 'docbook' + generate_docbook(parent, target, attrs) + end + end + + private + + def generate_html(parent, target, attrs) + section = attrs.has_key?(1) ? "(#{attrs[1]})" : '' + prefix = parent.document.attr('git-relative-html-prefix') || '' + %(#{target}#{section}\n) + end + + def generate_docbook(parent, target, attrs) + %( +#{target}#{attrs[1]} + +) + end + end + end +end + +Asciidoctor::Extensions.register do + inline_macro Git::Documentation::LinkGitProcessor, :linkgit +end -- cgit v1.2.1 From da8a3664b133926435e4de1c1d6a9008dd5b741b Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Mon, 27 Oct 2014 00:13:42 +0000 Subject: Documentation: refactor common operations into variables The Makefile performs several very similar tasks to convert AsciiDoc files into either HTML or DocBook. Move these items into variables to reduce the duplication. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/Makefile | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 00c50bf49f..5952cc2318 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -100,6 +100,10 @@ ASCIIDOC_EXTRA = ASCIIDOC_HTML = xhtml11 ASCIIDOC_DOCBOOK = docbook ASCIIDOC_CONF = -f asciidoc.conf +ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ + -agit-version=$(GIT_VERSION) +TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) +TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) MANPAGE_XSL = manpage-normal.xsl XMLTO = xmlto XMLTO_EXTRA = @@ -307,14 +311,12 @@ clean: $(MAN_HTML): %.html : %.txt asciidoc.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage $(ASCIIDOC_CONF) \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ + $(TXT_TO_HTML) -d manpage -o $@+ $< && \ mv $@+ $@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) -b $(ASCIIDOC_HTML) $(ASCIIDOC_CONF) \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ + $(TXT_TO_HTML) -o $@+ $< && \ mv $@+ $@ manpage-base-url.xsl: manpage-base-url.xsl.in @@ -326,13 +328,12 @@ manpage-base-url.xsl: manpage-base-url.xsl.in %.xml : %.txt asciidoc.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) -b $(ASCIIDOC_DOCBOOK) -d manpage $(ASCIIDOC_CONF) \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ + $(TXT_TO_XML) -d manpage -o $@+ $< && \ mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b $(ASCIIDOC_DOCBOOK) -d article -o $@+ $< && \ + $(TXT_TO_XML) -d article -o $@+ $< && \ mv $@+ $@ technical/api-index.txt: technical/api-index-skel.txt \ @@ -341,8 +342,7 @@ technical/api-index.txt: technical/api-index-skel.txt \ technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf - $(QUIET_ASCIIDOC)$(ASCIIDOC) -b $(ASCIIDOC_HTML) $(ASCIIDOC_CONF) \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt XSLT = docbook.xsl XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css @@ -389,7 +389,7 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt) mv $@+ $@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt - $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b $(ASCIIDOC_HTML) $*.txt + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt WEBDOC_DEST = /pub/software/scm/git/docs @@ -397,7 +397,7 @@ howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ sed -e '1,/^$$/d' $< | \ - $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b $(ASCIIDOC_HTML) - >$@+ && \ + $(TXT_TO_HTML) - >$@+ && \ mv $@+ $@ install-webdoc : html -- cgit v1.2.1 From c6c3e0db842c0c3649de27edd28f8a6975bee105 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Mon, 27 Oct 2014 00:13:43 +0000 Subject: Documentation: remove Asciidoctor linkgit macro Asciidoctor provides an extension implementing a backend-independent macro for dealing with manpage links just like the linkgit macro. As this is more likely to be up-to-date with future changes in Asciidoctor, prefer using it over reimplementing in Git. This reverts commit 773ee47c2b9c691d9758b2bea6cac10e3f0c4e12. Signed-off-by: Junio C Hamano --- Documentation/extensions.rb | 39 --------------------------------------- 1 file changed, 39 deletions(-) delete mode 100644 Documentation/extensions.rb diff --git a/Documentation/extensions.rb b/Documentation/extensions.rb deleted file mode 100644 index c33a50dce5..0000000000 --- a/Documentation/extensions.rb +++ /dev/null @@ -1,39 +0,0 @@ -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' - generate_html(parent, target, attrs) - elsif parent.document.basebackend? 'docbook' - generate_docbook(parent, target, attrs) - end - end - - private - - def generate_html(parent, target, attrs) - section = attrs.has_key?(1) ? "(#{attrs[1]})" : '' - prefix = parent.document.attr('git-relative-html-prefix') || '' - %(#{target}#{section}\n) - end - - def generate_docbook(parent, target, attrs) - %( -#{target}#{attrs[1]} - -) - end - end - end -end - -Asciidoctor::Extensions.register do - inline_macro Git::Documentation::LinkGitProcessor, :linkgit -end -- cgit v1.2.1