I'm not particularly knowledgeable about man pages, but as long as mdoc works on all our supported platforms, +1 on moving to it. Less room for error sounds good, and I don't think we need arbitrary formatting.

I'm not really sure who to cc for this, I'm not sure we have anyone who is particularly knowledgeable about the Node manpage. Maybe cc/ @silverwind @bnoordhuis @sam-github @strugee (from the commit history).

What would be really helpful is a way to evaluate PRs to the manpage. A rendered before/after might be adequate, how did you generate yours?

I'm not an mdoc expert (wrote a lot of roff in my time but not mdoc specifically) but the changes look good to me. @Alhadis Can you wrap lines at 80 columns and spice up the commit log?

as long as mdoc works on all our supported platforms

I'm not 100% sure but I think that's the case. It's probably an improvement over the current man page because I doubt it renders nicely when your roff isn't groff.

Can you wrap lines at 80 columns

I can, but having one sentence per line enables Troff (or mandoc) to generate nicer-looking paragraphs with better justification. Compare:

ONE SENTENCE PER LINE:
     Node.js is a set of libraries for JavaScript which allows it to be used
     outside of the browser.  It is primarily focused on creating simple,
     easy-to-build network clients and servers.

LINES WRAPPED TO 80 COLUMNS:
     Node.js is a set of libraries for JavaScript which allows it to be used
     outside of the browser. It is primarily focused on creating simple, easy-
     to-build network clients and servers.

Not a huge issue (unless you're a typography nerd like me), but you'll notice easy-to-build was broken across two lines, and extra spacing doesn't separate the two sentences. mandoc -T lint doc/node.1 will also warn you about this sort of thing:

λ node (docfix): mandoc -T lint doc/node.1 
mandoc: doc/node.1:28:17: WARNING: new sentence, new line

@bnoordhuis How should I proceed?

What would be really helpful is a way to evaluate PRs to the manpage. A rendered before/after might be adequate, how did you generate yours?

Using this, which started from this. Don't want this PR to become an advertisement for my own handiwork, but suffice to say if you're an Atom user, you'll damn well enjoy having a live previewer for editing Roff documents. It's not strictly reliant on Atom to work, either: its non-graphical output can be used from within Node alone:

groff -mandoc -tZTutf8 /path/to/man/page.1 | html-tty > wanky-preview.html

With html-tty being this. The styling was added manually, since the HTML-ified nroff output is intended to be styled from inside Atom.

Note: The previewer isn't finished, although it's 95% there. I'm itching to finish it.

Overall, I like the new concise rendering 👍

@Alhadis By the way, which tool would you recommend for linting? I see you've been using mandoc -T lint but the mandoc tools does not look readily available in Linux at least (For example, Arch Linux only has it in the user repository).

By the way, which tool would you recommend for linting? I see you've been using mandoc -T lint but the mandoc tools does not look readily available in Linux at least

Which Linux are you referring to? I had no problems installing it on Debian, and the project's site has a pretty comprehensive listing of ports and supported platforms.

For typesetter-roff (troff), well, your best bet is this:

troff -tTutf8 -wall /path/to/page.1 >/dev/null

Which Linux are you referring to

Arch Linux does not have it in the base repos, just in AUR, but that shouldn't be an issue for a possible future integration of a manpage linter if our lint job node-test-linter runs on a Debian derivate, but I'm not certain right now.

Linter job currently runs on FreeBSD, but I don't think moving to debian will be an issue.

Anybody want me to chuck this in as a bonus? 😀 It's a few years out-of-date and needs updating with V8's new command-switch set, but I've been meaning to hack a Perl script together to sync the v8.1 page with latest releases.

The page was hard-written but works beautifully.

Anybody want me to chuck this in as a bonus?

I wouldn't be against adding v8 options to the man page if you can get the updating integrated into our v8 update workflow (I think this is done using https://github.com/targos/update-v8). Would probably have to be written in JS, thought :)

cc: @targos

Updating a manual-page by comparing two lists of options gets a bit slippery because many of the manpage option-descriptions have been polished up in grammar or wording, possibly with marked-up links to other sections across pages, or what-have-you. =) (I'm hoping that makes sense).

FYI, it wouldn't take me very long to smash together a Node program that generates the API manpages from JSON source. 😉

Linter job currently runs on FreeBSD

Given that it's a BSD, it might just have the mandoc tool preinstalled. I don't have a FreeBSD available, can someone check?

many of the manpage option-descriptions have been polished up

I see that most v8 options are pretty inconsistently labeled. One suggestion might be to maintain a list of polished up descriptions and fallback to the default description in case no mapping is found.

Anybody want me to chuck this in as a bonus?

Sounds useful, but it might delay this PR, maybe just raise a separate one.

FYI, it wouldn't take me very long to smash together a Node program that generates the API manpages from JSON source. 😉

Please do!

Sounds useful, but it might delay this PR, maybe just raise a separate one.

Will do. ;)

