mdoc(7) police: overhaul.

Approved by:	re

2 files changed, 272 insertions, 182 deletions

diff --git a/adduser/adduser.8 b/adduser/adduser.8
index 9a3eea4..4af1ef7 100644
--- a/adduser/adduser.8
+++ b/adduser/adduser.8
@@ -34,7 +34,6 @@
 .Nd command for adding new users
 .Sh SYNOPSIS
 .Nm
-.Bk -words
 .Op Fl CENhq
 .Op Fl G Ar groups
 .Op Fl L Ar login_class
@@ -45,33 +44,35 @@
 .Op Fl s Ar shell
 .Op Fl u Ar uid_start
 .Op Fl w Ar type
-.Ek
 .Sh DESCRIPTION
 The
-.Nm adduser
-program is a shell script, implemented around the
+.Nm
+utility is a shell script, implemented around the
 .Xr pw 8
 command, for adding new users.
 It creates passwd/group entries, a home directory,
 copies dotfiles and sends the new user a welcome message.
-It supports two modes of operation. It may be used interactively
-at the command line to add one user at a time or it may be directed
+It supports two modes of operation.
+It may be used interactively
+at the command line to add one user at a time, or it may be directed
 to get the list of new users from a file and operate in batch mode
 without requiring any user interaction.
 .Sh RESTRICTIONS
-.Bl -tag -width Ds -compact
-.It Sy username
+.Bl -tag -width indent
+.It username
 Login name.
 The user name is restricted to whatever
 .Xr pw 8
-will accept. Generally this means it
+will accept.
+Generally this means it
 may contain only lowercase characters or digits.
 Maximum length
 is 16 characters.
-The reasons for this limit are "Historical".
+The reasons for this limit are historical.
 Given that people have traditionally wanted to break this
-limit for aesthetic reasons, it's never been of great importance to break
-such a basic fundamental parameter in UNIX.
+limit for aesthetic reasons, it has never been of great importance to break
+such a basic fundamental parameter in
+.Ux .
 You can change
 .Dv UT_NAMESIZE
 in
@@ -84,94 +85,113 @@ The NIS protocol mandates an 8-character username.
 If you need a longer login name for e-mail addresses,
 you can define an alias in
 .Pa /etc/mail/aliases .
-.It Sy full name
+.It "full name"
 This is typically known as the gecos field and usually contains
-the user's full name. Additionally, it may contain a comma separated
-list of values such as office number and work and home phones. If the
+the user's full name.
+Additionally, it may contain a comma separated
+list of values such as office number and work and home phones.
+If the
 name contains an amperstand it will be replaced by the capitalized
 login name when displayed by other programs.
 The
-.Ql Pa \&:
+.Ql \&:
 character is not allowed.
-.It Sy shell
-Only valid shells from the shell database (/etc/shells) are allowed. In
+.It shell
+Only valid shells from the shell database
+.Pq Pa /etc/shells
+are allowed.
+In
 addition, only the base name of the shell is necessary, not the full path.
-.It Sy uid
-Automatically generated or your choice. It must be less than 32000.
-.It Sy gid/login group
-Automatically generated or your choice. It must be less than 32000.
-.It Sy password
+.It UID
+Automatically generated or your choice.
+It must be less than 32000.
+.It "GID/login group"
+Automatically generated or your choice.
+It must be less than 32000.
+.It password
 You may choose an empty password, disable the password, use a
 randomly generated password or specify your own plaintext password,
 which will be encrypted before being stored in the user database.
 .El
 .Sh UNIQUE GROUPS
-Perhaps you're missing what
+Perhaps you are missing what
 .Em can
 be done with this scheme that falls apart
 with most other schemes.
-With each user in his/her own group the user can
+With each user in his/her own group, the user can
 safely run with a umask of 002 instead of the usual 022
 and create files in their home directory
 without worrying about others being able to change them.
 .Pp
-For a shared area you create a separate uid/gid (like cvs or ncvs on freefall),
+For a shared area you create a separate UID/GID (like cvs or ncvs on freefall),
 you place each person that should be able to access this area into that new
 group.
 .Pp
-This model of uid/gid administration allows far greater flexibility than lumping
+This model of UID/GID administration allows far greater flexibility than lumping
 users into groups and having to muck with the umask when working in a shared
 area.
 .Pp
 I have been using this model for almost 10 years and found that it works
-for most situations, and has never gotten in the way.  (Rod Grimes)
+for most situations, and has never gotten in the way.
+(Rod Grimes)
 .Sh CONFIGURATION
 The
 .Nm
 utility reads its configuration information from
