git: 77fd0356efa8 - main - pw.8: Use more appropriate mdoc macros
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Fri, 01 Apr 2022 22:52:05 UTC
The branch main has been updated by 0mp (doc, ports committer): URL: https://cgit.FreeBSD.org/src/commit/?id=77fd0356efa8a956a616ca8d7a51701cec426c88 commit 77fd0356efa8a956a616ca8d7a51701cec426c88 Author: Mateusz Piotrowski <0mp@FreeBSD.org> AuthorDate: 2022-04-01 11:52:39 +0000 Commit: Mateusz Piotrowski <0mp@FreeBSD.org> CommitDate: 2022-04-01 22:49:53 +0000 pw.8: Use more appropriate mdoc macros MFC after: 1 week --- 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