if we're fixing the style this is a perfect time to do this, these should not be quoted because this confuses people. Nd takes the rest of the line as an argument.

the hypen is not the command modifier. vcpu is also not a flexible argument. the entire -vcpu is the command modifier. the colon is also not a command modifier. it does not modify the command, it is a required part of it. note the way this renders is quite different, and this is also important for making apropos useful.

here's the extended documentation for mdoc(7) on the Cm macro for more details: https://mandoc.bsd.lv/mdoc/style/commands.html

same as above

N is the part that is a variable argument, vcpu is part of the fixed syntax

P.S. with this many Ns's it might be wise to use Sm off above instead

Good catch!

	if (sscanf(opt, "%d-%d:%d-%d", &vcpu_first, &vcpu_last, &pcpu_first, &pcpu_last) == 4) {
		if (vcpu_first > vcpu_last || pcpu_first > pcpu_last) {
			fprintf(stderr, "invalid range (must be ascending): %s\n", opt);
			return (-1);
		}
		if ((vcpu_last - vcpu_first) != (pcpu_last - pcpu_first)) {
			fprintf(stderr, "range sizes do not match: %s\n", opt);
			return (-1);
		}

vcpu is not a command modifier. An example of a -p use is: -p 0-3:12-15.

: is a command modifier because it is a required part of the string the you pass to a command. The logic I always apply in those cases is _if it is a string that is a part of a command's syntax and it is not variable I can style with Ar, then Cm should be used._. This is also what we document in style.mdoc(7).

In mdoc(7):

.Nm dd Cm if=	Ns Ar file1 Cm of= Ns Ar file2

Both "if" and "=" are styled with Cm because they are a part of the command-line syntax and are not arguments that should be styled with Ar.

An example of a -p use is: -p 0-3:12-15.

Oh, that's makes it a lot clearer. Then it should be:

.Op Fl p Ar vcpuN Ns Oo - Ns Ar vcpuM Oc : Ns Ar hostcpuN Ns Oo - Ns Ar hostcpuM Oc

: is a command modifier because it is a required part of the string the you pass to a command.

That is not a command modifier because it does not modify the command. As you said, it is a required part of the command. Please read mdoc(7). Here is a link https://man.freebsd.org/cgi/man.cgi?query=mdoc&apropos=0&sektion=0&manpath=FreeBSD+16.0-CURRENT&format=html

An example from mdoc(7):

.Nm dd Cm if=	Ns Ar file1 Cm of= Ns Ar file2

Both "if" and "=" are styled with Cm because they are a part of the command-line syntax and they are not arguments that should be styled with Ar.

The logic I always apply in those cases is _if it is a string that is a part of a command's syntax and it is not variable I can style with Ar, then Cm should be used._. This is also what we document in style.mdoc(7).

I'm looking at it right now in main, and do not see anything like that. I may be interpreting what you're saying incorrectly, but iiuc what you are saying is in conflict with the large body of documentation the compiler authors have written on the subject.

Fair point. It is not there, sorry. I thought that I've added it to style.mdoc(5) at one point.

An example from mdoc(7):

.Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2

Both "if" and "=" are styled with Cm because they are a part of the command-line syntax

No. In this case, the referenced command is obviously dd(1). "The dd utility copies the standard input to the standard output" (https://man.freebsd.org/cgi/man.cgi?dd). The "if=" command modifier modifies the command from it's default operation of taking it's input from stdin to instead take a file as the input, thus it is marked up with the command modifier macro. Same as we do in this file on lines 45-47.

and they are not arguments that should be styled with Ar.

They are not mutually exclusive. Ar is exclusively for arguments, that is, placeholder text for what the reader is intended to write.

The logic I always apply in those cases is _if it is a string that is a part of a command's syntax and it is not variable I can style with Ar, then Cm should be used._. This is also what we document in style.mdoc(7).

I'm looking at it right now in main, and do not see anything like that. I may be interpreting what you're saying incorrectly, but iiuc what you are saying is in conflict with the large body of documentation the compiler authors have written on the subject.

Fair point. It is not there, sorry. I thought that I've added it to style.mdoc(5) at one point.

Sorry. After looking through the history, you did. I wrote a review to remove it to fix the bug where we are shipping multiple conflicting documentation on how to write manual pages. I tagged you in it because I really wanted us to get on the same page, and then committed it after two weeks of silence including a ping. Please excuse me for forgetting and not mentioning it previously.