Give this manpage a good overhaul, including the markup.

Notable changes:

- Removed the "disktype" argument from the -B only synopsis
  form.  This form doesn't touch the disk label, and doesn't
  use this argument.

- Fixed the first example in the EXAMPLES section.  Support
  for compatibility slices has been recently dropped from
  the GEOM kernels, and a bit later GEOM became standard.

- Removed the buggy notion from rev. 1.37 that disklabel(8)
  may be used to define mount points; it cannot.  Improve
  some DOS partition / FreeBSD slice wording.  Among these,
  ``dangerously-dedicated slice'' was just a nonsense.  ;-)

1 files changed, 398 insertions, 327 deletions

diff --git a/sbin/disklabel/disklabel.8 b/sbin/disklabel/disklabel.8
index 9945038..6a57d40 100644
--- a/sbin/disklabel/disklabel.8
+++ b/sbin/disklabel/disklabel.8
@@ -35,7 +35,7 @@
 .\"	@(#)disklabel.8	8.2 (Berkeley) 4/19/94
 .\" $FreeBSD$
 .\"
-.Dd July 30, 1999
+.Dd March 15, 2003
 .Dt DISKLABEL 8
 .Os
 .Sh NAME
@@ -47,96 +47,91 @@
 .Ar disk
 .Nm
 .Fl w
-.Op Fl r
-.Op Fl n
+.Op Fl nr
 .Ar disk disktype Ns | Ns Cm auto
-.Oo Ar packid Oc
+.Op Ar packid
 .Nm
 .Fl e
-.Op Fl r
-.Op Fl n
+.Op Fl nr
 .Ar disk
 .Nm
 .Fl R
-.Op Fl r
-.Op Fl n
-.Ar disk Ar protofile
+.Op Fl nr
+.Ar disk protofile
 .Pp
 .Nm
 .Fl B
-.Oo
-.Fl b Ar boot
-.Oc
+.Op Fl b Ar boot
 .Ar disk
-.Op Ar disktype Ns | Ns Cm auto
 .Nm
-.Fl w
-.Fl B
+.Fl w B
 .Op Fl n
-.Oo
-.Fl b Ar boot
-.Oc
+.Op Fl b Ar boot
 .Ar disk disktype Ns | Ns Cm auto
-.Oo Ar packid Oc
+.Op Ar packid
 .Nm
-.Fl R
-.Fl B
+.Fl R B
 .Op Fl n
-.Oo
-.Fl b Ar boot
-.Oc
-.Ar disk Ar protofile
+.Op Fl b Ar boot
+.Ar disk protofile
 .Sh DESCRIPTION
 The
 .Nm
 utility
-installs, examines or modifies the label on a disk drive or pack.  When writing
+installs, examines or modifies the label on a disk drive or pack.
+When writing
 the label, it can be used to change the drive identification, the disk
-partitions on the drive, or to replace a damaged label.  There are several forms
-of the command that read (display), install or edit the label on a disk.  In
-addition,
+partitions on the drive, or to replace a damaged label.
+There are several forms
+of the command that read (display), install, or edit the label on a disk.
+In addition,
 .Nm
 can install bootstrap code.
-.Ss Raw or in-core label
-.Pp
+.Ss Raw or In-Core Label
 The disk label resides close to or at the beginning of each disk slice.
-For faster access, the kernel maintains a copy in core at all times.  By
-default, most
+For faster access, the kernel maintains a copy in core at all times.
+By default, most
 .Nm
-access the in-core copy of the label.  To access the raw (on-disk) copy, use the
+access the in-core copy of the label.
+To access the raw (on-disk) copy, use the
 .Fl r
-option.  This option allows a label to be installed on a disk without kernel
+option.
+This option allows a label to be installed on a disk without kernel
 support for a label, such as when labels are first installed on a system; it
-must be used when first installing a label on a disk.  The specific effect of
+must be used when first installing a label on a disk.
+The specific effect of
 .Fl r
 is described under each command.
-.Pp
-.Ss Disk device name
-.Pp
+.Ss Disk Device Name
 All
 .Nm
 forms require a disk device name, which should always be the raw
-device name representing the disk or slice.  For example
+device name representing the disk or slice.
+For example,
 .Pa da0
-represents the entire disk regardless of any DOS partitioning,
+represents the entire disk regardless of any
+.Tn DOS
+partitioning,
 and
 .Pa da0s1
