man node produces warnings on macOS

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

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

@ebraminio

/cc @ebraminio @Fishrock123

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

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

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

Thanks ben, that patch supresses the warnings for me.

#18440

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.)");
	}
}

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

doc: fix manpage warnings

Navigation Menu

Repository navigation

`man node` produces warnings on macOS #18434

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

man node produces warnings on macOS #18434

Description

Activity

silverwind commented on Jan 29, 2018

addaleax commented on Jan 29, 2018

ebraminio commented on Jan 29, 2018

silverwind commented on Jan 29, 2018

bnoordhuis commented on Jan 29, 2018

silverwind commented on Jan 29, 2018

silverwind commented on Jan 29, 2018

Alhadis commented on Feb 3, 2018

silverwind commented on Feb 4, 2018

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`man node` produces warnings on macOS #18434