-.Ar /etc/adduser.conf .
-If this file does not exist it will use predefined defaults. While
-this file may be edited by hand the safer option is to use the
-.Op Fl C
-command line argument. With this argument
+.Pa /etc/adduser.conf .
+If this file does not exist, it will use predefined defaults.
+While this file may be edited by hand,
+the safer option is to use the
+.Fl C
+command line argument.
+With this argument,
 .Nm
 will start interactive input, save the answers to its prompts in
-.Ar /etc/adduser.conf ,
+.Pa /etc/adduser.conf ,
 and promptly exit without modifying the user
-database. Options specified on the command line will take precedence over
+database.
+Options specified on the command line will take precedence over
 any values saved in this file.
 .Sh OPTIONS
-.Bl -tag -width Ds
+.Bl -tag -width indent
 .It Fl C
-Create new configuration file and exit. This option is mutually exclusive
-with the
-.Op Fl f
+Create new configuration file and exit.
+This option is mutually exclusive with the
+.Fl f
 option.
 .It Fl d Ar partition
-Home partition. Default partition, under which all user directories
+Home partition.
+Default partition, under which all user directories
 will be located.
 .It Fl E
-Disable the account. This option will lock the account by prepending
-the string *LOCKED* to the password field. The account may be unlocked
+Disable the account.
+This option will lock the account by prepending the string
+.Dq Li *LOCKED*
+to the password field.
+The account may be unlocked
 by the super-user with the
 .Xr pw 8
 command:
 .Pp
-.Dl "pw unlock [name|uid]"
+.D1 Nm pw Cm unlock Op Ar name | uid
 .It Fl f Ar file
 Get the list of accounts to create from
 .Ar file .
 If
 .Ar file
-is '`-'', then get the list from standard input. If this option
-is specified
+is
+.Dq Fl ,
+then get the list from standard input.
+If this option is specified,
 .Nm
-will operate in batch mode and will not seek any user input. If an
-error is encountered while processing an account it will write a
-message to standard error and move to the next account. The format
+will operate in batch mode and will not seek any user input.
+If an error is encountered while processing an account, it will write a
+message to standard error and move to the next account.
+The format
 of the input file is described below.
 .It Fl G Ar groups
-Additional group(s). By default the user name is used as the login group.
+Additional groups.
+By default, the user name is used as the login group.
 This option allows the user to specify additional groups to add users to.
 .It Fl h
 Print a summary of options and exit.
@@ -179,131 +199,179 @@ Print a summary of options and exit.
 Copy files from
 .Ar directory
 into the home
-directory of new users,
-.Ql Pa dot.foo
+directory of new users;
+.Pa dot.foo
 will be renamed to
-.Ql Pa .foo .
+.Pa .foo .
 .It Fl L Ar login_class
 Set default login class.
 .It Fl m Ar file
 Send new users a welcome message from
 .Ar file .
 Specifying a value of
-.Ar no
+.Cm no
 for
 .Ar file
-causes no message to be sent to new users. Please note that the message
+causes no message to be sent to new users.
+Please note that the message
 file can reference the internal variables of the
 .Nm
 script.
 .It Fl N
 Do not read the default configuration file.
 .It Fl q
-Minimal user feedback. In particular, the random password will not be echoed to
+Minimal user feedback.
+In particular, the random password will not be echoed to
 standard output.
 .It Fl s Ar shell
-Default shell for new users. The
+Default shell for new users.
+The
 .Ar shell
-argument must be the base name of the shell , NOT the full path.
+argument must be the base name of the shell,
+.Em not
+the full path.
 It must exist in
-.Ar /etc/shells
+.Pa /etc/shells
 to be considered a valid shell.
 .It Fl u Ar uid
-Use uid's from
+Use UIDs from
 .Ar uid
 on up.
 .It Fl w Ar type
-Password type. The
+Password type.
+The
 .Nm
 utility allows the user to specify what type of password to create.
 The
 .Ar type
 argument may have one of the following values:
-.Bl -tag -width ".Dv random"
-.It Dv no
-Disable the password. Instead of an encrypted string the passowrd field
-will contain a single '`*'' character.
-The user may not login until the super-user
+.Bl -tag -width ".Cm random"
+.It Cm no
+Disable the password.
+Instead of an encrypted string, the passowrd field will contain a single
+.Ql *
+character.
+The user may not log in until the super-user
 manually enables the password.
-.It Dv none
+.It Cm none
 Use an empty string as the password.
-.It Dv yes
-Use a user supplied string as the password. In interactive mode
-the user will be prompted for the password. In batch mode, the
+.It Cm yes
+Use a user-supplied string as the password.
+In interactive mode,
+the user will be prompted for the password.
+In batch mode, the
 last (10th) field in the line is assumed to be the password.
