Basic support for Atom feeds

• Files with an `.atom` extension will be passed through the same
  X·S·L·T transform as `.xml` files, which now has Atom‐specific rules.

• Automatic generation for basic metadata. There is probably more work
  to do here to automatically pull things like titles and summaries.

Other small improvements added as a part of this work :—

• The `transform.xslt` file is now specified via a `$(TRANSFORM)`
  variable in the Makefile and can be overridden.

• The `xmlns:html` attribute is manually removed from the root element
  of outputted H·T·M·L (if it exists).

• Subdirectories are now properly created in the `public/` folder when
  needed.

diff --git a/GNUmakefile b/GNUmakefile
index b8bbd4a0820324b743afbb39c17e36f8e7b7d8d1..a6b7b4acd46440336a8a14c3f66d2d495d8428dd 100644 (file)
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -1,13 +1,15 @@
 SHELL = /bin/sh
 
 SHELL = /bin/sh
 

-# This GNUmakefile searches the `sources/` directory for files with an extension of `.xml` and applies `transform.xslt` to them, outputting the result in one of two locations :—
+# This GNUmakefile searches the `sources/` directory for files with an extension of `.atom` or `.xml` and applies `transform.xslt` to them, outputting the result in one of the following locations :—

 #
 # • For files with a location of `sources/index.xml` or `sources/index-*.xml`, the transformed file will be written to `public/%.html` (where `%` is the filename).
 #
 # • For all other files with a location of `sources/*.xml` or `sources/*/*.xml`, the transformed file will be written to `public/%/index.html` (where `%` is the filename and subdirectory if applicable).
 #
 # • For files with a location of `sources/index.xml` or `sources/index-*.xml`, the transformed file will be written to `public/%.html` (where `%` is the filename).
 #
 # • For all other files with a location of `sources/*.xml` or `sources/*/*.xml`, the transformed file will be written to `public/%/index.html` (where `%` is the filename and subdirectory if applicable).

-# Other files in the corresponding directory (i·e without the `.xml`) are copied over verbatim.
+# Any files in a corresponding sibling directory (i·e without the `.xml`) are copied over verbatim.

 # Only one level of subdirectory is supported.
 #
 # Only one level of subdirectory is supported.
 #

+# • For files with a location of `sources/*.atom` or `sources/*/*.atom`, the transformed file will be written to `public/%.atom` (where `%` is the filename and subdirectory if applicable).
+#

 # By default, running `make` will do this for all applicable source files.
 #
 # ___
 # By default, running `make` will do this for all applicable source files.
 #
 # ___


@@ -17,12 +19,15 @@ SHELL = /bin/sh
 # This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
 # If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 # This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
 # If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.
 

+BASEIRI = http://example.com
+DATETIME = $(shell date -Iseconds)
+TRANSFORM = transform.xslt

 XSLT = xsltproc
 XSLTOPTS =
 
 headers := $(wildcard *-header.xml)
 footers := $(wildcard *-footer.xml)
 XSLT = xsltproc
 XSLTOPTS =
 
 headers := $(wildcard *-header.xml)
 footers := $(wildcard *-footer.xml)

-override prerequisites := transform.xslt $(headers) $(footers)
+override prerequisites := $(TRANSFORM) $(headers) $(footers)

 
 override indexsources := $(wildcard sources/index.xml sources/index-*.xml)
 override indices := $(patsubst sources/%.xml,public/%.html,$(indexsources))
 
 override indexsources := $(wildcard sources/index.xml sources/index-*.xml)
 override indices := $(patsubst sources/%.xml,public/%.html,$(indexsources))


@@ -33,23 +38,45 @@ override pages := $(patsubst sources/%.xml,public/%/index.html,$(pagesources))
 override resourcesources := $(wildcard $(addsuffix /*,$(basename $(pagesources))))
 override resources := $(patsubst sources/%,public/%,$(resourcesources))
 
 override resourcesources := $(wildcard $(addsuffix /*,$(basename $(pagesources))))
 override resources := $(patsubst sources/%,public/%,$(resourcesources))
 

+override feedsources := $(filter-out $(resourcesources),$(wildcard sources/*.atom sources/*/*.atom))
+override feeds := $(patsubst sources/%.atom,public/%.atom,$(feedsources))
+

 override content := $(indices) $(pages)
 
 override content := $(indices) $(pages)
 

