Improve mdoc(7) markup.

1 files changed, 190 insertions, 76 deletions

diff --git a/lib/libutil/login_cap.3 b/lib/libutil/login_cap.3
index a533421..ae95dc6 100644
--- a/lib/libutil/login_cap.3
+++ b/lib/libutil/login_cap.3
@@ -85,8 +85,11 @@ consist of colon
 .Ql \&:
 separated fields, the first field in each record being one or more
 identifiers for the record (which must be unique for the entire database),
-each separated by a '|', and may optionally include a description as
-the last 'name'.
+each separated by a
+.Ql | ,
+and may optionally include a description as
+the last
+.Sq name .
 Remaining fields in the record consist of keyword/data pairs.
 Long lines may be continued with a backslash within empty entries,
 with the second and subsequent lines optionally indented for readability.
@@ -95,9 +98,13 @@ This is similar to the format used in
 except that keywords are not limited to two significant characters,
 and are usually longer for improved readability.
 As with termcap entries, multiple records can be linked together
-(one record including another) using a field containing tc=<recordid>.
-The result is that the entire record referenced by <recordid> replaces
-the tc= field at the point at which it occurs.
+(one record including another) using a field containing
+.Ql tc= Ns Va <recordid> .
+The result is that the entire record referenced by
+.Va <recordid>
+replaces the
+.Va tc=
+field at the point at which it occurs.
 See
 .Xr getcap 3
 for further details on the format and use of a capabilities database.
@@ -105,7 +112,9 @@ for further details on the format and use of a capabilities database.
 The
 .Nm login_cap
 interface provides a convenient means of retrieving login class
-records with all tc= references expanded.
+records with all
+.Va tc=
+references expanded.
 A program will typically call one of
 .Fn login_getclass ,
 .Fn login_getpwclass ,
@@ -114,14 +123,20 @@ or
 .Fn login_getclassbyname
 according to its requirements.
 Each of these functions returns a login capabilities structure,
-.Ft login_cap_t ,
+.Vt login_cap_t ,
 which may subsequently be used to interrogate the database for
 specific values using the rest of the API.
-Once the login_cap_t is of no further use, the
+Once the
+.Vt login_cap_t
+is of no further use, the
 .Fn login_close
 function should be called to free all resources used.
 .Pp