-represents a slice.  Some devices, most notably
-.Ar ccd ,
+represents a slice.
+Some devices, most notably
+.Xr ccd 4 ,
 require that the
 .Dq whole-disk
 (or
-.Dq c )
-partition be specified.  For example
+.Ql c )
+partition be specified.
+For example,
 .Pa ccd0c .
-You do not have to include the
+When specifying the device,
+the
 .Pa /dev/
-path prefix when specifying the device.
-The
+path prefix may be omitted;
+the
 .Nm
 utility will automatically prepend it.
-.Ss Reading the disk label
-.Pp
+.Ss Reading the Disk Label
 To examine the label on a disk drive, use
 .Nm
 without options:
@@ -151,68 +146,68 @@ represents the raw disk in question, and may be in the form
 or
 .Pa /dev/da0c .
 It will display all of the parameters associated with the drive and its
-partition layout.  Unless the
+partition layout.
+Unless the
 .Fl r
-flag is given,
+option is given,
 the kernel's in-core copy of the label is displayed;
 if the disk has no label, or the partition types on the disk are incorrect,
 the kernel may have constructed or modified the label.
 If the
 .Fl r
-flag is given,
+option is given,
 .Nm
-reads the label from the raw disk and displays it.  Both versions are usually
+reads the label from the raw disk and displays it.
+Both versions are usually
 identical except in the case where a label has not yet been initialized or
 is corrupt.
-.Ss Writing a standard label
-.Pp
+.Ss Writing a Standard Label
 To write a standard label, use the form
 .Pp
 .Nm
 .Fl w
-.Op Fl r
-.Op Fl n
+.Op Fl nr
 .Ar disk disktype Ns | Ns Cm auto
-.Oo Ar packid Oc
-.Pp
-.Nm
-.Fl w
-.Op Fl r
-.Op Fl n
-.Ar disk
-.Cm auto
+.Op Ar packid
 .Pp
 The required arguments to
 .Nm
-are the drive to be labeled and the drive type as described in the
+are the drive to be labeled, and the drive type as described in the
+.Xr disktab 5
+file.
+The drive parameters and partitions are taken from that file.
+If different disks of the same physical type are to have different partitions,
+it will be necessary to have separate
 .Xr disktab 5
-file.  The drive parameters and partitions are taken from that file.  If
-different disks of the same physical type are to have different partitions, it
-will be necessary to have separate disktab entries describing each, or to edit
-the label after installation as described below.  The optional argument is a
-pack identification string, up to 16 characters long.  The pack id must be
-quoted if it contains blanks.
+entries describing each, or to edit
+the label after installation as described below.
+The optional argument is a
+pack identification string, up to 16 characters long.
+The
+.Ar packid
+must be quoted if it contains blanks.
 .Pp
-If the
+If
 .Fl n
-flag is given, no data will be written to the device, and instead the
-disklabel that would have been written will be printed to stdout.
+is used, no data will be written to the device, and instead the
+disk label that would have been written will be printed to standard output.
 .Pp
 If the
 .Fl r
-flag is given, the disk sectors containing the label and bootstrap
+option is given, the disk sectors containing the label and bootstrap
 will be written directly.
 A side-effect of this is that any existing bootstrap code will be overwritten
-and the disk rendered unbootable.  See the boot options below for a method of
+and the disk rendered unbootable.
+See the boot options below for a method of
 writing the label and the bootstrap at the same time.
 If
 .Fl r
 is not specified,
-the existing label will be updated via the in-core copy and any bootstrap
+the existing label will be updated via the in-core copy, and any bootstrap
 code will be unaffected.
 If the disk does not already have a label, the
 .Fl r
-flag must be used.
+option must be used.
 In either case, the kernel's in-core label is replaced.
 .Pp
 For a virgin disk that is not known to
@@ -221,13 +216,22 @@ For a virgin disk that is not known to
 can be specified as
 .Cm auto .
 In this case, the driver is requested to produce a virgin label for the
-disk.  This might or might not be successful, depending on whether the
+disk.
+This might or might not be successful, depending on whether the
 driver for the disk is able to get the required data without reading
-anything from the disk at all.  It will likely succeed for all SCSI
-disks, most IDE disks, and vnode devices.  Writing a label to the
+anything from the disk at all.
+It will likely succeed for all
+.Tn SCSI
+disks, most
+.Tn IDE
+disks, and
+.Cm vnode
+type memory disks
+.Pq Xr md 4 .
+Writing a label to the
 disk is the only supported operation, and the
 .Ar disk
-itself must be provided as the canonical name, i.e. not as a full
+itself must be provided as the canonical name, i.e., not as a full
 path name.
 .Pp
 For most harddisks, a label based on percentages for most partitions (and
@@ -235,167 +239,176 @@ one partition with a size of
 .Ql * )
 will produce a reasonable configuration.
 .Pp
-PC-based systems have special requirements in order for the BIOS to properly
-recognize a
+PC-based systems have special requirements in order for the
+.Tn BIOS
+to properly recognize a
 .Fx
-disklabel.  Older systems may require what is known as a
-.Dq dangerously dedicated
-disklabel, which creates a fake DOS partition to work around problems older
-BIOSes have with modern disk geometries.
-On newer systems you generally want
-to create a normal DOS partition using
-.Ar fdisk
-and then create a
+disk label.
+Older systems may require what is known as a
+.Dq dangerously-dedicated
+disk label, which creates a fake
+.Tn DOS
+partition to work around problems older
+.Tn BIOS Ns es
+have with modern disk geometries.
+On newer systems, a normal
+.Tn DOS
+partition should generally be created using
+.Xr fdisk 8 ,
+and then a
 .Fx
-disklabel within that slice.  This is described
-later on in this page.
+disk label within that slice.
+This is described later on in this page.
 .Pp
-Installing a new disklabel does not in of itself allow your system to boot
-a kernel using that label.  You must also install boot blocks, which is
+Installing a new disk label does not in of itself allow the system to boot
+a kernel using that label.
+Boot blocks must also be installed, which is
 described later on in this manual page.
-.Ss Editing an existing disk label
-.Pp
+.Ss Editing an Existing Disk Label
 To edit an existing disk label, use the form
 .Pp
 .Nm
 .Fl e
-.Op Fl r
-.Op Fl n
+.Op Fl nr
 .Ar disk
 .Pp
 This command reads the label from the in-core kernel copy, or directly from the
 disk if the
 .Fl r
-flag is also specified.  The label is written to a file in ASCII and then
-supplied to an editor for changes.  If no editor is specified in an
+option is also specified.
+The label is written to a file in
+.Tn ASCII
+format, and then supplied to an editor for changes.
+If no editor is specified in the
 .Ev EDITOR
 environment variable,
 .Xr vi 1
-is used.  When the editor terminates, the label file is used to rewrite the disk
-label.  Existing bootstrap code is unchanged regardless of whether
+is used.
+When the editor terminates, the label file is used to rewrite the disk label.
+Existing bootstrap code is unchanged regardless of whether
 .Fl r
-was specified.  If
+was specified.
+If
 .Fl n
-is specified, no data will be written to the device, and instead the
-disklabel that would have been written will be printed to stdout.  This is
+is used, no data will be written to the device, and instead the
+disk label that would have been written will be printed to standard output.
+This is
 useful to see how a partitioning scheme will work out for a specific disk.
-.Ss Restoring a disk label from a file
-.Pp
+.Ss Restoring a Disk Label From a File
 To restore a disk label from a file, use the form
 .Pp
 .Nm
 .Fl R
-.Op Fl r
-.Op Fl n
-.Ar disk Ar protofile
+.Op Fl nr
+.Ar disk protofile
 .Pp
 .Nm
-is capable of restoring a disk label that was previously saved in a file in ASCII format.
+is capable of restoring a disk label that was previously saved in a file in
+.Tn ASCII
+format.
 The prototype file used to create the label should be in the same format as that
-produced when reading or editing a label.  Comments are delimited by
-.Ar \&#
-and newline.  As when writing a new label, any existing bootstrap code will be
+produced when reading or editing a label.
+Comments are delimited by
+.Ql #
+and newline.
+As when writing a new label, any existing bootstrap code will be
 clobbered if
 .Fl r
-is specified and will be unaffected otherwise.  See the boot options below for a
+is specified, and will be unaffected otherwise.
+See the boot options below for a
 method of restoring the label and writing the bootstrap at the same time.
 If
 .Fl n
 is used, no data will be written to the device, and instead the
-disklabel that would have been written will be printed to stdout.  This is
+disk label that would have been written will be printed to standard output.
+This is
 useful to see how a partitioning scheme will work out for a specific disk.
-.Ss Installing bootstraps
-.Pp
+.Ss Installing Bootstraps
 The final three forms of
 .Nm
