-
Notifications
You must be signed in to change notification settings - Fork 29.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: Clean up roff source in manpage #7819
Conversation
* 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 <jasnell@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
. | ||
.\" See http://liw.fi/manpages/ for an overview, or http://www.troff.org/54.pdf | ||
.\" for detailed language reference. | ||
.de ur |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
.\" for detailed language reference.
.\" Macros
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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'san-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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, I think we should add a comment about the macro, and probably a space above it, that is all. Sorry for the confusion.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)
mostly seems fine, is a macro really the easiest way to achieve |
Looks like there is a whitespace error, could you please set |
[\fIscript.js\fR | \fB\-e \fR"\fIscript\fR" | \fI<host>:<port>\fR] \fI... | ||
.RI [ script.js " | " | ||
.B \-e | ||
.RI \&" script \&"\ | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can't just be \"
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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`
Not globally, no. But I will do it for this repo, of course. =) |
@Fishrock123 I've nuked the trailing whitespace. It must've slipped in there while breaking the previous formatting across lines. My fault. |
@Fishrock123, I've included the macro description you suggested, and deleted the superfluous 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:
Note too that every escape sequence used inside a macro definition is itself double-escaped. |
@@ -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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Brief explanation on the difference between troff and roff, dated 12 hours ago.
@Alhadis think you can leave black lines without any formatting for now? if you remove the two empty |
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 EDIT: Wait, I noticed the existing manpage source has no blank lines between the options... were you referring to two different |
|
@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). |
This LGTM. Thank you for this! |
@nodejs/documentation |
@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 <jasnell@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
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 <jasnell@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
@Fishrock123 / @jasnell Don't know if it means anything, but I compiled a manpage from I'm aware the
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 <jasnell@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
* 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 <jasnell@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
* 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 <jasnell@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Checklist
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