Improvements to the web server (#183)

lib/README.md

@@ -22,6 +22,7 @@ The [`number.js`](number.js) module generates a single Markdown document by prep
 - Generate section and example numbers
 - Generate a table of contents
 - Resolve references
+- Include files like `$$$include images/drawing.svg$$$`
 - Replace placeholders like `$$$pagetitle$$$` with values from a [`meta.yaml`](../odata-data-aggregation-ext/meta.yaml) file
 - Join multiple lines that end with a single space into one line
 - Sections of the file between `: varXXX` and `:` or between `::: {.varXXX ...}` and `:::` belong to a variant. One source file can contain several variants.
@@ -89,7 +90,11 @@ The [`pdf.js`](pdf.js) module uses a headless browser ([`puppeteer`](https://git
 
 The following scripts can be executed manually or as part of a GitHub Action:
 
-- [`npm run build`](build.js) runs the conversion and writes the Markdown output as well as the HTML output into the [`docs/*`](../docs) folder.
+- [`npm run build`](build.js) runs the conversion and writes the following into the [`docs/*`](../docs) folder:
+  - the Markdown output
+  - the HTML output
+  - 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 test`](../test) runs a test suite.
 

lib/number.js

@@ -15,7 +15,7 @@ class Number {
     this.meta =
       meta ||
       yaml.load(
-        fs.readFileSync(dir + "/" + (this.variant || "meta") + ".yaml")
+        fs.readFileSync(dir + "/" + (this.variant || "meta") + ".yaml"),
       );
   }
 
@@ -71,7 +71,7 @@ class Number {
                   this.toc[m[1]] = { sub: [] };
                 if (m[1].endsWith("sec")) {
                   m = line.match(
-                    / ##([A-Za-z0-9.]+)(?:_[A-Za-z0-9]+)?\s+(.+)$/
+                    / ##([A-Za-z0-9.]+)(?:_[A-Za-z0-9]+)?\s+(.+)$/,
                   );
                   m[3] = m[2].replace(/[^A-Za-z0-9]/g, "");
                 }
@@ -112,10 +112,10 @@ class Number {
                 }
                 this.match++;
               }
-            }.bind(this)
+            }.bind(this),
           )
           .on("close", resolve);
-      }.bind(this)
+      }.bind(this),
     );
   }
 
@@ -134,19 +134,28 @@ class Number {
             function (line) {
               lineno++;
               if (this.skip(line)) return;
-              var m1 = line.match(/^\$\$\$(.*?isec)\$\$\$$/);
+              var m1 = line.match(/^\$\$\$include\s+(.*?)\$\$\$\s*$/);
+              if (m1) {
+                try {
+                  out.write(fs.readFileSync(this.dir + "/" + m1[1]));
+                } catch (e) {
+                  this.errors.push(e);
+                }
+                return;
+              }
+              m1 = line.match(/^\$\$\$(.*?isec)\$\$\$\s*$/);
               if (m1) this.tableofcontents(this.toc[m1[1]]?.sub || [], out, "");
               else {
                 line = line.replace(
                   /\$\$\$(.*?)\$\$\$/g,
                   function (m, p) {
                     return this.meta[p] || m;
-                  }.bind(this)
+                  }.bind(this),
                 );
                 for (var m, regex = /\]\(#(.*?)\)/g; (m = regex.exec(line)); )
                   if (!this.refs[m[1]])
                     this.errors.push(
-                      `${this.dir}/${file}(${lineno}): Undefined link #${m[1]}`
+                      `${this.dir}/${file}(${lineno}): Undefined link #${m[1]}`,
                     );
                 m = line.match(/ ##([A-Za-z0-9.]+)(_([A-Za-z0-9]+))?/);
                 var outline = line;
@@ -171,19 +180,19 @@ class Number {
                       if (r) return `${r}](#${p})`;
                       else {
                         this.errors.push(
-                          `${this.dir}/${file}(${lineno}): Undefined link ##${p}`
+                          `${this.dir}/${file}(${lineno}): Undefined link ##${p}`,
                         );
                         return `~~${p}~~]`;
                       }
-                    }.bind(this)
-                  )
+                    }.bind(this),
+                  ),
                 );
                 if (!/\S\s$/.test(line)) out.write("\n");
               }
-            }.bind(this)
+            }.bind(this),
           )
           .on("close", resolve);
-      }.bind(this)
+      }.bind(this),
     );
   }
 
@@ -192,7 +201,7 @@ class Number {
       out.write(
         `${indent}- [${
           s.number.startsWith("i") ? "" : s.number + " "
-        }${s.name.replace(/,? $/, "")}](#${s.href})\n`
+        }${s.name.replace(/,? $/, "")}](#${s.href})\n`,
       );
       this.tableofcontents(s.sub, out, indent + "  ");
     }

lib/server.js

@@ -10,6 +10,7 @@ const liveReloadServer = livereload.createServer({ extraExts: ["md"] });
 liveReloadServer.watch(path.join(__dirname, ".."));
 
 const connectLivereload = require("connect-livereload");
+const statics = { images: {} };
 
 const app = express()
   .enable("strict routing")
@@ -57,16 +58,14 @@ const app = express()
     } catch (err) {
       next();
     }
+  })
+  .use("/:doc/styles", express.static(`${__dirname}/../styles`))
+  .use("/:doc/images", function (req, res, next) {
+    (statics.images[req.params.doc] ||= express.static(
+      `${__dirname}/../${req.params.doc}/images`,
+    ))(req, res, next);
   });
 
-iterator(function (srcname, name, variant) {
-  app.use(`/${srcname}/styles`, express.static(`${__dirname}/../styles`));
-  app.use(
-    `/${srcname}/images`,
-    express.static(`${__dirname}/../${srcname}/images`),
-  );
-});
-
 if (module.parent) module.exports = app;
 else
   app.listen(8080, function () {

odata-temporal-ext/2 Overview.md

@@ -58,7 +58,7 @@ Example ##ex_api1: model for `api-1` with snapshot entity sets (hidden
 application time), key properties marked with {id}
 :::
 
-![API-1](./images/api-1.drawio.svg)
+$$$include diagrams/api-1.drawio.svg$$$
 
 and
 
@@ -67,8 +67,7 @@ Example ##ex_api2: model for `api-2` with timeline entity sets (visible
 application time), key properties marked with {id}
 :::
 
-![API-2](./images/api-2.drawio.svg)
-
+$$$include diagrams/api-2.drawio.svg$$$
 
 ## ##subsec Example Data
 
@@ -80,7 +79,7 @@ Example ##ex: simple storage model: object key in dark green, temporal
 sub-key in light green, foreign keys in orange, non-key fields in blue
 :::
 
-![DB](./images/db.drawio.svg)
+$$$include diagrams/db.drawio.svg$$$
 
 The period start date is used as the temporal sub-key for identifying
 time slices together with the key of the temporal object.