Skip to content

Commit 7e99e14

Browse files
handrewshandrews
authored
Merge pull request #3978 from ralfhandl/normative-and-informative-references
Complete normative and informative references
2 parents bcdbb1a + b0574cd commit 7e99e14

File tree

1 file changed

+85
-32
lines changed

1 file changed

+85
-32
lines changed

‎scripts/md2html/md2html.js

Lines changed: 85 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,57 @@ function preface(title,options) {
8585
},
8686
],
8787
},
88-
]
88+
],
89+
localBiblio: {
90+
"OpenAPI-Learn": {
91+
title: "OpenAPI - Getting started, and the specification explained",
92+
href: "https://learn.openapis.org/",
93+
publisher: "OpenAPI Initiative"
94+
},
95+
"OpenAPI-Registry": {
96+
title: "OpenAPI Initiative Registry",
97+
href: "https://spec.openapis.org/registry/index.html",
98+
publisher: "OpenAPI Initiative"
99+
},
100+
//TODO: remove localBiblio once Specref PRs https://github.com/tobie/specref/pulls/ralfhandl are merged
101+
"JSON-Schema-Validation-04": {
102+
authors: [ "Kris Zyp", "Francis Galiegue", "Gary Court" ],
103+
href: "https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00",
104+
publisher: "Internet Engineering Task Force (IETF)",
105+
status: "Internet-Draft",
106+
title: "JSON Schema: interactive and non interactive validation. Draft 4",
107+
date: "1 February 2013"
108+
},
109+
"JSON-Schema-05": {
110+
authors: [ "Austin Wright" ],
111+
href: "https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00",
112+
publisher: "Internet Engineering Task Force (IETF)",
113+
status: "Internet-Draft",
114+
title: "JSON Schema: A Media Type for Describing JSON Documents. Draft 5",
115+
date: "13 October 2016"
116+
},
117+
"JSON-Schema-Validation-05": {
118+
authors: [ "Austin Wright", "G. Luff" ],
119+
href: "https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00",
120+
publisher: "Internet Engineering Task Force (IETF)",
121+
status: "Internet-Draft",
122+
title: "JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5",
123+
date: "13 October 2016"
124+
},
125+
"JSON-Schema-Validation-2020-12": {
126+
authors: [ "Austin Wright", "Henry Andrews", "Ben Hutton" ],
127+
href: "https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00",
128+
publisher: "Internet Engineering Task Force (IETF)",
129+
status: "Internet-Draft",
130+
title: "JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 2020-12",
131+
date: "8 December 2020"
132+
},
133+
"SPDX": {
134+
href: "https://spdx.org/licenses/",
135+
title: "SPDX License List",
136+
publisher: "Linux Foundation"
137+
}
138+
}
89139
};
90140

