[Bug 264317] handbook/jails: Mounting devfs in a jail is explained only for readers installing from source

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=264317

            Bug ID: 264317
           Summary: handbook/jails: Mounting devfs in a jail is explained
                    only for readers installing from source
           Product: Documentation
           Version: Latest
          Hardware: Any
                OS: Any
            Status: New
          Keywords: patch
          Severity: Affects Some People
          Priority: ---
         Component: Documentation
          Assignee: doc@FreeBSD.org
          Reporter: bspiegel100@gmail.com

Created attachment 234299
  --> https://bugs.freebsd.org/bugzilla/attachment.cgi?id=234299&action=edit
patch with email headers and commit message

In the Jails chapter of the handbook, the concept of mounting devfs in a jail
is introduced under "To build and install a Jail from source." If a reader
installs from the Internet or an ISO instead of from source, they might skip
that section. 

Then, the next section, "Configuring the Host," uses the devfs_ruleset and
mount.devfs arguments. Readers skipped the section about installing from source
haven't learned these arguments yet. This issue tripped me up the first time I
read the chapter.

Attached is a patch with the following changes:

1. Remove the mount.devfs line from "To build and install a Jail from source."
As of FreeBSD 12.3, it's gone from the cited man page example, anyway.

2. Move the explanation for that line to "Configuring the Host," building on
the idea of replicating a real FreeBSD system in the jail.

3. Update the explanation to mention that a reasonable default ruleset is used
if devfs_ruleset is not defined.

There are a few other points I didn't address. For example, "doing nasty stuff"
is a little dubious, and the jail(8) man page has some other deltas with "To
build and install a Jail from source."  I'd be happy do some more work here or
in a separate patch if you think these are important to fix. 

This is my first time submitting a patch here. I'm a bit confused about the
best way to do so, so I've two copies, one with email headers and commit
message and one as plain diff in a .txt file. Thanks for considering!

-- 
You are receiving this mail because:
You are the assignee for the bug.