mirror of
https://github.com/nodejs/node.git
synced 2024-11-24 12:10:08 +01:00
doc,tools: properly syntax highlight API ref docs
Prior to this commit, all <pre> tags were being highlighted as JavaScript. This has been corrected to syntax highlight all languages appearing in the API reference docs. This was accomplished by using highlight.js instead of SHJS for the frontend lib. * remove SHJS JavaScript code * add highlight.js bundle * fix script tags to reflect replacement * migrate CSS to use highlight.js classes * add appropriate documentation * ensure api_assets README.md stays interal Fixes: https://github.com/nodejs/node/issues/33363 PR-URL: https://github.com/nodejs/node/pull/33442 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org>
This commit is contained in:
Derek Lewis
Ruben Bridgewater
parent
9ad8b4d393
commit
dc6c93c03e
33
LICENSE
33
LICENSE
@ -1448,6 +1448,39 @@ The externally maintained libraries used by Node.js are:
|
||||
THE POSSIBILITY OF SUCH DAMAGE.
|
||||
"""
|
||||
|
||||
- highlight.js, located at doc/api_assets/highlight.pack.js, is licensed as follows:
|
||||
"""
|
||||
BSD 3-Clause License
|
||||
|
||||
Copyright (c) 2006, Ivan Sagalaev.
|
||||
All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
modification, are permitted provided that the following conditions are met:
|
||||
|
||||
* Redistributions of source code must retain the above copyright notice, this
|
||||
list of conditions and the following disclaimer.
|
||||
|
||||
* Redistributions in binary form must reproduce the above copyright notice,
|
||||
this list of conditions and the following disclaimer in the documentation
|
||||
and/or other materials provided with the distribution.
|
||||
|
||||
* Neither the name of the copyright holder nor the names of its
|
||||
contributors may be used to endorse or promote products derived from
|
||||
this software without specific prior written permission.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
||||
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||||
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||||
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
"""
|
||||
|
||||
- node-heapdump, located at src/heap_utils.cc, is licensed as follows:
|
||||
"""
|
||||
ISC License
|
||||
|
||||
2
Makefile
2
Makefile
@ -737,7 +737,7 @@ out/doc/api/assets:
|
||||
|
||||
# If it's not a source tarball, we need to copy assets from doc/api_assets
|
||||
out/doc/api/assets/%: doc/api_assets/% out/doc/api/assets
|
||||
@cp $< $@
|
||||
@cp $< $@ ; $(RM) out/doc/api/assets/README.md
|
||||
|
||||
|
||||
run-npm-ci = $(PWD)/$(NPM) ci
|
||||
|
||||
27
doc/api_assets/README.md
Normal file
27
doc/api_assets/README.md
Normal file
@ -0,0 +1,27 @@
|
||||
# API Reference Document Assets
|
||||
|
||||
## highlight.pack.js
|
||||
|
||||
_Generated by [highlightjs.org/download][] on 2020-05-16._
|
||||
|
||||
Grammars included in the custom bundle:
|
||||
|
||||
* Bash
|
||||
* C
|
||||
* C++
|
||||
* CoffeeScript
|
||||
* JavaScript
|
||||
* JSON
|
||||
* Markdown
|
||||
* Plaintext
|
||||
* Shell Session
|
||||
|
||||
## hljs.css
|
||||
|
||||
The syntax theme for code snippets in API reference documents.
|
||||
|
||||
## style.css
|
||||
|
||||
The main stylesheet for API reference documents.
|
||||
|
||||
[highlightjs.org/download]: https://highlightjs.org/download/
|
||||
6
doc/api_assets/highlight.pack.js
Normal file
6
doc/api_assets/highlight.pack.js
Normal file
File diff suppressed because one or more lines are too long
29
doc/api_assets/hljs.css
Normal file
29
doc/api_assets/hljs.css
Normal file
@ -0,0 +1,29 @@
|
||||
.hljs {
|
||||
font-weight: normal;
|
||||
font-style: normal;
|
||||
}
|
||||
|
||||
.hljs-symbol {
|
||||
color: #333;
|
||||
}
|
||||
|
||||
.hljs-keyword {
|
||||
color: #338;
|
||||
}
|
||||
|
||||
.hljs-string,
|
||||
.hljs-regexp,
|
||||
.hljs-number {
|
||||
color: #E54305;
|
||||
}
|
||||
|
||||
.hljs-doctag {
|
||||
color: #040404;
|
||||
}
|
||||
|
||||
.hljs-doctag .hljs-type,
|
||||
.hljs-doctag .hljs-variable,
|
||||
.hljs-comment {
|
||||
color: #666;
|
||||
font-weight: lighter;
|
||||
}
|
||||
@ -1,25 +0,0 @@
|
||||
.sh_sourceCode {
|
||||
font-weight: normal;
|
||||
font-style: normal;
|
||||
}
|
||||
|
||||
.sh_sourceCode .sh_symbol,
|
||||
.sh_sourceCode .sh_cbracket {
|
||||
color: #333;
|
||||
}
|
||||
|
||||
.sh_sourceCode .sh_keyword {
|
||||
color: #338;
|
||||
}
|
||||
|
||||
.sh_sourceCode .sh_string,
|
||||
.sh_sourceCode .sh_regexp,
|
||||
.sh_sourceCode .sh_number,
|
||||
.sh_sourceCode .sh_specialchar {
|
||||
color: #E54305;
|
||||
}
|
||||
|
||||
.sh_sourceCode .sh_comment {
|
||||
color: #666;
|
||||
font-weight: lighter;
|
||||
}
|
||||
1
doc/api_assets/sh_javascript.min.js
vendored
1
doc/api_assets/sh_javascript.min.js
vendored
@ -1 +0,0 @@
|
||||
if(!this.sh_languages){this.sh_languages={}}sh_languages.javascript=[[[/\/\/\//g,"sh_comment",1],[/\/\//g,"sh_comment",7],[/\/\*\*/g,"sh_comment",8],[/\/\*/g,"sh_comment",9],[/\b(?:abstract|break|case|catch|class|const|continue|debugger|default|delete|do|else|enum|export|extends|false|final|finally|for|function|goto|if|implements|in|instanceof|interface|native|new|null|private|protected|prototype|public|return|static|super|switch|synchronized|throw|throws|this|transient|true|try|typeof|var|volatile|while|with)\b/g,"sh_keyword",-1],[/(\+\+|--|\)|\])(\s*)(\/=?(?![*\/]))/g,["sh_symbol","sh_normal","sh_symbol"],-1],[/(0x[A-Fa-f0-9]+|(?:[\d]*\.)?[\d]+(?:[eE][+-]?[\d]+)?)(\s*)(\/(?![*\/]))/g,["sh_number","sh_normal","sh_symbol"],-1],[/([A-Za-z$_][A-Za-z0-9$_]*\s*)(\/=?(?![*\/]))/g,["sh_normal","sh_symbol"],-1],[/\/(?:\\.|[^*\\\/])(?:\\.|[^\\\/])*\/[gim]*/g,"sh_regexp",-1],[/\b[+-]?(?:(?:0x[A-Fa-f0-9]+)|(?:(?:[\d]*\.)?[\d]+(?:[eE][+-]?[\d]+)?))u?(?:(?:int(?:8|16|32|64))|L)?\b/g,"sh_number",-1],[/"/g,"sh_string",10],[/'/g,"sh_string",11],[/~|!|%|\^|\*|\(|\)|-|\+|=|\[|\]|\\|:|;|,|\.|\/|\?|&|<|>|\|/g,"sh_symbol",-1],[/\{|\}/g,"sh_cbracket",-1],[/\b(?:Math|Infinity|NaN|undefined|arguments)\b/g,"sh_predef_var",-1],[/\b(?:Array|Boolean|Date|Error|EvalError|Function|Number|Object|RangeError|ReferenceError|RegExp|String|SyntaxError|TypeError|URIError|decodeURI|decodeURIComponent|encodeURI|encodeURIComponent|eval|isFinite|isNaN|parseFloat|parseInt)\b/g,"sh_predef_func",-1],[/(?:[A-Za-z]|_)[A-Za-z0-9_]*(?=[ \t]*\()/g,"sh_function",-1]],[[/$/g,null,-2],[/(?:<?)[A-Za-z0-9_\.\/\-_~]+@[A-Za-z0-9_\.\/\-_~]+(?:>?)|(?:<?)[A-Za-z0-9_]+:\/\/[A-Za-z0-9_\.\/\-_~]+(?:>?)/g,"sh_url",-1],[/<\?xml/g,"sh_preproc",2,1],[/<!DOCTYPE/g,"sh_preproc",4,1],[/<!--/g,"sh_comment",5],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)/g,"sh_keyword",6,1],[/&(?:[A-Za-z0-9]+);/g,"sh_preproc",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*/g,"sh_keyword",6,1],[/@[A-Za-z]+/g,"sh_type",-1],[/(?:TODO|FIXME|BUG)(?:[:]?)/g,"sh_todo",-1]],[[/\?>/g,"sh_preproc",-2],[/([^=" \t>]+)([ \t]*)(=?)/g,["sh_type","sh_normal","sh_symbol"],-1],[/"/g,"sh_string",3]],[[/\\(?:\\|")/g,null,-1],[/"/g,"sh_string",-2]],[[/>/g,"sh_preproc",-2],[/([^=" \t>]+)([ \t]*)(=?)/g,["sh_type","sh_normal","sh_symbol"],-1],[/"/g,"sh_string",3]],[[/-->/g,"sh_comment",-2],[/<!--/g,"sh_comment",5]],[[/(?:\/)?>/g,"sh_keyword",-2],[/([^=" \t>]+)([ \t]*)(=?)/g,["sh_type","sh_normal","sh_symbol"],-1],[/"/g,"sh_string",3]],[[/$/g,null,-2]],[[/\*\//g,"sh_comment",-2],[/(?:<?)[A-Za-z0-9_\.\/\-_~]+@[A-Za-z0-9_\.\/\-_~]+(?:>?)|(?:<?)[A-Za-z0-9_]+:\/\/[A-Za-z0-9_\.\/\-_~]+(?:>?)/g,"sh_url",-1],[/<\?xml/g,"sh_preproc",2,1],[/<!DOCTYPE/g,"sh_preproc",4,1],[/<!--/g,"sh_comment",5],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)/g,"sh_keyword",6,1],[/&(?:[A-Za-z0-9]+);/g,"sh_preproc",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*/g,"sh_keyword",6,1],[/@[A-Za-z]+/g,"sh_type",-1],[/(?:TODO|FIXME|BUG)(?:[:]?)/g,"sh_todo",-1]],[[/\*\//g,"sh_comment",-2],[/(?:<?)[A-Za-z0-9_\.\/\-_~]+@[A-Za-z0-9_\.\/\-_~]+(?:>?)|(?:<?)[A-Za-z0-9_]+:\/\/[A-Za-z0-9_\.\/\-_~]+(?:>?)/g,"sh_url",-1],[/(?:TODO|FIXME|BUG)(?:[:]?)/g,"sh_todo",-1]],[[/"/g,"sh_string",-2],[/\\./g,"sh_specialchar",-1]],[[/'/g,"sh_string",-2],[/\\./g,"sh_specialchar",-1]]];
|
||||
@ -1,553 +0,0 @@
|
||||
/*
|
||||
SHJS - Syntax Highlighting in JavaScript
|
||||
Copyright (C) 2007, 2008 gnombat@users.sourceforge.net
|
||||
License: http://shjs.sourceforge.net/doc/gplv3.html
|
||||
*/
|
||||
|
||||
if (! this.sh_languages) {
|
||||
this.sh_languages = {};
|
||||
}
|
||||
var sh_requests = {};
|
||||
|
||||
function sh_isEmailAddress(url) {
|
||||
if (/^mailto:/.test(url)) {
|
||||
return false;
|
||||
}
|
||||
return url.indexOf('@') !== -1;
|
||||
}
|
||||
|
||||
function sh_setHref(tags, numTags, inputString) {
|
||||
var url = inputString.substring(tags[numTags - 2].pos, tags[numTags - 1].pos);
|
||||
if (url.length >= 2 && url.charAt(0) === '<' && url.charAt(url.length - 1) === '>') {
|
||||
url = url.substr(1, url.length - 2);
|
||||
}
|
||||
if (sh_isEmailAddress(url)) {
|
||||
url = 'mailto:' + url;
|
||||
}
|
||||
tags[numTags - 2].node.href = url;
|
||||
}
|
||||
|
||||
/*
|
||||
Konqueror has a bug where the regular expression /$/g will not match at the end
|
||||
of a line more than once:
|
||||
|
||||
var regex = /$/g;
|
||||
var match;
|
||||
|
||||
var line = '1234567890';
|
||||
regex.lastIndex = 10;
|
||||
match = regex.exec(line);
|
||||
|
||||
var line2 = 'abcde';
|
||||
regex.lastIndex = 5;
|
||||
match = regex.exec(line2); // fails
|
||||
*/
|
||||
function sh_konquerorExec(s) {
|
||||
var result = [''];
|
||||
result.index = s.length;
|
||||
result.input = s;
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
Highlights all elements containing source code in a text string. The return
|
||||
value is an array of objects, each representing an HTML start or end tag. Each
|
||||
object has a property named pos, which is an integer representing the text
|
||||
offset of the tag. Every start tag also has a property named node, which is the
|
||||
DOM element started by the tag. End tags do not have this property.
|
||||
@param inputString a text string
|
||||
@param language a language definition object
|
||||
@return an array of tag objects
|
||||
*/
|
||||
function sh_highlightString(inputString, language) {
|
||||
if (/Konqueror/.test(navigator.userAgent)) {
|
||||
if (! language.konquered) {
|
||||
for (var s = 0; s < language.length; s++) {
|
||||
for (var p = 0; p < language[s].length; p++) {
|
||||
var r = language[s][p][0];
|
||||
if (r.source === '$') {
|
||||
r.exec = sh_konquerorExec;
|
||||
}
|
||||
}
|
||||
}
|
||||
language.konquered = true;
|
||||
}
|
||||
}
|
||||
|
||||
var a = document.createElement('a');
|
||||
var span = document.createElement('span');
|
||||
|
||||
// the result
|
||||
var tags = [];
|
||||
var numTags = 0;
|
||||
|
||||
// each element is a pattern object from language
|
||||
var patternStack = [];
|
||||
|
||||
// the current position within inputString
|
||||
var pos = 0;
|
||||
|
||||
// the name of the current style, or null if there is no current style
|
||||
var currentStyle = null;
|
||||
|
||||
var output = function(s, style) {
|
||||
var length = s.length;
|
||||
// this is more than just an optimization - we don't want to output empty <span></span> elements
|
||||
if (length === 0) {
|
||||
return;
|
||||
}
|
||||
if (! style) {
|
||||
var stackLength = patternStack.length;
|
||||
if (stackLength !== 0) {
|
||||
var pattern = patternStack[stackLength - 1];
|
||||
// check whether this is a state or an environment
|
||||
if (! pattern[3]) {
|
||||
// it's not a state - it's an environment; use the style for this environment
|
||||
style = pattern[1];
|
||||
}
|
||||
}
|
||||
}
|
||||
if (currentStyle !== style) {
|
||||
if (currentStyle) {
|
||||
tags[numTags++] = {pos: pos};
|
||||
if (currentStyle === 'sh_url') {
|
||||
sh_setHref(tags, numTags, inputString);
|
||||
}
|
||||
}
|
||||
if (style) {
|
||||
var clone;
|
||||
if (style === 'sh_url') {
|
||||
clone = a.cloneNode(false);
|
||||
}
|
||||
else {
|
||||
clone = span.cloneNode(false);
|
||||
}
|
||||
clone.className = style;
|
||||
tags[numTags++] = {node: clone, pos: pos};
|
||||
}
|
||||
}
|
||||
pos += length;
|
||||
currentStyle = style;
|
||||
};
|
||||
|
||||
var endOfLinePattern = /\r\n|\r|\n/g;
|
||||
endOfLinePattern.lastIndex = 0;
|
||||
var inputStringLength = inputString.length;
|
||||
while (pos < inputStringLength) {
|
||||
var start = pos;
|
||||
var end;
|
||||
var startOfNextLine;
|
||||
var endOfLineMatch = endOfLinePattern.exec(inputString);
|
||||
if (endOfLineMatch === null) {
|
||||
end = inputStringLength;
|
||||
startOfNextLine = inputStringLength;
|
||||
}
|
||||
else {
|
||||
end = endOfLineMatch.index;
|
||||
startOfNextLine = endOfLinePattern.lastIndex;
|
||||
}
|
||||
|
||||
var line = inputString.substring(start, end);
|
||||
|
||||
var matchCache = [];
|
||||
for (;;) {
|
||||
var posWithinLine = pos - start;
|
||||
|
||||
var stateIndex;
|
||||
var stackLength = patternStack.length;
|
||||
if (stackLength === 0) {
|
||||
stateIndex = 0;
|
||||
}
|
||||
else {
|
||||
// get the next state
|
||||
stateIndex = patternStack[stackLength - 1][2];
|
||||
}
|
||||
|
||||
var state = language[stateIndex];
|
||||
var numPatterns = state.length;
|
||||
var mc = matchCache[stateIndex];
|
||||
if (! mc) {
|
||||
mc = matchCache[stateIndex] = [];
|
||||
}
|
||||
var bestMatch = null;
|
||||
var bestPatternIndex = -1;
|
||||
for (var i = 0; i < numPatterns; i++) {
|
||||
var match;
|
||||
if (i < mc.length && (mc[i] === null || posWithinLine <= mc[i].index)) {
|
||||
match = mc[i];
|
||||
}
|
||||
else {
|
||||
var regex = state[i][0];
|
||||
regex.lastIndex = posWithinLine;
|
||||
match = regex.exec(line);
|
||||
mc[i] = match;
|
||||
}
|
||||
if (match !== null && (bestMatch === null || match.index < bestMatch.index)) {
|
||||
bestMatch = match;
|
||||
bestPatternIndex = i;
|
||||
if (match.index === posWithinLine) {
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (bestMatch === null) {
|
||||
output(line.substring(posWithinLine), null);
|
||||
break;
|
||||
}
|
||||
else {
|
||||
// got a match
|
||||
if (bestMatch.index > posWithinLine) {
|
||||
output(line.substring(posWithinLine, bestMatch.index), null);
|
||||
}
|
||||
|
||||
var pattern = state[bestPatternIndex];
|
||||
|
||||
var newStyle = pattern[1];
|
||||
var matchedString;
|
||||
if (newStyle instanceof Array) {
|
||||
for (var subexpression = 0; subexpression < newStyle.length; subexpression++) {
|
||||
matchedString = bestMatch[subexpression + 1];
|
||||
output(matchedString, newStyle[subexpression]);
|
||||
}
|
||||
}
|
||||
else {
|
||||
matchedString = bestMatch[0];
|
||||
output(matchedString, newStyle);
|
||||
}
|
||||
|
||||
switch (pattern[2]) {
|
||||
case -1:
|
||||
// do nothing
|
||||
break;
|
||||
case -2:
|
||||
// exit
|
||||
patternStack.pop();
|
||||
break;
|
||||
case -3:
|
||||
// exitall
|
||||
patternStack.length = 0;
|
||||
break;
|
||||
default:
|
||||
// this was the start of a delimited pattern or a state/environment
|
||||
patternStack.push(pattern);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// end of the line
|
||||
if (currentStyle) {
|
||||
tags[numTags++] = {pos: pos};
|
||||
if (currentStyle === 'sh_url') {
|
||||
sh_setHref(tags, numTags, inputString);
|
||||
}
|
||||
currentStyle = null;
|
||||
}
|
||||
pos = startOfNextLine;
|
||||
}
|
||||
|
||||
return tags;
|
||||
}
|
||||
|
||||
////////////////////////////////////////////////////////////////////////////////
|
||||
// DOM-dependent functions
|
||||
|
||||
function sh_getClasses(element) {
|
||||
var result = [];
|
||||
var htmlClass = element.className;
|
||||
if (htmlClass && htmlClass.length > 0) {
|
||||
var htmlClasses = htmlClass.split(' ');
|
||||
for (var i = 0; i < htmlClasses.length; i++) {
|
||||
if (htmlClasses[i].length > 0) {
|
||||
result.push(htmlClasses[i]);
|
||||
}
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
function sh_addClass(element, name) {
|
||||
var htmlClasses = sh_getClasses(element);
|
||||
for (var i = 0; i < htmlClasses.length; i++) {
|
||||
if (name.toLowerCase() === htmlClasses[i].toLowerCase()) {
|
||||
return;
|
||||
}
|
||||
}
|
||||
htmlClasses.push(name);
|
||||
element.className = htmlClasses.join(' ');
|
||||
}
|
||||
|
||||
/**
|
||||
Extracts the tags from an HTML DOM NodeList.
|
||||
@param nodeList a DOM NodeList
|
||||
@param result an object with text, tags and pos properties
|
||||
*/
|
||||
function sh_extractTagsFromNodeList(nodeList, result) {
|
||||
var length = nodeList.length;
|
||||
for (var i = 0; i < length; i++) {
|
||||
var node = nodeList.item(i);
|
||||
switch (node.nodeType) {
|
||||
case 1:
|
||||
if (node.nodeName.toLowerCase() === 'br') {
|
||||
var terminator;
|
||||
if (/MSIE/.test(navigator.userAgent)) {
|
||||
terminator = '\r';
|
||||
}
|
||||
else {
|
||||
terminator = '\n';
|
||||
}
|
||||
result.text.push(terminator);
|
||||
result.pos++;
|
||||
}
|
||||
else {
|
||||
result.tags.push({node: node.cloneNode(false), pos: result.pos});
|
||||
sh_extractTagsFromNodeList(node.childNodes, result);
|
||||
result.tags.push({pos: result.pos});
|
||||
}
|
||||
break;
|
||||
case 3:
|
||||
case 4:
|
||||
result.text.push(node.data);
|
||||
result.pos += node.length;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
Extracts the tags from the text of an HTML element. The extracted tags will be
|
||||
returned as an array of tag objects. See sh_highlightString for the format of
|
||||
the tag objects.
|
||||
@param element a DOM element
|
||||
@param tags an empty array; the extracted tag objects will be returned in it
|
||||
@return the text of the element
|
||||
@see sh_highlightString
|
||||
*/
|
||||
function sh_extractTags(element, tags) {
|
||||
var result = {};
|
||||
result.text = [];
|
||||
result.tags = tags;
|
||||
result.pos = 0;
|
||||
sh_extractTagsFromNodeList(element.childNodes, result);
|
||||
return result.text.join('');
|
||||
}
|
||||
|
||||
/**
|
||||
Merges the original tags from an element with the tags produced by highlighting.
|
||||
@param originalTags an array containing the original tags
|
||||
@param highlightTags an array containing the highlighting tags - these must not overlap
|
||||
@result an array containing the merged tags
|
||||
*/
|
||||
function sh_mergeTags(originalTags, highlightTags) {
|
||||
var numOriginalTags = originalTags.length;
|
||||
if (numOriginalTags === 0) {
|
||||
return highlightTags;
|
||||
}
|
||||
|
||||
var numHighlightTags = highlightTags.length;
|
||||
if (numHighlightTags === 0) {
|
||||
return originalTags;
|
||||
}
|
||||
|
||||
var result = [];
|
||||
var originalIndex = 0;
|
||||
var highlightIndex = 0;
|
||||
|
||||
while (originalIndex < numOriginalTags && highlightIndex < numHighlightTags) {
|
||||
var originalTag = originalTags[originalIndex];
|
||||
var highlightTag = highlightTags[highlightIndex];
|
||||
|
||||
if (originalTag.pos <= highlightTag.pos) {
|
||||
result.push(originalTag);
|
||||
originalIndex++;
|
||||
}
|
||||
else {
|
||||
result.push(highlightTag);
|
||||
if (highlightTags[highlightIndex + 1].pos <= originalTag.pos) {
|
||||
highlightIndex++;
|
||||
result.push(highlightTags[highlightIndex]);
|
||||
highlightIndex++;
|
||||
}
|
||||
else {
|
||||
// new end tag
|
||||
result.push({pos: originalTag.pos});
|
||||
|
||||
// new start tag
|
||||
highlightTags[highlightIndex] = {node: highlightTag.node.cloneNode(false), pos: originalTag.pos};
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
while (originalIndex < numOriginalTags) {
|
||||
result.push(originalTags[originalIndex]);
|
||||
originalIndex++;
|
||||
}
|
||||
|
||||
while (highlightIndex < numHighlightTags) {
|
||||
result.push(highlightTags[highlightIndex]);
|
||||
highlightIndex++;
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
Inserts tags into text.
|
||||
@param tags an array of tag objects
|
||||
@param text a string representing the text
|
||||
@return a DOM DocumentFragment representing the resulting HTML
|
||||
*/
|
||||
function sh_insertTags(tags, text) {
|
||||
var doc = document;
|
||||
|
||||
var result = document.createDocumentFragment();
|
||||
var tagIndex = 0;
|
||||
var numTags = tags.length;
|
||||
var textPos = 0;
|
||||
var textLength = text.length;
|
||||
var currentNode = result;
|
||||
|
||||
// output one tag or text node every iteration
|
||||
while (textPos < textLength || tagIndex < numTags) {
|
||||
var tag;
|
||||
var tagPos;
|
||||
if (tagIndex < numTags) {
|
||||
tag = tags[tagIndex];
|
||||
tagPos = tag.pos;
|
||||
}
|
||||
else {
|
||||
tagPos = textLength;
|
||||
}
|
||||
|
||||
if (tagPos <= textPos) {
|
||||
// output the tag
|
||||
if (tag.node) {
|
||||
// start tag
|
||||
var newNode = tag.node;
|
||||
currentNode.appendChild(newNode);
|
||||
currentNode = newNode;
|
||||
}
|
||||
else {
|
||||
// end tag
|
||||
currentNode = currentNode.parentNode;
|
||||
}
|
||||
tagIndex++;
|
||||
}
|
||||
else {
|
||||
// output text
|
||||
currentNode.appendChild(doc.createTextNode(text.substring(textPos, tagPos)));
|
||||
textPos = tagPos;
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
Highlights an element containing source code. Upon completion of this function,
|
||||
the element will have been placed in the "sh_sourceCode" class.
|
||||
@param element a DOM <pre> element containing the source code to be highlighted
|
||||
@param language a language definition object
|
||||
*/
|
||||
function sh_highlightElement(element, language) {
|
||||
sh_addClass(element, 'sh_sourceCode');
|
||||
var originalTags = [];
|
||||
var inputString = sh_extractTags(element, originalTags);
|
||||
var highlightTags = sh_highlightString(inputString, language);
|
||||
var tags = sh_mergeTags(originalTags, highlightTags);
|
||||
var documentFragment = sh_insertTags(tags, inputString);
|
||||
while (element.hasChildNodes()) {
|
||||
element.removeChild(element.firstChild);
|
||||
}
|
||||
element.appendChild(documentFragment);
|
||||
}
|
||||
|
||||
function sh_getXMLHttpRequest() {
|
||||
if (window.ActiveXObject) {
|
||||
return new ActiveXObject('Msxml2.XMLHTTP');
|
||||
}
|
||||
else if (window.XMLHttpRequest) {
|
||||
return new XMLHttpRequest();
|
||||
}
|
||||
throw 'No XMLHttpRequest implementation available';
|
||||
}
|
||||
|
||||
function sh_load(language, element, prefix, suffix) {
|
||||
if (language in sh_requests) {
|
||||
sh_requests[language].push(element);
|
||||
return;
|
||||
}
|
||||
sh_requests[language] = [element];
|
||||
var request = sh_getXMLHttpRequest();
|
||||
var url = prefix + 'sh_' + language + suffix;
|
||||
request.open('GET', url, true);
|
||||
request.onreadystatechange = function () {
|
||||
if (request.readyState === 4) {
|
||||
try {
|
||||
if (! request.status || request.status === 200) {
|
||||
eval(request.responseText);
|
||||
var elements = sh_requests[language];
|
||||
for (var i = 0; i < elements.length; i++) {
|
||||
sh_highlightElement(elements[i], sh_languages[language]);
|
||||
}
|
||||
}
|
||||
else {
|
||||
throw 'HTTP error: status ' + request.status;
|
||||
}
|
||||
}
|
||||
finally {
|
||||
request = null;
|
||||
}
|
||||
}
|
||||
};
|
||||
request.send(null);
|
||||
}
|
||||
|
||||
/**
|
||||
Highlights all elements containing source code on the current page. Elements
|
||||
containing source code must be "pre" elements with a "class" attribute of
|
||||
"sh_LANGUAGE", where LANGUAGE is a valid language identifier; e.g., "sh_java"
|
||||
identifies the element as containing "java" language source code.
|
||||
*/
|
||||
function highlight(prefix, suffix, tag) {
|
||||
var nodeList = document.getElementsByTagName(tag);
|
||||
for (var i = 0; i < nodeList.length; i++) {
|
||||
var element = nodeList.item(i);
|
||||
var htmlClasses = sh_getClasses(element);
|
||||
var highlighted = false;
|
||||
var donthighlight = false;
|
||||
for (var j = 0; j < htmlClasses.length; j++) {
|
||||
var htmlClass = htmlClasses[j].toLowerCase();
|
||||
if (htmlClass === 'sh_none') {
|
||||
donthighlight = true
|
||||
continue;
|
||||
}
|
||||
if (htmlClass.substr(0, 3) === 'sh_') {
|
||||
var language = htmlClass.substring(3);
|
||||
if (language in sh_languages) {
|
||||
sh_highlightElement(element, sh_languages[language]);
|
||||
highlighted = true;
|
||||
}
|
||||
else if (typeof(prefix) === 'string' && typeof(suffix) === 'string') {
|
||||
sh_load(language, element, prefix, suffix);
|
||||
}
|
||||
else {
|
||||
throw 'Found <' + tag + '> element with class="' + htmlClass + '", but no such language exists';
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (highlighted === false && donthighlight == false) {
|
||||
sh_highlightElement(element, sh_languages["javascript"]);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
|
||||
function sh_highlightDocument(prefix, suffix) {
|
||||
highlight(prefix, suffix, 'tt');
|
||||
highlight(prefix, suffix, 'code');
|
||||
highlight(prefix, suffix, 'pre');
|
||||
}
|
||||
@ -30,7 +30,7 @@
|
||||
* When documenting APIs, update the YAML comment associated with the API as
|
||||
appropriate. This is especially true when introducing or deprecating an API.
|
||||
* For code blocks:
|
||||
* Use language aware fences. ("```js")
|
||||
* Use [language aware fences][]. (<code>```js</code>)
|
||||
* Code need not be complete. Treat code blocks as an illustration or aid to
|
||||
your point, not as complete running programs. If a complete running program
|
||||
is necessary, include it as an asset in `assets/code-examples` and link to
|
||||
@ -65,6 +65,7 @@
|
||||
|
||||
See also API documentation structure overview in [doctools README][].
|
||||
|
||||
[language aware fences]: https://github.com/highlightjs/highlight.js/blob/master/SUPPORTED_LANGUAGES.md
|
||||
[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
|
||||
[serial commas]: https://en.wikipedia.org/wiki/Serial_comma
|
||||
[plugin]: https://editorconfig.org/#download
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
<title>__SECTION__ | Node.js __VERSION__ Documentation</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback">
|
||||
<link rel="stylesheet" href="assets/style.css">
|
||||
<link rel="stylesheet" href="assets/sh.css">
|
||||
<link rel="stylesheet" href="assets/hljs.css">
|
||||
<link rel="canonical" href="https://nodejs.org/api/__FILENAME__.html">
|
||||
</head>
|
||||
<body class="alt apidoc" id="api-section-__FILENAME__">
|
||||
@ -51,8 +51,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<script src="assets/sh_main.js"></script>
|
||||
<script src="assets/sh_javascript.min.js"></script>
|
||||
<script>highlight(undefined, undefined, 'pre');</script>
|
||||
<script src="assets/highlight.pack.js"></script>
|
||||
<script>document.addEventListener('DOMContentLoaded', () => { hljs.initHighlightingOnLoad(); });</script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -102,6 +102,9 @@ addlicense "brotli" "deps/brotli" "$(cat ${rootdir}/deps/brotli/LICENSE)"
|
||||
|
||||
addlicense "HdrHistogram" "deps/histogram" "$(cat ${rootdir}/deps/histogram/LICENSE.txt)"
|
||||
|
||||
addlicense "highlight.js" "doc/api_assets/highlight.pack.js" \
|
||||
"$(curl -sL https://raw.githubusercontent.com/highlightjs/highlight.js/63f367c46f2eeb6f9b7a3545e325eeeb917f9942/LICENSE)"
|
||||
|
||||
addlicense "node-heapdump" "src/heap_utils.cc" \
|
||||
"$(curl -sL https://raw.githubusercontent.com/bnoordhuis/node-heapdump/0ca52441e46241ffbea56a389e2856ec01c48c97/LICENSE)"
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user