Parenthetical in the middle of a statement spawns a subshell in the brain. The foreground process in the brain is not multi threaded well and this is very difficult for people to maintain context on the first pass. If you must use them, you can use them at the end, but parentheticals at the end reads like you are trying to cram extra information into the sentence.

Consider using this form, it's clickable in graphical terminals, gnome-help et. al., and man.freebsd.org.

.Ss and .Sh pad themselves.

suspend and stop are very different.

I like what you did here and prefer we do that everywhere instead of using parentheticals.

Check out Oo and Oc here. You basically want to never use [ in mdoc.

Yes, it confused me too, but this is a direct passage from POSIX text. Also, POSIX provides a description for job state 'Stopped' which says: "Indicates that the job was suspended ...". Although, later it points out that "The implementation may substitute the string Suspended in place of Stopped".

In other words, that it is not very clear to me, so I thought I'm better off citing the original sentence.

OK, thank you! And what about '<' and '>'? Would Ao and Ac be better for writing <space> to represent the whitespace character? And the same question for '(' and ')': are they OK as characters or it's better to use Po and Pc?

The usual style for these is that the first letter is capitalized in this document, although it is quite inconsistent.

Please don't mark up random parts of sentences that just happen to match the title of a section.

des is right, my recommendation introduces a regression when rendered in plain text. The way you had it the first time was better. Sorry about that!

Now I understand, thank you. So does it mean I should turn all these references to manpages and section titles, which des is talking about, into 'See (...)'-like references?

Yeah I think so. I personally think they're better with a comma rather than a parentheses.

I would guess it's better to use parentheses just for consistency with style of this particular page.

There is no reason to capitalize this.

I would move the parenthesis to right before the comma to avoid breaking up the lemma.

Redundant article. I would perhaps rewrite to “The job control facility allows users”

Perhaps “Additionally, the following built-in commands accept a job ID as an argument:” would be better

either “see the <title> section below” or just “see <title> below”

remove the final “the” here because Ar signal acts as a proper noun.

I know that Oxford commas are controversial but the FDP mandates them (section 12).

“for additional information on the meanings of these signals”

Move the parenthesis to the end of the sentence, and perhaps switch to the shorter formulation that you used above.

If there is substantial text copied from POSIX after all review changes, please add a notice like in share/examples/mdoc/POSIX-copyright.

Might want to mention here how this can be done: Ctrl+Z (if not adjusted using stty(1)).

Nit: I think this sentence "At most one job can be identified with it." can be removed since "Identifies the job" above already implies it.

Nit: I think this sentence "At most one job can be identified with it." can be removed since "Identifies the job" above already implies it.

I think the "expressed as a decimal number" part is appropriate for a standards document but a little too verbose for a manual page. That the number is decimal would be what a normal person expects, so there is no need to mention it. (If it were hexadecimal, that would need to be mentioned.)

Perhaps add something like "This is typically because Ctrl+Z was pressed."

Unfortunately, these messages are messier than that. As can be found in lib/libc/gen/siglist.c, they are Suspended (signal), Stopped (tty input) and Stopped (tty output), for SIGSTOP, SIGTTIN and SIGTTOU respectively.