Use consistent markup for literals and quoted metasyntactic variables.

Left unfixed: `NIS' should be marked up as a tradename.

1 files changed, 144 insertions, 65 deletions

diff --git a/share/man/man5/passwd.5 b/share/man/man5/passwd.5
index b25d354..51b1c3b 100644
--- a/share/man/man5/passwd.5
+++ b/share/man/man5/passwd.5
@@ -42,7 +42,9 @@
 The
 .Nm passwd
 files are files consisting of newline separated records, one per user,
-containing ten colon (``:'') separated fields.  These fields are as
+containing ten colon
+.Pq Ql \&:
+separated fields.  These fields are as
 follows:
 .Pp
 .Bl -tag -width password -offset indent
@@ -83,15 +85,17 @@ across the system (and often across a group of systems) since they
 control file access.
 .Pp
 While it is possible to have multiple entries with identical login names
-and/or identical user id's, it is usually a mistake to do so.  Routines
+and/or identical uids, it is usually a mistake to do so.  Routines
 that manipulate these files will often return only one of the multiple
 entries, and that one by random selection.
 .Pp
-The login name must never begin with a hyphen (``-''); also, it is strongly
-suggested that neither upper-case characters nor dots (``.'') be part
-of the name, as this tends to confuse mailers.  No field may contain a
-colon (``:'') as this has been used historically to separate the fields
-in the user database.
+The login name must never begin with a hyphen
+.Pq Ql \&- ;
+also, it is strongly
+suggested that neither upper-case characters nor dots
+.Pq Ql \&.
+be part
+of the name, as this tends to confuse mailers.
 .Pp
 The password field is the
 .Em encrypted
@@ -143,20 +147,26 @@ aging feature.
 .Pp
 The
 .Ar gecos
-field normally contains comma (``,'') separated subfields as follows:
+field normally contains comma
+.Pq Ql \&,
+separated subfields as follows:
 .Pp
-.Bd -unfilled -offset indent
-fullname		user's full name
-office		user's office location
-wphone		user's work phone number
-hphone		user's home phone number
-.Ed
+.Bl -bullet -compact -offset indent
+.It
+user's full name
+.It
+user's office location
+.It
+user's work phone number
+.It
+user's home phone number
+.El
 .Pp
 This information is used by the
 .Xr finger 1
 program, and the first field used by the system mailer.
 If an ampersand
-.Ql \&&
+.Pq Ql \&&
 character appears within the fullname field, programs that
 use this field will substitute it with a capitalized version
 of the account's login name.
@@ -205,12 +215,16 @@ in some other way and then manually update the password databases with
 .Xr pwd_mkdb 8 .
 .Pp
 The simplest way to activate NIS is to add an empty record
-with only a plus sign (`+') in the name field, such as this:
+with only a plus sign
+.Pq Ql \&+
+in the name field, such as this:
 .Bd -literal -offset indent
 +:::::::::
 
 .Ed
-The `+' will tell the
+The
+.Ql \&+
+will tell the
 .Xr getpwent 3
 routines in
 .Tn FreeBSD Ns 's
@@ -219,11 +233,15 @@ for lookups.
 .Pp
 Note that the entry shown above is known as a
 .Em wildcard
-entry, because it matches all users (the `+' without any other information
+entry, because it matches all users (the
+.Ql \&+
+without any other information
 matches everybody) and allows all NIS password data to be retrieved
 unaltered.
 However, by
-specifying a username or netgroup next to the `+' in the NIS
+specifying a username or netgroup next to the
+.Ql \&+
+in the NIS
 entry, the administrator can affect what data are extracted from the
 NIS passwd maps and how it is interpreted.
 Here are a few example
@@ -241,30 +259,52 @@ file):
 
 .Ed
 Specific usernames are listed explicitly while netgroups are signified
-by a preceding `@'. In the above example, users in the ``staff'' and
-``permitted-users'' netgroups will have their password information
+by a preceding
+.Ql \&@ .
+In the above example, users in the
+.Dq staff
+and
+.Dq permitted-users
+netgroups will have their password information
 read from NIS and used unaltered.
 In other words, they will be allowed
 normal access to the machine.
