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

[tembun_bk.ru]

Ping @ziaee?

[tembun_bk.ru]

Bump document date.

[tembun_bk.ru]

@ziaee Does this patch look OK? Or shall I make some further changes?

[ziaee]

This is a great improvement. Sorry for the delay... There are people who have been using this language longer than I've been alive, and I hoped one of them would do it, but looking at this again, this is great, to me. If nobody else says anything, I'll merge this Monday for inclusion in FreeBSD 14.4 and 15.1.

[ziaee]

bin/sh/sh.1

1966

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

[tembun_bk.ru]

Use capital letters for list items.

[tembun_bk.ru]

In D49895#1232841, @ziaee wrote:

This is a great improvement. Sorry for the delay... There are people who have been using this language longer than I've been alive, and I hoped one of them would do it, but looking at this again, this is great, to me. If nobody else says anything, I'll merge this Monday for inclusion in FreeBSD 14.4 and 15.1.

Wonderful! Thank you for the review!

[des]

bin/sh/sh.1

1945

Missing article

1952

to selectively suspend

1954

s/to/and/

1956

Missing article

1957

s/be/take/

1972

s/string//

1984

Remove “The” and the comma

2045

Except for the addition of that final sentence, I prefer the original.

2410

Same comment as for bg.

2503

Same comment as for bg and fg.

2505

The options were previously ordered lexicographically, as they should. Why are you changing that?

2512

gratuitous change

2528

this list is out of order

2572

Please don't mark up random words just because they happen to match the title of a related page.

2575

As above.

2973

gratuitous change

[des]

bin/sh/sh.1

258

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

[ziaee]

bin/sh/sh.1

258

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!

[tembun_bk.ru]

bin/sh/sh.1

258

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?

[ziaee]

bin/sh/sh.1

258

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

[tembun_bk.ru]

bin/sh/sh.1

258

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

[tembun_bk.ru]

Address @des and @ziaee comments.