-.It Dv random
-Generate a random string and use it as a password. The password will
-be echoed to standard output. In addition it will be available for
-inclusion in the message file in the
-.Ar randompass
-environment variable.
+.It Cm random
+Generate a random string and use it as a password.
+The password will be echoed to standard output.
+In addition, it will be available for inclusion in the message file in the
+.Va randompass
+variable.
+.El
 .El
 .Sh FORMAT
-.Bl -tag -width Ds -compact
 When the
-.Op Fl f
-option is used the account information must be stored in a specific
-format. All empty lines or lines beginning with a
-.Ql Pa #
-will be ignored. All other lines must contain ten colon (:) separated
-fields as described below. Command line options do not take precedence
-over values in the fields. Only the password field may contain a
-.Ql Pa :
+.Fl f
+option is used, the account information must be stored in a specific
+format.
+All empty lines or lines beginning with a
+.Ql #
+will be ignored.
+All other lines must contain ten colon
+.Pq Ql \&:
+separated fields as described below.
+Command line options do not take precedence
+over values in the fields.
+Only the password field may contain a
+.Ql \&:
 character as part of the string.
 .Pp
-.Dl "name:uid:gid:class:change:expire:gecos:home_dir:shell:password"
-.Bl -tag -width ".Dv password"
-.It Dv name
-Login name. This field may not be empty.
-.It Dv uid
-Numeric login user id. If this field is left empty it will be automatically
-generated.
-.It Dv gid
-Numeric primary group id. If this field is left empty a group with the
-same name as the user name will be created and its gid will be used
+.Sm off
+.D1 Ar name : uid : gid : class : change : expire : gecos : home_dir : shell : password
+.Sm on
+.Bl -tag -width ".Ar password"
+.It Ar name
+Login name.
+This field may not be empty.
+.It Ar uid
+Numeric login user ID.
+If this field is left empty, it will be automatically generated.
+.It Ar gid
+Numeric primary group ID.
+If this field is left empty, a group with the
+same name as the user name will be created and its GID will be used
 instead.
-.It Dv class
-Login class. This field may be left empty.
-.It Dv change
+.It Ar class
+Login class.
+This field may be left empty.
+.It Ar change
 Password ageing.
-This field denotes the password change date for the account. The format of this
-field is the same as the format of the
-.Op Fl p
+This field denotes the password change date for the account.
+The format of this field is the same as the format of the
+.Fl p
 argument to
 .Xr pw 8 .
-It may be 'dd-mmm-yy[yy]', where 'dd' is for the day, 'mmm' is for the month
-in numeric or alphabetical format: '10 or Oct', and 'yy[yy]' is the four or two digit year.
-To denote a time relative to the current date the format
-is: '+n[mhdwoy]', where 'n' denotes a number, followed by the Minutes, Hours,
-Days, Weeks, Months or Years after which the password must be changed. 
+It may be
+.Ar dd Ns - Ns Ar mmm Ns - Ns Ar yy Ns Op Ar yy ,
+where
+.Ar dd
+is for the day,
+.Ar mmm
+is for the month in numeric or alphabetical format:
+.Dq Li 10
+or
+.Dq Li Oct ,
+and
+.Ar yy Ns Op Ar yy
+is the four or two digit year.
+To denote a time relative to the current date the format is:
+.No + Ns Ar n Ns Op Ar mhdwoy ,
+where
+.Ar n
+denotes a number, followed by the minutes, hours, days, weeks,
+months or years after which the password must be changed.
+This field may be left empty to turn it off.
+.It Ar expire
+Account expiration.
+This field denotes the expiry date of the account.
+The account may not be used after the specified date.
+The format of this field is the same as that for password ageing.
 This field may be left empty to turn it off.
-.It Dv expire
-Account expiration. This field denotes the expiry date of the account. The account may
-not be used after the specified date. The format of this field is the same as that
-for password ageing. This field may be left empty to turn it off.
-.It Dv gecos
+.It Ar gecos
 Full name and other extra information about the user.
-.It Dv home_dir
-Home directory. If this field is left empty it will be automatically
+.It Ar home_dir
+Home directory.
+If this field is left empty, it will be automatically
 created by appending the username to the home partition.
