git: dab7fc49e7a6 - main - jail: make jail(8) man page more readable and more correct

The branch main has been updated by jamie:

URL: https://cgit.FreeBSD.org/src/commit/?id=dab7fc49e7a65379a0050e8cab0b50afacdc0fc5

commit dab7fc49e7a65379a0050e8cab0b50afacdc0fc5
Author:     Jamie Gritton <jamie@FreeBSD.org>
AuthorDate: 2023-08-28 18:22:36 +0000
Commit:     Jamie Gritton <jamie@FreeBSD.org>
CommitDate: 2023-08-28 18:22:36 +0000

    jail: make jail(8) man page more readable and more correct
    
    The synopsis section of jail(8) is fine at showing everything that could
    be on the command line, but doesn't make much sense. Add some sub-
    ections for the different uses of the command.
    
    Also fix up the paragraph about command-line parameter specification,
    including removing some clearly erroneous information.
    
    Reviewed by:    dvl
    MFC after:      3 days
    Differential Revision:  https://reviews.freebsd.org/D41606
---
 usr.sbin/jail/jail.8 | 52 +++++++++++++++++++++++++++++-----------------------
 1 file changed, 29 insertions(+), 23 deletions(-)

diff --git a/usr.sbin/jail/jail.8 b/usr.sbin/jail/jail.8
index ef071aae863e..6fb5fdfa0623 100644
--- a/usr.sbin/jail/jail.8
+++ b/usr.sbin/jail/jail.8
@@ -23,32 +23,47 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd March 12, 2023
+.\" $FreeBSD$
+.\"
+.Dd August 26, 2023
 .Dt JAIL 8
 .Os
 .Sh NAME
 .Nm jail
 .Nd "manage system jails"
 .Sh SYNOPSIS
+.Ss From Configuration File
 .Nm
-.Op Fl dhilqv
-.Op Fl J Ar jid_file
-.Op Fl u Ar username
-.Op Fl U Ar username
-.Op Fl cmr
-.Ar param Ns = Ns Ar value ...
-.Op Cm command Ns = Ns Ar command ...
-.Nm
+.Op Fl cm
 .Op Fl dqv
 .Op Fl f Ar conf_file
 .Op Fl p Ar limit
-.Op Fl cmr
 .Op Ar jail
 .Nm
+.Op Fl r
 .Op Fl qv
 .Op Fl f Ar conf_file
+.Op Fl p Ar limit
+.Op Cm * | Ar jail ...
+.Ss Without Configuration File
+.Nm
+.Op Fl cm
+.Op Fl dhilqv
+.Op Fl J Ar jid_file
+.Op Fl u Ar username
+.Op Fl U Ar username
+.Ar param Ns = Ns Ar value ...
+.Op Cm command Ns = Ns Ar command ...
+.Nm
 .Op Fl rR
+.Op Fl qv
 .Op Cm * | Ar jail ...
+.Ss Show Parameters
+.Nm
+.Op Fl f Ar conf_file
+.Fl e
+.Ar separator
+.Ss Backward Compatibility
 .Nm
 .Op Fl dhilqv
 .Op Fl J Ar jid_file
@@ -58,10 +73,6 @@
 .Op Fl s Ar securelevel
 .Ar path hostname ip Ns Op Cm \&, Ns Ar ...
 .Ar command ...
-.Nm
-.Op Fl f Ar conf_file
-.Fl e
-.Ar separator
 .Sh DESCRIPTION
 The
 .Nm
@@ -238,10 +249,10 @@ would apply to jails with names like
 and
 .Dq foo.bar.baz .
 .Pp
-A jail may be specified with parameters directly on the command line.
-In this case, the
-.Xr jail.conf 5
-file will not be used.
+A jail may also be specified via parameters directly on the command line in
+.Dq name=value
+form, ignoring the contents of
+.Xr jail.conf 5 .
 For backward compatibility, the command line may also have four fixed
 parameters, without names:
 .Ar path ,
@@ -249,11 +260,6 @@ parameters, without names:
 .Ar ip ,
 and
 .Ar command .
-This mode will always create a new jail, and the
-.Fl c
-and
-.Fl m
-options do not apply (and must not be present).
 .Ss Jail Parameters
 Parameters in the
 .Xr jail.conf 5