sh.1: Provide detailed documentation for job control

[tembun_bk.ru]

Summary

The detailed description of shell job control
(particularly, for the format, in which job IDs are
specified) has been missed for years.

I adopted the POSIX standard text, describing shell
job control (https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_203),
tried to make it more easy-to-read and also made
some small changes according to the actual
implementation of sh(1) in FreeBSD (i.e., it reports
suspended status as 'Suspended', rather than 'Stopped').

I'm not very experienced with mdoc(7) and this
is my first more-or-less big patch, so I will be
very happy if you point out my mistakes.

PR: 206284

[ziaee]

This is by no means a complete review, and it's time for me to drive home from work, but here's what I've got so far:

Why did you change job to job_id?

Basically, you almost never want Em to mark up semantics, it defeats the entire point of mdoc, which is that we can mark up the document semantically. This lets us search by semantics and have a better chance at consistency. Afaict, everywhere you used Em needs to at least be Ar, but there are some more specific cases where Ar is a step in the right direction but something else is even more ideal.

bin/sh/sh.1

257–258

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.

1945

.Ss and .Sh pad themselves.

1953

suspend and stop are very different.

1959

1978

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

2511

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

[tembun_bk.ru]

Thank you for the quick reply, Alexander!

I did change job to job_id, because I think it makes the meaning of the argument more clear. Putting it just as "job" does _not_ tell the reader how actually refer to the job. Shall I write a single number (which is job _number_) or shall I put a % in front of it (which makes it a job _id_)? And, as I've just mentioned, there is a separate term and definition of what the job id is and which forms it may take, which allows us to simply refer to this term and name this thing consistently across sections.

Regarding macros to use instead of Em: I see that Ar is for command arguments, but, for example, in this part:

.Dl Oo Em job_number Oc Em current Em state Em command

where I'm describing the format of a string that is printed as a result of jobs command, I suppose the components, I marked up with Em are _not_ command arguments. The line itself is not a command, and these things are not arguments. I agree with you on point, that Em does not look very good - I tried to find a more suitable macro for this, but I couldn't, it seems like Ar is the only alternative indeed. But I'm afraid it doesn't reflect the actual semantics of these words.

As for

.It Li %? Ns Em string

shall I wrap the entire string into Ar (including %?)? I do want to put "string" aside, because it is in fact a variable part and should not be interpreted literaly. But if I do wrap in Ar only the "string" part, then it seems to me, it again does not convey the right semantics, because "string" is not a separate thing - it makes sense only when it's used with "%?".

Are my concerns reasonable or semantics is not supposed to be that strict? If it's not, would it be OK if I use Ar _everywhere_ I used Em?

bin/sh/sh.1

1953

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.

2511

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?

[tembun_bk.ru]

Rebase the patch, so that it could be applied to -CURRENT.

Address ziaee's comments:

• Change all .Em to .Ar, and, in some places, to .Cm.
• Do not do parenthesis for cross-referencing sections.
• Do not pad .Ss with .Pp.
• Use the longest string as -width for .Bl's.
• Use Oo and Oc instead of [ and ].
• Use Ao and Ac instead of < and >.