-are used to install bootstrap code.  If you are creating a
+are used to install bootstrap code.
+If a
 .Dq dangerously-dedicated
-slice for compatibility with older PC systems,
-you generally want to specify the raw disk name such as
-.Pa da0 .
-If you are creating a label within an existing DOS slice,
-you should specify
-the partition name such as
-.Pa da0s1a .
-Making a slice bootable can be tricky.  If you are using a normal DOS
-slice you typically install (or leave) a standard MBR on the base disk and
-then install the
-.Fx
-bootblocks in the slice.
+disk is created for compatibility with older PC systems,
+the raw disk name such as
+.Pa da0
+should be specified.
+If an existing slice should be labeled,
+the slice name such as
+.Pa da0s1
+should be specified,
+and to make it bootable,
+.Tn MBR
+on the base disk should probably be updated; see
+.Xr fdisk 8 .
 .Pp
 .Nm
 .Fl B
-.Oo
-.Fl b Ar boot
-.Oc
+.Op Fl b Ar boot
 .Ar disk
-.Oo Ar disktype Oc
 .Pp
-This form installs the bootstrap only.  It does not change the disk label.
-You should never use this command on a base disk unless you intend to create a
+This form installs the bootstrap only.
+It does not change the disk label.
+Never use this command on a base disk, such as
+.Pa da0 ,
+unless the intent is to create a
 .Dq dangerously-dedicated
-disk, such as
-.Ar da0 .
+disk.
 This command is typically run on a slice such as
-.Ar da0s1 .
+.Pa da0s1 .
 .Pp
 .Nm
-.Fl w
-.Fl B
+.Fl w B
 .Op Fl n
-.Oo
-.Fl b Ar boot
-.Oc
-.Ar disk Ar disktype
-.Oo Ar packid Oc
+.Op Fl b Ar boot
+.Ar disk disktype Ns | Ns Cm auto
+.Op Ar packid
 .Pp
 This form corresponds to the
-.Dq write label
+.Dq "write label"
 command described above.
 In addition to writing a new volume label, it also installs the bootstrap.
-If run on a base disk this command will create a
+If run on a base disk, this command will create a
 .Dq dangerously-dedicated
-label.  This command is normally run on a slice rather than a base disk.
+label.
+This command is normally run on a slice rather than a base disk.
 If
 .Fl n
 is used, no data will be written to the device, and instead the
-disklabel that would have been written will be printed to stdout.
+disk label that would have been written will be printed to standard output.
 .Pp
 .Nm
-.Fl R
-.Fl B
+.Fl R B
 .Op Fl n
-.Oo
-.Fl b Ar boot
-.Oc
-.Ar disk Ar protofile
+.Op Fl b Ar boot
+.Ar disk protofile
 .Pp
 This form corresponds to the
-.Dq restore label
+.Dq "restore label"
 command described above.
 In addition to restoring the volume label, it also installs the bootstrap.
-If run on a base disk this command will create a
+If run on a base disk, this command will create a
 .Dq dangerously-dedicated
-label.  This command is normally run on a slice rather than a base disk.
+label.
+This command is normally run on a slice rather than a base disk.
 .Pp
 The bootstrap commands always access the disk directly, so it is not necessary
 to specify the
 .Fl r
-flag.  If
+option.
+If
 .Fl n
 is used, no data will be written to the device, and instead the
-disklabel that would have been written will be printed to stdout.
+disk label that would have been written will be printed to standard output.
 .Pp
-The bootstrap code is comprised of two boot programs, both
-compiled into a single
+The bootstrap code is comprised of two boot programs compiled into a single
 .Pa /boot/boot
 image.
 An alternative boot image may be specified with the
 .Fl b
 option.
-.Ss Initializing/Formatting a bootable disk from scratch
-.Pp
-To initialize a disk from scratch the following sequence is recommended.
+.Ss Initializing/Formatting a Bootable Disk From Scratch
+To initialize a disk from scratch, the following sequence is recommended.
 Please note that this will wipe everything that was previously on the disk,
 including any
 .No non- Ns Fx
@@ -405,51 +418,59 @@ slices.
 Use
 .Xr fdisk 8
 to initialize the hard disk, and create a slice table, referred to
-as the partition table in DOS.
-Here you will define disk slices for your system.
+as the
+.Dq "partition table"
+in
+Tn DOS .
 .It
 Use
 .Nm
