docs: clean up login.1 manual

PATH contents for users & root in DESCRIPTION section where wrong,
and couple default values where missing.  Rest of the change is about
making the groff, and the output, to look good.

Signed-off-by: Sami Kerola <kerolasa@iki.fi>

1 files changed, 170 insertions, 106 deletions

diff --git a/login-utils/login.1 b/login-utils/login.1
index cb8024100..93c97699a 100644
--- a/login-utils/login.1
+++ b/login-utils/login.1
@@ -1,6 +1,6 @@
 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
 .\" May be distributed under the GNU General Public License
-.TH LOGIN 1 "March 2009" "util-linux" "User Commands"
+.TH LOGIN "1" "June 2012" "util-linux" "User Commands"
 .SH NAME
 login \- begin session on the system
 .SH SYNOPSIS
@@ -20,27 +20,27 @@ login \- begin session on the system
 ]
 .SH DESCRIPTION
 .B login
-is used when signing onto a system.
-If no argument is given,
+is used when signing onto a system.  If no argument is given,
 .B login
 prompts for the username.
-
-The user is then prompted for a password, where approprate.  Echoing is
-disabled to prevent revealing the password. Only a small number of password
-failures are permitted before
+.PP
+The user is then prompted for a password, where approprate.  Echoing
+is disabled to prevent revealing the password.  Only a small number
+of password failures are permitted before
 .B login
 exits and the communications link is severed.
-
-If password aging has been enabled for the account, the user may be prompted
-for a new password before proceeding. He will be forced to provide his old
-password and the new password before continuing. Please refer to
+.PP
+If password aging has been enabled for the account, the user may be
+prompted for a new password before proceeding.  He will be forced to
+provide his old password and the new password before continuing.
+Please refer to
 .BR passwd (1)
 for more information.
-
+.PP
 The user and group ID will be set according to their values in the
 .I /etc/passwd
-file. There is one exception if the user ID is zero: in this case,
-only the primary group ID of the account is set. This should allow
+file.  There is one exception if the user ID is zero: in this case,
+only the primary group ID of the account is set.  This should allow
 the system adminitrator to login even in case of network problems.
 The value for
 .BR $HOME ,
@@ -53,40 +53,39 @@ and
 are set according to the appropriate fields in the password entry.
 .B $PATH
 defaults to
-.I /usr/local/bin:/bin:/usr/bin:.
+.I /usr\:/local\:/bin:\:/bin:\:/usr\:/bin
 for normal users, and to
-.I /sbin:/bin:/usr/sbin:/usr/bin
+.I /usr\:/local\:/sbin:\:/usr\:/local\:/bin:\:/sbin:\:/bin:\:/usr\:/sbin:\:/usr\:/bin
 for root if not other configured.
-
+.P
 The environment variable
 .B $TERM
 will be preserved, if it exists (other environment variables are
 preserved if the
 .B \-p
-option is given) or be initialize to the terminal type on your tty
-
-Then the user's shell is started. If no shell is specified for the
+option is given) or be initialize to the terminal type on your tty.
+.PP
+Then the user's shell is started.  If no shell is specified for the
 user in
-.BR /etc/passwd ,
+.BR /etc\:/passwd ,
 then
-.B /bin/sh
+.B /bin\:/sh
 is used.  If there is no directory specified in
-.IR /etc/passwd ,
+.IR /etc\:/passwd ,
 then
 .I /
 is used (the home directory is checked for the
 .I .hushlogin
 file described below).
-
+.PP
 If the file
 .I .hushlogin
 exists, then a "quiet" login is performed (this disables the checking
-of mail and the printing of the last login time and message of the day).
-Otherwise, if
-.I /var/log/lastlog
+of mail and the printing of the last login time and message of the
+day).  Otherwise, if
+.I /var\:/log\:/lastlog
 exists, the last login time is printed (and the current login is
 recorded).
-
 .SH OPTIONS
 .TP
 .B \-p
@@ -94,7 +93,7 @@ Used by
 .BR getty (8)
 to tell
 .B login
-not to destroy the environment
+not to destroy the environment.
 .TP
 .B \-f
 Used to skip a second login authentication.  This specifically does
@@ -106,16 +105,24 @@ Used by other servers (i.e.,
 .BR telnetd (8))
 to pass the name of the remote host to
 .B login
