jail.conf(5): emphasize where to find jail parameters

[fernape]

Summary

Some people expect jail.conf(5) to have a list of jail parameters.
jail(8) contains a comprehensive list of all parameters to be used during jail
invocation or in jail.conf.

Highlighting where to look for jail parameters seems a reasonable solution.

PR: 244569
Reported by: joneum@

Test Plan

• mandoc -Tlint clean
• igor clean (warnings not related to this change)
• aspell happy
• man ./jail.conf.5 renders the page properly

Deferring .Dd bump until commit time.

There are some warnings reported by igor that could be fixed. But I think it
is better to do it in a different commit:

jail.conf.5:34:.Sh DESCRIPTION used here:but .Sh SYNOPSIS has not been defined
jail.conf.5:99:contraction:A token is any sequence of characters that [aren't] considered special in
jail.conf.5:147:no comma after "e.g.":This is useful for wildcard parameters based on [e.g.] a jail's name.
jail.conf.5:178:no comma after "i.e.":Comments are legal wherever whitespace is allowed, [i.e.] anywhere except

[debdrup]

I'm not sure I like the idea of putting emphasis on an entire sentence either via italics or underlining, as I haven't seen that done in any other manual page.

usr.sbin/jail/jail.conf.5

62–67

[fernape]

In D28701#642444, @debdrup wrote:

I'm not sure I like the idea of putting emphasis on an entire sentence either via italics or underlining, as I haven't seen that done in any other manual page.

There are some examples:

/share/man/man9/bus_dma.9:.Em Note: The use of filters is deprecated. Proper operation is not guaranteed.
./share/man/man9/bus_dma.9:.Em Note: The use of filters is deprecated. Proper operation is not guaranteed.

./share/man/man9/sysctl.9:.Em "Care should be taken to free all OIDs once they are no longer needed!"
./share/man/man9/sysctl_add_oid.9:.Em WARNING : "use recursive deletion with extreme caution" !

./usr.bin/chpass/chpass.1:.Em "Only the shell and GECOS information may be changed" .
./usr.bin/chpass/chpass.1:.Em "Password authentication is required" .
./usr.bin/chpass/chpass.1:.Em "Adding new records to the local password database is discouraged" .
./usr.bin/chpass/chpass.1:.Em "Password changes are not permitted".

But I'm open to ideas :-)

Maybe moving this to its own paragraph right after the "Parameters" section?

See jail(8) for a list of jail parameters passed to the
kernel, as well as internal parameters used when creating and removing
jails.

[debdrup]

I would argue those are important notes, and not simple sentences as this one appears to be, but I'm not going to block you from commiting it, and will defer to anyone else who's tagged as a reviewer. :)

[fernape]

In D28701#642452, @debdrup wrote:

I would argue those are important notes, and not simple sentences as this one appears to be, but I'm not going to block you from commiting it, and will defer to anyone else who's tagged as a reviewer. :)

Yes, I agree. Don't worry I will not commit anything yet, I'm being mentored here. Thanks for the input though.

[fernape]

Highlight just a portion of the relevant info.

debdrup@ expressed concerns abut highlighting the whole sentences since this is
not a very important notes/warnins.

This might be enough to catch the eye of the readers at a first glance.

[0mp]

Let's do it!