threads / patch / 37816

patch, 2 partsDocumentation: refactor common operations into variables

Subject: [PATCH 1/2] Documentation: refactor common operations into variables

## tl;dr

4 messages between Oct 27, 2014 and Oct 27, 2014. Diffs are folded; open one to read it.

replies: 3people: 2as markdown or json

brian m. carlson· Oct 27, 2014, 00:13 UTC · lore

[PATCH 0/2] Followup patches for Asciidoctor

This series is essentially the same as the previous v2, but against next instead. It moves most of the AsciiDoc operations into a set of variables (TXT_TO_HTML and TXT_TO_XML) as Junio suggested, and removes the extensions.rb file, as it is not needed.

I did note Peff's suggestion to add a macro to enable the use of Asciidoctor, but I want to defer that until a later point. There isn't a released version of Asciidoctor with the necessary changes and I'd like to avoid confusing users by making them think it will work when it probably won't.

brian m. carlson (2):
  Documentation: refactor common operations into variables
  Documentation: remove Asciidoctor linkgit macro

 Documentation/Makefile      | 22 +++++++++++-----------
 Documentation/extensions.rb | 39 ---------------------------------------
 2 files changed, 11 insertions(+), 50 deletions(-)
 delete mode 100644 Documentation/extensions.rb

-- 
2.1.1

brian m. carlson· Oct 27, 2014, 00:13 UTC · re: brian m. carlson · lore

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 <sandals@crustytoothpaste.net>
---
 Documentation/Makefile | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

Show changes to Documentation/Makefile +11 −11

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 4cdef45..2f6b6aa 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -102,6 +102,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 =
@@ -309,14 +313,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
@@ -328,13 +330,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 \
@@ -343,8 +344,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
@@ -391,7 +391,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
 
@@ -399,7 +399,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

-- 
2.1.1

brian m. carlson· Oct 27, 2014, 00:13 UTC · re: brian m. carlson · lore

[PATCH 2/2] 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.
---
 Documentation/extensions.rb | 39 ---------------------------------------
 1 file changed, 39 deletions(-)
 delete mode 100644 Documentation/extensions.rb

Show changes to Documentation/extensions.rb +0 −39

diff --git a/Documentation/extensions.rb b/Documentation/extensions.rb
deleted file mode 100644
index c33a50d..0000000
--- 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') || ''
-        %(<a href="#{prefix}#{target}.html">#{target}#{section}</a>\n)
-      end
-
-      def generate_docbook(parent, target, attrs)
-        %(<citerefentry>
-<refentrytitle>#{target}</refentrytitle><manvolnum>#{attrs[1]}</manvolnum>
-</citerefentry>
-)
-      end
-    end
-  end
-end
-
-Asciidoctor::Extensions.register do
-  inline_macro Git::Documentation::LinkGitProcessor, :linkgit
-end

-- 
2.1.1

Jeff King· Oct 27, 2014, 05:07 UTC · re: brian m. carlson · lore

Re: [PATCH 0/2] Followup patches for Asciidoctor

On Mon, Oct 27, 2014 at 12:13:41AM +0000, brian m. carlson wrote:

Show 5 quoted lines

> I did note Peff's suggestion to add a macro to enable the use of
> Asciidoctor, but I want to defer that until a later point.  There isn't
> a released version of Asciidoctor with the necessary changes and I'd
> like to avoid confusing users by making them think it will work when it
> probably won't.

Thanks for considering it; your analysis makes sense to me.

-Peff