Improve global params in parsers/transforms

- Uppercase global params to make them distinct.

- Make global params available in parsers, not just transforms, where
  possible.

- Add params for the current ⛩️📰 书社 version and the current rev
  of the source files (this requires `git` and makes some assumptions
  about the location of the git directory.)

diff --git a/GNUmakefile b/GNUmakefile
index 1603aef277133317dada830847d2f493f55cb710..ab8e828b23917c7e45be1c5a76df49df3bead98b 100644 (file)
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -10,7 +10,7 @@ override define makefileinfo
 ║│ Requires G·N·U Make, at least version 3.81, a version of   │║
 ║│ uuencode with base64 support, and the various programs     │║
 ║│ offered by libxml2 and libxslt. Beyond this, only programs │║
-║│ required by Posix are used, altho there is a chance of     │║
+║│ required by Posix are required, altho there is a chance of │║
 ║│ version incompatibilities. The full list of program        │║
 ║│ requirements is as follows :—                             │║
 ║│                                                            │║
@@ -21,6 +21,7 @@ override define makefileinfo
 ║│ • echo                                                     │║
 ║│ • file                                                     │║
 ║│ • find                                                     │║
+║│ • git (optional)                                           │║
 ║│ • mkdir (requires support for `-p´)                        │║
 ║│ • mv                                                       │║
 ║│ • od (requires support for `-t x1´)                        │║
@@ -89,6 +90,7 @@ DATE := date
 ECHO := echo
 FILE := file
 FIND := find
+GIT := git
 MKDIR := mkdir
 MV := mv
 OD := od
