1 files changed, 88 insertions, 68 deletions

diff --git a/share/man/man7/release.7 b/share/man/man7/release.7
index 0c207cede904a..0362e1d8d16d9 100644
--- a/share/man/man7/release.7
+++ b/share/man/man7/release.7
@@ -29,24 +29,24 @@
 .Os
 .Sh NAME
 .Nm release
-.Nd information on the process used to build a complete system release
+.Nd release building infrastructure
 .Sh DESCRIPTION
 .Fx
 provides a complete build environment suitable for users to make
 full releases of the
 .Fx
-Operating System.
+operating system.
 All of the tools necessary to build a release are available from the
-CVS repository in 
+CVS repository in
 .Pa src/release .
 A complete release can actually be built with only a single command,
 including the creation of ISO images suitable for burning to CDROM,
-installation floppies, and an FTP install directory.  
+installation floppies, and an FTP install directory.
 This command is aptly named
 .Dq make release .
 .Pp
 Before attempting to build a release, the user is expected to be
-experienced with the contents of
+familiar with the contents of
 .Xr build 7 ,
 and should have experience upgrading systems from source with
 .Dq make world .
@@ -55,24 +55,25 @@ The release build process requires that
 be populated with the output of
 .Dq make buildworld .
 This is necessary so that the object files for a complete system can
-be installed into a clean 
+be installed into a clean
 .Xr chroot 8
 environment.
 The release procedure also requires that the
-.Pa md 
-(memory disk) device driver be present in the kernel.
+.Xr md 4
+(memory disk) device driver be present in the kernel
+(either by being compiled in or loaded as a module).
 .Pp
 This document does not cover source code management, quality
 assurance, or other aspects of the release engineering process.
 .Sh TARGETS
-.Pp
 The release makefile
-.Pa (src/release/makefile)
+.Pq Pa src/release/Makefile
 is fairly abstruse.
 Most developers will only be concerned with the
-.Pa release
+.Ar release
 target.
-.Bl -tag -width configure
+.\" XXX: Some sort of introduction to this list?  All the others have one.
+.Bl -tag -width rerelease
 .It Ar release
 Uses
 .Dq make installworld
@@ -81,7 +82,7 @@ to install a clean system into a
 environment on the filesystem.
 Checks out the specified version of the source code and then rebuilds
 the entire system in the clean environment with
-.Dq make world .  
+.Dq make world .
 The detailed steps that follow are then executed to package up the
 different distributions, build the installation floppy disks, build
 release documentation, and so on.
@@ -93,10 +94,10 @@ the intermediate output of the previous
 .El
 .Pp
 Targets called by
-.Dq make release .
-.Bl -tag -width configure
+.Dq make release :
+.Bl -tag -width release.9
 .It Ar release.1
-Cleans out the 
+Cleans out the
 .Pa ${CHROOTDIR}/R
 directory and uses
 .Xr mtree 1
@@ -104,11 +105,15 @@ to build the directory hierarchy for the system.
 .It Ar release.2
 Installs the system into the distribution directories.
 .It Ar release.3
-Makes and installs the GENERIC kernel(s).
+.\" XXX: This should either be "GENERIC kernel" (singular) or
+.\" XXX: "GENERIC and <some other> kernels".
+Makes and installs the
+.Pa GENERIC
+kernel.
 .It Ar release.4
 Uses
 .Xr crunchgen 1
-to build 
+to build
 .Sq crunched
 binaries to live on the installation floppies.
 .It Ar release.5
@@ -127,50 +132,61 @@ Sets up a suitable area for FTP installations.
 .It Ar cdrom.1
 Sets up a suitable area to build CDROM images.
 .It Ar iso.1
-Builds two ISO images (installation and 
+Builds two ISO images (installation and
 .Sq live
-filesystem) from the CDROM release area.
+filesystem) from the CDROM release area
+(Disabled by default, see
+.Pa MAKE_ISOS
+below).
 .It Ar doc.1
-Builds all of the necessary tools to turn the FreeBSD Documentation
-Project source documents (SGML, XML) into HTML and text documents that
-will accompany the release.  Also, builds and installs the actual
-user documentation.  This includes the Handbook, FAQ, articles, and so
-on.
+Builds all of the necessary tools to turn the
+.Fx
+Documentation Project source documents (SGML, XML) into HTML
+and text documents that will accompany the release.
+Also, builds and installs the actual user documentation.
+This includes the Handbook, FAQ, articles, and so on.
 .It Ar doc.2
-Builds the release documentation.  This includes the release notes,
+Builds the release documentation.
+This includes the release notes,
 hardware guide, and installation instructions.
 .El
 .Sh ENVIRONMENT
-.Pp
-Variables that you must specify:
-.Bl -tag -width configure
+Variables that must be specified:
+.Bl -tag -width RELEASETAG
 .It Ev CHROOTDIR
 The directory to be used as the
 .Xr chroot 8
 environment for the entire release build.