-override makexslt = $(XSLT) --nonet --novalid $(XSLTOPTS) -o $(2) transform.xslt $(1)
+# This function does the following :—
+#
+# • Calls `transform.xslt` with the `$(1)`, providing `$(BASEIRI)` and `$(DATETIME) as params and providing `$(2)` (minus the initial `public/`) as the param `OUTPUTPATH`.
+#
+# • Removes any `xmlns` prefix declarations from output to `.html` files (with `sed`).
+#
+# • Removes any doctype for root elements other than `html` (with `grep -v`).
+#
+# • Saves the output to `$(2)`.
+override makexslt = $(XSLT) --nonet --novalid $(XSLTOPTS) --stringparam BASEIRI "$(BASEIRI)" --stringparam DATETIME "$(DATETIME)" --stringparam OUTPUTPATH "$(patsubst public/%,/%,$(2))" transform.xslt $(1)\
+       $(if $(filter %.html,$(2)),| sed 's/ xmlns:[0-9A-Za-z_-]*="[^"]*"//g',)\
+       | grep -v '^<!DOCTYPE \([^h]\|.[^t]\|..[^m]\|...[^l]\|....[^ >]\)'\
+       > $(2)

 
 

-all: $(content) $(resources);
+all: $(content) $(resources) $(feeds);

 
 $(indices): public/%.html: sources/%.xml $(prerequisites)
        @echo "Generating $@…"
 
 $(indices): public/%.html: sources/%.xml $(prerequisites)
        @echo "Generating $@…"

+       @mkdir -p $(dir $@)

        @$(call makexslt,$<,$@)
 
 $(pages): public/%/index.html: sources/%.xml $(prerequisites)
        @echo "Generating $@…"
        @$(call makexslt,$<,$@)
 
 $(pages): public/%/index.html: sources/%.xml $(prerequisites)
        @echo "Generating $@…"

+       @mkdir -p $(dir $@)

        @$(call makexslt,$<,$@)
 
 $(resources): public/%: sources/%
        @echo "Copying over $@…"
        @$(call makexslt,$<,$@)
 
 $(resources): public/%: sources/%
        @echo "Copying over $@…"

-       @mkdir -p $(dir $<)
+       @mkdir -p $(dir $@)

        @cp $< $@
 
        @cp $< $@
 

+$(feeds): public/%.atom: sources/%.atom $(TRANSFORM)
+       @echo "Generating $@…"
+       @mkdir -p $(dir $@)
+       @$(call makexslt,$<,$@)
+

 .PHONY: all ;
 .PHONY: all ;

diff --git a/README.markdown b/README.markdown
index 3b040d61f0bc11449938fc6e53032ca37a459667..0abeeb6d910fc95e24a168e43692b2b94b20ee3e 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -50,6 +50,31 @@ Finally, just run `make` from this directory, and H·T·M·L files
 corresponding to your source files will be created in the `public/`
 directory (which you can then serve statically from your server).
 
 corresponding to your source files will be created in the `public/`
 directory (which you can then serve statically from your server).
 

+## Atom Feeds
+
+Any `.atom` files you provide will automatically be filled out with
+`<id>`s, `<updated>` values, and other necessary information before
+being copied to the destination location. If you wish to use this
+feature, you will need to provide a `BASEIRI` variable when you run
+`make` to allow the X·S·L·T to transform relative links into absolute
+ones.
+
+It is recommended that :—
+
+- You do *not* provide your own `<id>`s and rely on the generated ones
+  (which will be an `oai:` URI derived from the file path).
+
+- You *do* manually provide `<updated>` times for individual entries
+  (although not the feed as a whole); otherwise every entry will be
+  marked as updated every time the feed is generated.
+
+- All `<link rel="alternate">` elements in `<entry>` elements use a
+  relative `@href` with a leading slash. This should point to the
+  *final* location of the entry (within, but not including, `public/`).
+
+There’s an example `feed.atom` provided so you can see what this
+  feature might look like in practice.
+

 ## Notes
 
 - The created files have a `.html` extension and need to be served
 ## Notes
 
 - The created files have a `.html` extension and need to be served

