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

Authored by fernape on Feb 16 2021, 11:53 AM.

Details

Reviewers

0mp
gbe

Group Reviewers

manpages

Commits

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

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

Diff Detail

Repository

rS FreeBSD src repository - subversion

Lint

Lint Passed

Unit

No Test Coverage

Build Status

Buildable 37306
Build 34195: arc lint + arc unit

Event Timeline

fernape created this revision.Feb 16 2021, 11:53 AM

Herald added a reviewer: manpages. · View Herald TranscriptFeb 16 2021, 11:53 AM

Herald added a subscriber: imp. · View Herald Transcript

Harbormaster completed remote builds in B37049: Diff 84001.Feb 16 2021, 11:53 AM

fernape requested review of this revision.Feb 16 2021, 11:53 AM

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

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.

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

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.

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.

Harbormaster completed remote builds in B37306: Diff 84544.Feb 23 2021, 2:21 PM

Let's do it!

This revision is now accepted and ready to land.Apr 17 2021, 9:55 PM

Closed by commit rG8b1a5062e054: jail.conf(5): emphasize where to find jail parameters (authored by fernape). · Explain WhyApr 18 2021, 4:03 PM

This revision was automatically updated to reflect the committed changes.

fernape added a commit: rG8b1a5062e054: jail.conf(5): emphasize where to find jail parameters.