tidy up this page;

1 files changed, 50 insertions, 83 deletions

diff --git a/share/man/man5/files.conf.5 b/share/man/man5/files.conf.5
index 5d4c2c4e03f..d83d9197a6f 100644
--- a/share/man/man5/files.conf.5
+++ b/share/man/man5/files.conf.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: files.conf.5,v 1.17 2007/11/26 08:55:04 deraadt Exp $
+.\"	$OpenBSD: files.conf.5,v 1.18 2007/11/26 11:38:05 jmc Exp $
 .\"
 .\" Copyright (c) 2002 Miodrag Vallat.
 .\" All rights reserved.
@@ -38,16 +38,14 @@ contain all the necessary information needed by
 .Xr config 8
 to parse a kernel configuration file and determine the list of files to
 compile.
-.Sh SYNTAX
+.Pp
 The
 .Pa files.*\&
 rules base are simple, human-readable, text files.
 Empty lines, as well as text prefixed by the
-.Dq #
+.Sq #
 character, are ignored.
-.\"
-.Ss Device tree concept
-.\"
+.Sh DEVICE TREE CONCEPT
 The
 .Ox
 kernel
@@ -68,14 +66,11 @@ a device node may have;
 some device drivers can attach themselves to different kinds of parent devices.
 For example, the logical
 .Xr scsibus 4
-device can either attach at an
-.Tn SCSI
-controller device, or at the logical
+device can either attach at a SCSI controller device,
+or at the logical
 .Xr atapiscsi 4
 bus.
-.\"
-.Ss Locators
-.\"
+.Sh LOCATORS
 Some device attachments need to provide attachment information.
 For example, an
 .Xr isa 4
@@ -100,50 +95,45 @@ devices
 .Pp
 Attachment lines in the kernel configuration file must match the locators of
 the device they are attaching to.
-For example, given
+For example:
 .Bd -literal -offset indent
 define pci {[dev = -1], [function = -1]}
 .Ed
 .Pp
-in the rules files, the following kernel configuration lines are valid:
+With the rule above,
+the following kernel configuration lines are valid:
 .Bd -literal -offset indent
 pciknob0 at pci? dev 2 function 42 # use fixed values
 pciknob* at pci? dev ? function ?  # use default values
 pciknob* at pci?                   # use default locators
 .Ed
 .Pp
-but the following are not:
+But the following are not:
 .Bd -literal -offset indent
 pciknob* at pci? trick ? treat ?               # unknown locators
 pciknob* at pci? dev ? function ? usefulness ? # unknown locators
 .Ed
-.\"
-.Ss Attributes
-.\"
-The syntax
+.Sh ATTRIBUTES
+The following syntax defines a simple attribute,
+which can be later used to factorize code dependencies:
 .Pp
 .Dl define attribute
 .Pp
-defines a simple attribute, which can be later used to factorize
-code dependencies.
-An attachment-like attribute will also require locators to be specified,
-such as
+An attachment-like attribute will also require locators to be specified.
+If no locators are necessary:
 .Pp
 .Dl define attribute {}
 .Pp
-if no locators are necessary, or
+If locators are provided:
 .Pp
 .Dl define attribute {[locator1 = default1], [locator2 = default2]}
 .Pp
-if locators are provided.
-.\"
-.Ss Devices
-.\"
-For simple device attachment, the syntax
+.Sh DEVICES
+For simple device attachment, the following syntax
+defines a simple device, with no locators:
 .Pp
 .Dl device devicename {}
 .Pp
-defines a simple device, with no locators.
 If locators are necessary, they are specified as:
 .Pp
 .Dl device devicename {[locator1 = default1], [locator2 = default2]}
@@ -152,15 +142,11 @@ A device can also reference an attribute with locators.
 This is in fact a dependency rule.
 For example,
 .Pa sys/conf/files
-defines the following attribute for
-.Tn SCSI
-controllers:
+defines the following attribute for SCSI controllers:
 .Pp
 .Dl define scsi {}			# no locators
 .Pp
-and
-.Tn SCSI
-drivers can then be defined as
+And SCSI drivers can then be defined as:
 .Pp
 .Dl device scsictrl: scsi
 .Pp
@@ -168,9 +154,7 @@ A device may depend on as many attributes as necessary:
 .Pp
 .Dl device complexdev: simpledev, otherdev, specialattribute
 .Pp
-.\"
-.Ss Pseudo devices
-.\"
+.Sh PSEUDO DEVICES
 Pseudo devices are defined as regular devices, except that they do not
 need locators, and use a different keyword:
 .Bd -literal -offset indent
@@ -178,11 +162,9 @@ pseudo-device loop: inet
 pseudo-device ksyms
 .Ed
 .Pp
-define, respectively, the loopback network interface and the kernel symbols
-pseudo-device.
-.\"
-.Ss Device attachment rules
-.\"
+The rules above define, respectively,
+the loopback network interface and the kernel symbols pseudo-device.
+.Sh DEVICE ATTACHMENT RULES
 Due to the tree structure of the device nodes, every device but the pseudo
 devices need to attach to some parent node.
 A device driver has to specify to which parents it can attach, with the