diff --git a/sources/blog/1972-12-31.xml b/sources/blog/1972-12-31.xml
new file mode 100644 (file)
index 0000000..9b28668
--- /dev/null
+++ b/sources/blog/1972-12-31.xml
@@ -0,0 +1,3 @@
+<article xmlns="http://www.w3.org/1999/xhtml" lang="en">
+       <h1>My Blog Post</h1>
+</article>

diff --git a/sources/feed.atom b/sources/feed.atom
new file mode 100644 (file)
index 0000000..2246fd4
--- /dev/null
+++ b/sources/feed.atom
@@ -0,0 +1,9 @@
+<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
+       <title>My Amazing Shrine</title>
+       <author>Me</author>
+       <entry>
+               <link rel="alternate" href="/blog/1972-12-31/" type="text/html"/>
+               <title>My Blog Post</title>
+               <updated>1972-12-31T00:00:00Z</updated>
+       </entry>
+</feed>

diff --git a/transform.xslt b/transform.xslt
index 0919121f56192ea1934cd58726d8f19c7db478df..20fe4c29b354fa5166cba66c9a17e9c3647f2829 100644 (file)
--- a/transform.xslt
+++ b/transform.xslt
@@ -23,10 +23,41 @@ This Source Code Form is subject to the terms of the Mozilla Public License, v.
 If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.
 -->
 <xslt:transform
 If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.
 -->
 <xslt:transform

+       xmlns:atom="http://www.w3.org/2005/Atom"

        xmlns:html="http://www.w3.org/1999/xhtml"
        xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
        version="1.0"
 >
        xmlns:html="http://www.w3.org/1999/xhtml"
        xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
        version="1.0"
 >

+       <xslt:param name="BASEIRI" select="'http://example.com'"/>
+       <xslt:param name="DATETIME" select="'1972-12-31T00:00:00Z'"/>
+       <xslt:param name="OUTPUTPATH" select="'/unknown'"/>
+       <xslt:variable name="baseiri">
+               <xslt:choose>
+                       <xslt:when test="contains($BASEIRI, '://')"> <!-- there is an authority -->
+                               <xslt:variable name="noscheme" select="substring-after($BASEIRI, '://')"/>
+                               <xslt:value-of select="substring-before($BASEIRI, '://')"/>
+                               <xslt:text>://</xslt:text>
+                               <xslt:choose>
+                                       <xslt:when test="contains($noscheme, '/')">
+                                               <xslt:value-of select="substring-before($noscheme, '/')"/>
+                                       </xslt:when>
+                                       <xslt:otherwise>
+                                               <xslt:value-of select="$noscheme"/>
+                                       </xslt:otherwise>
+                               </xslt:choose>
+                       </xslt:when>
+                       <xslt:otherwise>
+                               <xslt:value-of select="substring-before($BASEIRI, ':')"/>
+                       </xslt:otherwise>
+               </xslt:choose>
+       </xslt:variable>
+       <xslt:variable name="datetime" select="string($DATETIME)"/>
+       <xslt:variable name="outputpath">
+               <xslt:if test="not(starts-with($OUTPUTPATH, '/'))">
+                       <xslt:text>/</xslt:text>
+               </xslt:if>
+               <xslt:value-of select="$OUTPUTPATH"/>
+       </xslt:variable>

        <xslt:variable name="source" select="current()"/>
        <xslt:variable name="template" select="document('./template.xml')"/>
 
        <xslt:variable name="source" select="current()"/>
        <xslt:variable name="template" select="document('./template.xml')"/>
 


@@ -34,7 +65,14 @@ If a copy of the MPL was not distributed with this file, You can obtain one at h
                Instead of actually processing the root node, process the template in `template` mode.
        -->
        <xslt:template match="/">
                Instead of actually processing the root node, process the template in `template` mode.
        -->
        <xslt:template match="/">

-               <xslt:apply-templates select="$template" mode="template"/>
+               <xslt:choose>
+                       <xslt:when test="atom:feed">
+                               <xslt:apply-templates mode="feed"/>
+                       </xslt:when>
+                       <xslt:otherwise>
+                               <xslt:apply-templates select="$template" mode="template"/>
+                       </xslt:otherwise>
+               </xslt:choose>

        </xslt:template>
 
        <!--
        </xslt:template>
 
        <!--


@@ -122,6 +160,7 @@ If a copy of the MPL was not distributed with this file, You can obtain one at h
                                        <xslt:apply-templates select="$source//html:h1" mode="text"/>
                                </title>
                        </xslt:if>
                                        <xslt:apply-templates select="$source//html:h1" mode="text"/>
                                </title>
                        </xslt:if>

+                       <meta name="generator" content="https://github.com/marrus-sh/shrine-xslt"/>

                        <xslt:apply-templates mode="template"/>
                        <xslt:for-each select="$source//*[@slot='shrine-head']">
                                <xslt:apply-templates select="." mode="content"/>
                        <xslt:apply-templates mode="template"/>
                        <xslt:for-each select="$source//*[@slot='shrine-head']">
                                <xslt:apply-templates select="." mode="content"/>


@@ -158,6 +197,135 @@ If a copy of the MPL was not distributed with this file, You can obtain one at h
                <xslt:apply-templates select="$source/*" mode="content"/>
        </xslt:template>
 
                <xslt:apply-templates select="$source/*" mode="content"/>
        </xslt:template>
 

+       <!--
+               Process feed elements and text.
+               By default, just make a copy.
+               This behaviour will be overridden for certain elements to generate feed metadata.
+       -->
+       <xslt:template match="*|text()" mode="feed">
+               <xslt:copy>
+                       <xslt:for-each select="@*">
+                               <xslt:copy/>
+                       </xslt:for-each>
+                       <xslt:apply-templates mode="feed"/>
+               </xslt:copy>
+       </xslt:template>
+
+       <!--
+               Process the root feed element.
+               This adds required metadata when it has not been provided in the source X·M·L.
+       -->
+       <xslt:template match="atom:feed" mode="feed">
+               <xslt:text>&#x0A;</xslt:text> <!-- ensure a newline between the doctype and the feed element -->
+               <feed xmlns="http://www.w3.org/2005/Atom">
+                       <xslt:for-each select="@*">
+                               <xslt:copy/>
+                       </xslt:for-each>
+                       <xslt:apply-templates select="text()[following-sibling::*[not(self::atom:entry)]]|*[not(self::atom:entry)]" mode="feed"/>
+                       <xslt:if test="not(atom:id)">
+                               <xslt:text>&#x0A;&#x09;</xslt:text>
+                               <id>
+                                       <xslt:choose>
+                                               <xslt:when test="contains($baseiri, '://')">
+                                                       <xslt:text>oai:</xslt:text>
+                                                       <xslt:value-of select="substring-after($baseiri, '://')"/>
+                                                       <xslt:text>:</xslt:text>
+                                               </xslt:when>
+                                               <xslt:otherwise>
+                                                       <xslt:value-of select="$baseiri"/>
+                                                       <xslt:text>/</xslt:text>
+                                               </xslt:otherwise>
+                                       </xslt:choose>
+                                       <xslt:value-of select="$outputpath"/>
+                               </id>
+                       </xslt:if>
+                       <xslt:if test="not(atom:title)">
+                               <xslt:text>&#x0A;&#x09;</xslt:text>
+                               <title xml:lang="en">Untitled</title>
+                       </xslt:if>
+                       <xslt:if test="not(atom:author)">
+                               <xslt:text>&#x0A;&#x09;</xslt:text>
+                               <author>
+                                       <name xml:lang="en">Anonymous</name>
+                               </author>
+                       </xslt:if>
+                       <xslt:if test="not(atom:link[@rel='alternate'][@type='text/html'])">
+                               <xslt:text>&#x0A;&#x09;</xslt:text>
+                               <link rel="alternate" type="text/html" href="{$baseiri}/"/>
+                       </xslt:if>
+                       <xslt:if test="not(atom:link[@rel='self'])">
+                               <xslt:text>&#x0A;&#x09;</xslt:text>
+                               <link rel="self" type="application/atom+xml" href="{$baseiri}{$outputpath}"/>
+                       </xslt:if>
+                       <xslt:if test="not(atom:updated)">
+                               <xslt:text>&#x0A;&#x09;</xslt:text>
+                               <updated>
+                                       <xslt:value-of select="$datetime"/>
+                               </updated>
+                       </xslt:if>
+                       <xslt:if test="not(atom:generator)">
+                               <xslt:text>&#x0A;&#x09;</xslt:text>
+                               <generator uri="https://github.com/marrus-sh/shrine-xslt">shrine-xslt</generator>
+                       </xslt:if>
+                       <xslt:apply-templates select="atom:entry" mode="feed"/>
+                       <xslt:text>&#x0A;</xslt:text> <!-- newline before close tag -->
+               </feed>
+       </xslt:template>
+
+       <!--
+               Process feed entry elements.
+       -->
+       <xslt:template match="atom:entry[atom:link[@rel='alternate'][starts-with(@href, '/')][@type='text/html']]" mode="feed">
+               <xslt:variable name="entryhref" select="atom:link[@rel='alternate'][starts-with(@href, '/')][@type='text/html'][1]/@href"/>
+               <xslt:text>&#x0A;&#x09;</xslt:text>
+               <entry xmlns="http://www.w3.org/2005/Atom">
+                       <xslt:for-each select="@*">
+                               <xslt:copy/>
+                       </xslt:for-each>
+                       <xslt:apply-templates select="text()[following-sibling::*]|*" mode="feed"/>
+                       <xslt:if test="not(atom:id)">
+                               <xslt:text>&#x0A;&#x09;&#x09;</xslt:text>
+                               <id>
+                                       <xslt:choose>
+                                               <xslt:when test="contains($baseiri, '://')">
+                                                       <xslt:text>oai:</xslt:text>
+                                                       <xslt:value-of select="substring-after($baseiri, '://')"/>
+                                                       <xslt:text>:</xslt:text>
+                                               </xslt:when>
+                                               <xslt:otherwise>
+                                                       <xslt:value-of select="$baseiri"/>
+                                                       <xslt:text>/</xslt:text>
+                                               </xslt:otherwise>
+                                       </xslt:choose>
+                                       <xslt:value-of select="$entryhref"/>
+                               </id>
+                       </xslt:if>
+                       <xslt:if test="not(atom:title)">
+                               <xslt:text>&#x0A;&#x09;&#x09;</xslt:text>
+                               <title xml:lang="en">Untitled</title>
+                       </xslt:if>
+                       <xslt:if test="not(atom:updated)">
+                               <xslt:text>&#x0A;&#x09;&#x09;</xslt:text>
+                               <updated>
+                                       <xslt:value-of select="$datetime"/>
+                               </updated>
+                       </xslt:if>
+                       <xslt:text>&#x0A;&#x09;</xslt:text> <!-- newline before close tag -->
+               </entry>
+       </xslt:template>
+
+       <!--
+               Process feed link elements.
+               This simply rewrites absolute links to be relative.
+       -->
+       <xslt:template match="atom:link[starts-with(@href, '/')]" mode="feed">
+               <link xmlns="http://www.w3.org/2005/Atom" rel="{@rel}" href="{$baseiri}{@href}">
+                       <xslt:for-each select="@*[local-name()!='rel' and local-name()!='href']">
+                               <xslt:copy/>
+                       </xslt:for-each>
+               </link>
+       </xslt:template>
+

        <!--
                Provide the complete text content of the provided element.
        -->
        <!--
                Provide the complete text content of the provided element.
        -->


@@ -173,7 +341,9 @@ If a copy of the MPL was not distributed with this file, You can obtain one at h
        </xslt:template>
 
        <!--
        </xslt:template>
 
        <!--

-               Set the output mode to HTML.
+               Set up output.
+               Note that this relies on “default” output method detection specified in X·S·L·T in order to work.
+               The `about:legacy-compat` system doctype is for H·T·M·L compatibility but is harmless in X·M·L.

        -->
        -->

-       <xslt:output method="html" charset="UTF-8" doctype-system="about:legacy-compat" indent="no"/>
+       <xslt:output charset="UTF-8" doctype-system="about:legacy-compat" indent="no"/>

 </xslt:transform>
 </xslt:transform>