-to define and write partitions and mount points.
-You are not required to define the mount points here though,
-they can be defined later using
-.Xr mount 8 .
+to define partitions on
+.Fx
+slices created in the previous step.
 .It
 Finally use
 .Xr newfs 8
-to create a file system on the new partition.
+to create file systems on new partitions.
+.El
+.Pp
 A typical partitioning scheme would be to have an
-.Dq a
+.Ql a
 partition
 of approximately 128MB to hold the root file system, a
-.Dq b
+.Ql b
 partition for
 swap, a
-.Dq d
-partition for /var (usually 128MB), an
-.Dq e
+.Ql d
+partition for
+.Pa /var
+(usually 128MB), an
+.Ql e
 partition
-for /var/tmp (usually 128MB), an
-.Dq f
-partition for /usr (usually around 2G),
+for
+.Pa /var/tmp
+(usually 128MB), an
+.Ql f
+partition for
+.Pa /usr
+(usually around 2GB),
 and finally a
-.Dq g
-partition for /home (usually all remaining space).
+.Ql g
+partition for
+.Pa /home
+(usually all remaining space).
 Your mileage may vary.
-.El
 .Pp
-.Nm fdisk Fl BI Ar da0
+.Nm fdisk Fl BI Pa da0
 .Pp
 .Nm
-.Fl w
-.Fl B
-.Ar da0s1
+.Fl w B
+.Pa da0s1
 .Cm auto
 .Pp
-.Pp
 .Nm
 .Fl e
-.Ar da0s1
+.Pa da0s1
 .Sh FILES
 .Bl -tag -width ".Pa /etc/disktab" -compact
 .It Pa /boot/boot
@@ -461,8 +482,11 @@ Disk description file.
 The
 .Nm
 utility
-uses an ASCII version of the label when examining, editing or restoring a disk
-label.  The format is:
+uses an
+.Tn ASCII
+version of the label when examining, editing, or restoring a disk
+label.
+The format is:
 .Bd -literal -offset 4n
 # /dev/da1c:
 type: SCSI
@@ -491,51 +515,56 @@ drivedata: 0
   h:   962010   211920     vinum                        # (Cyl.  218*- 1211*)
 .Ed
 .Pp
-Lines starting with a # mark are comments.  Most of the other specifications are
-no longer used.  The ones which must still be set correctly are:
+Lines starting with a
+.Ql #
+mark are comments.
+Most of the other specifications are no longer used.
+The ones which must still be set correctly are:
 .Pp
-.Bl -hang -width 20n
-.It Nm label
+.Bl -inset
+.It Ar label
 is an optional label, set by the
 .Ar packid
 option when writing a label.
-.It Nm flags
-Flags may be
-.Ar removable ,
-.Ar ecc
+.It Ar flags
+may be
+.Cm removable , ecc
 or
-.Ar badsect .
-.Ar removable
+.Cm badsect .
+.Cm removable
 is set for removable media drives, but no current
 .Fx
 driver evaluates this
 flag.
-.Ar ecc
+.Cm ecc
 is no longer supported;
-.Ar badsect
+.Cm badsect
 specifies that the drive can perform bad sector remapping.
-.It Nm sectors/unit
-describes the total size of the disk.  This value must be correct.
-.It Nm the partition table
-This is the
+.It Ar sectors/unit
+describes the total size of the disk.
+This value must be correct.
+.It Ar "the partition table"
+is the
 .Ux
-partition table, not the Microsoft partition table described in
+partition table, not the
+.Tn DOS
+partition table described in
 .Xr fdisk 8 .
 .El
 .Pp
-The partition table can have up to 8 entries.  It contains the following
-information:
-.Bl -hang -width 10n
-.It identifier
+The partition table can have up to 8 entries.
+It contains the following information:
+.Bl -tag -width indent
+.It Ar #
 The partition identifier is a single letter in the range
-.Dq a
+.Ql a
 to
-.Dq h .
+.Ql h .
 By convention, partition
-.Dq c
+.Ql c
 is reserved to describe the entire disk.
-.It size
-is the size of the partition in sectors,
+.It Ar size
+The size of the partition in sectors,
 .Cm K
 (kilobytes - 1024),
 .Cm M
@@ -543,51 +572,59 @@ is the size of the partition in sectors,
 .Cm G
 (gigabytes - 1024*1024*1024),
 .Cm %