@@ -190,23 +172,21 @@ following syntax:
 .Pp
 .Dl attach device at parent, parent2, parent3
 .Pp
-which lists all the parent attributes a device may attach to.
-For example, if a device is specified as:
+The rule above lists all the parent attributes a device may attach to.
+For example, given the following:
 .Bd -literal -offset indent
 device smartknob: bells, whistles
 attach smartknob at brainbus
 .Ed
 .Pp
-then a
+The following configuration line is then valid:
 .Pp
 .Dl smartknob* at brainbus?
 .Pp
-configuration file line is valid, while a
+Whilst the following is not:
 .Pp
 .Dl smartknob* at dumbbus?
 .Pp
-is not.
-.Pp
 If a device supports attachments to multiple parents, using different
 .Dq glue
 routines every time, the following syntax specifies the details:
@@ -215,18 +195,16 @@ attach device at parent with device_parent_glue
 attach device at parent2 with device_parent2_glue
 .Ed
 .Pp
-and will define more required attributes, depending on the kernel
+This will define more required attributes, depending on the kernel
 configuration file's contents.
-.\"
-.Ss Rule file inclusion
-.\"
+.Sh RULE FILE INCLUSION
 It is possible to include other rules files anywhere in a file, using the
 .Dq include
 keyword:
 .Pp
 .Dl include \&"dev/pci/files.pci\&"
 .Pp
-will include the rules for machine-independent PCI code.
+The above rule will include the rules for machine-independent PCI code.
 .Pp
 The files
 .Pa sys/arch/machine/conf/files.machine ,
@@ -235,19 +213,17 @@ for every
 listed in the machine line in the kernel configuration file, as well as
 .Pa sys/conf/files ,
 are always processed, and do not need to be included.
-.\"
-.Ss Attribute requirements
-.\"
+.Sh ATTRIBUTE REQUIREMENTS
 The kernel configuration file description passed to
 .Xr config 8
 lists several compilation options, as well as several device definitions.
 From this list,
 .Xr config 8
-will build a list of required attributes, which are
+will build a list of required attributes, which are:
 .Pp
 .Bl -bullet -offset indent -compact
 .It
-the
+The
 .Dq option
 lines, with the option name translated to lowercase (for example, an
 .Dq option INET
@@ -255,29 +231,25 @@ line will produce the
 .Dq inet
 attribute).
 .It
-the device and pseudo-device names, except for
+The device and pseudo-device names, except for
 .Dq root .
 .El
-.\"
-.Ss Kernel file list
-.\"
+.Sh KERNEL FILE LIST
 Kernel source files are defined as:
 .Bd -literal -offset indent
 file file-list	dependencies	need-rules
 .Ed
 .Pp
-The
 .Dq file-list
-typically only specifies only one filename.
-Alternatively a list of potential filenames can be supplied,
-seperated by
-.Dq \&| Ns ,
-and
+typically only specifies a single filename.
+If instead it contains a list of filenames separated by the
+.Sq \&|
+character,
 .Xr config 8
-will select a file based on existance.
+will select the first file from the list which exists.
 If
 .Dq ${MACHINE_ARCH}
-or 
+or
 .Dq ${MACHINE}
 is found in the filename, it will be substited with the
 relevant base architecture name.
@@ -293,11 +265,11 @@ Multiple dependencies can be written using the
 and
 .Dq &
 operators.
-For example, the line
+For example:
 .Pp
 .Dl file netinet/ipsec_input.c	(inet | inet6) & ipsec
 .Pp
-teaches
+The above rule teaches
 .Xr config 8
 to only add
 .Pa sys/netinet/ipsec_input.c
@@ -332,7 +304,7 @@ and containing the following line:
 .Pp
 .Dl #define NATTRIBUTE	0
 .Pp
-substituting the attribute name and its uppercase form, prefixed with
+This would substitute the attribute name and its uppercase form, prefixed with
 the letter
 .Dq N ,
 to
@@ -353,9 +325,7 @@ if the device is not required.
 Attribute files are created for every attribute listed with a
 .Dq need
 rule, even if it is never referenced from the kernel configuration file.
-.\"
-.Ss Miscellaneous items
-.\"
+.Sh MISCELLANEOUS ITEMS
 .Pa sys/arch/machine/conf/files.machine
 must also supply the following special commands:
 .Bl -tag -width maxpartitions
@@ -374,9 +344,8 @@ will report an error if the
 .Dq maxusers parameter
 in the kernel configuration file does not fit in the specified range.
 .El
-.\"
 .Sh FILES
-.Bl -tag -width XXX \" deliberately small width
+.Bl -tag -width Ds
 .It Pa sys/arch/machine/conf/files.machine
 Rules for architecture-dependent files, for the
 .Dq machine
@@ -390,9 +359,7 @@ Rules for the
 .Dq class
 class of devices.
 .It Pa sys/scsi/files.scsi
-Rules for the common
-.Tn SCSI
-subsystem.
+Rules for the common SCSI subsystem.
 .El
 .Sh SEE ALSO
 .Xr config 8