various text improvements to make this page read better. also add in

a little of afterboot(8)'s wisdom to prepare for my killing the kernel
building section in afterboot(8) (which is here replicated);

1 files changed, 59 insertions, 73 deletions

diff --git a/usr.sbin/config/config.8 b/usr.sbin/config/config.8
index 207f739a509..ba86452b869 100644
--- a/usr.sbin/config/config.8
+++ b/usr.sbin/config/config.8
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: config.8,v 1.48 2007/03/20 19:42:14 jmc Exp $
+.\"	$OpenBSD: config.8,v 1.49 2007/03/20 20:19:09 jmc Exp $
 .\"	$NetBSD: config.8,v 1.10 1996/08/31 20:58:16 mycroft Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
@@ -35,7 +35,7 @@
 .Os
 .Sh NAME
 .Nm config
-.Nd "build kernel compilation directories or modify a kernel"
+.Nd build kernel compilation directories or modify a kernel
 .Sh SYNOPSIS
 .Nm config
 .Op Fl p
@@ -53,39 +53,18 @@ In the first synopsis form, the
 program creates a kernel build directory from the kernel configuration file
 specified by
 .Ar config-file .
+.Pp
 In the second synopsis form,
 .Nm
 allows editing of the kernel binary specified by
 .Ar infile .
-.Pp
-Furthermore, devices may be enabled, disabled, or modified without
-recompiling, by editing the kernel executable using the
-.Fl e
-option.
-Similarly, you can do the same editing at boot-time, using
-the in-kernel editor, as described in
+Devices may be enabled, disabled, or modified without recompiling,
+by editing the kernel executable.
+Similarly, the same editing can be done at boot-time,
+using the in-kernel editor,
+as described in
 .Xr boot_config 8 .
 .Pp
-.Nm
-is most commonly invoked from the directory containing
-.Ox
-kernel configuration files (i.e.,
-.Pa /usr/src/sys/arch/i386/conf
-for i386 machines).
-For instance, the following steps would be followed to configure and compile
-a new GENERIC kernel (assuming a complete kernel source tree is available in
-.Pa /usr/src/sys ) :
-.Bd -literal -offset indent
-# cd /usr/src/sys/arch/i386/conf
-# config ./GENERIC
-# cd ../compile/GENERIC
-# make depend && make
-.Ed
-.Pp
-Replace
-.Dq i386
-with the appropriate architecture name.
-.Pp
 For kernel building, the options are as follows:
 .Bl -tag -width Ds
 .It Fl b Ar builddir
