git: eecae51acfc0 - stable/12 - pw.8: Use more appropriate mdoc macros

The branch stable/12 has been updated by 0mp (doc, ports committer):

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

commit eecae51acfc09397dd481d7b4130fd690e1ac68c
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2022-04-01 11:52:39 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2022-04-08 08:59:34 +0000

    pw.8: Use more appropriate mdoc macros
    
    MFC after:      1 week
    
    (cherry picked from commit 77fd0356efa8a956a616ca8d7a51701cec426c88)
---
 usr.sbin/pw/pw.8 | 107 ++++++++++++++++++++++++++++++-------------------------
 1 file changed, 58 insertions(+), 49 deletions(-)

diff --git a/usr.sbin/pw/pw.8 b/usr.sbin/pw/pw.8
index f7b6a8a4830b..2ea9729c1031 100644
--- a/usr.sbin/pw/pw.8
+++ b/usr.sbin/pw/pw.8
@@ -321,9 +321,9 @@ databases.
 .El
 .Sh USER OPTIONS
 The following options apply to the
-.Ar useradd
+.Cm useradd
 and
-.Ar usermod
+.Cm usermod
 commands:
 .Bl -tag -width "-G grouplist"
 .It Oo Fl n Oc Ar name
@@ -332,15 +332,16 @@ Required unless
 is given.
 Specify the user/account name.
 In the case of
-.Ar usermod
-can be a uid.
+.Cm usermod
+can be a
+.Ar uid .
 .It Fl u Ar uid
 Required if
 .Ar name
 is not given.
 Specify the user/account numeric id.
 In the case of
-.Ar usermod
+.Cm usermod
 if paired with
 .Ar name ,
 changes the numeric id of the named user/account.
@@ -349,22 +350,22 @@ Usually, only one of these options is required,
 as the account name will imply the uid, or vice versa.
 However, there are times when both are needed.
 For example, when changing the uid of an existing user with
-.Ar usermod ,
+.Cm usermod ,
 or overriding the default uid when creating a new account with
-.Ar useradd .
+.Cm useradd .
 To automatically allocate the uid to a new user with
-.Ar useradd ,
+.Cm useradd ,
 then do
 .Em not
 use the
 .Fl u
 option.
 Either the account or userid can also be provided immediately after the
-.Ar useradd ,
-.Ar userdel ,
-.Ar usermod
+.Cm useradd ,
+.Cm userdel ,
+.Cm usermod ,
 or
-.Ar usershow
+.Cm usershow
 keywords on the command line without using the
 .Fl n
 or
@@ -444,7 +445,7 @@ This option instructs
 .Nm
 to attempt to create the user's home directory.
 While primarily useful when adding a new account with
-.Ar useradd ,
+.Cm useradd ,
 this may also be of use when moving an existing user's home directory elsewhere
 on the file system.
 The new home directory is populated with the contents of the
@@ -459,7 +460,7 @@ prefix will be stripped.
 When
 .Fl m
 is used on an account with
-.Ar usermod ,
+.Cm usermod ,
 existing configuration files in the user's home directory are
 .Em not
 overwritten from the skeleton files.
@@ -469,7 +470,7 @@ it will by default be a subdirectory of the
 .Ar basehome
 directory as specified by the
 .Fl b
-option (see below), bearing the name of the new account.
+option, bearing the name of the new account.
 This can be overridden by the
 .Fl d
 option on the command line, if desired.
@@ -556,7 +557,7 @@ suitable for writing directly to the password database.
 .El
 .Pp
 It is possible to use
-.Ar useradd
+.Cm useradd
 to create a new account that duplicates an existing user id.
 While this is normally considered an error and will be rejected, the
 .Fl o
@@ -568,7 +569,7 @@ directory, different shell) while providing basically the same
 permissions for access to the user's files in each account.
 .Pp
 The
-.Ar useradd
+.Cm useradd
 command also has the ability to set new user and group defaults by using the
 .Fl D
 option.
@@ -653,8 +654,8 @@ See description of
 .Fl k
 for naming conventions of these files.
 .It Xo
-.Fl u Ar min , Ns Ar max ,
-.Fl i Ar min , Ns Ar max
+.Fl u Ar min Ns Cm \&, Ns Ar max ,
+.Fl i Ar min Ns Cm \&, Ns Ar max
 .Xc
 Set the minimum and maximum user and group ids allocated for new
 accounts and groups created by
@@ -678,20 +679,20 @@ accounts.
 is one of:
 .Pp
 .Bl -tag -width random -offset indent -compact
-.It no
+.It Cm no
 disable login on newly created accounts
-.It yes
+.It Cm yes
 force the password to be the account name
-.It none
+.It Cm none
 force a blank password
-.It random
+.It Cm random
 generate a random password
 .El
 .Pp
 The
-.Ql \&random
+.Cm random
 or
-.Ql \&no
+.Cm no
 methods are the most secure; in the former case,
 .Nm
 generates a password and prints it to stdout,
@@ -700,7 +701,7 @@ to select their own
 .Pq possibly poorly chosen
 password.
 The