-so that it may be placed in utmp and wtmp.  Only the superuser may use
-this option.
-
-Note that the \fB-h\fP option has impact on the \fBPAM service name\fP. The standard
-service name is "login", with the \fB-h\fP option the name is "remote". It's
-necessary to create a proper PAM config files (e.g.
-.I /etc/pam.d/login
-and 
-.I /etc/pam.d/remote
-).
+so that it may be placed in utmp and wtmp.  Only the superuser may
+use this option.
+.IP
+Note that the
+.B \-h
+option has impact on the
+.B PAM service
+.BR name .
+The standard service name is
+.IR login ,
+with the
+.B \-h
+option the name is
+.IR remote .
+It is necessary to create a proper PAM config files (e.g.
+.I /etc\:/pam.d\:/login
+and
+.IR /etc\:/pam.d\:/remote ).
 .TP
 .B \-H
 Used by other servers (i.e.,
@@ -126,98 +133,139 @@ that printing the hostname should be suppressed in the login: prompt.
 .TP
 .B \-V
 Print version and exit.
-
 .SH CONFIG FILE ITEMS
 .B login
 reads the
-.IR /etc/login.defs (5)
-configuration file. Note that the configuration file could be distributed with
-another package (e.g. shadow-utils). The following configuration items are
-relevant for
+.IR /etc\:/login.defs (5)
+configuration file.  Note that the configuration file could be
+distributed with another package (e.g. shadow-utils).  The following
+configuration items are relevant for
 .BR login (1):
 .PP
-\fBMOTD_FILE\fR (string)
+.B MOTD_FILE
+(string)
 .RS 4
-If defined, ":" delimited list of "message of the day" files to be displayed
-upon login. The default value is "/etc/motd". If the \fBMOTD_FILE\fR item is
-empty or "quiet" login is enabled then the message of the day is not displayed.
-Note that the same functionality is also provided by
+If defined, ":" delimited list of "message of the day" files to be
+displayed upon login.  The default value is
+.IR /etc\:/motd .
+If the
+.B MOTD_FILE
+item is empty or quiet login is enabled then the message of the day
+is not displayed.  Note that the same functionality is also provided
+by
 .BR pam_motd (8)
 PAM module.
 .RE
 .PP
-\fBLOGIN_TIMEOUT\fR (number)
+.B LOGIN_TIMEOUT
+(number)
 .RS 4
-Max time in seconds for login. The default value is 60.
+Max time in seconds for login.  The default value is
+.IR 60 .
 .RE
 .PP
-\fBLOGIN_RETRIES\fR (number)
+.B LOGIN_RETRIES
+(number)
 .RS 4
-Maximum number of login retries in case of bad password.
+Maximum number of login retries in case of bad password.  The default
+value is
+.IR 3 .
 .RE
 .PP
-\fBFAIL_DELAY\fR (number)
+.B FAIL_DELAY
+(number)
 .RS 4
-Delay in seconds before being allowed another three tries after a login
-failure. The default value is 5.
+Delay in seconds before being allowed another three tries after a
+login failure.  The default value is
+.IR 5 .
 .RE
 .PP
-\fBTTYPERM\fR (string)
+.B TTYPERM
+(string)
 .RS 4
-The terminal permissions. The default value is 0600.
+The terminal permissions.  The default value is
+.IR 0600 .
 .RE
 .PP
-\fBTTYGROUP\fR (string)
+.B TTYGROUP
+(string)
 .RS 4
 The login tty will be owned by the
-\fBTTYGROUP\fR. The default value is 'tty'. If the \fBTTYGROUP\fR does not exist
-then the ownership of the terminal is set to the user\'s primary group.
+.BR TTYGROUP .
+The default value is
+.IR tty .
+If the
+.B TTYGROUP
+does not exist then the ownership of the terminal is set to the
+user\'s primary group.
 .SP
-The \fBTTYGROUP\fR can be either the name of a group or a numeric group identifier.
+The
+.B TTYGROUP
+can be either the name of a group or a numeric group identifier.
 .RE
 .PP
-\fBHUSHLOGIN_FILE\fR (string)
+.B HUSHLOGIN_FILE
+(string)
 .RS 4
-If defined, this file can inhibit all the usual chatter during the login
-sequence.  If a full pathname (e.g. /etc/hushlogins) is specified, then hushed
-mode will be enabled if the user\'s name or shell are found in the file. If
-this global hush login file is empty then the hushed mode will be enabled for
-all users.
-
-If not a full pathname is specified, then hushed mode will be enabled if the
-file exists in the user\'s home directory.
-
-The default is to check "/etc/hushlogins" and if does not exist then
-"~/.hushlogin".
-
-If the \fBHUSHLOGIN_FILE\fR item is empty then all checks are disabled.
+If defined, this file can inhibit all the usual chatter during the
+login sequence.  If a full pathname (e.g.
+.IR /etc\:/hushlogins )
+is specified, then hushed mode will be enabled if the user\'s name or
+shell are found in the file.  If this global hush login file is empty
+then the hushed mode will be enabled for all users.
+.PP
+If not a full pathname is specified, then hushed mode will be enabled
+if the file exists in the user\'s home directory.
+.PP
+The default is to check
+.I /etc\:/hushlogins
+and if does not exist then
+.I ~/.hushlogin
+.PP
+If the
+.B HUSHLOGIN_FILE
+item is empty then all checks are disabled.
 .RE
 .PP
-\fBDEFAULT_HOME\fR (boolean)
+.B DEFAULT_HOME
+(boolean)
 .RS 4
-Indicate if login is allowed if we can\'t cd to the home directory. If set to
-\fIyes\fR, the user will login in the root (/) directory if it is not possible
-to cd to her home directory. The default value is 'yes'.
+Indicate if login is allowed if we can not change directory to the
+home directory.  If set to
+.IR yes ,
+the user will login in the root (/) directory if it is not possible
+to change directory to her home.  The default value is
+.IR yes .
 .RE
 .PP
-\fBLOG_UNKFAIL_ENAB\fR (boolean)
+.B LOG_UNKFAIL_ENAB
+(boolean)
 .RS 4
-Enable display of unknown usernames when login failures are recorded\&.
-.sp
-Note that logging unknown usernames may be a security issue if an user enter
-her password instead of her login name.
+Enable display of unknown usernames when login failures are recorded.
+The default value is
+.IR no .
+.PP
+Note that logging unknown usernames may be a security issue if an
+user enter her password instead of her login name.
 .RE
 .PP
-\fBENV_PATH\fR (string)
+.B ENV_PATH
+(string)
 .RS 4
-If set, it will be used to define the PATH environment variable when a regular
-user login. The default value is "/usr/local/bin:/bin:/usr/bin".
+If set, it will be used to define the PATH environment variable when
+a regular user login.  The default value is
+.I /usr\:/local\:/bin:\:/bin:\:/usr\:/bin
 .RE
 .PP
-\fBENV_ROOTPATH\fR (string), \fBENV_SUPATH\fR (string)
+.B ENV_ROOTPATH
+(string)
+.br
+.B ENV_SUPATH
+(string)
 .RS 4
-If set, it will be used to define the PATH environment variable when the superuser
-login. The default value is "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin".
+If set, it will be used to define the PATH environment variable when
+the superuser login.  The default value is
+.I /usr\:/local\:/sbin:\:/usr\:/local\:/bin:\:/sbin:\:/bin:\:/usr\:/sbin:\:/usr\:/bin
 .RE
 .SH FILES
 .nf
@@ -242,29 +290,45 @@ login. The default value is "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin
 .BR environ (7),
 .BR shutdown (8)
 .SH BUGS
-
 The undocumented BSD
 .B \-r
 option is not supported.  This may be required by some
 .BR rlogind (8)
 programs.
-
-A recursive login, as used to be possible in the good old days,
-no longer works; for most purposes
+.PP
+A recursive login, as used to be possible in the good old days, no
+longer works; for most purposes
 .BR su (1)
-is a satisfactory substitute. Indeed, for security reasons,
-login does a vhangup() system call to remove any possible
-listening processes on the tty. This is to avoid password
-sniffing. If one uses the command "login", then the surrounding shell
-gets killed by vhangup() because it's no longer the true owner of the tty.
-This can be avoided by using "exec login" in a top-level shell or xterm.
+is a satisfactory substitute.  Indeed, for security reasons, login
+does a vhangup() system call to remove any possible listening
+processes on the tty.  This is to avoid password sniffing.  If one
+uses the command
+.BR login ,
+then the surrounding shell gets killed by vhangup() because it's no
+longer the true owner of the tty.  This can be avoided by using
+.B exec login
+in a top-level shell or xterm.
 .SH AUTHOR
-Derived from BSD login 5.40 (5/9/89) by Michael Glad (glad@daimi.dk)
+Derived from BSD login 5.40 (5/9/89) by
+.MT glad@\:daimi.\:dk
+Michael Glad
+.ME
 for HP-UX
 .br
-Ported to Linux 0.12: Peter Orbaek (poe@daimi.aau.dk)
+Ported to Linux 0.12:
+.MT poe@\:daimi.\:aau.\:dk
+Peter Orbaek
+.ME
 .br
-Rewritten to PAM-only version by Karel Zak (kzak@redhat.com)
+Rewritten to PAM-only version by
+.MT kzak@\:redhat.\:com
+Karel Zak
+.ME
 .SH AVAILABILITY
-The login command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+The
+.B login
+command is part of the util-linux package and is
+available from
+.UR ftp:\://ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .