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

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

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

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

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.
varBSD_ONLY_SYSCALLS=newSet(['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

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

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

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

@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

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

+ '&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 445a1e4Compare 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 19a0876Compare February 6, 2016 03:02

bnoordhuis reviewed Feb 6, 2016
View reviewed changes

Comment threaddoc/api/documentation.markdown Outdated
bnoordhuisFeb 6, 2016
Copy link
Copy Markdown
Member
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you wrap lines at 80 columns in this file?

thefourtheye reviewed Feb 8, 2016
View reviewed changes

dcposch force-pushed the manpages branch from e9509a9 to 5c2b275Compare 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 125cae3Compare 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

Uh oh!

Uh oh!

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!

thefourtheye commented Feb 8, 2016

Uh oh!

silverwind commented Feb 9, 2016