Initial attempt to get xcore working with SIRI

.github/workflows/ci.yml

@@ -35,6 +35,9 @@ jobs:
       - name: Validate SIRI XML examples
         run: ./.github/scripts/validate-examples.sh
 
+      - name: Generate documentation tables
+        run: ./docs/generate-tables.sh
+
       - name: Commit changes
         uses: EndBug/add-and-commit@v9 # https://github.com/marketplace/actions/add-commit
         with:

.github/workflows/deploy-pages.yml

@@ -0,0 +1,38 @@
+name: Deploy documentation tables
+
+on:
+  push:
+    branches: ["master"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: './docs/generated'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

docs/README.md

@@ -0,0 +1,36 @@
+
+# Generating OJP Documentation
+
+This document describes the generation of documentation for the OJP XML schemas. There are two goals:
+
+* Generate plain HTML documentation with a table of contents for reference purposes.
+* Provide the HTML documentation in a format so it can be easily integrated into the associated CEN standards document which is maintained as an MS Word file.
+
+## Prerequisites
+
+The documentation generation process requires an XSLT 1.0 processor like [Apache Xalan-J](http://xalan.apache.org/xalan-j/index.html) or (xsltproc](http://xmlsoft.org/XSLT/).
+
+On Linux, install xsltproc running `apt-get install xsltproc` (or the required equivalent in non-Debian based distributions).
+
+For Windows, you'll find Windows binaries for xsltproc at http://xmlsoft.org/XSLT/.
+
+## Generation of HTML documentation
+
+### Instructions
+
+On Linux and with the above prerequisites at hand, you can run `generate-tables.sh` to convert the XML schemas into a single HTML file [`index.html`](generated/index.html) in the `generated` subdirectory.
+
+The generated HTML file requires the file `asciidoc.css` to be in the same directory. The above script makes sure it's there.
+
+On Windows, please refer to the `generate-tables.sh` to figure out the necessary program invocations for your XSLT processor of choice.
+
+### Inner workings
+
+`generate-tables.sh` runs `xsltproc` twice. First the file `schema-collection.xml` is run against `ojp-to-prepdoc.xsl`. This combines all references XSD files to a single intermediate XML files which maps all information into a simplified structure that will make it easier in the second step to generate the final HTML documentation.
+
+Once, you have the intermediate XML file (`generated/OJP-prep.xml`), you can run that against the `ojp-prep-to-html-with-toc.xsl` stylesheet. This will generate the final `index.html` (HTML with table of contents). Alternatively, if you don't want the table of contents, you can use the stylesheet `ojp-prep-to-html.xsl`.
+
+## XML Schema Convention Check
+
+There is an additional XSLT stylesheet `check-ojp-schemas.xsl` (invoked by `check-ojp-schemas.sh`) that can be used to check whether certain conventions for the design
+of the XML schemas for OJP have been violated.

docs/custom-netex-perxsd.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<custom>
+	<!-- Title appearing on the entry page -->
+	<systemTitle><strong>Ne</strong>twork <strong>T</strong>imetable 
+        <strong>EX</strong>change</systemTitle>
+	<!-- Standardized namespace bindings -->
+	<namespaces>
+		<namespace prefix="orc" uri="http://datex2.eu/schema/2_0RC1/2_0"/>
+		<namespace prefix="wsdl" uri="http://wsdl.siri.org.uk"/>
+		<namespace prefix="acsb" uri="http://www.ifopt.org.uk/acsb"/>
+		<namespace prefix="ifopt" uri="http://www.ifopt.org.uk/ifopt"/>
+		<namespace prefix="netex" uri="http://www.netex.org.uk/netex"/>
+		<namespace prefix="gml" uri="http://www.opengis.net/gml/3.2"/>
+		<namespace prefix="siri" uri="http://www.siri.org.uk/siri"/>
+		<namespace prefix="ojp" uri="http://www.vdv.de/ojp"/>
+	</namespaces>
+	<!-- Report type specific rules -->
+	<reportTypes/>
+</custom>

docs/custom-ojp-perxsd.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<custom>
+	<!-- Title appearing on the entry page -->
+	<systemTitle><strong>O</strong>pen API for distributed <strong>J</strong>ourney 
+        <strong>P</strong>lanning</systemTitle>
+	<!-- Standardized namespace bindings -->
+	<namespaces>
+		<namespace prefix="orc" uri="http://datex2.eu/schema/2_0RC1/2_0"/>
+		<namespace prefix="wsdl" uri="http://wsdl.siri.org.uk"/>
+		<namespace prefix="acsb" uri="http://www.ifopt.org.uk/acsb"/>
+		<namespace prefix="ifopt" uri="http://www.ifopt.org.uk/ifopt"/>
+		<namespace prefix="netex" uri="http://www.netex.org.uk/netex"/>
+		<namespace prefix="gml" uri="http://www.opengis.net/gml/3.2"/>
+		<namespace prefix="siri" uri="http://www.siri.org.uk/siri"/>
+		<namespace prefix="ojp" uri="http://www.vdv.de/ojp"/>
+	</namespaces>
+	<!-- Report type specific rules -->
+	<reportTypes/>
+	<!--
+    <domains>
+        <domain name="xsd">
+            <content>
+                <foreach>xsd</foreach>
+            </content>
+            <processing>
+                <outputPath>../output/ojp2</outputPath>
+                <title>#xsdname</title>
+            </processing>
+        </domain>
+    </domains>
+    -->
+</custom>

docs/custom-ojp.xml

@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<custom>
+	<!-- Title appearing on the entry page -->
+	<systemTitle><strong>O</strong>pen API for distributed <strong>J</strong>ourney 
+        <strong>P</strong>lanning</systemTitle>
+	<!-- Standardized namespace bindings -->
+	<namespaces>
+		<namespace prefix="orc" uri="http://datex2.eu/schema/2_0RC1/2_0"/>
+		<namespace prefix="wsdl" uri="http://wsdl.siri.org.uk"/>
+		<namespace prefix="acsb" uri="http://www.ifopt.org.uk/acsb"/>
+		<namespace prefix="ifopt" uri="http://www.ifopt.org.uk/ifopt"/>
+		<namespace prefix="netex" uri="http://www.netex.org.uk/netex"/>
+		<namespace prefix="gml" uri="http://www.opengis.net/gml/3.2"/>
+		<namespace prefix="siri" uri="http://www.siri.org.uk/siri"/>
+		<namespace prefix="ojp" uri="http://www.vdv.de/ojp"/>
+	</namespaces>
+	<!-- Report type specific rules -->
+	<reportTypes/>
+	<domains>
+		<domain name="datex2">
+			<content>
+				<targetNamespace>http://datex2.eu/schema/2_0RC1/2_0</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed 
+                    <strong>J</strong>ourney <strong>P</strong>lanning (datex2)</title>
+				<titleEnumDict>OJP Enumeration Dictionary - DATEX2</titleEnumDict>
+				<reportFileBaseName>datex2</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="siri-wsdl">
+			<content>
+				<targetNamespace>http://wsdl.siri.org.uk</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed 
+                    <strong>J</strong>ourney <strong>P</strong>lanning (wsdl)</title>
+				<titleEnumDict>OJP Enumeration Dictionary - WSDL</titleEnumDict>
+				<reportFileBaseName>siri-wsdl</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="acsb">
+			<content>
+				<targetNamespace>http://www.ifopt.org.uk/acsb</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed 
+                    <strong>J</strong>ourney <strong>P</strong>lanning (ACSB)</title>
+				<titleEnumDict>OJP Enumeration Dictionary - ACSB</titleEnumDict>
+				<reportFileBaseName>acsb</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="ifopt">
+			<content>
+				<targetNamespace>http://www.ifopt.org.uk/ifopt</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed 
+                    <strong>J</strong>ourney <strong>P</strong>lanning (IFOPT)</title>
+				<titleEnumDict>OJP Enumeration Dictionary - IFOPT</titleEnumDict>
+				<reportFileBaseName>ifopt</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="opengis">
+			<content>
+				<targetNamespace>http://www.opengis.net/gml/3.2</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed 
+                    <strong>J</strong>ourney <strong>P</strong>lanning (GML)</title>
+				<titleEnumDict>OJP Enumeration Dictionary - OJP</titleEnumDict>
+				<reportFileBaseName>gml</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="siri">
+			<content>
+				<targetNamespace>http://www.siri.org.uk/siri</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed 
+                    <strong>J</strong>ourney <strong>P</strong>lanning (SIRI)</title>
+				<reportFileBaseName>siri</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="ojp">
+			<content>
+				<targetNamespace>http://www.vdv.de/ojp</targetNamespace>
+				<files dir="ojp" name="ojp.xsd"/>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed 
+                    <strong>J</strong>ourney <strong>P</strong>lanning</title>
+				<reportFileBaseName>ojp</reportFileBaseName>
+				<order>
+					<first>
+						<xsd filePath="OJP.xsd"/>
+						<xsd filePath="ojp/OJP_Requests.xsd"/>
+						<xsd filePath="ojp/OJP_RequestSupport.xsd"/>
+						<xsd filePath="ojp/OJP_Fare.xsd"/>
+						<xsd filePath="ojp/OJP_FareSupport.xsd"/>
+						<xsd filePath="ojp/OJP_Lines.xsd"/>
+						<xsd filePath="ojp/OJP_Locations.xsd"/>
+						<xsd filePath="ojp/OJP_PlaceSupport.xsd"/>
+						<xsd filePath="ojp/OJP_StopEvents.xsd"/>
+						<xsd filePath="ojp/OJP_TripInfo.xsd"/>
+						<xsd filePath="ojp/OJP_Trips.xsd"/>
+						<xsd filePath="ojp/OJP_JourneySupport.xsd"/>
+						<xsd filePath="ojp/OJP_Availability.xsd"/>
+						<xsd filePath="ojp/OJP_Common.xsd"/>
+						<xsd filePath="ojp/OJP_FacilitySupport.xsd"/>
+						<xsd filePath="ojp/OJP_ModesSupport.xsd"/>
+						<xsd filePath="ojp/OJP_SituationSupport.xsd"/>
+						<xsd filePath="ojp/OJP_Utility.xsd"/>
+						<xsd filePath="ojp/OJP_Status.xsd"/>
+					</first>
+				</order>
+				<reportTypes>
+					<!-- Report "edisc-html" -->
+					<reportType name="contab">
+						<!-- XSD titles -->
+						<xsdTitle pref1="singleSentenceAnno" pref2="fileName"/>
+						<!-- Name edits - prefix removal and substring replacement -->
+						<nameEdit>
+							<comp removePrefix="ojp" use="main" kind="element"/>
+							<comp removePrefix="ojp" use="main" kind="complexType"/>
+							<comp removePrefix="ojp" use="main" kind="group"/>
+							<comp removePrefix="ojp" use="main" kind="simpleType"/>
+							<comp removePrefix="ojp" use="sub" kind="element"/>
+							<comp removePrefix="ojp" use="sub" kind="group" replace="Group$" with=""/>
+							<comp removePrefix="ojp" use="sub" kind="complexType" replace="Structure$" with=""/>
+						</nameEdit>
+					</reportType>
+				</reportTypes>
+			</processing>
+		</domain>
+	</domains>
+</custom>

docs/custom-siri-perxsd.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<custom>
+	<!-- Title appearing on the entry page -->
+	<systemTitle><strong>S</strong>erver <strong>I</strong>nterface for 
+        <strong>R</strong>eal-time <strong>I</strong>nformation (SIRI)</systemTitle>
+	<!-- Standardized namespace bindings -->
+	<namespaces>
+		<namespace prefix="orc" uri="http://datex2.eu/schema/2_0RC1/2_0"/>
+		<namespace prefix="wsdl" uri="http://wsdl.siri.org.uk"/>
+		<namespace prefix="acsb" uri="http://www.ifopt.org.uk/acsb"/>
+		<namespace prefix="ifopt" uri="http://www.ifopt.org.uk/ifopt"/>
+		<namespace prefix="netex" uri="http://www.netex.org.uk/netex"/>
+		<namespace prefix="gml" uri="http://www.opengis.net/gml/3.2"/>
+		<namespace prefix="siri" uri="http://www.siri.org.uk/siri"/>
+		<namespace prefix="ojp" uri="http://www.vdv.de/ojp"/>
+	</namespaces>
+	<!-- Report type specific rules -->
+	<reportTypes/>
+</custom>

docs/generate-tables.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Generate the documentation tables as docs/generated/OJP.html from the .xsd schema files
+#
+# You need the binary `java`
+# apt-get install xsltproc
+
+# The -e flag causes the script to exit as soon as one command returns a non-zero exit code
+set -e
+
+base_dir="$(readlink -f $(dirname "$0")/..)"
+xsd_dir=$base_dir/xsd
+xsl_dir=$base_dir/docs
+generated_dir="${base_dir}/docs/generated"
+basex="/tmp/basex.jar"
+
+echo "Download BaseX ..."
+
+if [ ! -e ${basex} ]; then
+	wget --output-document=${basex} https://files.basex.org/releases/10.6/BaseX106.jar
+fi
+
+echo "Generating documentation tables ..."
+
+# prepare generated_dir
+mkdir -p "${generated_dir}"
+rm -f "${generated_dir}"/contab/*.html
+cd ${xsl_dir}
+java -cp /tmp/basex.jar org.basex.BaseX -b report=contab -b dir=${xsd_dir} -b odir=${generated_dir} -b custom=custom-ojp.xml -b dnamesExcluded=".git .github" xcore.xq
+rm -fr "${generated_dir}"/edesc
+
+echo -e '\033[0;32mFinished generating documentation tables\033[0m'