-.Ql \&no
+.Cm no
 method requires that the superuser use
 .Xr passwd 1
 to render the account accessible with a password.
@@ -718,7 +719,7 @@ servers.
 .El
 .Pp
 The
-.Ar userdel
+.Cm userdel
 command has three distinct options.
 The
 .Fl n Ar name
@@ -736,7 +737,9 @@ The
 utility errs on the side of caution when removing files from the system.
 Firstly,
 it will not do so if the uid of the account being removed is also used by
-another account on the system, and the 'home' directory in the password file is
+another account on the system, and the
+.Dq home
+directory in the password file is
 a valid path that commences with the character
 .Ql \&/ .
 Secondly, it will only remove files and directories that are actually owned by
@@ -746,26 +749,28 @@ will be removed.
 If any additional cleanup work is required, this is left to the administrator.
 .El
 .Pp
-Mail spool files and crontabs are always removed when an account is deleted as
+Mail spool files and
+.Xr crontab 5
+files are always removed when an account is deleted as
 these are unconditionally attached to the user name.
 Jobs queued for processing by
-.Ar at
+.Xr at 1
 are also removed if the user's uid is unique and not also used by another
 account on the system.
 .Pp
 The
-.Ar usermod
+.Cm usermod
 command adds one additional option:
 .Bl -tag -width "-G grouplist"
 .It Fl l Ar newname
 This option allows changing of an existing account name to
-.Ql \&newname .
+.Ar newname .
 The new name must not already exist, and any attempt to duplicate an
 existing account name will be rejected.
 .El
 .Pp
 The
-.Ar usershow
+.Cm usershow
 command allows viewing of an account in one of two formats.
 By default, the format is identical to the format used in
 .Pa /etc/master.passwd
@@ -789,7 +794,7 @@ forces
 to print the details of an account even if it does not exist.
 .Pp
 The command
-.Ar usernext
+.Cm usernext
 returns the next available user and group ids separated by a colon.
 This is normally of interest only to interactive scripts or front-ends
 that use
@@ -809,7 +814,7 @@ Required unless
 is given.
 Specify the group name.
 In the case of
-.Ar groupmod
+.Cm groupmod
 can be a gid.
 .It Fl g Ar gid
 Required if
@@ -817,7 +822,7 @@ Required if
 is not given.
 Specify the group numeric id.
 In the case of
-.Ar groupmod
+.Cm groupmod
 if paired with
 .Ar name ,
 changes the numeric id of the named group.
@@ -829,8 +834,10 @@ You will only need to use both when setting a specific group id
 against a new group or when changing the uid of an existing group.
 .It Fl M Ar memberlist
 This option provides an alternative way to add existing users to a
-new group (in groupadd) or replace an existing membership list (in
-groupmod).
+new group
+.Pq in Cm groupadd
+or replace an existing membership list
+.Pq in Cm groupmod .
 .Ar memberlist
 is a comma separated list of valid and existing user names or uids.
 .It Fl m Ar newmembers
@@ -853,7 +860,7 @@ Login names or user ids may be used, and duplicate users are
 silently eliminated.
 .El
 .Pp
-.Ar groupadd
+.Cm groupadd
 also has a
 .Fl o
 option that allows allocation of an existing group id to a new group.
@@ -862,21 +869,21 @@ and this option overrides the check for duplicate group ids.
 There is rarely any need to duplicate a group id.
 .Pp
 The
-.Ar groupmod
+.Cm groupmod
 command adds one additional option:
 .Bl -tag -width "-m newmembers"
 .It Fl l Ar newname
 This option allows changing of an existing group name to
-.Ql \&newname .
+.Ar newname .
 The new name must not already exist,
 and any attempt to duplicate an existing group
 name will be rejected.
 .El
 .Pp
 Options for
-.Ar groupshow
+.Cm groupshow
 are the same as for
-.Ar usershow ,
+.Cm usershow ,
 with the
 .Fl g Ar gid
 replacing
@@ -885,11 +892,11 @@ to specify the group id.
 The
 .Fl 7
 option does not apply to the
-.Ar groupshow
+.Cm groupshow
 command.
 .Pp
 The command
-.Ar groupnext
+.Cm groupnext
 returns the next available group id on standard output.
 .Sh USER LOCKING
 The
@@ -899,13 +906,13 @@ supports a simple password locking mechanism for users; it works by
 prepending the string
 .Ql *LOCKED*
 to the beginning of the password field in
-.Pa master.passwd
+.Xr master.passwd 5
 to prevent successful authentication.
 .Pp
 The
-.Ar lock
+.Cm lock
 and
-.Ar unlock
+.Cm unlock
 commands take a user name or uid of the account to lock or unlock,
 respectively.
 The
@@ -919,7 +926,9 @@ For a summary of options available with each command, you can use
 .Dl pw [command] help
 For example,
 .Dl pw useradd help
-lists all available options for the useradd operation.
+lists all available options for the
+.Cm useradd
+operation.
 .Pp
 The
 .Nm