-(percentage of free space AFTER removing any fixed-size partitions other
-than partition
-.Dq c) ,
+(percentage of free space
+.Em after
+removing any fixed-size partitions other than partition
+.Ql c ) ,
 or
 .Cm *
-(all remaining free space AFTER fixed-size and percentage
-partitions).  For partition
-.Dq c ,
+(all remaining free space
+.Em after
+fixed-size and percentage partitions).
+For partition
+.Ql c ,
 a size of
 .Cm *
-indicates the entire disk.  Lowercase versions of
+indicates the entire disk.
+Lowercase versions of
 .Cm K , M ,
 and
 .Cm G
 are allowed.
 Size and type should be specifed without any spaces between them.
 .Pp
-Example: 2097152, 1g, 1024m and 1048576k are all the same size
+Example: 2097152, 1G, 1024M and 1048576K are all the same size
 (assuming 512-byte sectors).
-.It offset
-is the offset of the start of the partition from the beginning of the
+.It Ar offset
+The offset of the start of the partition from the beginning of the
 drive in sectors, or
 .Cm *
 to have
 .Nm
 calculate the correct offset to use (the end of the previous partition plus
 one, ignoring partition
-.Dq c .
+.Ql c .
 For partition
-.Dq c ,
+.Ql c ,
 .Cm *
 will be interpreted as an offset of 0.
-.It fstype
-describes the purpose of the partition.  The example shows all currently used
-partition types.
-For UFS file systems and ccd partitions, use type
+.It Ar fstype
+Describes the purpose of the partition.
+The example shows all currently used partition types.
+For
+.Tn UFS
+file systems and
+.Xr ccd 4
+partitions, use type
 .Cm 4.2BSD .
 For Vinum drives, use type
 .Cm vinum .
 Other common types are
-.Cm unused
+.Cm swap
 and
-.Cm swap .
+.Cm unused .
 By convention, partition
-.Dq c
+.Ql c
 represents the entire slice and should be of type
 .Cm unused ,
 though
@@ -596,51 +633,59 @@ does not enforce this convention.
 The
 .Nm
 utility
-also knows about a number of other partition types, none of which are in current
-use.
-See the definitions starting with
+also knows about a number of other partition types,
+none of which are in current use.
+(See the definitions starting with
 .Dv FS_UNUSED
 in
-.Pa /usr/include/sys/disklabel.h
-for more details.
-.It fsize
+.Aq Pa sys/disklabel.h
+for more details.)
+.It Ar fsize
 For
 .Cm 4.2BSD
-and LFS file systems only, the fragment size.  Defaults to 1024 for
-partitions smaller than 1 GB, 4096 for partitions 1GB or larger.
-.It bsize
+and
+.Tn LFS
+file systems only, the fragment size.
+Defaults to 1024 for partitions smaller than 1GB,
+4096 for partitions 1GB or larger.
+.It Ar bsize
 For
 .Cm 4.2BSD
-and LFS file systems only, the block size.  Defaults to 8192 for
-partitions smaller than 1 GB, 16384 for partitions 1GB or larger.
-.It bps/cpg
+and
+.Tn LFS
+file systems only, the block size.
+Defaults to 8192 for partitions smaller than 1GB,
+16384 for partitions 1GB or larger.
+.It Ar bps/cpg
 For
 .Cm 4.2BSD
-file systems, the number of cylinders in a cylinder group.  For LFS file
-systems, the segment shift value.  Defaults to 16 for
-partitions smaller than 1 GB, 64 for partitions 1GB or larger.
+file systems, the number of cylinders in a cylinder group.
+For
+.Tn LFS
+file systems, the segment shift value.
+Defaults to 16 for partitions smaller than 1GB,
+64 for partitions 1GB or larger.
 .El
 .Pp
 The remainder of the line is a comment and shows the cylinder allocations based
 on the obsolete (but possibly correct) geometry information about the drive.
-The asterisk (*) indicates that the partition does not begin or end exactly on a
+The asterisk
+.Pq Ql *
+indicates that the partition does not begin or end exactly on a
 cylinder boundary.
 .Sh EXAMPLES
-.Dl disklabel da0
+.Dl "disklabel da0s1"
 .Pp
-Display the in-core label for
-.Pa da0s1
-as obtained via
+Display the in-core label for the first slice of the
+.Pa da0
+disk, as obtained via
 .Pa /dev/da0s1 .
-When reading a label,
-.Fx
-will allow you to specify the base disk name
-even if the label resides on a slice.  However, to be proper you should
-specify the base disk name only if you are using a
-.Dq dangerously-dedicated
-label.  Normally you specify the slice.
+(If the disk is
+.Dq dangerously-dedicated ,
+the base disk name should be specified, such as
+.Pa da0 . )
 .Pp
-.Dl disklabel da0s1 > savedlabel
+.Dl "disklabel da0s1 > savedlabel"
 .Pp
 Save the in-core label for
 .Pa da0s1
@@ -648,9 +693,9 @@ into the file
 .Pa savedlabel .
 This file can be used with the
 .Fl R
-flag to restore the label at a later date.
+option to restore the label at a later date.
 .Pp
-.Dl disklabel -w -r /dev/da0s1 da2212 foo
+.Dl "disklabel -w -r /dev/da0s1 da2212 foo"
 .Pp
 Create a label for
 .Pa da0s1
@@ -658,30 +703,36 @@ based on information for
 .Dq da2212
 found in
 .Pa /etc/disktab .
-Any existing bootstrap code will be clobbered.
+Any existing bootstrap code will be clobbered
+and the disk rendered unbootable.
 .Pp
-.Dl disklabel -e -r da0s1
+.Dl "disklabel -e -r da0s1"
 .Pp
 Read the on-disk label for
 .Pa da0s1 ,
-edit it and reinstall in-core as well as on-disk.  Existing bootstrap code is
-unaffected.
+edit it, and reinstall in-core as well as on-disk.
+Existing bootstrap code is unaffected.
 .Pp
-.Dl disklabel -e -r -n da0s1
+.Dl "disklabel -e -r -n da0s1"
 .Pp
 Read the on-disk label for
 .Pa da0s1 ,
-edit it, and display what the new label would be (in sectors).  It does
-NOT install the new label either in-core or on-disk.
+edit it, and display what the new label would be (in sectors).
+It does
+.Em not
+install the new label either in-core or on-disk.
 .Pp
-.Dl disklabel -r -w da0s1 auto
+.Dl "disklabel -r -w da0s1 auto"
 .Pp
 Try to auto-detect the required information from
 .Pa da0s1 ,
-and write a new label to the disk.  Use another disklabel -e command to edit the
+and write a new label to the disk.
+Use another
+.Nm Fl e
+command to edit the
 partitioning and file system information.
 .Pp
-.Dl disklabel -R da0s1 savedlabel
+.Dl "disklabel -R da0s1 savedlabel"
 .Pp
 Restore the on-disk and in-core label for
 .Pa da0s1
@@ -689,7 +740,7 @@ from information in
 .Pa savedlabel .
 Existing bootstrap code is unaffected.
 .Pp
-.Dl disklabel -R -n da0s1 label_layout
+.Dl "disklabel -R -n da0s1 label_layout"
 .Pp
 Display what the label would be for
 .Pa da0s1
@@ -702,7 +753,7 @@ or
 .Cm *
 partition sizes.
 .Pp
-.Dl disklabel -B da0s1
+.Dl "disklabel -B da0s1"
 .Pp
 Install a new bootstrap on
 .Pa da0s1 .
@@ -710,38 +761,45 @@ The boot code comes from
 .Pa /boot/boot .
 On-disk and in-core labels are unchanged.
 .Pp
-.Dl disklabel -w -B /dev/da0s1 -b newboot da2212
+.Dl "disklabel -w -B /dev/da0s1 -b newboot da2212"
 .Pp
 Install a new label and bootstrap.
-The label is derived from disktab information for
-.Dq da2212
+The label is derived from
+.Xr disktab 5
+information for
+.Dq da2212 ,
 and installed both in-core and on-disk.
-The bootstrap code comes from the files
-.Pa /boot/newboot
-.Pp
-.Dl dd if=/dev/zero of=/dev/da0 bs=512 count=32
-.Dl fdisk -BI da0
-.Dl dd if=/dev/zero of=/dev/da0s1 bs=512 count=32
-.Dl disklabel -w -B da0s1 auto
-.Dl disklabel -e da0s1
+The bootstrap code comes from the file
+.Pa newboot
+in the current working directory.
+.Bd -literal -offset indent
+dd if=/dev/zero of=/dev/da0 bs=512 count=32
+fdisk -BI da0
+dd if=/dev/zero of=/dev/da0s1 bs=512 count=32
+disklabel -w -B da0s1 auto
+disklabel -e da0s1
+.Ed
 .Pp
 Completely wipe any prior information on the disk, creating a new bootable
-disk with a DOS partition table containing one
-.Dq whole-disk
-slice.  Then
-initialize the slice, then edit it to your needs.  The
-.Pa dd
-commands are optional, but may be necessary for some BIOSes to properly
+disk with a
+.Tn DOS
+partition table containing one slice, covering the whole disk.
+Initialize the label on this slice,
+then edit it.
+The
+.Xr dd 1
+commands are optional, but may be necessary for some
+.Tn BIOS Ns es
+to properly
 recognize the disk.
 .Pp
-This is an example disklabel that uses some of the new partition size types
+This is an example disk label that uses some of the new partition size types
 such as
 .Cm % , M , G ,
 and
 .Cm * ,
 which could be used as a source file for
-.Pp
-.Dl disklabel -R ad0s1c new_label_file
+.Dq Li "disklabel -R ad0s1c new_label_file" :
 .Bd -literal -offset 4n
 # /dev/ad0s1c:
 type: ESDI
@@ -773,6 +831,7 @@ drivedata: 0
 .Ed
 .Sh SEE ALSO
 .Xr ccd 4 ,
+.Xr md 4 ,
 .Xr disklabel 5 ,
 .Xr disktab 5 ,
 .Xr boot0cfg 8 ,
@@ -783,35 +842,43 @@ The kernel device drivers will not allow the size of a disk partition
 to be decreased or the offset of a partition to be changed while it is open.
 Some device drivers create a label containing only a single large partition
 if a disk is unlabeled; thus, the label must be written to the
-.Dq a
-partition of the disk while it is open.  This sometimes requires the desired
-label to be set in two steps, the first one creating at least one other
-partition, and the second setting the label on the new partition while shrinking
-the
-.Dq a
+.Ql a
+partition of the disk while it is open.
+This sometimes requires the desired label to be set in two steps,
+the first one creating at least one other partition,
+and the second one setting the label on the new partition
+while shrinking the
+.Ql a
 partition.
 .Pp
-On some machines the bootstrap code may not fit entirely in the area
+On some machines, the bootstrap code may not fit entirely in the area
 allocated for it by some file systems.
-As a result, it may not be possible to have file systems on some partitions
-of a
+As a result,
+it may not be possible to have file systems on some partitions of a
 .Dq bootable
 disk.
 When installing bootstrap code,
 .Nm
 checks for these cases.
-If the installed boot code would overlap a partition of type FS_UNUSED
-it is marked as type FS_BOOT.
+If the installed boot code would overlap a partition of type
+.Dv FS_UNUSED ,
+it is marked as type
+.Dv FS_BOOT .
 The
 .Xr newfs 8
-utility will disallow creation of file systems on FS_BOOT partitions.
-Conversely, if a partition has a type other than FS_UNUSED or FS_BOOT,
+utility will disallow creation of file systems on
+.Dv FS_BOOT
+partitions.
+Conversely, if a partition has a type other than
+.Dv FS_UNUSED
+or
+.Dv FS_BOOT ,
 .Nm
 will not install bootstrap code that overlaps it.
 .Sh BUGS
 When a disk name is given without a full pathname,
 the constructed device name uses the
-.Dq c
+.Ql c
 partition.
 .Pp
 For the i386 architecture, the primary bootstrap sector contains
@@ -831,18 +898,22 @@ or
 .Fl R ,
 thus replacing the
 .Em fdisk
-table by the dummy one in the bootstrap program.  This is only of
+table by the dummy one in the bootstrap program.
+This is only of
 concern if the disk is fully dedicated, so that the
-.Bx
-disklabel
+.Fx
+disk label
 starts at absolute block 0 on the disk.
 .Pp
 The
 .Nm
 utility
-does not perform all possible error checking.  Warning *is* given if partitions
-overlap; if an absolute offset does not match the expected offset; if the
-.Dq c
-partition does not start at 0 or does not cover the entire slice; if a
-partition runs past the end of the device; and a number of other errors; but
-no warning is given if space remains unused.
+does not perform all possible error checking.
+Warning is given if partitions overlap,
+if an absolute offset does not match the expected offset,
+if the
+.Ql c
+partition does not start at 0 or does not cover the entire slice,
+if a partition runs past the end of the device,
+and a number of other errors,
+but no warning is given if space remains unused.