91141
let preface = `<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>${md.utils.escapeHtml(title)}</title>`;
@@ -115,6 +165,7 @@ function preface(title,options) {
115165
preface += 'table tr:nth-child(2n) { background-color: #f6f8fa; }';
116166
preface += 'pre { background-color: #f6f8fa !important; }';
117167
preface += 'code { color: #c83500 } th code { color: inherit }';
168+
preface += 'a.bibref { text-decoration: underline;}';
118169
preface += fs.readFileSync(path.resolve(__dirname,'gist.css'),'utf8').split('\n').join(' ');
119170
preface += '</style>';
120171
preface += `<h1 id="title">${title.split('|')[0]}</h1>`;
@@ -269,46 +320,52 @@ for (let l in lines) {
269320
line = line.replace('RFC [','[RFC');
270321
line = line.replace('[Authorization header as defined in ','Authorization header as defined in [');
271322
line = line.replace('[JSON Pointer]','JSON Pointer [RFC6901]'); // only in 2.0.md
323+
line = line.replace('[media type range](https://tools.ietf.org/html/rfc7231#appendix-D) ','media type range, see [RFC7231](https://tools.ietf.org/html/rfc7231#appendix-D), ');
272324

273-
//TODO: more "hidden" RFC references in older specs, for example
274-
// [media type range](https://tools.ietf.org/html/rfc7231#appendix-D)
275-
// [ABNF](https://tools.ietf.org/html/rfc5234)
276-
277-
//TODO: unconventional references to RFCs in 3.0.4 and 3.1.1, for example
278-
// [RFC3986 §5.1.2 – 5.1.4](https://tools.ietf.org/html/rfc3986#section-5.1.2)
279-
// RFC6570 [mentions](https://www.rfc-editor.org/rfc/rfc6570.html#section-2.4.2)
280-
// [are not](https://datatracker.ietf.org/doc/html/rfc3986#appendix-A)
281-
// [special behavior](https://www.rfc-editor.org/rfc/rfc1866#section-8.2.1)
282-
// [RFC6570 considers to be _undefined_](https://datatracker.ietf.org/doc/html/rfc6570#section-2.3)
283-
284-
if (line.indexOf('[RFC')>=0) {
285-
// also detect [RFC4648 §3.2] etc. in 3.0.4.md and 3.1.1.md
286-
line = line.replace(/\[RFC ?([0-9]{1,5})( §[0-9 .-]+)?\]/g,function(match,group1){
287-
// console.warn('Fixing RFC reference',match,group1);
288-
return '[[RFC'+group1+']]';
289-
});
290-
}
291-
292-
//TODO: non-link mentions of RFCs in 3.0.4 and 3.1.1, for example
293-
// RFC3986's definition of [reserved](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2)
325+
line = line.replace(/\[RFC ?([0-9]{1,5})\]\(/g,'[[RFC$1]](');
294326

295327
// harmonize RFC URLs
296-
line = line.replace('http://www.ietf.org/rfc/rfc2119.txt','https://tools.ietf.org/html/rfc2119'); // only in 2.0.md
328+
//TODO: harmonize to https://www.rfc-editor.org/rfc/rfc*
329+
line = line.replaceAll('](http://','](https://');
330+
line = line.replace('https://www.ietf.org/rfc/rfc2119.txt','https://tools.ietf.org/html/rfc2119'); // only in 2.0.md
297331
line = line.replace(/https:\/\/www.rfc-editor.org\/rfc\/rfc([0-9]{1,5})(\.html)?/g,'https://tools.ietf.org/html/rfc$1');
298-
line = line.replaceAll('https://datatracker.ietf.org/doc/html/rfc','https://tools.ietf.org/html/rfc');
299-
line = line.replaceAll('http://tools.ietf.org','https://tools.ietf.org');
332+
line = line.replaceAll('https://datatracker.ietf.org/doc/html/','https://tools.ietf.org/html/');
300333

301-
// handle url fragments in RFC links and construct section titles links as well as RFC links
334+
// handle url fragments in RFC links and construct section links as well as RFC links
302335
line = line.replace(/\]\]\(https:\/\/tools.ietf.org\/html\/rfc([0-9]{1,5})\/?(\#[^)]*)?\)/g, function(match, rfcNumber, fragment) {
303336
if (fragment) {
304337
// Extract section title from the fragment
305338
let sectionTitle = fragment.replace('#', '').replace(/-/g, ' ');
306339
sectionTitle = sectionTitle.charAt(0).toUpperCase() + sectionTitle.slice(1); // Capitalize the first letter
340+
//TODO: section links to https://www.rfc-editor.org/rfc/rfc* for newer RFCs (>= 8700)
307341
return `]] [${sectionTitle}](https://datatracker.ietf.org/doc/html/rfc${rfcNumber}${fragment})`;
308342
} else {
309343
return ']]';
310344
}
311345
});
346+
347+
// non-RFC references
348+
line = line.replace('[ABNF](https://tools.ietf.org/html/rfc5234)','[[ABNF]]');
349+
line = line.replace('[CommonMark 0.27](https://spec.commonmark.org/0.27/)','[[CommonMark-0.27]]');
350+
line = line.replace('[CommonMark syntax](https://spec.commonmark.org/)','[[CommonMark]] syntax');
351+
line = line.replace('CommonMark markdown formatting','[[CommonMark]] markdown formatting');
352+
line = line.replace('consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4)','consult [[HTML401]] [Section 17.13.4](http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4)');
353+
line = line.replace('[IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml)','[[IANA-HTTP-STATUS-CODES|IANA Status Code Registry]]');
354+
line = line.replace('[IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml)','[[IANA-HTTP-AUTHSCHEMES]]');
355+
line = line.replace('[JSON Schema Specification Draft 4](https://json-schema.org/)','[[JSON-Schema-04|JSON Schema Specification Draft 4]]');
356+
line = line.replace('[JSON Schema Core](https://tools.ietf.org/html/draft-zyp-json-schema-04)','[[JSON-Schema-04|JSON Schema Core]]');
357+
line = line.replace('[JSON Schema Validation](https://tools.ietf.org/html/draft-fge-json-schema-validation-00)','[[JSON-Schema-Validation-04|JSON Schema Validation]]');
358+
line = line.replace('[JSON Schema Specification Wright Draft 00](https://json-schema.org/)','[[JSON-Schema-05|JSON Schema Specification Wright Draft 00]]');
359+
line = line.replace('[JSON Schema Core](https://tools.ietf.org/html/draft-wright-json-schema-00)','[[JSON-Schema-05|JSON Schema Core]]');
360+
line = line.replace('[JSON Schema Validation](https://tools.ietf.org/html/draft-wright-json-schema-validation-00)','[[JSON-Schema-Validation-05|JSON Schema Validation]]');
361+
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]]');
362+
line = line.replace('[JSON Schema Core](https://tools.ietf.org/html/draft-bhutton-json-schema-00)','[[JSON-Schema-2020-12|JSON Schema Core]]');
363+
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]]');
364+
line = line.replace('[SPDX](https://spdx.org/licenses/)','[[SPDX]]');
365+
line = line.replace('[XML namespaces](https://www.w3.org/TR/xml-names11/)','[[xml-names11|XML namespaces]]');
366+
line = line.replace('JSON standards. YAML,','[[RFC7159|JSON]] standards. [[YAML|YAML]],'); // 2.0.md only
367+
line = line.replace('JSON or YAML format.','[[RFC7159|JSON]] or [[YAML|YAML]] format.');
368+
line = line.replace(/YAML version \[1\.2\]\(https:\/\/(www\.)?yaml\.org\/spec\/1\.2\/spec\.html\)/,'[[YAML|YAML version 1.2]]');
312369
}
313370

