Details

Reviewers

ziaee
jilles
des

Group Reviewers

docs
manpages
Contributor Reviews (src)

Commits

rG2711852bd9ac: sh.1: Provide detailed job control documentation

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 sh(1) implementation in FreeBSD.

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

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

des added inline comments.Nov 27 2025, 7:41 PM

bin/sh/sh.1
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

This revision now requires changes to proceed.Nov 27 2025, 7:41 PM

des added inline comments.Nov 27 2025, 7:44 PM

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 added inline comments.Nov 27 2025, 8:28 PM

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 added inline comments.Nov 27 2025, 8:38 PM

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 added inline comments.Nov 27 2025, 8:47 PM

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 added inline comments.Nov 27 2025, 8:57 PM

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

Address @des and @ziaee comments.

tembun_bk.ru marked 6 inline comments as done.Nov 28 2025, 7:16 AM

tembun_bk.ru edited the summary of this revision. (Show Details)Nov 28 2025, 2:51 PM

des added inline comments.Nov 28 2025, 3:56 PM

bin/sh/sh.1
257	There is no reason to capitalize this.
1123	I would move the parenthesis to right before the comma to avoid breaking up the lemma.
1951	Redundant article. I would perhaps rewrite to “The job control facility allows users”
1983	Perhaps “Additionally, the following built-in commands accept a job ID as an argument:” would be better
1988	either “see the <title> section below” or just “see <title> below”
2563	remove the final “the” here because `Ar signal` acts as a proper noun.
2568	I know that Oxford commas are controversial but the FDP mandates them (section 12).
2573	“for additional information on the meanings of these signals”
2602	Move the parenthesis to the end of the sentence, and perhaps switch to the shorter formulation that you used above.

Address @des comments.

jilles added inline comments.Nov 29 2025, 12:26 AM

bin/sh/sh.1
33	If there is substantial text copied from POSIX after all review changes, please add a notice like in share/examples/mdoc/POSIX-copyright.
1952	Might want to mention here how this can be done: Ctrl+Z (if not adjusted using stty(1)).
2534	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.
2538	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.
2556–2557	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.)
2558–2562	Perhaps add something like "This is typically because Ctrl+Z was pressed."
2563	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.

tembun_bk.ru added inline comments.Nov 29 2025, 1:18 PM

bin/sh/sh.1
1952	Then I guess we would also need to mention how to 'continue their execution at a later point' and 'run them in the foreground or in the background'? I.e. for some reason we explained 'selectively suspend the execution of processes', but forgot about other actions in this list...
2558–2562	Will this sentence better be put in parenthesis after '(see ...)', or just as a standalone sentence?

tembun_bk.ru added inline comments.Nov 29 2025, 1:32 PM

bin/sh/sh.1
2563	Indeed, thanks for that! Will it be ok if we list all of this messages (including 'Suspended') as separate `.It` items first and below write a single description, where names of the signal, which interrupted the process, will be listed in the same order as their messages?

Address some @jilles comments.

tembun_bk.ru marked 5 inline comments as done.Nov 29 2025, 5:59 PM

@jilles @des @ziaee Can we proceed with it now? Or shall we request review from someone else maybe?

I've been traveling and haven't yet had time to review the latest changes, but last I looked it was moving in the right direction. Just give me a few more days.

jilles added inline comments.Dec 7 2025, 4:46 PM

bin/sh/sh.1
1952	That would be using the `bg` and `fg` builtins.
2558–2562	I'd say a standalone sentence would be good enough.
2563	`SIGTTIN` could be described as "This is typically because the command attempted to read from the terminal while in the background." and `SIGTTOU` could be described as "This is typically because the command attempted to change terminal settings or (if `stty tostop` is in effect) write to the terminal while in the background." `SIGSTOP` can be described as a signal since it does not have common ways of generation other than `kill`.

tembun_bk.ru added inline comments.Dec 7 2025, 7:55 PM

bin/sh/sh.1
1952	Sure, but just to be sure that I understood what you mean right: we put this additional info in the parenthesis after every statement about these features in this sentence?

Address @jilles comments about signal descriptions.

@jilles did I implement the changes you asked for correctly?

Ping @des :)

jilles accepted this revision as: jilles.Dec 30 2025, 9:11 PM

Update diff with -U9999.

Ping anybody? Can it be landed now?

I'm happy to land it, but I don't know if we should wait for @des

good to go with just a few grammar nits