-Users ``ken'' and ``dennis,'' who have
+Users
+.Dq ken
+and
+.Dq dennis ,
+who have
 been named explicitly rather than through a netgroup, will also have
-their password data read from NIS, _except_ that user ``ken'' will
-have his shell remapped to
+their password data read from NIS,
+.Em except
+that user
+.Dq ken
+will have his shell remapped to
 .Pa /bin/csh .
 This means that value for his shell specified in the NIS password map
 will be overridden by the value specified in the special NIS entry in
 the local
 .Pa master.passwd
 file.
-User ``ken'' may have been assigned the csh shell because his
+User
+.Dq ken
+may have been assigned the csh shell because his
 NIS password entry specified a different shell that may not be
 installed on the client machine for political or technical reasons.
-Meanwhile, users in the ``rejected-users'' netgroup are prevented
+Meanwhile, users in the
+.Dq rejected-users
+netgroup are prevented
 from logging in because their UIDs, GIDs and shells have been overridden
 with invalid values.
 .Pp
-User ``mitnick'' will be be ignored entirely because his entry is
-specified with a `-' instead of a `+'. A minus entry can be used
+User
+.Dq mitnick
+will be be ignored entirely because his entry is
+specified with a
+.Ql \&-
+instead of a
+.Ql \&+ .
+A minus entry can be used
 to block out certain NIS password entries completely; users whose
 password data has been excluded in this way are not recognized by
 the system at all.
@@ -274,12 +314,16 @@ for a user that the system isn't going to recognize in the first place.)
 In general, a minus entry is used to specifically exclude a user
 who might otherwise be granted access because he happens to be a
 member of an authorized netgroup.
-For example, if ``mitnick'' is
-a member of the ``permitted-users'' netgroup and must, for whatever
+For example, if
+.Dq mitnick
+is
+a member of the
+.Dq permitted-users
+netgroup and must, for whatever
 the reason, be permitted to remain in that netgroup (possibly to
 retain access to other machines within the domain), the administrator
 can still deny him access to a particular system with a minus entry.
-Also, it is sometimes easier to explicitly list those users who aren't
+Also, it is sometimes easier to explicitly list those users who are not
 allowed access rather than generate a possibly complicated list of
 users who are allowed access and omit the rest.
 .Pp
@@ -287,13 +331,23 @@ Note that the plus and minus entries are evaluated in order from
 first to last with the first match taking precedence.
 This means
 the system will only use the first entry that matches a particular user.
-If, for instance, we have a user ``foo'' who is a member of both the ``staff''
-netgroup and the ``rejected-users'' netgroup, he will be admitted to
-the system because the above example lists the entry for ``staff'' 
-before the entry for ``rejected-users.''
-If we reversed the order,
-user ``foo'' would be flagged as a ``rejected-user'' instead and
-denied access.
+If, using the same example, there is a user
+.Dq foo
+who is a member of both the
+.Dq staff
+netgroup and the
+.Dq rejected-users
+netgroup, he will be admitted to
+the system because the above example lists the entry for
+.Dq staff
+before the entry for
+.Dq rejected-users .
+If the order were reversed,
+user
+.Dq foo
+would be flagged as a
+.Dq rejected-user
+instead and denied access.
 .Pp
 Lastly, any NIS password database records that do not match against
 at least one of the users or netgroups specified by the NIS access
@@ -303,9 +357,16 @@ file will be ignored (along with any users specified using minus
 entries). In our example shown above, we do not have a wildcard
 entry at the end of the list; therefore, the system will not recognize
 anyone except
-``ken,'' ``dennis,'' the ``staff'' netgroup and the ``permitted-users''
+.Dq ken ,
+.Dq dennis ,
+the
+.Dq staff
+netgroup, and the
+.Dq permitted-users
 netgroup as authorized users.
-The ``rejected-users'' netgroup will
+The
+.Dq rejected-users
+netgroup will
 be recognized but all members will have their shells remapped and
 therefore be denied access.
 All other NIS password records
@@ -313,19 +374,15 @@ will be ignored.
 The administrator may add a wildcard entry to the
 end of the list such as:
 .Bd -literal -offset indent
-+:::::::::/usr/local/bin/go_away
++:::::::::/sbin/nologin
 
 .Ed
 This entry acts as a catch-all for all users that don't match against
 any of the other entries.
