Skip to content

Commit

Permalink
doc: link to man pages
Browse files Browse the repository at this point in the history
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: #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>
  • Loading branch information
dcposch authored and Myles Borins committed Mar 1, 2016
1 parent 29951cf commit a9035b5
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 0 deletions.
16 changes: 16 additions & 0 deletions doc/api/documentation.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 32 additions & 0 deletions tools/doc/html.js
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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) {
Expand Down

0 comments on commit a9035b5

Please sign in to comment.