From f26919aad0cbd8456105d3967cddf11105488da2 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 2 Aug 2024 11:37:26 +0200 Subject: [PATCH 01/10] No local biblio, use only Specref --- scripts/md2html/md2html.js | 55 +++----------------------------------- 1 file changed, 4 insertions(+), 51 deletions(-) diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js index 40d4230800..0c6199faa2 100644 --- a/scripts/md2html/md2html.js +++ b/scripts/md2html/md2html.js @@ -86,56 +86,9 @@ function preface(title,options) { ], }, ], - localBiblio: { - "OpenAPI-Learn": { - title: "OpenAPI - Getting started, and the specification explained", - href: "https://learn.openapis.org/", - publisher: "OpenAPI Initiative" - }, - "OpenAPI-Registry": { - title: "OpenAPI Initiative Registry", - href: "https://spec.openapis.org/registry/index.html", - publisher: "OpenAPI Initiative" - }, - //TODO: remove localBiblio once Specref PRs https://github.com/tobie/specref/pulls/ralfhandl are merged - "JSON-Schema-Validation-04": { - authors: [ "Kris Zyp", "Francis Galiegue", "Gary Court" ], - href: "https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00", - publisher: "Internet Engineering Task Force (IETF)", - status: "Internet-Draft", - title: "JSON Schema: interactive and non interactive validation. Draft 4", - date: "1 February 2013" - }, - "JSON-Schema-05": { - authors: [ "Austin Wright" ], - href: "https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00", - publisher: "Internet Engineering Task Force (IETF)", - status: "Internet-Draft", - title: "JSON Schema: A Media Type for Describing JSON Documents. Draft 5", - date: "13 October 2016" - }, - "JSON-Schema-Validation-05": { - authors: [ "Austin Wright", "G. Luff" ], - href: "https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00", - publisher: "Internet Engineering Task Force (IETF)", - status: "Internet-Draft", - title: "JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5", - date: "13 October 2016" - }, - "JSON-Schema-Validation-2020-12": { - authors: [ "Austin Wright", "Henry Andrews", "Ben Hutton" ], - href: "https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00", - publisher: "Internet Engineering Task Force (IETF)", - status: "Internet-Draft", - title: "JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 2020-12", - date: "8 December 2020" - }, - "SPDX": { - href: "https://spdx.org/licenses/", - title: "SPDX License List", - publisher: "Linux Foundation" - } - } + // localBiblio: { + // // add local bibliography entries here, add them to https://www.specref.org/, and remove them here once published + // } }; let preface = `${md.utils.escapeHtml(title)}`; @@ -361,7 +314,7 @@ for (let l in lines) { line = line.replace('[JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00)','[[JSON-Schema-2020-12|JSON Schema Specification Draft 2020-12]]'); line = line.replace('[JSON Schema Core](https://tools.ietf.org/html/draft-bhutton-json-schema-00)','[[JSON-Schema-2020-12|JSON Schema Core]]'); line = line.replace('[JSON Schema Validation](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00)','[[JSON-Schema-Validation-2020-12|JSON Schema Validation]]'); - line = line.replace('[SPDX](https://spdx.org/licenses/)','[[SPDX]]'); + line = line.replace('[SPDX](https://spdx.org/licenses/) license','[[SPDX-Licenses]]'); line = line.replace('[XML namespaces](https://www.w3.org/TR/xml-names11/)','[[xml-names11|XML namespaces]]'); line = line.replace('JSON standards. YAML,','[[RFC7159|JSON]] standards. [[YAML|YAML]],'); // 2.0.md only line = line.replace('JSON or YAML format.','[[RFC7159|JSON]] or [[YAML|YAML]] format.'); From 79cdabef0979d12d3d25a6ae0fc800e4e5d64560 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 2 Aug 2024 15:17:13 +0200 Subject: [PATCH 02/10] Process Version headline also in 3.0.4.md --- scripts/md2html/md2html.js | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js index 0c6199faa2..6e9fe14841 100644 --- a/scripts/md2html/md2html.js +++ b/scripts/md2html/md2html.js @@ -337,9 +337,14 @@ for (let l in lines) { if (delta>0) delta = 1; let prefix = ''; let newSection = '
'; - if (line.includes('## Version ')) { + const m = line.match(/# Version ([0-9.]+)$/); + if (m) { // our conformance section is headlined with 'Version x.y.z' newSection = '
'; + // adjust the heading to be a level 2 heading + line = '##' + m[0]; + delta = 1; + heading = 2; } if (line.includes('Appendix')) { newSection = '
'; From 6305acf9b1302b55c739ee545ac2179a74845ef3 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 2 Aug 2024 15:27:09 +0200 Subject: [PATCH 03/10] Update md2html.js --- scripts/md2html/md2html.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js index 6e9fe14841..32554927a5 100644 --- a/scripts/md2html/md2html.js +++ b/scripts/md2html/md2html.js @@ -341,8 +341,8 @@ for (let l in lines) { if (m) { // our conformance section is headlined with 'Version x.y.z' newSection = '
'; - // adjust the heading to be a level 2 heading - line = '##' + m[0]; + // adjust the heading to be at level 2 + line = '#' + m[0]; delta = 1; heading = 2; } From 75e7f5ee37b29370db6cc37173248e8a6db339c0 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 8 Aug 2024 19:29:24 +0200 Subject: [PATCH 04/10] Improved formatting * better green for headlines * consistent headline styles * JSON Reference as normative reference --- scripts/md2html/md2html.js | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js index 32554927a5..a621d502a9 100644 --- a/scripts/md2html/md2html.js +++ b/scripts/md2html/md2html.js @@ -107,9 +107,10 @@ function preface(title,options) { preface += ''; preface += '

OpenAPI Specification v30.0.1

Copyright © 3001 the Linux Foundation

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Status of This Document

The source-of-truth for the specification is the GitHub markdown file referenced above.

+

Heading 1

+

Text for first chapter

+

Version 30.0.1

+

This is the conformance section

+

Heading 2

+

Text for first section

+

Heading 3

+

Text for first subsection

+ + + + + + + + + + + + + +
VersionDate
30.0.13001-04-01
+ diff --git a/tests/md2html/fixtures/basic-new.md b/tests/md2html/fixtures/basic-new.md new file mode 100644 index 0000000000..51b1569aca --- /dev/null +++ b/tests/md2html/fixtures/basic-new.md @@ -0,0 +1,20 @@ +# Heading 1 + +Text for first chapter + +## Version 30.0.1 + +This is the conformance section + +## Heading 2 + +Text for first section + +### Heading 3 + +Text for first subsection + + +Version | Date +--------|----------- +30.0.1 | 3001-04-01 diff --git a/tests/md2html/fixtures/basic-old.html b/tests/md2html/fixtures/basic-old.html new file mode 100644 index 0000000000..cc8807fc74 --- /dev/null +++ b/tests/md2html/fixtures/basic-old.html @@ -0,0 +1,89 @@ +OpenAPI Specification v30.0.1 | Introduction, Definitions, & More

OpenAPI Specification v30.0.1

Copyright © 3001 the Linux Foundation

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Status of This Document

The source-of-truth for the specification is the GitHub markdown file referenced above.

+

Heading 1

+

Text for first chapter

+

Version 30.0.1

+

This is the conformance section

+

Heading 2

+

Text for first section

+

Heading 3

+

Text for first subsection

+ + + + + + + + + + + + + +
VersionDate
30.0.13001-04-01
+ diff --git a/tests/md2html/fixtures/basic-old.md b/tests/md2html/fixtures/basic-old.md new file mode 100644 index 0000000000..ff809d170f --- /dev/null +++ b/tests/md2html/fixtures/basic-old.md @@ -0,0 +1,20 @@ +# Heading 1 + +Text for first chapter + +### Version 30.0.1 + +This is the conformance section + +## Heading 2 + +Text for first section + +### Heading 3 + +Text for first subsection + + +Version | Date +--------|----------- +30.0.1 | 3001-04-01 diff --git a/tests/md2html/md2html.test.js b/tests/md2html/md2html.test.js new file mode 100644 index 0000000000..3bb6ec2c14 --- /dev/null +++ b/tests/md2html/md2html.test.js @@ -0,0 +1,37 @@ +import { readdirSync, readFileSync } from "node:fs"; +import { exec } from "node:child_process"; +import { resolve } from "node:path"; +import { describe, test, expect } from "vitest"; + +const folder = "./tests/md2html/fixtures/"; +describe("v3.0 - Validate examples", async () => { + readdirSync(folder, { withFileTypes: true }) + .filter((entry) => entry.isFile() && /\.md$/.test(entry.name)) + .forEach((entry) => { + test(entry.name, async () => { + const expected = readFileSync( + folder + entry.name.replace(".md", ".html"), + "utf8", + ); + const output = await md2html([entry.name], folder); + expect(output.stdout).to.equal(expected); + }); + }); +}); + +function md2html(args, cwd) { + return new Promise((res) => { + exec( + `node ${resolve("./scripts/md2html/md2html.js")} ${args.join(" ")}`, + { cwd }, + (error, stdout, stderr) => { + res({ + code: error?.code || 0, + error, + stdout, + stderr, + }); + }, + ); + }); +} From 055382bdabac6b71e3d5fc5a6f3b364c21d2bc1f Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Sun, 11 Aug 2024 12:59:31 +0200 Subject: [PATCH 07/10] normalize line-endings --- tests/md2html/fixtures/.gitattributes | 1 - tests/md2html/md2html.test.js | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) delete mode 100644 tests/md2html/fixtures/.gitattributes diff --git a/tests/md2html/fixtures/.gitattributes b/tests/md2html/fixtures/.gitattributes deleted file mode 100644 index e54b0b9ecb..0000000000 --- a/tests/md2html/fixtures/.gitattributes +++ /dev/null @@ -1 +0,0 @@ -*.html text eol=lf diff --git a/tests/md2html/md2html.test.js b/tests/md2html/md2html.test.js index 3bb6ec2c14..b0c1345843 100644 --- a/tests/md2html/md2html.test.js +++ b/tests/md2html/md2html.test.js @@ -12,7 +12,7 @@ describe("v3.0 - Validate examples", async () => { const expected = readFileSync( folder + entry.name.replace(".md", ".html"), "utf8", - ); + ).split(/\r\n|\n/).join("\n"); const output = await md2html([entry.name], folder); expect(output.stdout).to.equal(expected); }); From bb89f3e4d85f3eb8e8294af86f079a64afb26a50 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Sun, 11 Aug 2024 13:04:55 +0200 Subject: [PATCH 08/10] Try assert --- tests/md2html/md2html.test.js | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tests/md2html/md2html.test.js b/tests/md2html/md2html.test.js index b0c1345843..d440022b4b 100644 --- a/tests/md2html/md2html.test.js +++ b/tests/md2html/md2html.test.js @@ -2,6 +2,7 @@ import { readdirSync, readFileSync } from "node:fs"; import { exec } from "node:child_process"; import { resolve } from "node:path"; import { describe, test, expect } from "vitest"; +import assert from "node:assert"; const folder = "./tests/md2html/fixtures/"; describe("v3.0 - Validate examples", async () => { @@ -12,9 +13,9 @@ describe("v3.0 - Validate examples", async () => { const expected = readFileSync( folder + entry.name.replace(".md", ".html"), "utf8", - ).split(/\r\n|\n/).join("\n"); + ).split(/\r\n|\n/); const output = await md2html([entry.name], folder); - expect(output.stdout).to.equal(expected); + assert.deepStrictEqual(output.stdout.split("\n"), expected); }); }); }); From 4d990d9ae7905283ee2bc3fd89df0aa4c661ccdf Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Sun, 11 Aug 2024 13:52:10 +0200 Subject: [PATCH 09/10] line-endings --- scripts/md2html/md2html.js | 2 +- tests/md2html/fixtures/.gitattributes | 1 + tests/md2html/fixtures/basic-new.html | 67 +-------------------------- tests/md2html/fixtures/basic-old.html | 67 +-------------------------- tests/md2html/md2html.test.js | 4 +- 5 files changed, 6 insertions(+), 135 deletions(-) create mode 100644 tests/md2html/fixtures/.gitattributes diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js index 77b0a56bdc..34ca8ae4ef 100644 --- a/scripts/md2html/md2html.js +++ b/scripts/md2html/md2html.js @@ -120,7 +120,7 @@ function preface(title,options) { preface += 'pre { background-color: #f6f8fa !important; }'; preface += 'code { color: #c83500 } th code { color: inherit }'; preface += 'a.bibref { text-decoration: underline;}'; - preface += fs.readFileSync(path.resolve(__dirname,'gist.css'),'utf8').split('\n').join(' '); + preface += fs.readFileSync(path.resolve(__dirname,'gist.css'),'utf8').split(/\r?\n/).join(' '); preface += ''; preface += `

${title.split('|')[0]}

`; preface += `

Copyright © ${options.publishDate.getFullYear()} the Linux Foundation

`; diff --git a/tests/md2html/fixtures/.gitattributes b/tests/md2html/fixtures/.gitattributes new file mode 100644 index 0000000000..9a582600c1 --- /dev/null +++ b/tests/md2html/fixtures/.gitattributes @@ -0,0 +1 @@ +*.html text eol=lf \ No newline at end of file diff --git a/tests/md2html/fixtures/basic-new.html b/tests/md2html/fixtures/basic-new.html index cc8807fc74..5280441b47 100644 --- a/tests/md2html/fixtures/basic-new.html +++ b/tests/md2html/fixtures/basic-new.html @@ -1,69 +1,4 @@ -OpenAPI Specification v30.0.1 | Introduction, Definitions, & More

OpenAPI Specification v30.0.1

Copyright © 3001 the Linux Foundation

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Status of This Document

The source-of-truth for the specification is the GitHub markdown file referenced above.

+OpenAPI Specification v30.0.1 | Introduction, Definitions, & More

OpenAPI Specification v30.0.1

Copyright © 3001 the Linux Foundation

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Status of This Document

The source-of-truth for the specification is the GitHub markdown file referenced above.

Heading 1

Text for first chapter

Version 30.0.1

diff --git a/tests/md2html/fixtures/basic-old.html b/tests/md2html/fixtures/basic-old.html index cc8807fc74..5280441b47 100644 --- a/tests/md2html/fixtures/basic-old.html +++ b/tests/md2html/fixtures/basic-old.html @@ -1,69 +1,4 @@ -OpenAPI Specification v30.0.1 | Introduction, Definitions, & More

OpenAPI Specification v30.0.1

Copyright © 3001 the Linux Foundation

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Status of This Document

The source-of-truth for the specification is the GitHub markdown file referenced above.

+OpenAPI Specification v30.0.1 | Introduction, Definitions, & More

OpenAPI Specification v30.0.1

Copyright © 3001 the Linux Foundation

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Status of This Document

The source-of-truth for the specification is the GitHub markdown file referenced above.

Heading 1

Text for first chapter

Version 30.0.1

diff --git a/tests/md2html/md2html.test.js b/tests/md2html/md2html.test.js index d440022b4b..30ee446e5e 100644 --- a/tests/md2html/md2html.test.js +++ b/tests/md2html/md2html.test.js @@ -13,9 +13,9 @@ describe("v3.0 - Validate examples", async () => { const expected = readFileSync( folder + entry.name.replace(".md", ".html"), "utf8", - ).split(/\r\n|\n/); + ); const output = await md2html([entry.name], folder); - assert.deepStrictEqual(output.stdout.split("\n"), expected); + expect(output.stdout).to.equal(expected); }); }); }); From aa17cea7438a59f411d72b84d21e3ee5dc0a65d7 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Sun, 11 Aug 2024 14:00:18 +0200 Subject: [PATCH 10/10] Code blocks --- tests/md2html/fixtures/basic-new.html | 11 +++++++++++ tests/md2html/fixtures/basic-new.md | 13 +++++++++++++ 2 files changed, 24 insertions(+) diff --git a/tests/md2html/fixtures/basic-new.html b/tests/md2html/fixtures/basic-new.html index 5280441b47..b79429bbec 100644 --- a/tests/md2html/fixtures/basic-new.html +++ b/tests/md2html/fixtures/basic-new.html @@ -7,6 +7,17 @@

Text for first section

Heading 3

Text for first subsection

+

+{
+  "foo": true
+}
+
+

+text/plain
+
+

+no language
+
diff --git a/tests/md2html/fixtures/basic-new.md b/tests/md2html/fixtures/basic-new.md index 51b1569aca..2c29f56e1a 100644 --- a/tests/md2html/fixtures/basic-new.md +++ b/tests/md2html/fixtures/basic-new.md @@ -14,6 +14,19 @@ Text for first section Text for first subsection +```json +{ + "foo": true +} +``` + +```text +text/plain +``` + +``` +no language +``` Version | Date --------|-----------