doc: Clean up roff source in manpage #7819

Alhadis · 2016-07-21T12:48:13Z

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

I was prompted to submit a PR to make some trivial corrections to Node's manpage source. While I was there, I took the liberty of tidying up some of the source to make things less noisy to the uninitiated.

The only noticeable change is the addition of underlines to the URLs in the footer:

This stays more consistent with existing manual-page formatting, which usually employs underlines to pronounce URLs in text.

If you prefer I revert that addition, please advise if I should do so as a separate commit, or through --amend / push -f.

/cc @Fishrock123

* The header's comments were written incorrectly. A comment line in Roff starts with a .\" sequence, whereas .\ is attempting to call a command whose name starts with a space. Because Roff interpreters will discard unrecognised control lines, the malformed "comments" were just noops. * Repeating font macros have been used to format the synopsis instead of escape sequences (\fB…\fR). This makes for admittedly more sustainable source code for an editor who lacks knowledge of Roff. * A basic macro has been added to insert highlighted URLs with less line noise. To insert a bold and underlined URL on a new line, one only has to write ".ur http://…"

Uses better troff formatting. Removes v8 options from the man page. Also edits `node -h` in node.cc slightly. PR-URL: #5497 Reviewed-By: James Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]>

Fishrock123 · 2016-07-21T15:24:14Z

doc/node.1

+.
+.\" See http://liw.fi/manpages/ for an overview, or http://www.troff.org/54.pdf
+.\" for detailed language reference.
+.de ur


.\" for detailed language reference. .\" Macros

?

I'm not sure what's being asked here... is this concerning the first or second line?

I felt impelled to offer readers a link to a more authoritative resource on the language, as the former link, while helpful, is extremely limited and only covers very rudimentary aspects of the language.

The macro is simply a cleaner way of formatting the links below. Ordinarily I would've used the .UR/.UE macros provided by Groff's an-ext.tmac, but I'm aware that this isn't available on all systems. I wanted to guarantee this manpage would pose no portability issues. Which is also the reason I named the macro .ur instead of .url, as classical troff didn't permit macro names longer than 2 characters.

Oh, I think we should add a comment about the macro, and probably a space above it, that is all. Sorry for the confusion.

Did you want me to amend an explanation? :)

And as for the .fi request, did you want me to kill it off?

