Skip to content
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

Closed
wants to merge 6 commits into from
Closed

doc: Clean up roff source in manpage #7819

wants to merge 6 commits into from

Conversation

Alhadis
Copy link
Contributor

@Alhadis Alhadis commented Jul 21, 2016

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:

Figure 1

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://…"
@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Jul 21, 2016
Alhadis referenced this pull request Jul 21, 2016
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>
@Fishrock123 Fishrock123 self-assigned this Jul 21, 2016
.
.\" See http://liw.fi/manpages/ for an overview, or http://www.troff.org/54.pdf
.\" for detailed language reference.
.de ur
Copy link
Contributor

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

?

Copy link
Contributor Author

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?

  1. 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.
  2. 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.

Copy link
Contributor

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.

Copy link
Contributor Author

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)

@Fishrock123
Copy link
Contributor

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

@Fishrock123
Copy link
Contributor

/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!

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can't just be \"?

Copy link
Contributor Author

@Alhadis Alhadis Jul 21, 2016

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.

@Alhadis
Copy link
Contributor Author

Alhadis commented Jul 21, 2016

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
Copy link
Contributor Author

Alhadis commented Jul 21, 2016

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

@Alhadis
Copy link
Contributor Author

Alhadis commented Jul 21, 2016

@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:

  1. .de ur
    The .de request defines a new macro of the given name. In this case, we're defining ur.
  2. .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.
  3. .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.
  4. \$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
  5. .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.
  6. ..
    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.

@@ -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
Copy link
Contributor Author

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.

@Fishrock123
Copy link
Contributor

@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
Copy link
Contributor Author

Alhadis commented Aug 2, 2016

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

Figure 1

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
Copy link
Contributor Author

Alhadis commented Aug 2, 2016

<<'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
Copy link
Contributor Author

Alhadis commented Aug 3, 2016

@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
Copy link
Member

jasnell commented Aug 3, 2016

This LGTM. Thank you for this!

@jasnell
Copy link
Member

jasnell commented Aug 4, 2016

@nodejs/documentation

@jasnell
Copy link
Member

jasnell commented Aug 5, 2016

@Fishrock123 ... ping

Fishrock123 pushed a commit to Fishrock123/node that referenced this pull request Aug 8, 2016
* 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>
@Fishrock123
Copy link
Contributor

Thanks! Squashed and landed in eb172fe :)

@Fishrock123 Fishrock123 closed this Aug 8, 2016
@Alhadis Alhadis deleted the roff-polish branch August 8, 2016 18:15
@cjihrig cjihrig mentioned this pull request Aug 8, 2016
cjihrig pushed a commit that referenced this pull request Aug 10, 2016
* 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>
@cjihrig cjihrig mentioned this pull request Aug 11, 2016
@Alhadis
Copy link
Contributor Author

Alhadis commented Aug 22, 2016

@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:

Figure 1

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).

MylesBorins pushed a commit that referenced this pull request Sep 30, 2016
* 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>
rvagg pushed a commit that referenced this pull request Oct 18, 2016
* 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>
MylesBorins pushed a commit that referenced this pull request Oct 26, 2016
* 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>
@MylesBorins MylesBorins mentioned this pull request Oct 26, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants