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

lib/README.md

@@ -77,10 +77,10 @@ new Number("odata-data-aggregation-ext").build(proc.stdin);
 
 The HTML file uses CSS stylesheets contained in the [`docs/*/styles`](../docs/odata-data-aggregation-ext/styles) subfolder in order to render keywords in the same font (MathJax Typewriter) whether they occur standalone or in a formula:
 
-| Keyword occurs     | Markdown source                      | Rendered result                      |
-| ------------------ | ------------------------------------ | ------------------------------------ |
-| standalone         | `` The `aggregate` transformation `` | The ${\tt aggregate}$ transformation |
-| in MathJax formula | `${\tt aggregate}(α{\tt\ as\ }D)$`   | ${\tt aggregate}(α{\tt\ as\ }D)$     |
+| Keyword occurs     | Markdown source                    | Rendered result                      |
+| ------------------ | ---------------------------------- | ------------------------------------ |
+| standalone         | ``The `aggregate` transformation`` | The ${\tt aggregate}$ transformation |
+| in MathJax formula | `${\tt aggregate}(α{\tt\ as\ }D)$` | ${\tt aggregate}(α{\tt\ as\ }D)$     |
 
 A monospaced font (Courier New) is used for OData requests and their JSON or XML responses.
 
@@ -96,6 +96,10 @@ The following scripts can be executed manually or as part of a GitHub Action:
   - a copy of the common [`styles`](../styles) folder
   - a copy of the document-specific `*/images` folder, if this exists.
 - [`npm run pdf`](build-pdf.mjs) runs the PDF conversion and writes the PDF document into the [`docs/*`](../docs) folder.
+- [`npm run select <CSS selector> [<XPath expression>]`](selector.mjs) selects parts of the generated HTML documents by executing a CSS selector and optionally an XPath expression relative to each match. For example, syntax errors in JSON code snippets can be detected with
+  ```sh
+  npm run select ".json .er" "self::*[.!='…']/text()"
+  ```
 - [`npm test`](../test) runs a test suite.
 
 ## A note on diagrams

lib/build-pdf.js