314371
if (!inCodeBlock && line.indexOf('](../') >= 0) {
@@ -325,8 +382,6 @@ for (let l in lines) {
325382
let delta = heading-prevHeading;
326383
if (delta>1) console.warn(delta,line);
327384
if (delta>0) delta = 1;
328-
//if (delta<0) delta = -1;
329-
// if (Math.abs(delta)>1) console.warn(delta,line);
330385
let prefix = '';
331386
let newSection = '<section>';
332387
if (line.includes('## Version ')) {
@@ -358,8 +413,6 @@ for (let l in lines) {
358413

359414
s = preface(`OpenAPI Specification v${argv.subtitle} | Introduction, Definitions, & More`,argv)+'\n\n'+lines.join('\n');
360415
let out = md.render(s);
361-
out = out.replace(/\[([RGB])\]/g,function(match,group1){
362-
console.warn('Fixing',match,group1);
363-
return '&#91;'+group1+'&#93;';
364-
});
416+
out = out.replace(/\[([RGB])\]/g,'&#91;$1&#93;');
417+
out = out.replace('[[IANA-HTTP-AUTHSCHEMES]]','[[IANA-HTTP-AUTHSCHEMES|IANA Authentication Scheme registry]]');
365418
console.log(out);

0 commit comments

Comments
 (0)