doc: link to man pages #5073

dcposch · 2016-02-04T12:14:20Z

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

Fixes #4375

dcposch · 2016-02-04T12:16:40Z

Before

After

dcposch · 2016-02-04T12:17:15Z

Links to e.g. http://man7.org/linux/man-pages/man2/chmod.2.html

thefourtheye · 2016-02-04T12:17:36Z

tools/doc/html.js

+// '<a href="http://man7.org/linux/man-pages/man2/open.2.html">open(2)</a>'
+function getManLink(text) {
+  // It's safe to concatenate into HTML like this because `text` matches
+  var found = text.match(/([a-z]+)\(([0-9])\)/);


Only one digit inside the parenthesis? There could be more than one. Also, use \d

I think man pages only go 1-8 actually

http://unix.stackexchange.com/questions/3586/what-do-the-numbers-in-a-man-page-mean

Changed it to use \d

dcposch · 2016-02-04T12:21:00Z

@Fishrock123

thefourtheye · 2016-02-04T12:21:02Z

tools/doc/html.js

+// Handle references to man pages, eg "open(2)" or "lchmod(2)"
+// Returns modified text, with such refs replace with HTML links
+function linkManPages(text) {
+  return text.replace(/ [a-z]+\([0-9]\)/, getManLink);


Instead of matching again in getManLink, grouping can be done here itself, right?

Also what if there is more than one reference?

yeah good call, i changed it to /g

i did the grouping there to make it clear that name and number are safe to concat into an HTML string, but i'll just combine the two methods to keep things simple

evanlucas · 2016-02-04T12:24:44Z

/cc @nodejs/documentation

estliberitas · 2016-02-04T13:28:28Z

Would also be good to handle cases when POSIX call is wrapped in backquotes.

For, example in #5075 I did this with a sed and your solution is much better. 😉

thefourtheye · 2016-02-04T13:30:56Z

tools/doc/html.js

@@ -165,10 +175,32 @@ function parseLists(input) {
 }


+// Syscalls which appear in the docs, but which only exist in BSD / OSX
+var BSD_ONLY_SYSCALLS = ['lchmod'];


Suggestion: Now that we have Sets in core, we may be able to speed up this lookup.

Yeah, I would think that utilizing a Set or even an object would be faster here (assuming we get more items added to here as well.

var BSD_ONLY_SYSCALLS = new Set(['lchmod']); ... if (BSD_ONLY_SYSCALLS.has(name)( { ... } else { ... }

Fishrock123 · 2016-02-04T14:33:59Z

I think every link should also have a ^[?] (<sup>[?]</sup>) link pointing towards some sort of doc on what a man page is. I.e. how to do man N thing and what that means in terms of different operating systems.

Fishrock123 · 2016-02-04T14:34:37Z

tools/doc/html.js

+        '&sektion=' + number + '">' + displayAs + '</a>';
+    } else {
+      return ' <a href="http://man7.org/linux/man-pages/man' + number + '/' +
+        name + '.' + number + '.html">' + displayAs + '</a>';


cc @bnoordhuis what so you think about these sources for generic man docs?

I was curious about that as well. I went through some digging on Man pages, so that particular set of docs is linked to from kernel.org as well. There's a bunch more sources for the Linux docs but I can't really find any official source. die.net for example.

freebsd.org and man7.org are the official man pages so +1 from me. For freebsd.org, consider linking to the https:// site.

dcposch · 2016-02-04T22:01:49Z

@Fishrock123 dunno, some parts of the docs, like here, have a lot of man page links. I think it would look distracting for each of those to have a superscript.

Fishrock123 · 2016-02-05T15:22:43Z

Hmmm, then we should probably add a thing to "about these docs" at the very least.

bnoordhuis · 2016-02-05T15:50:23Z

tools/doc/html.js

+// 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) {


Would the regex match if the markdown had a code snippet with, say, foo(1) in it?

@bnoordhuis yes

everything it matches currently is a syscall: #4375 (comment)

but i agree it's jank

NVM. Here's a place where it fails

doc/api/modules.markdown:var mySquare = square(2);

I'll change it to require special markup to generate the link, so we don't get false positives.

@bnoordhuis actually it might be fine!

I just generated the docs and it seems that JS passes through the HTML syntax highlighter before it gets to linkManPages. The square(2) above doesn't turn into a link.

dcposch · 2016-02-06T02:57:38Z

@Fishrock123 done

bnoordhuis · 2016-02-06T10:42:11Z

doc/api/documentation.markdown

+
+**Caveat:** some syscalls, like lchown(2), are BSD-specific. That means, for example, that `fs.lchown()` only works on Mac OSX 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 OSX. 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).


Can you wrap lines at 80 columns in this file?

bnoordhuis · 2016-02-06T10:44:17Z

LGTM with style nits.

jasnell · 2016-02-07T20:47:33Z

LGTM with @bnoordhuis' nits addressed

dcposch · 2016-02-08T00:53:03Z

@bnoordhuis @jasnell fixed

LMK if you want me to squash this PR to a single commit

DavidTPate · 2016-02-08T14:39:55Z

LGTM

thefourtheye · 2016-02-08T15:42:52Z

doc/api/documentation.markdown

@@ -66,3 +66,19 @@ Every HTML file in the markdown has a corresponding JSON file with the
 same data.


@estliberitas Hope you are taking care of this page as well :)

@thefourtheye Np, will do soon )

@thefourtheye Hi, I'm a bit out of context. I'll do the usual stuff I do for API pages. Also, once I structure what's on my mind, I'll add maybe a section to this page on how things should be formatted, etc. If it's not added yet, hah.

Sounds OK? Or I do not get what should be done, coz the only thing to be added here would be something like a cool guide on formatting the stuff. But I'm not sure if this page is appropriate for this.

Ah my bad. I just saw few linkable text on this page and reached out for your help. Perhaps we can leave this page as nothing much is needed here.

Anyways, I'll continue my crusade on docs today and tomorrow. :)

On Sat, Feb 13, 2016, 08:59 thefourtheye notifications@github.com wrote:

In doc/api/documentation.markdown
#5073 (comment):

@@ -66,3 +66,19 @@ Every HTML file in the markdown has a corresponding JSON file with the
same data.

Ah my bad. I just saw few linkable text on this page and reached out for
your help. Perhaps we can leave this page as nothing much is needed here.

—
Reply to this email directly or view it on GitHub
https://github.com/nodejs/node/pull/5073/files#r52824032.

Sincerely,
Alexander Makarenko

thefourtheye · 2016-02-08T15:45:22Z

LGTM

silverwind · 2016-02-09T17:09:00Z

@dcposch please rebase you branch.

a0viedo · 2016-02-09T18:08:13Z

@dcposch if you could use a hand squashing your commits into one, please let me know

dcposch · 2016-02-10T03:07:11Z

@a0viedo @silverwind done

silverwind · 2016-02-10T06:10:06Z

Regarding the section Syscalls and man pages: I'd suggest moving it near the top of the fs page. I'm not sure the place below the stability index is really the right one for it, it feels out of place there.

bnoordhuis · 2016-02-11T14:47:27Z

doc/api/documentation.markdown

+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 OSX and other BSD-derived systems,


Tiny nit: we write Mac OS X (space before X) almost everywhere else.

@bnoordhuis fixed

bnoordhuis · 2016-02-11T14:48:35Z

Changes LGTM sans nit. If other collaborators agree, please land it.

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

dcposch · 2016-02-11T16:08:35Z

@silverwind dunno, syscalls are used elsewhere to (not just in fs) and @Fishrock123 wanted the explanation under About These Docs

jasnell · 2016-02-15T15:34:43Z

Still LGTM

Fix missing links. Fix styling of printf() - once #5073 lands, link to man page will be auto-generated. Fix several typos. PR-URL: #5225 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: James M Snell <jasnell@gmail.com>

silverwind · 2016-02-17T22:58:46Z

@dcposch hmm, alright then. LGTM.

Fix missing links. Fix styling of printf() - once #5073 lands, link to man page will be auto-generated. Fix several typos. PR-URL: #5225 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: James M Snell <jasnell@gmail.com>

stevemao · 2016-02-21T22:56:25Z

tools/doc/html.js

+             '&sektion=' + number + '">' + displayAs + '</a>';
+    } else {
+      return ' <a href="http://man7.org/linux/man-pages/man' + number +
+             '/' + name + '.' + number + '.html">' + displayAs + '</a>';


template literal?

Fix missing links. Fix styling of printf() - once #5073 lands, link to man page will be auto-generated. Fix several typos. PR-URL: #5225 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: James M Snell <jasnell@gmail.com>

silverwind · 2016-02-27T13:08:32Z

Thanks! Landed in 4e77a7c.

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>

Fix missing links. Fix styling of printf() - once #5073 lands, link to man page will be auto-generated. Fix several typos. PR-URL: #5225 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: James M Snell <jasnell@gmail.com>

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>

thefourtheye reviewed Feb 4, 2016
View reviewed changes

thefourtheye added the doc Issues and PRs related to the documentations. label Feb 4, 2016

dcposch force-pushed the manpages branch 2 times, most recently from 7bc5a9d to 445a1e4 Compare February 4, 2016 13:05

thefourtheye reviewed Feb 4, 2016
View reviewed changes

Fishrock123 reviewed Feb 4, 2016
View reviewed changes

jasnell added the lts-watch-v4.x label Feb 4, 2016

bnoordhuis reviewed Feb 5, 2016
View reviewed changes

dcposch force-pushed the manpages branch from d64409f to 19a0876 Compare February 6, 2016 03:02

bnoordhuis reviewed Feb 6, 2016
View reviewed changes

thefourtheye reviewed Feb 8, 2016
View reviewed changes

dcposch force-pushed the manpages branch from e9509a9 to 5c2b275 Compare February 10, 2016 03:06

bnoordhuis reviewed Feb 11, 2016
View reviewed changes

doc: link to man pages

125cae3

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

dcposch force-pushed the manpages branch from 5c2b275 to 125cae3 Compare February 11, 2016 16:07

estliberitas mentioned this pull request Feb 14, 2016

doc: improvements to console.markdown copy #5225

Closed

silverwind mentioned this pull request Feb 16, 2016

doc: improvements to child_process, process docs #5075

Closed

stevemao reviewed Feb 21, 2016
View reviewed changes

silverwind closed this Feb 27, 2016

Fishrock123 mentioned this pull request Mar 1, 2016

Release proposal: v5.7.1 #5464

Merged

5 tasks

MylesBorins added land-on-v4.x and removed lts-watch-v4.x labels Mar 1, 2016


		Caveat: some syscalls, like lchown(2), are BSD-specific. That means, for example, that `fs.lchown()` only works on Mac OSX 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 OSX. 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).

		@@ -66,3 +66,19 @@ Every HTML file in the markdown has a corresponding JSON file with the
		same data.

doc: link to man pages #5073

doc: link to man pages #5073

Conversation

dcposch commented Feb 4, 2016

dcposch commented Feb 4, 2016

dcposch commented Feb 4, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dcposch commented Feb 4, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

evanlucas commented Feb 4, 2016

estliberitas commented Feb 4, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Fishrock123 commented Feb 4, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dcposch commented Feb 4, 2016

Fishrock123 commented Feb 5, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dcposch commented Feb 6, 2016

Choose a reason for hiding this comment

bnoordhuis commented Feb 6, 2016

jasnell commented Feb 7, 2016

dcposch commented Feb 8, 2016

DavidTPate commented Feb 8, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thefourtheye commented Feb 8, 2016

silverwind commented Feb 9, 2016

a0viedo commented Feb 9, 2016

dcposch commented Feb 10, 2016

silverwind commented Feb 10, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bnoordhuis commented Feb 11, 2016

dcposch commented Feb 11, 2016

jasnell commented Feb 15, 2016

silverwind commented Feb 17, 2016

Choose a reason for hiding this comment

silverwind commented Feb 27, 2016