Merge remote-tracking branch 'origin/main' into ODATA-1491

.github/workflows/nodejs.yml

@@ -8,7 +8,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x]
+        node-version: [20.x]
 
     steps:
       - uses: actions/checkout@v3
@@ -24,11 +24,5 @@ jobs:
       - name: Build docs
         run: |
           npm ci
-          npm run build --if-present
-          git config user.name ${GITHUB_ACTOR}
-          git config user.email ${PUSHER_EMAIL}
-          git add docs/*/*.html docs/*/*.md docs/*/styles/*
-          git diff-index --quiet HEAD docs/*/*.html docs/*/*.md docs/*/styles/* || (npm run pdf --if-present && git add docs/*/*.pdf && git commit -m "auto-refreshed")
-          test `git branch --show-current` && git push
-        env:
-          PUSHER_EMAIL: ${{ github.event.pusher.email }}
+          npm run build
+          git diff --exit-code docs

.github/workflows/pdf.yml

@@ -13,6 +13,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v3
         with:
@@ -21,9 +23,9 @@ jobs:
       - name: Generate PDF
         run: |
           npm ci
-          npm run pdf --if-present
+          npm run pdf
           git config user.name ${GITHUB_ACTOR}
           git config user.email [email protected]
           git add docs/*/*.pdf
-          git diff-index --quiet HEAD || git commit -m "PDF generation"
+          git diff-index --quiet HEAD docs/*/*.pdf || git commit -m "PDF generation"
           git push

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "hediet.vscode-drawio"
+  ]
+}

.vscode/settings.json

@@ -1,5 +1,6 @@
 {
   "cSpell.words": [
+    "ABNF",
     "asec",
     "CSDL",
     "ETag",
@@ -8,6 +9,8 @@
     "subasec",
     "subsec",
     "subsubsec",
-    "subsubsubsec"
+    "subsubsubsec",
+    "subsubsubsubsec",
+    "upsert"
   ]
 }

README.md

@@ -19,19 +19,26 @@
 
 ## How to view the documents
 
-Documents are generated from a Markdown source using Node.js modules described [here](lib).
+Documents are generated from Markdown sources using Node.js modules described [here](lib) and Pandoc.
 
-To view mathematical formulas, install pandoc as explained in the section on [Document Conventions](odata-data-aggregation-ext/1%20Introduction.md). This is invoked by the Node.js module [`lib/pandoc.js`](lib/pandoc.js).
+### Installation
 
-Clone this repository, run `npm install` and `npm start` to start a Node.js server and access the HTML pages at, for example, `http://localhost:8080/odata-data-aggregation-ext` (see [`lib/server.js`](lib/server.js)).
+1. Download and install [Node.js](https://nodejs.org/), verify via `node -v`
+2. Download and install [Pandoc](https://pandoc.org/), verify via `pandoc -v`
+3. Download and install [git](https://git-scm.com/), verify via `git -v`
+4. Optionally download and install [GitHub Desktop](https://desktop.github.com/)
+5. Clone this repository
+6. In the local repository folder run `npm install`, verify via `npm test`
 
-Run `npm run build` to build HTML and Markdown files for publication on github.io (see [`lib/build.js`](lib/build.js)).
+### Document preparation
 
-Run `npm run pdf` to convert the HTML files into PDF files (using puppeteer, see [`lib/pdf.js`](lib/pdf.js)).
+- `npm start` starts a [local web server](lib/server.js) to serve the HTML pages at <http://localhost:8080>
 
-## To Do
+  - The HTML pages are rebuilt and the browser is auto-refreshed whenever one of the source files changes
 
-- [ ] Check MD/HTML for broken and inconsistent links (similar to what we currently do with the `ExtractHyperlinksToExcel` Word macro)
-  - [x] Check for use of undefined anchors
-  - [ ] Check for hyperlinks with the same link target and different texts
-  - [ ] Check for hyperlinks with the same text and different link targets
+- `npm run build` builds HTML and Markdown files for publication on <https://oasis-tcs.github.io/odata-specs/>
+
+  - Do this before pushing to GitHub to avoid build errors
+
+- `npm run pdf` converts the HTML files to PDF
+  - This is only necessary for publication to the [OASIS Library](https://www.oasis-open.org/standards/)

docs/index.md

@@ -2,9 +2,10 @@
 
 This repository contains working drafts for OData specifications:
 
-* [OData Version 4.02 Part 1: Protocol - Working Draft for CS01](odata-protocol/odata-protocol.html)
-* [OData Version 4.02 Part 2: URL Conventions - Working Draft for CS01](odata-url-conventions/odata-url-conventions.html)
-* [OData CSDL JSON Version 4.02 - Working Draft for CS01](odata-csdl-json/odata-csdl-json.html)
-* [OData CSDL XML Version 4.02 - Working Draft for CS01](odata-csdl-xml/odata-csdl-xml.html)
-* [OData JSON Format Version 4.02 - Working Draft for CS01](odata-json-format/odata-json-format.html)
-* [OData Extension for Data Aggregation Version 4.0 - Working Draft for CS03](odata-data-aggregation-ext/odata-data-aggregation-ext.html)
+* [OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02 - Committee Specification Draft 01](odata-csdl-json/odata-csdl-json.html)
+* [OData Common Schema Definition Language (CSDL) XML Representation Version 4.02 - Committee Specification Draft 01](odata-csdl-xml/odata-csdl-xml.html)
+* [OData Extension for Data Aggregation Version 4.0 - Committee Specification 03](odata-data-aggregation-ext/odata-data-aggregation-ext.html)
+* [OData Extension for Temporal Data Version 4.0 - Committee Specification Draft 04](odata-temporal-ext/odata-temporal-ext.html)
+* [OData JSON Format Version 4.02 - Committee Specification Draft 01](odata-json-format/odata-json-format.html)
+* [OData Version 4.02. Part 1: Protocol - Committee Specification Draft 01](odata-protocol/odata-protocol.html)
+* [OData Version 4.02. Part 2: URL Conventions - Committee Specification Draft 01](odata-url-conventions/odata-url-conventions.html)