doc: link to man pages by dcposch · Pull Request #5073 · nodejs/node · GitHub

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

Before

After

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

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

@Fishrock123

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

/cc @nodejs/documentation

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. 😉

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 {
...
}

done

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.

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.

done

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

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

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.

@Fishrock123 done

Can you wrap lines at 80 columns in this file?

LGTM with style nits.

LGTM with @bnoordhuis' nits addressed

@bnoordhuis @jasnell fixed

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

LGTM

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

@thefourtheye Np, will do soon )

Thanks :)

@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

LGTM

@dcposch please rebase you branch.

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

@a0viedo @silverwind done

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.

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

@bnoordhuis fixed

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

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

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>

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

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>

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

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

doc: link to man pages by dcposch · Pull Request #5073 · nodejs/node · GitHub

Uh oh!

Uh oh!

doc: link to man pages - #5073

doc: link to man pages#5073dcposch wants to merge 1 commit intonodejs:masternodejs/node:masterfrom dcposch:manpagesdcposch/node:manpagesCopy head branch name to clipboard

Conversation

dcposch commented Feb 4, 2016

Uh oh!

dcposch commented Feb 4, 2016

Uh oh!

dcposch commented Feb 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcposch commented Feb 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evanlucas commented Feb 4, 2016

Uh oh!

estliberitas commented Feb 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fishrock123 commented Feb 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcposch commented Feb 4, 2016

Uh oh!

Fishrock123 commented Feb 5, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcposch commented Feb 6, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bnoordhuis commented Feb 6, 2016

Uh oh!

jasnell commented Feb 7, 2016

Uh oh!

dcposch commented Feb 8, 2016

Uh oh!

DavidTPate commented Feb 8, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

doc: link to man pages#5073
dcposch wants to merge 1 commit into
nodejs:masterfrom
dcposch:manpages