-The structure of login_cap_t is defined in login_cap.h, as:
+The structure of
+.Vt login_cap_t
+is defined in
+.In login_cap.h ,
+as:
 .Bd -literal -offset indent
 typedef struct {
 	char *lc_class;
@@ -131,7 +146,7 @@ typedef struct {
 .Ed
 .Pp
 The
-.Ar lc_class
+.Fa lc_class
 member contains a pointer to the name of the login class
 retrieved.
 This may not necessarily be the same as the one requested,
@@ -145,21 +160,28 @@ or
 .Fn login_getuserclass .
 If the referenced user has no login class specified in
 .Pa /etc/master.passwd ,
-the class name is NULL or an empty string.
+the class name is
+.Dv NULL
+or an empty string.
 If the class
 specified does not exist in the database, each of these
-functions will search for a record with an id of "default",
+functions will search for a record with an id of
+.Ql default ,
 with that name returned in the
-.Ar lc_class
+.Fa lc_class
 field.
 In addition, if the referenced user has a UID of 0 (normally,
-"root", although the user name is not considered) then
+.Ql root ,
+although the user name is not considered) then
 .Fn login_getpwclass
-will search for a record with an id of "root" before it searches
-for the record with the id of "default".
+will search for a record with an id of
+.Ql root
+before it searches
+for the record with the id of
+.Ql default .
 .Pp
 The
-.Ar lc_cap
+.Fa lc_cap
 field is used internally by the library to contain the
 expanded login capabilities record.
 Programs with unusual requirements may wish to use this
@@ -168,7 +190,7 @@ with the lower-level
 style functions to access the record directly.
 .Pp
 The
-.Ar lc_style
+.Fa lc_style
 field is set by the
 .Fn login_getstyle
 function to the authorisation style, according to the requirements
@@ -176,37 +198,48 @@ of the program handling a login itself.
 .Pp
 As noted above, the
 .Fn login_get*class
-functions return a login_cap_t object which is used to access
+functions return a
+.Vt login_cap_t
+object which is used to access
 the matching or default record in the capabilities database.
 The
 .Fn login_getclassbyname
 function accepts two arguments: the first one is the record identifier of the
 record to be retrieved, the second is an optional pointer to a
-.Li passwd
+.Vt passwd
 structure.
 If the first
-.Ar name
-argument is NULL, an empty string, or a class that does not exist
+.Fa name
+argument is
+.Dv NULL ,
+an empty string, or a class that does not exist
 in the supplemental or system login class database, then the system
-.Em default
+.Ql default
 record is returned instead.
 If the second
-.Ar pwd
-parameter is NULL, then only the system login class database is
+.Fa pwd
+parameter is
+.Dv NULL ,
+then only the system login class database is
 used.
 However,
 if the
-.Ar pwd
+.Fa pwd
 parameter and the value of
-.Ar pwd->pw_dir
-are both not NULL, then the directory contained in
-.Ar pwd->pw_dir
+.Fa pwd->pw_dir
+are both not
+.Dv NULL ,
+then the directory contained in
+.Fa pwd->pw_dir
 is searched for
-a login database file called ".login_conf", and capability records
+a login database file called
+.Pa .login_conf ,
+and capability records
 contained within it may override the system defaults.
 This scheme allows users to override some login settings from
 those in the system login class database by creating class records
-for their own private class with a record id of `me'.
+for their own private class with a record id of
+.Ql me .
 In the context of a
 .Em login ,
 it should be noted that some options cannot by overridden by
@@ -232,15 +265,20 @@ and
 files will only be performed subject to the security checks documented in
 .Xr _secure_path 3
 for the uids 0 and
-.Ar pwd->pw_uid
+.Fa pwd->pw_uid
 respectively.
 .Pp
-If the specified record is NULL, empty or does not exist, and the
-system has no "default" record available to fall back to, there is a
+If the specified record is
+.Dv NULL ,
+empty or does not exist, and the
+system has no
+.Ql default
+record available to fall back to, there is a
 memory allocation error or for some reason
 .Xr cgetent 3
 is unable to access the login capabilities database, this function
-returns NULL.
+returns
+.Dv NULL .
 .Pp
 The functions
 .Fn login_getpwclass ,
@@ -250,7 +288,9 @@ and
 retrieve the applicable login class record for the user's passwd
 entry or class name by calling
 .Fn login_getclassbyname .
-On failure, NULL is returned.
+On failure,
+.Dv NULL
+is returned.
 The difference between these functions is that
 .Fn login_getuserclass
 includes the user's overriding
@@ -265,21 +305,32 @@ As explained earlier,
 .Fn login_getpwclass
 only differs from
 .Fn login_getclass
-in that it allows the default class for user 'root' as "root"
+in that it allows the default class for a super-user as
+.Ql root
 if none has been specified in the password database.
-Otherwise, if the passwd pointer is NULL, or the user record
-has no login class, then the system "default" entry is retrieved.
+Otherwise, if the passwd pointer is
+.Dv NULL ,
+or the user record
+has no login class, then the system
+.Ql default
+entry is retrieved.
 .Pp
-Once a program no longer wishes to use a login_cap_t object,
+Once a program no longer wishes to use a
+.Vt login_cap_t
+object,
 .Fn login_close
 may be called to free all resources used by the login class.
 The
 .Fn login_close
-function may be passed a NULL pointer with no harmful side-effects.
+function may be passed a
+.Dv NULL
+pointer with no harmful side-effects.
 .Pp
 The remaining functions may be used to retrieve individual
 capability records.
-Each function takes a login_cap_t object as its first parameter,
+Each function takes a
+.Vt login_cap_t
+object as its first parameter,
 a capability tag as the second, and remaining parameters being
 default and error values that are returned if the capability is
 not found.
@@ -304,17 +355,18 @@ in this group, or deallocated on calling
 .It Fn login_getcapstr
 This function returns a simple string capability.
 If the string is not found, then the value in
-.Ar def
+.Fa def
 is returned as the default value, or if an error
 occurs, the value in the
-.Ar error
+.Fa error
 parameter is returned.
 .It Fn login_getcaplist
 This function returns the value corresponding to the named
-capability tag as a list of values in a NULL terminated
-array.
+capability tag as a list of values in a
+.Dv NULL
+terminated array.
 Within the login class database, some tags are of type
-.Em list ,
+.Vt list ,
 which consist of one or more comma- or space separated
 values.
 Usually, this function is not called directly from an
@@ -327,52 +379,86 @@ Capability tags for which this function is called consist of a list of
 directories separated by spaces.
 .It Fn login_getcaptime
 This function returns a
-.Em time value
+.Vt time value
 associated with a particular capability tag with the value expressed
 in seconds (the default), minutes, hours, days, weeks or (365 day)
 years or any combination of these.
-A suffix determines the units used: S for seconds, M for minutes,
-H for hours, D for days, W for weeks and Y for 365 day years.
+A suffix determines the units used:
+.Ql S
+for seconds,
+.Ql M
+for minutes,
+.Ql H
+for hours,
+.Ql D
+for days,
+.Ql W
+for weeks and
+.Ql Y
+for 365 day years.
 Case of the units suffix is ignored.
 .Pp
 Time values are normally used for setting resource, accounting and
 session limits.
 If supported by the operating system and compiler (which is true of
 .Fx ) ,
-the value returned is a quad (long long), of type
-.Em rlim_t .
-A value "inf" or "infinity" may be used to express an infinite
-value, in which case RLIM_INFINITY is returned.
+the value returned is a
+.Vt quad
+.Pq Vt long long ,
+of type
+.Vt rlim_t .
+A value
+.Ql inf
+or
+.Ql infinity
+may be used to express an infinite
+value, in which case
+.Dv RLIM_INFINITY
+is returned.
 .It Fn login_getcapnum
 This function returns a numeric value for a tag, expressed either as
-tag=<value> or the standard
+.Ql tag=<value>
+or the standard
 .Fn cgetnum
-format tag#<value>.
+format
+.Ql tag#<value> .
 The first format should be used in preference to the second, the
 second format is provided for compatibility and consistency with the
 .Xr getcap 3
 database format where numeric types use the
 .Ql \&#
 as the delimiter for numeric values.
-If in the first format, then the value given may be "inf" or
-"infinity" which results in a return value of RLIM_INFINITY.
+If in the first format, then the value given may be
+.Ql inf
+or
+.Ql infinity
+which results in a return value of
+.Dv RLIM_INFINITY .
 If the given capability tag cannot be found, the
-.Ar def
+.Fa def
 parameter is returned, and if an error occurs, the
-.Ar error
+.Fa error
 parameter is returned.
 .It Fn login_getcapsize
 .Fn login_getcapsize
 returns a value representing a size (typically, file or memory)
 which may be expressed as bytes (the default), 512 byte blocks,
 kilobytes, megabytes, gigabytes, and on systems that support the
-.Ar long long
+.Vt long long
 type, terabytes.
 The suffix used determines the units, and multiple values and
 units may be used in combination (e.g.\& 1m500k = 1.5 megabytes).
-A value with no suffix is interpreted as bytes, B as 512-byte
-blocks, K as kilobytes, M as megabytes, G as gigabytes and T as
-terabytes.
+A value with no suffix is interpreted as bytes,
+.Ql B
+as 512-byte blocks,
+.Ql K
+as kilobytes,
+.Ql M
+as megabytes,
+.Ql G
+as gigabytes and
+.Ql T
+as terabytes.
 Case is ignored.
 The error value is returned if there is a login capabilities database
 error, if an invalid suffix is used, or if a numeric value cannot be
@@ -380,33 +466,61 @@ interpreted.
 .It Fn login_getcapbool
 This function returns a boolean value tied to a particular flag.
 It returns 0 if the given capability tag is not present or is
-negated by the presence of a "tag@" (See
+negated by the presence of a
+.Ql tag@
+(see
 .Xr getcap 3
 for more information on boolean flags), and returns 1 if the tag
 is found.
 .It Fn login_getstyle
 This function is used by the login authorisation system to determine
 the style of login available in a particular case.
-The function accepts three parameters, the login_cap entry itself and
-two optional parameters, and authorisation type 'auth' and 'style', and
+The function accepts three parameters, the
+.Fa lc
+entry itself and
+two optional parameters, and authorisation type
+.Fa auth
+and
+.Fa style ,
+and
 applies these to determine the authorisation style that best suites
 these rules.
 .Bl -bullet
 .It
-If 'auth' is neither NULL nor an empty string, look for a tag of type
-"auth-<auth>" in the capability record.
-If not present, then look for the default tag "auth=".
+If 
+.Fa auth
+is neither
+.Dv NULL
+nor an empty string, look for a tag of type
+.Ql auth- Ns Fa <auth>
+in the capability record.
+If not present, then look for the default tag
+.Va auth= .
 .It
 If no valid authorisation list was found from the previous step, then
-default to "passwd" as the authorisation list.
+default to
+.Ql passwd
+as the authorisation list.
 .It
-If 'style' is not NULL or empty, look for it in the list of authorisation
+If 
+.Fa style
+is not
+.Dv NULL
+or empty, look for it in the list of authorisation
 methods found from the previous step.
-If 'style' is NULL or an empty string, then default to "passwd"
+If
+.Fa style
+is
+.Dv NULL
+or an empty string, then default to
+.Ql passwd
 authorisation.
 .It
-If 'style' is found in the chosen list of authorisation methods, then
-return that, otherwise return NULL.
+If
+.Fa style
+is found in the chosen list of authorisation methods, then
+return that, otherwise return
+.Dv NULL .
 .El
 .Pp
 This scheme allows the administrator to determine the types of
@@ -423,7 +537,7 @@ The
 function is used to set the
 .Xr crypt 3
 format using the
-.Ql passwd_format
+.Va passwd_format
 configuration entry.
 If no entry is found,
 .Fa def