doc: link to man pages

doc/api/documentation.markdown

@@ -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).

tools/doc/html.js

@@ -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) {