1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: link to man pages

Browse Source 
This changes the doc generator to automatically link references such as
`open(2)` to a man page on man7.org or freebsd.org

PR-URL: https://github.com/nodejs/node/pull/5073
Reviewed-By: Ben Noorhduis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
This commit is contained in:
dcposch@dcpos.ch 2016-02-04 04:11:17 -08:00 committed by Roman Reiss
parent 9894c026f5
commit 4e77a7ce29
2 changed files with 48 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/api/documentation.markdown
View File

@ -66,3 +66,19 @@ Every HTML file in the markdown has a corresponding JSON file with the
same data.
This feature was added in Node.js v0.6.12. It is experimental.
## Syscalls and man pages
System calls like open(2) and read(2) define the interface between user programs
and the underlying operating system. Node functions which simply wrap a syscall,
like `fs.open()`, will document that. The docs link to the corresponding man
pages (short for manual pages) which describe how the syscalls work.
**Caveat:** some syscalls, like lchown(2), are BSD-specific. That means, for
example, that `fs.lchown()` only works on Mac OS X and other BSD-derived systems,
and is not available on Linux.
Most Unix syscalls have Windows equivalents, but behavior may differ on Windows
relative to Linux and OS X. For an example of the subtle ways in which it's
sometimes impossible to replace Unix syscall semantics on Windows, see [Node
issue 4760](https://github.com/nodejs/node/issues/4760).

32
tools/doc/html.js
View File

@ -77,6 +77,7 @@ function render(lexed, filename, template, cb) {
filename = path.basename(filename, '.markdown');
parseText(lexed);
lexed = parseLists(lexed);
// generate the table of contents.
@ -105,6 +106,15 @@ function render(lexed, filename, template, cb) {
});
}
// handle general body-text replacements
// for example, link man page references to the actual page
function parseText(lexed) {
lexed.forEach(function(tok) {
if (tok.text) {
tok.text = linkManPages(tok.text);
}
});
}
// just update the list item text in-place.
// lists that come right after a heading are what we're after.
@ -167,11 +177,33 @@ function parseLists(input) {
}
// Syscalls which appear in the docs, but which only exist in BSD / OSX
var BSD_ONLY_SYSCALLS = new Set(['lchmod']);
// Handle references to man pages, eg "open(2)" or "lchmod(2)"
// Returns modified text, with such refs replace with HTML links, for example
// '<a href="http://man7.org/linux/man-pages/man2/open.2.html">open(2)</a>'
function linkManPages(text) {
return text.replace(/ ([a-z]+)\((\d)\)/gm, function(match, name, number) {
// name consists of lowercase letters, number is a single digit
var displayAs = name + '(' + number + ')';
if (BSD_ONLY_SYSCALLS.has(name)) {
return ' <a href="https://www.freebsd.org/cgi/man.cgi?query=' + name +
'&sektion=' + number + '">' + displayAs + '</a>';
} else {
return ' <a href="http://man7.org/linux/man-pages/man' + number +
'/' + name + '.' + number + '.html">' + displayAs + '</a>';
}
});
}
function parseListItem(text) {
var parts = text.split('`');
var i;
var typeMatches;
// Handle types, for example the source Markdown might say
// "This argument should be a {Number} or {String}"
for (i = 0; i < parts.length; i += 2) {
typeMatches = parts[i].match(/\{([^\}]+)\}/g);
if (typeMatches) {