@@ -10,7 +10,7 @@ iterator(function (srcname, name, variant, meta) {
       console.log(
         refreshed ? "✓" : "=",
         srcname,
-        variant === "meta" ? "" : variant
+        variant === "meta" ? "" : variant,
       );
     })
     .catch((error) => {

lib/build.js

@@ -22,7 +22,7 @@ iterator(function (srcname, name, variant, meta) {
     "--metadata-file": `${__dirname}/../${srcname}/${variant}.yaml`,
   });
   html.stdout.pipe(
-    fs.createWriteStream(`${__dirname}/../docs/${name}/${name}.html`)
+    fs.createWriteStream(`${__dirname}/../docs/${name}/${name}.html`),
   );
   new Number(srcname, variant, meta)
     .build(
@@ -34,7 +34,7 @@ iterator(function (srcname, name, variant, meta) {
         .on("end", function () {
           md.end();
           html.stdin.end();
-        })
+        }),
     )
     .then(() => {
       console.log("✓", srcname, variant === "meta" ? "" : variant);
@@ -53,5 +53,5 @@ fs.writeFileSync(
 This repository contains working drafts for OData specifications:
 
 ${docs.sort().join("\n")}
-`
+`,
 );

lib/clean.mjs

@@ -18,7 +18,7 @@ const clean = old
   .replaceAll("\r\n", "\n")
   .replace(
     /<span[ \n]style='font:7.0pt "Times New Roman"'>(&nbsp;|\n|\s)+<\/span>/g,
-    " "
+    " ",
   )
   .replace(/<a[ \n]name="_[^"]+">[\d\. \n]*<\/a>/g, "")
   .replace(/<a[ \n]name="_[^"]+">([^>]*)<\/a>/g, "$1")
@@ -28,30 +28,30 @@ const clean = old
   // clean up formatting
   .replace(
     /<span[ \n]+style='font-family:\n?"Arial",sans-serif'>([^<]*)<\/span>/g,
-    "$1"
+    "$1",
   )
   .replace(
     /<span[ \n](lang=[A-Z]+ )?style='(font-size:\n?[\d\.]+pt;[ \n]*)?color:\n?black(;\n?background:\n?(white|#D9D9D9))?'>([^<]*)<\/span>/g,
-    "$5"
+    "$5",
   )
   .replace(
     /<span[ \n]style='font-family:"Calibri",sans-serif'>([^<]*)<\/span>/g,
-    "$1"
+    "$1",
   )
   .replace(/<span[ \n]style='color:windowtext'>([^<]*)<\/span>/g, "$1")
   .replace(
     /<span[ \n]style='background:(white|#D9D9D9)'>([^<]*)<\/span>/g,
-    "$2"
+    "$2",
   )
   .replace(/<span[ \n]style='color:(black|#333333)'>([^<]*)<\/span>/g, "$2")
   .replace(
     /<span[ \n]style='color:\n?(black|#333333);\n?background:\n?white'>([^<]*)<\/span>/g,
-    "$2"
+    "$2",
   )
   .replace(/<span[ \n]class=MsoHyperlink>([^<]*)<\/span>/g, "$1")
   .replace(
     /<span[ \n]class=MsoHyperlink>([^<]*)<b>([^<]*)<\/b><\/span>/g,
-    "$1$2"
+    "$1$2",
   )
   .replace(/<span[ \n]lang=EN>([^<]*)<\/span>/g, "$1")
   .replace(/<span[ \n]class=string>([^<]*)<\/span>/g, "$1")
@@ -61,7 +61,7 @@ const clean = old
   // clean up code formatting
   .replace(
     /<span[ \n]+style='(font-size:[\d\.]+pt;[ \n]*)?font-family:[ \n]*"Courier[ \n]New"(;\n?color:black)?(;\n?background:\n?white)?'>([^<]*)<\/span>/g,
-    "<code>$4</code>"
+    "<code>$4</code>",
   )
   .replace(/<span[ \n]+class=Datatype>([^<]*)<\/span>/g, "<code>$1</code>")
   .replace(/<span[ \n]+class=Keyword>([^<]*)<\/span>/g, "<code>$1</code>")
@@ -70,19 +70,19 @@ const clean = old
   .replaceAll("</code><code>", "")
   .replace(
     /<span[ \n]style='color:(black|#333333)'>((<code>|<\/code>|[^<])*)<\/span>/g,
-    "$2"
+    "$2",
   )
   .replace(
     /<p[ \n]+class=SourceCode>([^<]*)<\/p>/g,
-    "<p class=SourceCode><code>$1</code></p>"
+    "<p class=SourceCode><code>$1</code></p>",
   )
   .replace(/<span[ \n]+class=MsoHyperlink><code> <\/code><\/span>/g, "")
   .replace(/<span[ \n]+class=MsoHyperlink><i> <\/i><\/span>/g, "")
 
   // clean up headings
   .replace(
     /<a[ \n]href="#sec[^"]+">((<code>|<\/code>|[^<])*)<\/a><\/h/g,
-    "$1</h"
+    "$1</h",
   )
   .replace(/<h1>[\d\.\s]*/g, "<h1>##sec ")
   .replace(/<h2>[\d\.\s]*/g, "<h2>##subsec ")
@@ -94,7 +94,7 @@ const clean = old
   // TODO: clean up more <div> tags
   .replace(
     /<div style='border:none;border-top:solid gray 1.0pt;padding:6.0pt 0in 0in 0in'>([\s\S]*?)<\/div>/g,
-    "$1"
+    "$1",
   )
 
   // clean up references
@@ -134,11 +134,11 @@ const final = raw
   // bullet points
   .replace(
     /\n\[· \]\{style="(font-size:[\d\.]+pt;)?font-family:\n?Symbol(;color:black)?(;font-style:normal)?"\}/g,
-    "- "
+    "- ",
   )
   .replace(
     /\n\[\[·[ \n]\]\{style="(font-size:[\d\.]+pt;)?font-family:Symbol(;\n?color:(black|windowtext))?"\}\]\{[^}]*\}/g,
-    "- "
+    "- ",
   )
   // code blocks
   .replace(
@@ -149,25 +149,25 @@ const final = raw
         .replace(/`\n\n`/g, "\n")
         .replace(/^`/, "")
         .replace(/`$/, "") +
-      "\n```\n"
+      "\n```\n",
   )
   // CSDL representation-specific stuff
   .replace(
     /^::: \{style="border:none;border-left:solid windowtext 1.0pt;padding:0in 0in 0in 8.0pt;\nmargin-left:21.55pt;margin-right:0in"\}\n/gm,
-    "::: csdlHeadline\n"
+    "::: csdlHeadline\n",
   )
   .replace(
     /^::: \{style="border:none;border-left:solid windowtext 1.0pt;padding:0in 0in 0in 8.0pt;\nmargin-left:21.55pt;margin-right:21.55pt"\}\n/gm,
-    "::: csdl\n"
+    "::: csdl\n",
   )
   // examples: twice for consecutive examples without empty lines between them
   .replace(
     /\nExample \d+:([\s\S]*?)\n\n/g,
-    "\n::: example\nExample ##ex:$1\n:::\n\n"
+    "\n::: example\nExample ##ex:$1\n:::\n\n",
   )
   .replace(
     /\n ?Example \d+:([\s\S]*?)\n\n/g,
-    "\n::: example\nExample ##ex:$1\n:::\n\n"
+    "\n::: example\nExample ##ex:$1\n:::\n\n",
   )
   // minor tweaks
   .replace(/\[([^\]]+)\]\{#_Toc[^}]+\}/g, "$1");

lib/iterator.js

@@ -2,25 +2,27 @@ const fs = require("fs");
 const yaml = require("js-yaml");
 
 module.exports = function (callback) {
-  fs.readdirSync(__dirname + "/..", { withFileTypes: true }).forEach(function (
-    doc
-  ) {
-    if (doc.isDirectory() && doc.name.startsWith("odata-")) {
-      fs.readdirSync(`${__dirname}/../${doc.name}`)
-        .filter((fn) => fn.endsWith(".yaml"))
-        .forEach(function (metaname) {
-          var meta = yaml.load(
-            fs.readFileSync(`${__dirname}/../${doc.name}/${metaname}`)
-          );
-          var name =
-            metaname === "meta.yaml" || !meta.dirname ? doc.name : meta.dirname;
-          callback(
-            doc.name,
-            name,
-            metaname.substring(0, metaname.length - 5),
-            meta
-          );
-        });
-    }
-  });
+  fs.readdirSync(__dirname + "/..", { withFileTypes: true }).forEach(
+    function (doc) {
+      if (doc.isDirectory() && doc.name.startsWith("odata-")) {
+        fs.readdirSync(`${__dirname}/../${doc.name}`)
+          .filter((fn) => fn.endsWith(".yaml"))
+          .forEach(function (metaname) {
+            var meta = yaml.load(
+              fs.readFileSync(`${__dirname}/../${doc.name}/${metaname}`),
+            );
+            var name =
+              metaname === "meta.yaml" || !meta.dirname
+                ? doc.name
+                : meta.dirname;
+            callback(
+              doc.name,
+              name,
+              metaname.substring(0, metaname.length - 5),
+              meta,
+            );
+          });
+      }
+    },
+  );
 };