(Built-in language functions are what're known as "requests" in Roff terminology. User-defined routines constructed using requests are known as "macros". Both have identical syntax)

Fishrock123 · 2016-07-21T15:34:40Z

mostly seems fine, is a macro really the easiest way to achieve .ur though?

Fishrock123 · 2016-07-21T15:36:37Z

/Users/Jeremiah/Documents/node/.git/rebase-apply/patch:55: trailing whitespace. .B -e

Looks like there is a whitespace error, could you please set git config --global --add core.whitespace fix for next time? Thanks!

Fishrock123 · 2016-07-21T15:38:08Z

doc/node.1

-[\fIscript.js\fR | \fB\-e \fR"\fIscript\fR" | \fI<host>:<port>\fR] \fI...
+.RI [ script.js " | "
+.B \-e
+.RI \&" script \&"\ |


can't just be \"?

No, because the \" sequence initiates a comment, resulting in the rest of the line being dropped.

The \& is basically Roff's escaping mechanism for certain characters.

Alhadis · 2016-07-21T15:42:57Z

mostly seems fine, is a macro really the easiest way to achieve .ur though?

No, but it's the cleanest way. The easiest but arguably noisier way (with guaranteed portability in mind) would look like this:

`\f4http://www.github.com/\f1`

Looks like there is a whitespace error, could you please set git config --global --add core.whitespace fix for next time? Thanks!

Not globally, no. But I will do it for this repo, of course. =)

Alhadis · 2016-07-21T15:47:51Z

@Fishrock123 I've nuked the trailing whitespace. It must've slipped in there while breaking the previous formatting across lines. My fault.

Alhadis · 2016-07-21T17:33:23Z

@Fishrock123, I've included the macro description you suggested, and deleted the superfluous .fi request. Since these "maintenance" commits break away from your project's styleguide, you'll probably want to squash-merge this (which I assume you were going to do anyway). =)

BTW, the macro I wrote is probably slightly more complex than it needs to be... but I was simply erring on the side of caution. Basically, I was making sure the existing formatting state wasn't going to be disrupted by the macro's execution.

FMTEYEWTK:

To give you a breakdown of exactly what each line is doing:

.de ur
The .de request defines a new macro of the given name. In this case, we're defining ur.
.nr CF \\n(.f
The .nr request stores a value in a number register (like a global variable, if you will).
1. CF
  The name of the register we're writing to.
  I named it CF to stand for CURRENT FONT.
2. \n(XX
  This escape sequence expands to the value of a number register with the name XX.
  In Roff, .f is a predefined readonly register that holds the index of the current font.
  Roff's typesetting method is modal, and there can only be one font enabled at any one time.
.ft 4
The .ft request changes the current font to the one at the given index.
In Roff, there are four default font families:
1. Roman (Regular/Default)
2. Italic
3. Bold
4. Bold Italic
  Recalling that italics are rendered in terminal emulators as underlined text, setting the font to "bold italic" establishes the intended formatting for whatever content follows.
\$1
This expands to the value of the first argument. Note there's no leading . - this tells Roff that the line is copy, so it sends it to the output buffer
.ft \n(CF
As we learned in point test: don't remove empty.txt on win32 #2, the \n(CF expands to the content of a register, which in our case is the CF register we used on line 2.
Here, the .ft command restores the previous font setting to whatever it was before the macro was executed.
..
This indicates the end of the macro's definition

Note too that every escape sequence used inside a macro definition is itself double-escaped.
This is to delay expansion of the escape character until the macro's actually invoked.
Otherwise, the values would be expanded the first time the macro definition is processed.

Alhadis · 2016-07-21T17:42:43Z

doc/node.1

@@ -2,7 +2,7 @@

 .\" This is a man page comment.
 .
-.\" Man page syntax (actually troff syntax) is somewhat obscure, but the
+.\" Man page syntax (actually roff syntax) is somewhat obscure, but the


Brief explanation on the difference between troff and roff, dated 12 hours ago.

Fishrock123 · 2016-08-02T14:19:19Z

@Alhadis think you can leave black lines without any formatting for now? if you remove the two empty .'s I'll land it -- let's do that in another PR if it is critical, but imo blank lines format well enough in most cases that it;s worth the ease of reading without them.

Alhadis · 2016-08-02T14:29:27Z

As you wish. Be advised the removal of the dot-only lines in the synopsis will cause a paragraph break, resulting in this:

I'm assuming this is acceptable?

(I also remind you the double-dot .. line is required in order to terminate the macro definition).

EDIT: Wait, I noticed the existing manpage source has no blank lines between the options... were you referring to two different . lines...?

Alhadis · 2016-08-02T14:34:21Z

<<'SHAMELESSADVERT'
BTW, it may also please you to know that I've plans to publish a Node module to handle manual-page generation so the average JavaScripter can produce proper Linux-quality documentation. =) There're already plenty of tools to generate manpages from Markdown and RDoc and stuff, but that's a lazy cop-out. We need the real deal, here (preferably something that'll allow project maintainers to "import" existing "documentation" from yargs or commander or whatever).
SHAMELESSADVERT

Alhadis · 2016-08-03T12:03:04Z

@Fishrock123 I deleted the empty lines in the synopsis section, so the output retains the same formatting as before (e.g., no extra line-breaks inserted between usage lines, as I explained in my earlier comment).

jasnell · 2016-08-03T16:17:22Z

This LGTM. Thank you for this!

jasnell · 2016-08-04T20:11:59Z

@nodejs/documentation

jasnell · 2016-08-05T21:46:34Z

@Fishrock123 ... ping

* The header's comments were written incorrectly. A comment line in Roff starts with a .\" sequence, whereas .\ is attempting to call a command whose name starts with a space. Because Roff interpreters will discard unrecognised control lines, the malformed "comments" were just noops. * Repeating font macros have been used to format the synopsis instead of escape sequences (\fB…\fR). This makes for admittedly more sustainable source code for an editor who lacks knowledge of Roff. * A basic macro has been added to insert highlighted URLs with less line noise. To insert a bold and underlined URL on a new line, one only has to write ".ur http://…" PR-URL: nodejs#7819 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>

Fishrock123 · 2016-08-08T18:10:58Z

Thanks! Squashed and landed in eb172fe :)

* The header's comments were written incorrectly. A comment line in Roff starts with a .\" sequence, whereas .\ is attempting to call a command whose name starts with a space. Because Roff interpreters will discard unrecognised control lines, the malformed "comments" were just noops. * Repeating font macros have been used to format the synopsis instead of escape sequences (\fB…\fR). This makes for admittedly more sustainable source code for an editor who lacks knowledge of Roff. * A basic macro has been added to insert highlighted URLs with less line noise. To insert a bold and underlined URL on a new line, one only has to write ".ur http://…" PR-URL: #7819 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>

Alhadis · 2016-08-22T09:02:25Z

@Fishrock123 / @jasnell Don't know if it means anything, but I compiled a manpage from v8 --help's output to avoid getting crushed by feedback when I forget to pipe it to less. It was written for personal use, but I'm wondering if somebody else might like it too.

I'm aware the --help output is probably a dump of constants declared in C++ source somewhere, so I wrote the page's source to be easily edited:

.V8 trace_wasm_decode_time
Trace decoding time of WASM code.

.V8 trace_wasm_compiler
Trace compiling of WASM code.

.V8 trace_wasm_ast_start | Int 0
Start function for WASM AST trace (inclusive).

.V8 trace_wasm_ast_end | Int 0
End function for WASM AST trace (exclusive).

It looks like this:

It's long, so I converted it to PDF for you if you wanted to look.

I'd submit this to V8's repo, but it's a read-only mirror. Hence why I'm bugging you guys with an unsolicited paging (sorry).

* The header's comments were written incorrectly. A comment line in Roff starts with a .\" sequence, whereas .\ is attempting to call a command whose name starts with a space. Because Roff interpreters will discard unrecognised control lines, the malformed "comments" were just noops. * Repeating font macros have been used to format the synopsis instead of escape sequences (\fB…\fR). This makes for admittedly more sustainable source code for an editor who lacks knowledge of Roff. * A basic macro has been added to insert highlighted URLs with less line noise. To insert a bold and underlined URL on a new line, one only has to write ".ur http://…" PR-URL: #7819 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Jul 21, 2016

Fishrock123 self-assigned this Jul 21, 2016

Fishrock123 reviewed Jul 21, 2016
View reviewed changes

Strip trailing whitespace

82a2cde

Alhadis added 2 commits July 22, 2016 03:14

Add brief description for URL-formatting macro

ae90a72

Delete redundant .fi request

4500432

Use correct name for Roff typesetting language

57e48cb

Alhadis reviewed Jul 21, 2016
View reviewed changes

Delete empty lines

3a30132

Fishrock123 closed this Aug 8, 2016

Alhadis deleted the roff-polish branch August 8, 2016 18:15

cjihrig mentioned this pull request Aug 8, 2016

v6.4.0 Release Proposal #8020

Closed

cjihrig mentioned this pull request Aug 11, 2016

v6.4.0 Proposal #8070

Merged

MylesBorins added the land-on-v4.x label Sep 30, 2016

MylesBorins mentioned this pull request Oct 26, 2016

V4.6.2 proposal #9298

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: Clean up roff source in manpage #7819

doc: Clean up roff source in manpage #7819

Alhadis commented Jul 21, 2016 •

edited

Loading

Fishrock123 Jul 21, 2016

Alhadis Jul 21, 2016

Fishrock123 Jul 21, 2016

Alhadis Jul 21, 2016

Fishrock123 commented Jul 21, 2016

Fishrock123 commented Jul 21, 2016

Fishrock123 Jul 21, 2016

Alhadis Jul 21, 2016 •

edited

Loading

Alhadis commented Jul 21, 2016

Alhadis commented Jul 21, 2016

Alhadis commented Jul 21, 2016 •

edited

Loading

Alhadis Jul 21, 2016

Fishrock123 commented Aug 2, 2016

Alhadis commented Aug 2, 2016 •

edited

Loading

Alhadis commented Aug 2, 2016 •

edited

Loading

Alhadis commented Aug 3, 2016

jasnell commented Aug 3, 2016

jasnell commented Aug 4, 2016

jasnell commented Aug 5, 2016

Fishrock123 commented Aug 8, 2016

Alhadis commented Aug 22, 2016 •

edited

Loading

doc: Clean up roff source in manpage #7819

doc: Clean up roff source in manpage #7819

Conversation

Alhadis commented Jul 21, 2016 • edited Loading

Checklist

Affected core subsystem(s)

Description of change

Fishrock123 Jul 21, 2016

Choose a reason for hiding this comment

Alhadis Jul 21, 2016

Choose a reason for hiding this comment

Fishrock123 Jul 21, 2016

Choose a reason for hiding this comment

Alhadis Jul 21, 2016

Choose a reason for hiding this comment

Fishrock123 commented Jul 21, 2016

Fishrock123 commented Jul 21, 2016

Fishrock123 Jul 21, 2016

Choose a reason for hiding this comment

Alhadis Jul 21, 2016 • edited Loading

Choose a reason for hiding this comment

Alhadis commented Jul 21, 2016

Alhadis commented Jul 21, 2016

Alhadis commented Jul 21, 2016 • edited Loading

FMTEYEWTK:

Alhadis Jul 21, 2016

Choose a reason for hiding this comment

Fishrock123 commented Aug 2, 2016

Alhadis commented Aug 2, 2016 • edited Loading

Alhadis commented Aug 2, 2016 • edited Loading

Alhadis commented Aug 3, 2016

jasnell commented Aug 3, 2016

jasnell commented Aug 4, 2016

jasnell commented Aug 5, 2016

Fishrock123 commented Aug 8, 2016

Alhadis commented Aug 22, 2016 • edited Loading

Alhadis commented Jul 21, 2016 •

edited

Loading

Alhadis Jul 21, 2016 •

edited

Loading

Alhadis commented Jul 21, 2016 •

edited

Loading

Alhadis commented Aug 2, 2016 •

edited

Loading

Alhadis commented Aug 2, 2016 •

edited

Loading

Alhadis commented Aug 22, 2016 •

edited

Loading