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).
filename = path.basename(filename, '.markdown');
+ parseText(lexed);
lexed = parseLists(lexed);
// generate the table of contents.
});
}
+// 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.
}
+// 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) {