Just waiting on @bnoordhuis to clarify what he wants me to do regarding that line-wrapping matter. Then I'll amend my commit and force-push something merge-worthy. 👍

It's fine but can you add a comment to the document explaining why it has long lines? Otherwise someone will clean it up sooner or later.

Wilco. =) I'll include a note about why blank lines are bad, too.

Alright, done. Does that look adequate?

I started with the .ig command for embedding the notes at the top:

.ig
This manpage is written in mdoc(7).

 * Language reference:
   https://man.openbsd.org/mdoc.7

 * Atom editor support:
   https://atom.io/packages/language-roff

 * Linting changes:
   mandoc -Wall -Tlint /path/to/this.file  # BSD
   groff -w all -z /path/to/this.file      # GNU/Linux, macOS


 Before making changes, please note the following:

 * In Roff, each new sentence should begin on a new line. This gives
   the Roff formatter better control over text-spacing, line-wrapping,
   and paragraph justification.

 * Do not leave blank lines in the markup. If whitespace is desired
   for readability, put a dot in the first column to indicate a null/empty
   command. Comments and horizontal whitespace may optionally follow: each
   of these lines are an example of a null command immediately followed by
   a comment.
..

Of course, then I had to explain (tersely) what the .ig (Ignore text) command does, and why those lines were an exception to what they were explaining. 😞 Since there was no concise way to do so, I resorted to using the regular .\" comments just to simplify things for readers.

Out of interest did you edit your commit message to make every line exactly 72 columns? If so then I'm kind of amazed by the commitment 😁 .

Like man(7), mdoc(7) is a macro package for marking up computer manuals.
The main difference is that mdoc is semantic rather than presentational,
providing authors with a full DSL to abstract page markup from low-level
Roff commands. By contrast, `man` is minimalist and leaves formatting to
the author, who is expected to have a working amount of Roff knowledge.

Therefore the use of `mdoc` for marking up Node's manpage is a decidedly
better choice than bare `man`. Less room is left for error and mandoc(1)
offers very robust error-checking and linting.

Also do you have an updated rendered link to compare against?

Out of interest did you edit your commit message to make every line exactly 72 columns? If so then I'm kind of amazed by the commitment 😁 .

That's, uh, literally every commit message I've ever written. 😅 I'm not even making this up.

Think that's absurd? Scroll down.

Also do you have an updated rendered link to compare against?

Output is still the same. 😉 All I did was add comments:

• Before: d6eab8d
• After: 375f46f

Yeah, I'd approve as well once those two points are adressed (boldening of - and -- and adding the = on options that require it).

Very well. Done. Here's the updated rendered view.

To explain the Ns = Ns weirdness: the Ns macro is used for suppressing the preceding space that would otherwise be inserted automatically (Ns = "No Space").

It's necessary to stop --inspect=[host:]port coming out like --inspect = [host:]port.

Light-CI https://ci.nodejs.org/job/node-test-commit-light/280/

Landed in ef7f5a1 🎉

@Alhadis thanks a lot for your hard work.