bin/sh/sh.1
2574	either “by `SIGTSTP`” or “by the `SIGTSTP` signal”.
2581	either “by `SIGSTOP`” or “by the `SIGSTOP` signal”.
2585	either “by `SIGTTIN`” or “by the `SIGTTIN` signal”.
2591	either “by `SIGTTOU`” or “by the `SIGTTOU` signal”.
2602	alternatively, “the signals mentioned above”.
2628	This is actually backward; POSIX considers `kill(1)` an intrinsic utility which must exist as a shell builtin and may optionally also exist as a discrete binary. But we can deal with that later.

This revision is now accepted and ready to land.Thu, Jan 22, 6:26 PM

Implement grammar improvements suggested by des.

This revision now requires review to proceed.Thu, Jan 22, 6:41 PM

@ziaee I believe it's ready now.

ziaee added inline comments.Fri, Jan 23, 8:31 PM

bin/sh/sh.1
2553	You didn't test this, you can't use Ao/Ac here.

tembun_bk.ru added inline comments.Mon, Jan 26, 9:15 PM

bin/sh/sh.1
2553	I didn't know that - as I can see, it renders fine. Is there a semantic issue here? Shall we instead use just '<space>'?

ziaee added inline comments.Mon, Jan 26, 9:43 PM

bin/sh/sh.1
2553	it renders fine. Sorry, my mistake! How are you rendering and viewing it?

tembun_bk.ru added inline comments.Mon, Jan 26, 9:52 PM

bin/sh/sh.1
2553	How are you rendering and viewing it? Just simply `man bin/sh/sh.1`. It is displayed like this: `⟨space⟩`. This is in xterm. Are there other ways to render and view the manpage? Isn't `man` sufficient?

kib added inline comments.Mon, Jan 26, 10:01 PM

bin/sh/sh.1
2553	For long and content-saturated man pages, I find it often useful to render into ps/pdf and read like an article, instead of the terminal rendering. Either mandoc bin/sh/sh.1 >/tmp/sh.1.pdf or, if groff is installed (if not installed, better install and check with groff as well) groff -Tpdf -mdoc bin/sh/sh.1 >/tmp/sh.1.pdf

tembun_bk.ru added inline comments.Mon, Jan 26, 10:10 PM

bin/sh/sh.1
2553	mandoc bin/sh/sh.1 >/tmp/sh.1.pdf I guess `mandoc -T pdf bin/sh/sh.1 >/tmp/sh.1.pdf` was meant. Thank you! I tested with both mandoc and groff and in both cases `<space>` renders good.

That syntax doesn't work for me on FreeBSD console, and I know others too, so I took it for granted. I'll dig in a bit when I get back to my desk. Just to give some idea on the range of moving parts:

Rendering with: the mandoc compiler (default, could be: groff, man-db, heirloom, others?) to render to UTF-8 (default, for mandoc could be: ascii, html, ps, PDF, md, tree; groff and heirloom has way more.

Viewing with: less (default, for utf8 could be: qman (check this out), gnome-help, khelpcenter, man.cgi, others) called by man.sh through xterm on x11 (could be: vt, syscons, wscons, Linux gettty, wayland, mac, android, iOS, firefox, typesetters supported by groff/heirloom).

Your use of angle macro instead of less-than/greater-than is correct. mandoc renders Aq/Ao/Ac to UTF-8 as Mathematical Angle Brackets (U+27E8 and U+27E9), and viewing this with the default FreeBSD console font for higher resolution displays fails because it is missing this character. I reported these upstream to the fonts author.

bin/sh/sh.1
2553	You can actually write it a little neater like this
2567
2578
2582
2588

Use Aq and Pq for brackets.

@ziaee Thank you for the explanation and the recommendations!

Ping.

This revision was not accepted when it landed; it landed in state Needs Review.Thu, Jan 29, 5:45 PM

Closed by commit rG2711852bd9ac: sh.1: Provide detailed job control documentation (authored by tembun_bk.ru, committed by ziaee). · Explain Why

This revision was automatically updated to reflect the committed changes.

ziaee added a commit: rG2711852bd9ac: sh.1: Provide detailed job control documentation.

sh.1: Provide detailed documentation for job control
ClosedPublic
Actions

Details

Diff Detail

Event Timeline

Revision Contents
Changeset List

Diff 170706

bin/sh/sh.1

sh.1: Provide detailed documentation for job controlClosedPublicActions

Details

Diff Detail

Event Timeline

Revision ContentsChangeset List

Diff 170706

bin/sh/sh.1

sh.1: Provide detailed documentation for job control
ClosedPublic
Actions

Revision Contents
Changeset List