docs: clarify man(N) references

[SetTrend]

Reading the documentation I noticed a fair number of strange looking references:

It looks as if these are supposed to be hyperlinks. But instead they are being displayed as only some name with a confusing number.

[r-52]

Some docs mention these functions like e.g. ftruncate(2) as a reference how they are implemented.

[Fishrock123]

These refer to man 2 link, etc. That is, the Unix manual page of the specified sort (2)(The C/C++ actual functions).

These have been left like this because they very by platform slightly. However, it is confusing and we should link to some online reference, or even material explaining what they are.

This has come up in the past but I'm not sure there is an issue for it.

[SetTrend]

Ah, I see. Thanks for clarifying!

Yes, to me as a Windows programmer these look rather alien.

[benjamingr]

Yes, I agree we need more documentation on fs. It's hard for people without a unix background to understand.

I think we should add a usage example for each one and link to the pages on http://linux.die.net/ for the references.

I can work on the PR over the weekend if that sounds reasonable to you @Fishrock123 .

[Fishrock123]

I think @ashleygwilliams has a tool for this? I mentioned it to her a while back. The trick would be putting it into our markdown-a-majig.

[sam-github]

The other problem with linking to linux man pages, is they only apply a bit if you run node on other unixen, and only a vague outline of what the Windows equivalent is. Personally, I prefer linking them ALL to a single page, that describes how to do man 2 open (or whatever) on your OS (and how to install the man pages for OS X), but I've no time to do the work, so anything that helps a bit would be good.

Or we could just link to https://en.wikipedia.org/wiki/Advanced_Programming_in_the_Unix_Environment

[SetTrend]

On Windows the relevant OS API functions are called entirely different.

I tend to believe that references to a particular operating system's API or API help are no appropriate way of describing functionality if Node is supposed to be targeted to other operating systems, too.

[dcposch]

Think I found all of them:

$ grep ' [a-z]\+([0-9])' doc/ -R
doc/api/fs.markdown:Asynchronous chmod(2). No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous chmod(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous chown(2). No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous chown(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous close(2).  No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous close(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous fchmod(2). No arguments other than a possible exception
doc/api/fs.markdown:Synchronous fchmod(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous fchown(2). No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous fchown(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where
doc/api/fs.markdown:Synchronous fstat(2). Returns an instance of `fs.Stats`.
doc/api/fs.markdown:Asynchronous fsync(2). No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous fsync(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous ftruncate(2). No arguments other than a possible exception are
doc/api/fs.markdown:Synchronous ftruncate(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous lchmod(2). No arguments other than a possible exception
doc/api/fs.markdown:Synchronous lchmod(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous lchown(2). No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous lchown(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous link(2). No arguments other than a possible exception are given to
doc/api/fs.markdown:Synchronous link(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where
doc/api/fs.markdown:Synchronous lstat(2). Returns an instance of `fs.Stats`.
doc/api/fs.markdown:Asynchronous mkdir(2). No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous mkdir(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous file open. See open(2). `flags` can be:
doc/api/fs.markdown:The exclusive flag `'x'` (`O_EXCL` flag in open(2)) ensures that `path` is newly
doc/api/fs.markdown:`flags` can also be a number as documented by open(2); commonly used constants
doc/api/fs.markdown:Asynchronous readdir(3).  Reads the contents of a directory.
doc/api/fs.markdown:Synchronous readdir(3). Returns an array of filenames excluding `'.'` and
doc/api/fs.markdown:Asynchronous readlink(2). The callback gets two arguments `(err,
doc/api/fs.markdown:Synchronous readlink(2). Returns the symbolic link's string value.
doc/api/fs.markdown:Asynchronous realpath(2). The `callback` gets two arguments `(err,
doc/api/fs.markdown:Synchronous realpath(2). Returns the resolved path. `cache` is an
doc/api/fs.markdown:Asynchronous rename(2). No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous rename(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous rmdir(2). No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous rmdir(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
doc/api/fs.markdown:Synchronous stat(2). Returns an instance of [`fs.Stats`][].
doc/api/fs.markdown:Asynchronous symlink(2). No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous symlink(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous truncate(2). No arguments other than a possible exception are
doc/api/fs.markdown:Synchronous truncate(2). Returns `undefined`.
doc/api/fs.markdown:Asynchronous unlink(2). No arguments other than a possible exception are given
doc/api/fs.markdown:Synchronous unlink(2). Returns `undefined`.
doc/api/fs.markdown:at the current position. See pwrite(2).
doc/api/fs.markdown:the current position. See pwrite(2).
doc/api/cluster.markdown:  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
doc/api/cluster.markdown:  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
doc/api/modules.markdown:var mySquare = square(2);
doc/api/child_process.markdown:  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
doc/api/child_process.markdown:  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
doc/api/child_process.markdown:  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
doc/api/child_process.markdown:  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
doc/api/child_process.markdown:  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
doc/api/child_process.markdown:  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
doc/api/child_process.markdown:  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
doc/api/child_process.markdown:  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
doc/api/child_process.markdown:  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
doc/api/child_process.markdown:  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
doc/api/child_process.markdown:  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
doc/api/child_process.markdown:  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
doc/api/child_process.markdown:  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
doc/api/child_process.markdown:  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
doc/api/process.markdown:Emitted when the processes receives a signal. See sigaction(2) for a list of
doc/api/process.markdown:  platforms under various similar conditions, see signal(7). It can have a
doc/api/process.markdown:An object containing the user environment. See environ(7).
doc/api/process.markdown:Gets the effective group identity of the process. (See getegid(2).)
doc/api/process.markdown:Gets the effective user identity of the process. (See geteuid(2).)
doc/api/process.markdown:Gets the group identity of the process. (See getgid(2).)
doc/api/process.markdown:Gets the user identity of the process. (See getuid(2).)
doc/api/process.markdown:See [Signal Events][] and kill(2) for more information.
doc/api/process.markdown:Sets the effective group identity of the process. (See setegid(2).)
doc/api/process.markdown:Sets the effective user identity of the process. (See seteuid(2).)
doc/api/process.markdown:Sets the group identity of the process. (See setgid(2).)  This accepts either
doc/api/process.markdown:Sets the user identity of the process. (See setuid(2).)  This accepts either
doc/api/stream.markdown:  // read(0) will not consume any bytes

[dcposch]

If you want I can link these to the corresponding pages on man7.org and freebsd.org, for example

http://man7.org/linux/man-pages/man2/open.2.html
http://www.freebsd.org/cgi/man.cgi?query=lchmod&sektion=2

[dcposch]

On Windows the relevant OS API functions are called entirely different.

Many of these are platform specific. For example, the docs for fs.lchmod say it's only available on OSX. (I bet it would actually work on all BSD derived systems.)

[eljefedelrodeodeljefe]

On Windows the relevant OS API functions are called entirely different.

For our docs that shouldn't be too bad, although you are right. Unices documentation and APIs are open source, very transparent and match a lot of the POSIX API. Windows system programming is the total opposite, but will eventually also match POSIX or if you know it you can easily adapt he concepts.

It being sort of the standard to start system programming with Unices the interested user will be able to tell the difference. The world is just too complex to describe it correctly in an API two-liner. Also the way I read libuv is that a lot of concepts are derived from either platform. E.g. thread pools of NT, fs of Unix.

[jasnell]

this has been addressed in master and v5

[SetTrend]

Brilliant 👏