mdoc(7) police: overhaul.

Approved by:	re

1 files changed, 221 insertions, 141 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.