docs: incorrect man page link in html modules doc

[sbc100]

In https://nodejs.org/dist/latest-v5.x/docs/api/modules.html#modules_modules

The following line appears:
var mySquare = square(2);

Which should just be:
var mySquare = square(2);

Looks like the thing that generates links to man pages automatically is a little overzealous.

[jvcjunior]

Hi, I am new in the open source world and would like to help with this. I think it is easy and it would be my second experience contributing to an open source project. Can I do this?

[Fishrock123]

@jvcjunior Sure, It's some regex parsing. The code can be found at https://github.com/nodejs/node/blob/master/tools/doc/html.js#L183-L198

It's possible that we should instead put some extra formatting around what should be man links, something like [man(2)]() maybe?

cc @nodejs/documentation for advice

[claudiorodriguez]

We could either add some extra formatting (which would require changing all man links in all the docs, not sure how many there are), or change the doc markdown-to-html tool so that linkManPages is not called within code blocks (by tracking tok.type, sort of like parseLists does). That wouldn't solve the problem in a definitive fashion of course, it just changes less files, and the two can be done in parallel, even. It mostly depends on how many man links there are lying around. If there ain't that many, I'd say go for changing the format, and change the regex in the tool and the links in the markdown (you'll need to rebase the PR periodically).

[mithun-daa]

Just out of curiosity, how do I convert the mardown files to html locally?

[Fishrock123]

@mithun-daa make doc (assuming you are on Unix and have make)

See https://github.com/nodejs/node/blob/master/Makefile#L238-L249 for the source, or if on windows

[mithun-daa]

Another way to solve it would be not to convert to links (linkManPages) when the tok.type === code.

function parseText(lexed) {
  lexed.forEach(function(tok) {
    if (tok.text && tok.type !== 'code') {
      tok.text = linkManPages(tok.text);
    }
  });
}

[Fishrock123]

(Removing label so that @jvcjunior can tackle this)

@mithun-daa Hmm, what if it were in a code comment?

[mithun-daa]

@Fishrock123 Can code blocks have man page links? If I am not mistaken you cannot have any other markdown formatting inside a code block. I tried doing the same on some online markdown editors and it does not work.

[Fishrock123]

I wasn't sure, but fair enough. :)