-.Pa /usr/local/bin/go_away
-can be a short shell script or program
-that prints a message telling the user that he is not allowed access
-to the system.
 This technique is sometimes useful when it is
 desirable to have the system be able to recognize all users in a
 particular NIS domain without necessarily granting them login access.
-See the above text on the shell field regarding security concerns when using
+See the description of the shell field regarding security concerns when using
 a shell script as the login shell.
 .Pp
 The primary use of this
@@ -459,11 +516,13 @@ Or worse, this
 .Sy FILE!!
 The first tells
 .Tn FreeBSD
-to remap all passwords to `*' (which
+to remap all passwords to
+.Ql \&*
+(which
 will prevent anybody from logging in) and to remap all UIDs and GIDs
 to 0 (which will make everybody appear to be the superuser). The
 second case just maps all UIDs and GIDs to 0, which means that
-.Pa all users will appear to be root!
+all users will appear to be root!
 .Pp
 .Ss Compatibility of NIS override evaluation
 When Sun originally added NIS support to their
@@ -478,17 +537,25 @@ format.
 The
 .Tn SunOS
 documentation claims that
-adding a '+' entry to the password file causes the contents of
-the NIS password database to be 'inserted' at the position in
-the file where the '+' entry appears.
+adding a 
+.Ql \&+
+entry to the password file causes the contents of
+the NIS password database to be
+.Dq inserted
+at the position in the file where the
+.Ql \&+
+entry appears.
 If, for example, the
-administrator places the +:::::: entry in the middle of
-.Pa /etc/passwd,
+administrator places a
+.Ql \&+::::::
+entry in the middle of
+.Pa /etc/passwd ,
 then the entire contents of the NIS password map would appear
 as though it had been copied into the middle of the password
 file.
-If the administrator places the +:::::: entry at both the
-middle and the end of
+If the administrator places
+.Ql \&+::::::
+entries at both the middle and the end of
 .Pa /etc/passwd ,
 then the NIS password map would appear twice: once in the middle
 of the file and once at the end.
@@ -496,7 +563,7 @@ of the file and once at the end.
 instead of simple wildcards, other combinations could be achieved.)
 .Pp
 By contrast,
-.Tn FreeBSD
+.Fx
 does not have a single
 .Tn ASCII
 password file: it
@@ -531,15 +598,19 @@ is compared against the override filter exactly once and
 treated accordingly: if the filter allows the entry through
 unaltered, it's treated unaltered; if the filter calls for remapping
 of fields, then fields are remapped; if the filter calls for
-explicit exclusion (i.e. the entry matches a '-' override),
-the entry is ignored; if the entry doesn't match against any
+explicit exclusion (i.e., the entry matches a
+.Ql \&-
+override), the entry is ignored; if the entry doesn't match against any
 of the filter specifications, it's discarded.
 .Pp
-Again, note that the NIS '+' and '-' entries
-themselves are handled in the order in which they were specified
+Again, note that the NIS
+.Ql \&+
+and
+.Ql \&-
+entries themselves are handled in the order in which they were specified
 in the
 .Pa /etc/master.passwd
-file since doing otherwise would lead to unpredictable behavior.
+file, since doing otherwise would lead to unpredictable behavior.
 .Pp
 The end result is that
 .Tn FreeBSD Ns 's
@@ -557,7 +628,11 @@ The primary differences are:
 Each NIS password map record can be mapped into the password
 local password space only once.
 .It
-The placement of the NIS '+' and '-' entries does not necessarily
+The placement of the NIS
+.Ql \&+
+and
+.Ql \&-
+entries does not necessarily
 affect where NIS password records will be mapped into
 the password space.
 .El
@@ -582,9 +657,13 @@ is specified as:
 
 .Ed
 the system will first try to match users against a netgroup called
-`operator'. If an `operator' netgroup doesn't exist, the system
-will try to match users against the normal `operator' group
-instead. 
+.Ql operator .
+If an
+.Ql operator
+netgroup doesn't exist, the system
+will try to match users against the normal
+.Ql operator
+group instead. 
 .Ss Changes in behavior from older versions of FreeBSD
 There have been several bug fixes and improvements in
 .Tn FreeBSD Ns 's