@@ -130,7 +109,7 @@ Allows the modification of kernel device configuration (see
 Temporary changes can be made to the running kernel's configuration or a new
 kernel binary may be written for permanent changes between system reboots.
 See the section
-.Sx Kernel modification
+.Sx KERNEL MODIFICATION
 below for more details.
 .It Fl f
 Overwrite the
@@ -144,7 +123,7 @@ Write the modified kernel to
 .Ar outfile .
 .It Fl u
 Check to see if the kernel configuration was modified at boot-time
-(i.e.,
+(i.e.\&
 .Cm boot -c
 was used).
 If so, compare the running kernel with the kernel to be edited
@@ -152,7 +131,7 @@ If so, compare the running kernel with the kernel to be edited
 If they seem to be the same, apply all configuration changes performed at
 boot.
 .El
-.Pp
+.Sh KERNEL BUILDING
 The old
 .Fl g
 flag is deprecated and no longer supported.
@@ -197,10 +176,10 @@ is not specified,
 uses the current directory as the build directory, and looks in it for
 a file called
 .Pa CONFIG .
-If you run
+If
 .Nm
-this way, you must specify the location of the top-level kernel source
-directory using the
+is run this way, the location of the top-level kernel source
+directory must be specified using the
 .Fl s
 option or by using the
 .Dq Li source
@@ -256,7 +235,7 @@ well as
 for the
 .Nm
 rules base.
-.Ss Kernel modification
+.Sh KERNEL MODIFICATION
 When
 .Fl e
 is specified, device parameters that are normally hard-coded into the kernel
@@ -266,16 +245,16 @@ Modifications are made to the currently running kernel and can be written to
 a new kernel binary so changes are preserved during subsequent system restarts.
 .Pp
 When invoked, the kernel identification is first shown.
-.Bd -literal
+.Bd -literal -offset indent
 # config -e -o bsd.new /bsd
 OpenBSD 2.6-beta (GENERIC.rz0) #0: Mon Oct  4 03:57:22 MEST 1999
     root@winona:/usr/src/sys/arch/pmax/compile/GENERIC.rz0
 Enter 'help' for information
-ukc>
+ukc\*(Gt
 .Ed
 .Pp
 One or more warnings may be printed before the
-.Li ukc>
+.Li ukc\*(Gt
 prompt.
 .Bd -literal -offset indent
 warning: no output file specified
@@ -318,7 +297,7 @@ The commands are as follows:
 Add a device through copying another.
 .It Ic base Ar 8 | 10 | 16
 Change the base of numbers displayed and entered,
-e.g., I/O addresses in a VAXen are octal.
+e.g. I/O addresses in a VAXen are octal.
 .It Ic cachepct Op Ar number
 Change the BUFCACHEPERCENT value.
 Without arguments, displays its current value.
@@ -360,10 +339,17 @@ Change the
 timezone structure.
 Without arguments, displays its current value.
 .El
-.Sh EXAMPLES (First synopsis)
+.Sh EXAMPLES (kernel building)
+Note:
+The standard
+.Ox
+kernel configuration
+(GENERIC or GENERIC.MP)
+is suitable for most purposes.
+Use of an alternative kernel configuration is not recommended.
 A custom kernel is built in the following way.
 .Pp
-To compile your own kernel from a non-writable media (such as a CD-ROM)
+To compile a kernel from a non-writable media (such as a CD-ROM)
 mounted on
 .Pa /usr/src ,
 do the following:
@@ -384,50 +370,48 @@ To compile a kernel inside a writable source tree, do the following:
 # make
 .Ed
 .Pp
-where
+In the examples above,
 .Ar somedir
 is a writable directory,
 .Ar somearch
-is the architecture (e.g.,
-.Ic i386 ) ,
+is the architecture (e.g. i386),
 and
 .Ar SOMEFILE
 should be a name indicative of a particular configuration (often
 that of the hostname).
 .Nm config
-will warn you if a
+will warn if a
 .Dq make clean
 is required;
-you can also do a
+a
 .Dq make depend
-so that you will have dependencies there the next time you do a compile.
+can also be run
+to have dependencies there the next time sources are compiled.
 .Pp
-After either of these two methods, you can place the new kernel (called
-.Pa bsd )
-in
-.Pa /
-(i.e.,
-.Pa /bsd )
+The new kernel, called
+.Pa bsd ,
+can be copied to
+.Pa /bsd
 and the system will boot it next time.
 Most people save their backup kernels as
 .Pa /bsd.1 ,
 .Pa /bsd.2 ,
 etc.
-.Sh EXAMPLES (Second synopsis)
+.Sh EXAMPLES (kernel modification)
 The Ethernet card is not detected at boot because the kernel configuration
 does not match the physical hardware configuration,
-e.g., wrong IRQ in OpenBSD/i386.
+e.g. wrong IRQ in OpenBSD/i386.
 The Ethernet card is supposed to use the
 .Xr ne 4
 driver.
 .Bd -literal
-.No ukc> Ic find ne
+.No ukc\*(Gt Ic find ne
 24 ne0 at isa0 port 0x240 size 0 iomem 0xd8000 iosiz 0 irq 9 drq -1 drq2 -1 flags 0x0
 25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
 26 ne* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 flags 0x0
 27 ne* at pci* dev -1 function -1 flags 0x0
 28 ne* at pcmcia* function -1 irq -1 flags 0x0
-ukc>
+ukc\*(Gt
 .Ed
 .Pp
 ne1 seems to match the configuration except it uses IRQ 5 instead of IRQ 10.
@@ -436,7 +420,7 @@ So the irq on ne1 should be changed via the
 command.
 The device can be specified by either name or number.
 .Bd -literal
-.No ukc> Ic change ne1
+.No ukc\*(Gt Ic change ne1
 25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1
 .No change (y/n) \&? Ic y
 .No port [0x300] \&?
@@ -449,7 +433,7 @@ The device can be specified by either name or number.
 .No flags [0] \&?
 25 ne1 changed
 25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 5 drq -1 drq2 -1 flags 0x0
-ukc>
+ukc\*(Gt
 .Ed
 .Pp
 Another case is a mistakenly detected non-existing device instead of another
@@ -458,17 +442,18 @@ One known case is the Mitsumi
 CD-ROM in OpenBSD/i386.
 The simplest thing to solve that problem is to disable mcd0.
 .Bd -literal
-.No ukc> Ic find mcd0
+.No ukc\*(Gt Ic find mcd0
  29 mcd0 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
-.No ukc> Ic disable mcd0
+.No ukc\*(Gt Ic disable mcd0
  29 mcd0 disabled
-.No ukc> Ic find 29
+.No ukc\*(Gt Ic find 29
  29 mcd0 at isa0 disable port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
 .Ed
 .Pp
-It's also possible to disable all devices with a common attribute. e.g.,
+It's also possible to disable all devices with a common attribute.
+For example:
 .Bd -literal
-.No ukc> Ic disable port 0x300
+.No ukc\*(Gt Ic disable port 0x300
  25 ne1 disabled
  29 mcd0 already disabled
  72 we1 disabled
@@ -482,26 +467,26 @@ command is useful for finding which devices have a certain attribute.
 It can also be used to find those devices with a particular value for
 an attribute.
 .Bd -literal
-.No ukc> Ic show slot
+.No ukc\*(Gt Ic show slot
   2 ahc* at eisa0 slot -1
  10 uha* at eisa0 slot -1
  12 ep0 at eisa0 slot -1
  17 ep* at eisa0 slot -1
 102 ahb* at eisa0 slot -1
 103 fea* at eisa0 slot -1
-.No ukc> Ic show port 0x300
+.No ukc\*(Gt Ic show port 0x300
  25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
  72 we1 at isa0 port 0x300 size 0 iomem 0xcc000 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
  75 el0 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 9 drq -1 drq2 -1 flags 0x0
  77 ie1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
-ukc>
+ukc\*(Gt
 .Ed
 .Pp
 It is possible to add new devices, but only devices that were linked into the
 kernel.
 If a new device is added, following devices will be renumbered.
 .Bd -literal
-.No ukc> Ic find ep
+.No ukc\*(Gt Ic find ep
  11 ep0 at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1 flags 0x0
  12 ep0 at eisa0 slot -1 flags 0x0
  13 ep0 at pci* dev -1 function -1 flags 0x0
@@ -510,11 +495,11 @@ If a new device is added, following devices will be renumbered.
  16 ep* at eisa0 slot -1 flags 0x0
  17 ep* at pci* dev -1 function -1 flags 0x0
  18 ep* at pcmcia* dev -1 irq -1 flags 0x0
-.No ukc> Ic add ep1
+.No ukc\*(Gt Ic add ep1
 .No "Clone Device (DevNo, 'q' or '\&?') \&?" Ic 13
 .No "Insert before Device (DevNo, 'q' or '\&?')" Ic 14
  14 ep1 at pci* dev -1 function -1
-.No ukc> Ic change 14
+.No ukc\*(Gt Ic change 14
  14 ep1 at pci* dev -1 function -1
 .No change (y/n) \&? Ic y
 .No dev [-1] \&? Ic 14
@@ -522,7 +507,7 @@ If a new device is added, following devices will be renumbered.
 .No flags [0] \&? Ic 18
  14 ep1 changed
  14 ep1 at pci* dev 14 function -1 flags 0x12
-ukc>
+ukc\*(Gt
 .Ed
 .Pp
 When done, exit the program with the
@@ -541,10 +526,11 @@ or
 .Fl f
 was given, else ignore changes).
 .Bd -literal
-.No ukc> Ic quit
+.No ukc\*(Gt Ic quit
 .Ed
 .Sh SEE ALSO
 .Xr options 4 ,
+.Xr boot.conf 5 ,
 .Xr files.conf 5 ,
 .Xr boot_config 8
 .Pp