-.It Dv shell
-Login Shell. This field should contain the full path to a valid login shell.
-.It Dv password
-User password. This field should contain a plaintext string, which will
-be encrypted before being placed in the user database. If the password type is 'yes'
-and this field is empty it is assumed the account will have any empty password. If
-the password type is 'random' and this field is NOT empty its contents will be used
-as a password. This field will be ignored if the
-.Op Fl p
-flag is used with a
-.Ar no
+.It Ar shell
+Login shell.
+This field should contain the full path to a valid login shell.
+.It Ar password
+User password.
+This field should contain a plaintext string, which will
+be encrypted before being placed in the user database.
+If the password type is
+.Cm yes
+and this field is empty, it is assumed the account will have an empty password.
+If the password type is
+.Cm random
+and this field is
+.Em not
+empty, its contents will be used
+as a password.
+This field will be ignored if the
+.Fl p
+option is used with a
+.Cm no
 or
-.Ar none
-argument. Be carefull not to terminate this field with a closing ':' because it will
-be treated as part of the password.
+.Cm none
+argument.
+Be carefull not to terminate this field with a closing
+.Ql \&:
+because it will be treated as part of the password.
 .El
 .Sh FILES
-.Bl -tag -width /etc/master.passwdxx -compact
+.Bl -tag -width ".Pa /etc/adduser.message" -compact
 .It Pa /etc/master.passwd
 user database
 .It Pa /etc/group
@@ -313,13 +381,16 @@ shell database
 .It Pa /etc/login.conf
 login classes database
 .It Pa /etc/adduser.conf
-configuration file for adduser
+configuration file for
+.Nm
 .It Pa /etc/adduser.message
-message file for adduser
+message file for
+.Nm
 .It Pa /usr/share/skel
 skeletal login directory
 .It Pa /var/log/adduser
-logfile for adduser
+logfile for
+.Nm
 .El
 .Sh SEE ALSO
 .Xr chpass 1 ,
@@ -340,22 +411,31 @@ The
 command appeared in
 .Fx 2.1 .
 .Sh AUTHORS
-This manual page and the original script, in perl, was written by
-.An Wolfram Schneider <wosch@FreeBSD.org>. The replacement script, written as a Bourne
+.An -nosplit
+This manual page and the original script, in Perl, was written by
+.An Wolfram Schneider Aq wosch@FreeBSD.org .
+The replacement script, written as a Bourne
 shell script with some enhancements, and the man page modification that
 came with it were done by
-.An Mike Makonnen <mtm@identd.net> .
+.An Mike Makonnen Aq mtm@identd.net .
 .Sh BUGS
 In order for
 .Nm
-to correctly expand variables such as $username and $randompass in the message sent
-to new users it must let the shell evaluate each line of the message file. This means
-that shell commands can also be embedded in the message file. The
+to correctly expand variables such as
+.Va $username
+and
+.Va $randompass
+in the message sent to new users, it must let the shell evaluate
+each line of the message file.
+This means that shell commands can also be embedded in the message file.
+The
 .Nm
-utility attemps to mitigate the possibility of an attacker using this feature by
-refusing to evaluate the file if it is not owned and writeable only by the root user.
-In addition, shell special characters and operators will have to be escaped when
-used in the message file.
+utility attemps to mitigate the possibility of an attacker using this
+feature by refusing to evaluate the file if it is not owned and writeable
+only by the root user.
+In addition, shell special characters and operators will have to be
+escaped when used in the message file.
 .Pp
-Also, password ageing and account expiry times are currently setable only in batch mode.
+Also, password ageing and account expiry times are currently setable
+only in batch mode.
 The user should be able to set them in interactive mode as well.
diff --git a/adduser/rmuser.8 b/adduser/rmuser.8
index 85d6657..e27241a 100644
--- a/adduser/rmuser.8
+++ b/adduser/rmuser.8
@@ -31,7 +31,7 @@
 .Os
 .Sh NAME
 .Nm rmuser
-.Nd removes users from the system
+.Nd remove users from the system
 .Sh SYNOPSIS
 .Nm
 .Op Fl y
@@ -41,8 +41,8 @@
 The
 .Nm
 utility removes one or more users submitted on the command line
-or from a file. In removing a user from the system, this utility
-.Pp
+or from a file.
+In removing a user from the system, this utility:
 .Bl -enum
 .It
 Removes the user's
@@ -53,7 +53,9 @@ Removes any
 .Xr at 1
 jobs belonging to the user.
 .It
-Sends a SIGKILL signal to all processes owned by the user.
+Sends a
+.Dv SIGKILL
+signal to all processes owned by the user.
 .It
 Removes the user from the system's local password file.
 .It
@@ -61,13 +63,12 @@ Removes the user's home directory (if it is owned by the user),
 including handling of symbolic links in the path to the actual home
 directory.
 .It
-Removes the incoming mail and pop daemon mail files belonging to the
+Removes the incoming mail and POP daemon mail files belonging to the
 user from
 .Pa /var/mail .
 .It
 Removes all files owned by the user from
-.Pa /tmp ,
-.Pa /var/tmp ,
+.Pa /tmp , /var/tmp ,
 and
 .Pa /var/tmp/vi.recover .
 .It
@@ -76,66 +77,76 @@ Removes the username from all groups to which it belongs in
 (If a group becomes empty and the group name is the same as the username,
 the group is removed; this complements
 .Xr adduser 8 Ns 's
-per-user unique groups).
+per-user unique groups.)
 .El
 .Pp
-The 
+The
 .Nm
-utility refuses to remove users whose uid is 0 (typically root), since
+utility refuses to remove users whose UID is 0 (typically root), since
 certain actions (namely, killing all the user's processes, and perhaps
 removing the user's home directory) would cause damage to a running system.
-If it is necessary to remove a user whose uid is 0, see
+If it is necessary to remove a user whose UID is 0, see
 .Xr vipw 8
-for information on directly editing the password file
+for information on directly editing the password file.
 .Pp
 If
 .Nm
 was not invoked with the
 .Fl y
-switch it will
+option, it will
 show the selected user's password file entry and ask for confirmation
-that the user be removed.  It will then ask for confirmation to delete
-the user's home directory. If the answer is in the affirmative, the home
+that the user be removed.
+It will then ask for confirmation to delete
+the user's home directory.
+If the answer is in the affirmative, the home
 directory and any files and subdirectories under it will be deleted only if
-they are owned by the user. See
+they are owned by the user.
+See
 .Xr pw 8
 for more details.
 .Pp
 As
 .Nm
-operates, it informs the user regarding the current activity.  If any
+operates, it informs the user regarding the current activity.
+If any
 errors occur, they are posted to standard error and, if it is possible for
 .Nm
 to continue, it will.
 .Pp
-Available options:
-.Pp
-.Bl -tag -width username
-.It Fl y
-Implicitly answer "yes" to any and all prompts. Currently this includes
-prompts on whether to remove the specified user and whether to remove
-the home directory. This option requires that either the
-.Fl f
-option be used or one or more user names be given as commmand line
-arguments.
-.It Fl f
+The options are as follows:
+.Bl -tag -width ".Ar username"
+.It Fl f Ar file
 The
 .Nm
 utility will get a list of users to be removed from
 .Ar file ,
-which will contain one user per line. Anything following a hash mark (#),
+which will contain one user per line.
+Anything following a hash mark
+.Pq Ql # ,
 including the hash mark itself, is considered a comment and will not
-be processed. If the file is owned by anyone other than a user with
-uid 0 or is writeable by anyone other than the owner
+be processed.
+If the file is owned by anyone other than a user with
+UID 0, or is writeable by anyone other than the owner,
 .Nm
 will refuse to continue.
-.It Ar \&username
+.It Fl y
+Implicitly answer
+.Dq Li yes
+to any and all prompts.
+Currently, this includes
+prompts on whether to remove the specified user and whether to remove
+the home directory.
+This option requires that either the
+.Fl f
+option be used, or one or more user names be given as commmand line
+arguments.
+.It Ar username
 Identifies one or more users to be removed; if not present,
 .Nm
 interactively asks for one or more users to be removed.
 .El
 .Sh FILES
-.Bl -tag -width /etc/master.passwd -compact
+.Bl -tag -compact
 .It Pa /etc/master.passwd
 .It Pa /etc/passwd
 .It Pa /etc/group
@@ -157,10 +168,8 @@ interactively asks for one or more users to be removed.
 .Sh HISTORY
 The
 .Nm
-command appeared in
+utility appeared in
 .Fx 2.2 .
-.\" .Sh AUTHOR
-.\" Guy Helmer, Ames, Iowa
 .Sh BUGS
 The
 .Nm
@@ -171,19 +180,20 @@ It is also unable to remove symbolic links that were created by the
 user in
 .Pa /tmp
 or
-.Pa /var/tmp
+.Pa /var/tmp ,
 as symbolic links on
 .Bx 4.4
 filesystems do not contain information
-as to who created them.  Also, there may be other files created in
+as to who created them.
+Also, there may be other files created in
 .Pa /var/mail
 other than
-.Pa /var/mail/username
+.Pa /var/mail/ Ns Ar username
 and
-.Pa /var/mail/.pop.username
+.Pa /var/mail/.pop. Ns Ar username
 that are not owned by the removed user but should be removed.
 .Pp
 The
 .Nm
-utility has no knowledge of NIS (Yellow Pages), and it operates only on the
+utility has no knowledge of YP/NIS, and it operates only on the
 local password file.