@@ -229,6 +231,20 @@ sourceincludes := $(shell $(FIND) $(FINDOPTS) $(INCLUDEDIR) -type f '(' $(FINDRU
 # source directory, removing any which are also includes.
 sourcefiles := $(filter-out $(sourceincludes),$(shell $(FIND) $(FINDOPTS) $(SRCDIR) -type f '(' $(FINDRULES) ')'))
 
+ifdef GIT
+ifneq ($(wildcard $(THISDIR)/.git),)
+# (overridable) The name of the current revision of ⛩️📰 书社, or its
+# hash if the current revision is not a tag.
+thisrev = $(shell cd $(THISDIR); $(GIT) describe 2> /dev/null || $(GIT) rev-parse HEAD)
+endif
+
+ifneq ($(wildcard .git),)
+# (overridable) The name of the current revision of the working
+# directory, or its hash if the current revision is not a tag.
+srcrev = $(shell $(GIT) describe 2> /dev/null || $(GIT) rev-parse HEAD)
+endif
+endif
+
 # Figure out the file type of each source file and source include.
 ifneq ($(wildcard $(BUILDDIR)/magic.mgc),)
 override types := $(shell $(SED) 's/^ *//;s/ *$$//;s/ {2,}/ /g' <<< $(call quote,$(sourcefiles) $(sourceincludes)) | $(TR) ' ' '\n' | $(FILE) -m $(call quote,$(BUILDDIR)/magic.mgc) --mime-type --separator '|' --files-from - | $(SED) 's/| */|/g')
@@ -453,7 +469,7 @@ $(BUILDDIR)/parser.xslt: $(BUILDDIR)/parser.catalog $(THISDIR)/lib/catalog2parse
 $(call parsed,$(sourcefiles) $(sourceincludes)): %: $$(call unparsed,$$@) $(typeupdates)
        @$(PRINTF) '%s\n' $(call quote,Processing `$<´…)
        $(silent)$(call ensuredirectory,$(dir $@))
-       $(silent)$(if $(filter $<,$(assetfiles)),$(PRINTF) '%s\n' $(call quote,<object xmlns="http://www.w3.org/1999/xhtml" type="$(call typeoffile,$<)" data="$(call datauri,$<)"/>) > $(call quote,$@),$(if $(filter $<,$(plaintextfiles)),$(call wrapplaintext,$<),$(CAT) $(call quote,$<)) | $(XSLTPROC) -o $(call quote,$@) $(call quote,$(BUILDDIR)/parser.xslt) -)
+       $(silent)$(if $(filter $<,$(assetfiles)),$(PRINTF) '%s\n' $(call quote,<object xmlns="http://www.w3.org/1999/xhtml" type="$(call typeoffile,$<)" data="$(call datauri,$<)"/>) > $(call quote,$@),$(if $(filter $<,$(plaintextfiles)),$(call wrapplaintext,$<),$(CAT) $(call quote,$<)) | $(XSLTPROC) -o $(call quote,$@) --stringparam BUILDTIME '$(shell TZ= $(DATE) '+%Y-%m-%dT%H:%M:%SZ')' --stringparam SRCTIME '$(shell TZ= $(STAT) -f '%Sm' -t '%Y-%m-%dT%H:%M:%SZ' $(call quote,$(call unparsed,$@)))'$(if $(thisrev), --stringparam VERSION $(call quote,$(thisrev)),)$(if $(srcrev), --stringparam SRCREV $(call quote,$(srcrev)),) $(call quote,$(BUILDDIR)/parser.xslt) -)
 
 # Generate a catalog of all parsed files, for use when processing
 # includes. This does not depend on actually transforming the files.
@@ -487,7 +503,7 @@ $(BUILDDIR)/transform.xslt: $(BUILDDIR)/transform.catalog $(THISDIR)/lib/catalog
 $(call compiled,$(compilablefiles)): $(BUILDDIR)/public/%: $$(call parsed,$$(call uncompiled,$$@)) $(BUILDDIR)/transform.xslt $$(call parsed,$$(call dependencies,$$(call uncompiled,$$@)))
        $(silent)$(call ensuredirectory,$(dir $@))
        @$(PRINTF) '%s\n' $(call quote,Compiling </$*>…)
-       $(silent)$(XSLTPROC) -o $(call quote,$@) --stringparam catalog 'catalog' --stringparam buildtime '$(shell TZ= $(DATE) '+%Y-%m-%dT%H:%M:%SZ')' --stringparam srctime '$(shell TZ= $(STAT) -f '%Sm' -t '%Y-%m-%dT%H:%M:%SZ' $(call quote,$(call uncompiled,$@)))' --stringparam path $(call quote,/$*) $(call quote,$(BUILDDIR)/transform.xslt) $(call quote,$<)
+       $(silent)$(XSLTPROC) -o $(call quote,$@) --stringparam CATALOG 'catalog' --stringparam BUILDTIME '$(shell TZ= $(DATE) '+%Y-%m-%dT%H:%M:%SZ')' --stringparam SRCTIME '$(shell TZ= $(STAT) -f '%Sm' -t '%Y-%m-%dT%H:%M:%SZ' $(call quote,$(call uncompiled,$@)))' --stringparam PATH $(call quote,/$*)$(if $(thisrev), --stringparam VERSION $(call quote,$(thisrev)),)$(if $(srcrev), --stringparam SRCREV $(call quote,$(srcrev)),) $(call quote,$(BUILDDIR)/transform.xslt) $(call quote,$<)
 $(call compiled,$(filter $(assetfiles),$(sourcefiles))): $(BUILDDIR)/public/%: $$(call uncompiled,$$@)
        @$(PRINTF) '%s\n' $(call quote,Compiling </$*>…)
        $(silent)$(call ensuredirectory,$(dir $@))

diff --git a/README.markdown b/README.markdown
index 4427c7fed710eb40a5051e147688b77e1f843478..400679f090097a8bbb2368fc438a55c6a5c57084 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -98,6 +98,7 @@ In every case, you may supply your own implementation by overriding the
 - `echo`
 - `file`
 - `find`
+- `git` (optional; set `GIT=` to disable)
 - `mkdir` (requires support for `-p`)
 - `mv`
 - `od` (requires support for `-t x1`)
@@ -374,10 +375,32 @@ The following are recommendations on effective creation of
 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
     to reduce the number of declared namespaces in the final result.
 
-The params `$buildtime`, `$srctime`, and `$path` are available within
-  transforms and are initialized to the current time, the time that the
-  source file was last modified, and the path of the output file within
-  $(DESTDIR).
+## Global Params
+
+The following params are made available globally in parsers and
+  transforms :⁠—
+
+- **`BUILDTIME`:**
+  The current time.
+
+- **`SRCREV`:**
+  The tag or hash of the current commit in the working directory (if
+    `GIT` is defined and `./.git` exists).
+
+- **`SRCTIME`:**
+  The time at which the source file was last modified.
+
+- **`VERSION`:**
+  The tag or hash of the current commit in `THISDIR` (if `GIT` is
+    defined and `$(THISDIR)/.git` exists).
+
+The following params are only available in transforms :⁠—
+
+- **`CATALOG`:**
+  The path of the catalog file (within `BUILDDIR`).
+
+- **`PATH`:**
+  The path of the output file (within `DESTDIR`).
 
 ## Output Wrapping
 

diff --git a/lib/catalog2parser.xslt b/lib/catalog2parser.xslt
index d1d2babac7142bf4de72671abfd45ca47594751c..0b66c4ef1812b9d0382e9b3353d8fb0b2d63a0a1 100644 (file)
--- a/lib/catalog2parser.xslt
+++ b/lib/catalog2parser.xslt
@@ -22,6 +22,10 @@ If a copy of the M·P·L was not distributed with this file, You can obtain one
        <namespace-alias stylesheet-prefix="xslt" result-prefix="#default"/>
        <template match="/">
                <xslt:transform version="1.0">
+                       <xslt:param name="BUILDTIME" select="'1972-12-31T00:00:00Z'"/>
+                       <xslt:param name="SRCTIME" select="'1972-12-31T00:00:00Z'"/>
+                       <xslt:param name="VERSION" select="false"/>
+                       <xslt:param name="SRCREV" select="false"/>
                        <xslt:variable name="书社:parsers">
                                <html:dl>
                                        <for-each select="//catalog:uri">

diff --git a/lib/catalog2transform.xslt b/lib/catalog2transform.xslt
index 2be92185f5e4b25f57ba822f2d96805b1a81ccc5..953a68352239f7ad0d76ea24f6f5a3a0a89d28d2 100644 (file)
--- a/lib/catalog2transform.xslt
+++ b/lib/catalog2transform.xslt
@@ -25,10 +25,12 @@ If a copy of the M·P·L was not distributed with this file, You can obtain one
        <namespace-alias stylesheet-prefix="xslt" result-prefix="#default"/>
        <template match="/">
                <xslt:transform exclude-result-prefixes="catalog exsl exslstr" version="1.0">
-                       <xslt:param name="buildtime" select="'1972-12-31T00:00:00Z'"/>
-                       <xslt:param name="catalog" select="'catalog'"/>
-                       <xslt:param name="srctime" select="'1972-12-31T00:00:00Z'"/>
-                       <xslt:param name="path" select="'/unknown'"/>
+                       <xslt:param name="BUILDTIME" select="'1972-12-31T00:00:00Z'"/>
+                       <xslt:param name="CATALOG" select="'catalog'"/>
+                       <xslt:param name="SRCTIME" select="'1972-12-31T00:00:00Z'"/>
+                       <xslt:param name="PATH" select="'/unknown'"/>
+                       <xslt:param name="VERSION" select="false"/>
+                       <xslt:param name="SRCREV" select="false"/>
                        <xslt:variable name="书社:expansion">
                                <xslt:apply-templates select="/" mode="书社:expand"/>
                        </xslt:variable>
@@ -49,7 +51,12 @@ If a copy of the M·P·L was not distributed with this file, You can obtain one
                                        <xslt:when test="exsl:node-set($书社:result)/*[@书社:disable-output-wrapping]">
                                                <xslt:for-each select="exsl:node-set($书社:result)/*">
                                                        <xslt:copy>
-                                                               <xslt:copy-of select="@*[not(namespace-uri()='&书社;' and local-name()='disable-output-wrapping')]|node()"/>
+                                                               <xslt:if test="$VERSION">
+                                                                       <xslt:attribute name="书社:version">
+                                                                               <xslt:value-of select="$VERSION"/>
+                                                                       </xslt:attribute>
+                                                               </xslt:if>
+                                                               <xslt:copy-of select="@*[not(namespace-uri()='&书社;' and contains('disable-output-wrapping version', local-name()))]|node()"/>
                                                        </xslt:copy>
                                                </xslt:for-each>
                                        </xslt:when>
@@ -78,7 +85,7 @@ If a copy of the M·P·L was not distributed with this file, You can obtain one
                                </xslt:copy>
                        </xslt:template>
                        <xslt:template match="书社:link[@xlink:show='embed']" mode="书社:expand" priority="1">
-                               <xslt:variable name="uri" select="substring-before(document($catalog)//catalog:uri[@name=current()/@xlink:href]/@uri[1], '#')"/>
+                               <xslt:variable name="uri" select="substring-before(document($CATALOG)//catalog:uri[@name=current()/@xlink:href]/@uri[1], '#')"/>
                                <xslt:choose>
                                        <xslt:when test="$uri">
                                                <xslt:variable name="expanded">
@@ -120,6 +127,11 @@ If a copy of the M·P·L was not distributed with this file, You can obtain one
                                        <xslt:apply-templates select="document('')/xslt:transform/xslt:include" mode="书社:metadata"/>
                                </xslt:variable>
                                <html:html>
+                                       <xslt:if test="$VERSION">
+                                               <xslt:attribute name="书社:version">
+                                                       <xslt:value-of select="$VERSION"/>
+                                               </xslt:attribute>
+                                       </xslt:if>
                                        <xslt:copy-of select="html:html/@*|*/@xml:lang|html:*/@lang|svg:*/@lang"/>
                                        <html:head>
                                                <xslt:copy-of select="html:html/html:head/@*"/>
@@ -130,7 +142,16 @@ If a copy of the M·P·L was not distributed with this file, You can obtain one
                                                </html:title>
                                                <xslt:copy-of select="exsl:node-set($metadata)/node()[self::comment() or self::* and not(self::html:title)]"/>
                                                <xslt:if test="not(exsl:node-set($metadata)/html:meta[@name='generator'])">
-                                                       <html:meta name="generator" content="⛩️📰 书社"/>
+                                                       <html:meta name="generator">
+                                                               <xslt:attribute name="content">
+                                                                       <xslt:text>⛩️📰 书社</xslt:text>
+                                                                       <xslt:if test="$VERSION">
+                                                                               <xslt:text> (</xslt:text>
+                                                                               <xslt:value-of select="$VERSION"/>
+                                                                               <xslt:text>)</xslt:text>
+                                                                       </xslt:if>
+                                                               </xslt:attribute>
+                                                       </html:meta>
                                                </xslt:if>
                                        </html:head>
                                        <html:body>