+.\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
+.\" XXX: perhaps it should be replaced with something to the effect of
+.\" XXX: "we don't know how much space you'll need, but make sure you have
+.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
+.\" XXX: but at least it looks less like a decree and more like an estimate.
 This filesystem should have at least 2.3 gigabytes of free space on the
 i386 architecture.
 .It Ev BUILDNAME
-The name of the release to be built.  This is used to set the
-.Pa RELEASE
+The name of the release to be built.
+This is used to set the
+.Dv RELEASE
 value in
 .Pa sys/conf/newvers.sh ,
 which affects the output of
 .Xr uname 1 .
 .It Ev CVSROOT
-The location of a CVS Repository.
+The location of the
+.Fx
+CVS repository.
 .It Ev RELEASETAG
-The CVS tag corresponding to the release you would like to build.
+The CVS tag corresponding to the release that is to be built.
 If undefined, the release will be built from the HEAD of the CVS tree
 (a
-.Sq -CURRENT snapshot
-).
+.Sq -CURRENT snapshot ) .
 .El
 .Pp
 Optional variables:
-.Bl -tag -width configure
+.Bl -tag -width RELEASEDISTFILES
 .It Ev LOCAL_PATCHES
-A patch file against 
+A patch file against
 .Pa /usr/src
 that will be applied in the
 .Xr chroot 8
@@ -179,18 +195,18 @@ environment before the release build begins.
 Arguments for the
 .Xr patch 1
 command used to apply
-.Pa LOCAL_PATCHES .
+.Ev LOCAL_PATCHES .
 .It Ev MAKE_ISOS
 If defined, bootable ISO CDROM images will be created from the
 contents of the CDROM stage directory.
 .It Ev NODOC
 If set to
 .Dq YES
-then the documentation will not be built.  Due to the SGML based
+then the documentation will not be built.
+Due to the SGML-based
 toolchain and multiple languages supported by the
 .Fx
-Documentation Project, this may speed up the release build time
-considerably.
+Documentation Project, this may speed up the release build considerably.
 .It Ev NOPORTS
 If set to
 .Dq YES
@@ -222,9 +238,9 @@ the source code will not be updated with
 .It Pa /usr/src/release/${arch}/fixit_crunch.conf
 .El
 .Sh EXAMPLES
-The following commands were used to build the
+The following sequence of commands was used to build the
 .Fx 4.5
-release :
+release:
 .Bd -literal -offset indent
 cd /usr
 cvs co -rRELENG_4_5_0_RELEASE src
@@ -237,11 +253,13 @@ make release CHROOTDIR=/local3/release BUILDNAME=4.5-RELEASE \\
 .Pp
 After running these commands, a complete system suitable for FTP or
 CDROM distribution is available in the
-.Pa /local3/release/R/
+.Pa /local3/release/R
 directory.
 .Pp
-The following commands can be used to build a -CURRENT snapshot of a
-locally modified source tree :
+The following sequence of commands can be used to build a
+.Sq -CURRENT snapshot
+of a
+locally modified source tree:
 .Bd -literal -offset indent
 cd /usr/src
 cvs diff -u > /path/to/local.patch
@@ -262,38 +280,40 @@ make release CHROOTDIR=/local3/release BUILDNAME=5.0-SNAPSHOT \\
 .Xr build 7 ,
 .Xr ports 7 ,
 .Xr chroot 8
-.Pp
-.Fx
-Release Engineering
-http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng
-.Pp
-.Fx
-Release Engineering of Third Party Packages
-http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages
-.Pp
-.Fx
-Developer's Handbook
-http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook
+.Rs
+.%T FreeBSD Release Engineering
+.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
+.Re
+.Rs
+.%T FreeBSD Release Engineering of Third Party Packages
+.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
+.Re
+.Rs
+.%T FreeBSD Developers' Handbook
+.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
+.Re
 .Sh HISTORY
-.Pp
 .Fx
 1.x
-used a manual checklist, compiled by Rod Grimes to produce a release.
+used a manual checklist, compiled by Rod Grimes, to produce a release.
 Apart from being incomplete, the list put a lot of specific demands on
-available filesystems and was quite torturous to execute. 
+available filesystems and was quite torturous to execute.
 .Pp
-As part of the FreeBSD 2.0 release engineering effort, significant
-effort was spent getting 
+As part of the
+.Fx 2.0
+release engineering effort, significant
+effort was spent getting
 .Pa src/release/Makefile
 into a shape where it could at least automate most of the tediousness
 of building a release in a sterile environment.
 .Pp
-With its almost 1000 revisions spread over multiple branches, the cvs
-log of src/release/Makefile contains a vivid historical record of some
+With its almost 1000 revisions spread over multiple branches, the CVS
+log of
+.Pa src/release/Makefile
+contains a vivid historical record of some
 of the hardships release engineers go through.
 .Sh AUTHORS
 .Pa src/release/Makefile
-was originally written by Rod Grimes, Jordan Hubbard, and Poul-Henning
-Kamp.
-This man page was written by
+was originally written by Rod Grimes, Jordan Hubbard, and Poul-Henning Kamp.
+This manual page was written by
 .An Murray Stokely Aq murray@FreeBSD.org .