man node produces warnings on macOS

[silverwind]

On macOS 10.13.3 with node 9.4.0, I get these warnings printed after opening and closing node's manpage via man node and q:

`R' is a string (producing the registered sign), not a macro.
`R' is a string (producing the registered sign), not a macro.

Versions of tools involved in man processing:

# groff --version
GNU troff (groff) version 1.19.2
GNU grops (groff) version 1.19.2

[silverwind]

I think this is because of the two .Rs introduced here, but not sure what do do about them.

[addaleax]

/cc @ebraminio @Fishrock123

[ebraminio]

:( no idea about the archaic markup honestly but will have a look. Thanks for raising the issue and CCing me.

[silverwind]

👍 if it helps, troff 1.22.3 on Linux seems unaffected by this. Also the specific section with the .R renders fine on both macOS and Linux for me.

[bnoordhuis]

It's the .R tags that commit introduces. Whether or not it generates warnings depends on whether the system's mandoc macro package defines it.

diff --git a/doc/node.1 b/doc/node.1
index a4395c099b..836b901bea 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -37,9 +37,9 @@ node \- Server-side JavaScript runtime
 .RI [ script.js \ |
 .B -e
 .RI \&" script \&"
-.R |
+.RI |
 .B -
-.R ]
+.RI ]
 .B [--]
 .RI [ arguments ]
 .br

[silverwind]

Thanks ben, that patch supresses the warnings for me.

[silverwind]

#18440

[Alhadis]

In Roff, a string register can be expanded using the same syntax for invoking a macro or function call:

.ds JS "JavaScript"  \" Define string `JS`
.as JS " kicks ass!" \" Append to string `JS`
.
.JS \" Outputs "JavaScript kicks ass!"

Macros/functions operate in a similar fashion:

.\" Define macro named `JS`
.de JS
JavaScript \\$1 \\$2
..
.
.JS kicks ass!

The former usage is rare; in almost all cases, Roff authors will use the following syntax for expanding a string:

\*X     \" Expands string with 1-letter name X
\*(XY   \" Expands string with 2-letter name XY
\*[XYZ] \" Expands string with variable-length name (GNU extension)

Now, it's pretty silly to have a macro that applies the default font, which is why .R warns the user when it detects it's been called as a macro. Here's the macro's actual definition in an.tmac:

.de1 R
\c
.  ie \\n[.$] \{\                                                                                                                                                                                                  
.    tm `R' is a string (producing the registered sign), not a macro.
.    nop \\$*
.  \}
.  el \{\                                                                                                                                                                                                          
.    ie c\[rg] \                                                                                                                                                                                                   
.      nop \[rg]\c
.    el \                                                                                                                                                                                                          
.      nop (Reg.)\c
.  \}
..

And here's the macro's rough approximation in JavaScript:

function R (...args) {
	if (arguments.length) {
		console.warn("`R' is a string (producing the registered sign), not a macro.");
		process.stdout.write(...args);
	}
	else {
		if(characters.has("RG"))
			process.stdout.write(characters.get("RG"));
		else
			process.stdout.write("(Reg.)");
	}
}

[silverwind]

It might be a good idea run man ./doc/node.1 > /dev/null during our linter tests and verify that it doesn't print any warnings on stderr (exit code is 0, even with warnings present).