Develop

.github/workflows/check-docs.yml

@@ -14,8 +14,25 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      # Jena 6 requires Java 21; the runner defaults to 17
+      - name: Set up Java 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
       - name: RDF syntax check
         uses: AtomGraph/RDF-syntax-check@v1.0.5
+        with:
+          jena-version: 6.1.0
+
+      - name: Install Linux packages
+        run: sudo apt-get update && sudo apt-get install -y libxml2-utils
+
+      # riot checks rdf:XMLLiteral well-formedness; canonical form is only
+      # enforced up to Jena 4.7.0, so it is checked separately
+      - name: XMLLiteral canonical form check
+        run: ./check-xmlliterals.sh
 
       - name: Check links
         run: ./check-links.sh

.gitignore

@@ -4,3 +4,4 @@ linkeddatahub/.DS_Store
 docs/docs.trix
 docs/files.xml
 docs/html
+docs/timestamps.xml

README.md

@@ -136,6 +136,6 @@ Installation integrates the package by:
 - **Declarative only** - RDF + XSLT, no Java code
 - **Installation-time composition** - Pre-composed before loading, no runtime overhead
 - **Property views** (`ldh:view` / `ldh:inverseView`) - SPARQL-based views attached to properties
-- **XSLT overrides** - Custom rendering using system modes (`bs2:*`, `xhtml:*`, etc.)
+- **XSLT overrides** - Custom rendering using system modes (`ac:*`, `ldh:*`, `xhtml:*`, etc.)
 
 [Read the full packages documentation →](packages/README.md)

check-links.sh

@@ -15,7 +15,16 @@ print(result[len('http://x/'):])
 
 while IFS= read -r -d '' ttl_file; do
     rel="${ttl_file#"$REPO_DIR"/}"
-    url_path="${rel%.ttl}/"
+
+    # A .ttl is served at <its path minus .ttl>/ — except root.ttl, which install.sh PUTs
+    # at the application base itself rather than at <dir>/root/. Resolving a root.ttl's
+    # relative links against <dir>/root/ would send them one level too deep.
+    if [[ "$(basename "$rel")" == "root.ttl" ]]; then
+        url_path="$(dirname "$rel")/"
+        [[ "$url_path" == "./" ]] && url_path=""
+    else
+        url_path="${rel%.ttl}/"
+    fi
 
     while IFS= read -r url; do
         [[ "$url" =~ ^https?:// ]]  && continue

check-xmlliterals.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Checks that every rdf:XMLLiteral lexical form in the RDF corpus is in exclusive
+# canonical XML form, which RDF 1.1 requires of the datatype's lexical space.
+#
+# Jena 4.7.0 enforced this while validating; Jena 5 and later only check
+# well-formedness. Without this check a non-canonical literal passes both
+# `make validate` and the CI syntax check while still being invalid.
+#
+# The rules that follow from canonical form, when authoring XHTML literals:
+# attributes in alphabetical order, explicit end tags (<br></br>, never <br/>),
+# and each start tag on a single line.
+#
+# Usage: check-xmlliterals.sh [directory]   (defaults to the script's own directory)
+
+ROOT_DIR="$(cd "${1:-$(dirname "$0")}" && pwd)"
+EXIT_CODE=0
+
+if ! command -v xmllint > /dev/null; then
+    echo "check-xmlliterals.sh: xmllint is required (Debian/Ubuntu: libxml2-utils)" >&2
+    exit 2
+fi
+
+WORK_DIR="$(mktemp -d)"
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+cd "$ROOT_DIR"
+
+while IFS= read -r -d '' file; do
+    rm -f "$WORK_DIR"/lit.*
+
+    # Write the lexical form of each """..."""^^rdf:XMLLiteral literal to its own
+    # file under $WORK_DIR, and report the literal's number and starting line.
+    awk -v out="$WORK_DIR" '
+        function emit(body, start,    path) {
+            path = out "/lit." ++n
+            printf "%s", body > path
+            close(path)
+            print n, start
+        }
+        {
+            pos = 1
+            while ((idx = index(substr($0, pos), "\"\"\"")) > 0) {
+                at = pos + idx - 1
+                if (inside) {
+                    body = body substr($0, pos, at - pos)
+                    inside = 0
+                    if (substr($0, at + 3) ~ /^[ \t]*\^\^[ \t]*rdf:XMLLiteral/) emit(body, start)
+                } else {
+                    inside = 1
+                    start = NR
+                    body = ""
+                }
+                pos = at + 3
+            }
+            if (inside) body = body substr($0, pos) "\n"
+        }
+    ' "$file" > "$WORK_DIR/manifest"
+
+    while read -r literal start; do
+        lexical_form="$WORK_DIR/lit.$literal"
+
+        if ! xmllint --exc-c14n "$lexical_form" > "$WORK_DIR/canonical" 2> "$WORK_DIR/parse-error"; then
+            echo "$file:$start: rdf:XMLLiteral is not well-formed XML" >&2
+            sed 's|^|    |' "$WORK_DIR/parse-error" >&2
+            EXIT_CODE=1
+            continue
+        fi
+
+        if ! cmp -s "$lexical_form" "$WORK_DIR/canonical"; then
+            echo "$file:$start: rdf:XMLLiteral is not canonical XML" >&2
+            # diff exits non-zero when the files differ, which set -e would treat as fatal
+            diff -u "$lexical_form" "$WORK_DIR/canonical" | sed -e '1,2d' -e 's|^|    |' >&2 || true
+            EXIT_CODE=1
+        fi
+    done < "$WORK_DIR/manifest"
+done < <(find . \( -name '*.ttl' -o -name '*.trig' \) -type f -not -path '*/.git/*' -not -path '*/html/*' -print0)
+
+exit "$EXIT_CODE"

demo/copenhagen/root.ttl

@@ -25,12 +25,34 @@
 
 <#page-header> a ldh:XHTML ;
     rdf:value """<div xmlns="http://www.w3.org/1999/xhtml">
-        <div class="page-header">
+        <div class="ldh-section">
             <h2>Copenhagen</h2>
-            <p class="lead">Geospatial and other open data about the city of Copenhagen</p>
+            <p>Geospatial and other open data about the city of Copenhagen</p>
+        </div>
+        <div class="ldhc-tabs or-horizontal">
+            <div class="ldhc-tablist sz-md va-line" role="tablist">
+                <button aria-controls="imports-pane" aria-selected="true" class="ldhc-tab is-on" id="imports-tab" role="tab" type="button"><span class="ldhc-tab-lbl">Imports</span></button>
+                <button aria-controls="charts-pane" aria-selected="false" class="ldhc-tab" id="charts-tab" role="tab" type="button"><span class="ldhc-tab-lbl">Charts</span></button>
+                <button aria-controls="faceted-search-pane" aria-selected="false" class="ldhc-tab" id="faceted-search-tab" role="tab" type="button"><span class="ldhc-tab-lbl">Faceted search</span></button>
+                <button aria-controls="parallax-pane" aria-selected="false" class="ldhc-tab" id="parallax-tab" role="tab" type="button"><span class="ldhc-tab-lbl">Parallax</span></button>
+                <button aria-controls="rich-content-pane" aria-selected="false" class="ldhc-tab" id="rich-content-tab" role="tab" type="button"><span class="ldhc-tab-lbl">Rich content</span></button>
+            </div>
+            <div aria-labelledby="imports-tab" class="ldhc-tabpanel" id="imports-pane" role="tabpanel">
+                <p>Every dataset here arrived as an open CSV file from the city's data portal, lifted to RDF by LinkedDataHub's CSV <a href="https://atomgraph.github.io/LinkedDataHub/linkeddatahub/docs/reference/imports/csv/" target="_blank">imports</a> — one mapping query per facility type.</p>
+            </div>
+            <div aria-labelledby="charts-tab" class="ldhc-tabpanel" hidden="hidden" id="charts-pane" role="tabpanel">
+                <p>SPARQL queries drive live <a href="https://atomgraph.github.io/LinkedDataHub/linkeddatahub/docs/reference/data-model/resources/charts/" target="_blank">charts</a> — the facilities-by-type breakdown below and the largest <a href="parking-facilities/">parking facilities</a> ranking are both recomputed from the graph on each request.</p>
+            </div>
+            <div aria-labelledby="faceted-search-tab" class="ldhc-tabpanel" hidden="hidden" id="faceted-search-pane" role="tabpanel">
+                <p>Container listings offer faceted search over the facilities they hold — filter <a href="schools/">schools</a>, <a href="playgrounds/">playgrounds</a> or <a href="libraries/">libraries</a> by their properties without writing a query.</p>
+            </div>
+            <div aria-labelledby="parallax-tab" class="ldhc-tabpanel" hidden="hidden" id="parallax-pane" role="tabpanel">
+                <p>Following a facility's links walks the Knowledge Graph — related results surface as you navigate, a style known as parallax navigation.</p>
+            </div>
+            <div aria-labelledby="rich-content-tab" class="ldhc-tabpanel" hidden="hidden" id="rich-content-pane" role="tabpanel">
+                <p>Documents like this one compose prose, charts and maps as structured content blocks backed by the graph — the map of <a href="bicycle-parkings/">bicycle parkings</a> is a block like any other.</p>
+            </div>
         </div>
-        <p>Features include CSV data <a href="https://atomgraph.github.io/LinkedDataHub/linkeddatahub/docs/reference/imports/csv/" target="_blank">imports</a>, SPARQL-based <a href="https://atomgraph.github.io/LinkedDataHub/linkeddatahub/docs/reference/data-model/resources/charts/" target="_blank">charts</a>, faceted search and related results (parallax navigation) as well as
-            rich documents composed of structured content backed by RDF Knowledge Graph data.</p>
         <p>This application was created on <a href="https://atomgraph.github.io/LinkedDataHub/" target="_blank">LinkedDataHub</a> using the low code paradigm: no programming was required, only scripts that
             invoke LinkedDataHub's CLI commands.</p>
     </div>"""^^rdf:XMLLiteral .

demo/northwind-traders/.ldhignore

@@ -3,3 +3,4 @@ Makefile
 imports.csv
 root.ttl
 screenshot.gif
+unesco-mappings.ttl