Update, simplify, and clarify the doc-build chapter.

svn path=/head/; revision=42328

en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml

@@ -34,75 +34,41 @@
 <chapter id="doc-build">
   <title>The Documentation Build Process</title>
 
-  <para>This chapter's main purpose is to clearly explain
-    <emphasis>how the documentation build process is
-      organized</emphasis>, and <emphasis>how to affect modifications
-      to this process</emphasis>.</para>
-
-  <para>After you have finished reading this chapter you
-    should:</para>
-
-  <itemizedlist>
-    <listitem>
-      <para>Know what you need to build the FDP documentation, in
-	addition to those mentioned in the
-	<link linkend="tools">XML tools chapter</link>.</para>
-    </listitem>
-
-    <listitem>
-      <para>Be able to read and understand the
-	<application>make</application> instructions that are present
-	in each document's <filename>Makefile</filename>s, as well as
-	an overview of the <filename>doc.project.mk</filename>
-	includes.</para>
-    </listitem>
-
-    <listitem>
-      <para>Be able to customize the build process by using
-	<application>make</application> variables and
-	<application>make</application> targets.</para>
-    </listitem>
-  </itemizedlist>
+  <para>This chapter covers organization of the
+    documentation build process
+    and how &man.make.1; is used to control
+    it.</para>
 
   <sect1 id="doc-build-toolset">
-    <title>The FreeBSD Documentation Build Toolset</title>
+    <title>The &os; Documentation Build Toolset</title>
 
-    <para>Here are your tools.  Use them every way you can.</para>
+    <para>These are the tools used to build and install the <acronym>FDP</acronym> documentation.</para>
 
     <itemizedlist>
       <listitem>
-	<para>The primary build tool you will need is
-	  <application>make</application>, but specifically
+	<para>The primary build tool is
+	  &man.make.1;, specifically
 	  <application>Berkeley Make</application>.</para>
       </listitem>
 
       <listitem>
-	<para>Package building is handled by FreeBSD's
-	  <application>pkg_create</application>.  If you are not using
-	  FreeBSD, you will either have to live without packages, or
-	  compile the source yourself.</para>
+	<para>Package building is handled by &os;'s
+	  &man.pkg.create.1;.</para>
       </listitem>
 
       <listitem>
-	<para><application>gzip</application> is needed to create
+	<para>&man.gzip.1; is used to create
 	  compressed versions of the document.
-	  <application>bzip2</application> compression and
-	  <application>zip</application> archives are also supported.
-	  <application>tar</application> is supported, but package
-	  building demands it.</para>
+	  &man.bzip2.1; archives are also supported.
+	  &man.tar.1; is used for package
+	  building.</para>
       </listitem>
 
       <listitem>
-	<para><application>install</application> is the default method
-	  to install the documentation.  There are alternatives,
-	  however.</para>
+	<para>&man.install.1; is used
+	  to install the documentation.</para>
       </listitem>
     </itemizedlist>
-
-    <note>
-      <para>It is unlikely you will have any trouble finding these
-	last two, they are mentioned for completeness only.</para>
-    </note>
   </sect1>
 
   <sect1 id="doc-build-makefiles">
@@ -111,7 +77,7 @@
       Documentation Tree</title>
 
     <para>There are three main types of <filename>Makefile</filename>s
-      in the FreeBSD Documentation Project tree.</para>
+      in the &os; Documentation Project tree.</para>
 
     <itemizedlist>
       <listitem>
@@ -150,13 +116,13 @@ COMPAT_SYMLINK = en
 DOC_PREFIX?= ${.CURDIR}/..
 .include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
 
-      <para>In quick summary, the first four non-empty lines define
-	the <application>make</application> variables,
+      <para>The first four non-empty lines define
+	the &man.make.1; variables
 	<makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>,
 	and <makevar>DOC_PREFIX</makevar>.</para>
 
-      <para>The first <makevar>SUBDIR</makevar> statement, as well as
-	the <makevar>COMPAT_SYMLINK</makevar> statement, shows how to
+      <para>The <makevar>SUBDIR</makevar> statement and
+	<makevar>COMPAT_SYMLINK</makevar> statement show how to
 	assign a value to a variable, overriding any previous
 	value.</para>
 
@@ -172,7 +138,7 @@ DOC_PREFIX?= ${.CURDIR}/..
 	<filename>Makefile</filename> thinks it is - the user can
 	override this and provide the correct value.</para>
 
-      <para>Now what does it all mean?  <makevar>SUBDIR</makevar>
+      <para>What does it all mean?  <makevar>SUBDIR</makevar>
 	mentions which subdirectories below this one the build process
 	should pass any work on to.</para>
 
@@ -182,14 +148,14 @@ DOC_PREFIX?= ${.CURDIR}/..
 	point to <filename>en_US.ISO-8859-1</filename>).</para>
 
       <para><makevar>DOC_PREFIX</makevar> is the path to the root of
-	the FreeBSD Document Project tree.  This is not always that
+	the &os; Document Project tree.  This is not always that
 	easy to find, and is also easily overridden, to allow for
 	flexibility.  <makevar>.CURDIR</makevar> is a
-	<application>make</application> builtin variable with the path
+	&man.make.1; builtin variable with the path
 	to the current directory.</para>
 
-      <para>The final line includes the FreeBSD Documentation
-	Project's project-wide <application>make</application> system
+      <para>The final line includes the &os; Documentation
+	Project's project-wide &man.make.1; system
 	file <filename>doc.project.mk</filename> which is the glue
 	which converts these variables into build instructions.</para>
     </sect2>
@@ -197,8 +163,8 @@ DOC_PREFIX?= ${.CURDIR}/..
     <sect2 id="doc-make">
       <title>Documentation <filename>Makefile</filename>s</title>
 
-      <para>These <filename>Makefile</filename>s set a bunch of
-	<application>make</application> variables that describe how to
+      <para>These <filename>Makefile</filename>s set
+	&man.make.1; variables that describe how to
 	build the documentation contained in that directory.</para>
 
       <para>Here is an example:</para>
@@ -219,10 +185,10 @@ DOC_PREFIX?= ${.CURDIR}/../../..
 
 .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
 
-      <para>The <makevar>MAINTAINER</makevar> variable is a very
-	important one.  This variable provides the ability to claim
-	ownership over a document in the FreeBSD Documentation
-	Project, whereby you gain the responsibility for maintaining
+      <para>The <makevar>MAINTAINER</makevar> variable
+	allows committers to claim
+	ownership of a document in the &os; Documentation
+	Project, and take responsibility for maintaining
 	it.</para>
 
       <para><makevar>DOC</makevar> is the name (sans the
@@ -240,21 +206,16 @@ DOC_PREFIX?= ${.CURDIR}/../../..
 	default, should be non-empty if only compressed documents are
 	desired in the build.</para>
 
-      <note>
-	<para>We covered optional variable assignments in the
-	  <link linkend="sub-make">previous section</link>.</para>
-      </note>
-
       <para>The <makevar>DOC_PREFIX</makevar> and include statements
 	should be familiar already.</para>
     </sect2>
   </sect1>
 
   <sect1 id="make-includes">
-    <title>FreeBSD Documentation Project
+    <title>&os; Documentation Project
       <application>Make</application> Includes</title>
 
-    <para>This is best explained by inspection of the code.  Here are
+    <para>&man.make.1; includes are best explained by inspection of the code.  Here are
       the system include files:</para>
 
     <itemizedlist>
@@ -321,10 +282,10 @@ PRI_LANG?=	en_US.ISO8859-1
 	  default.</para>
 
 	<note>
-	  <para><makevar>PRI_LANG</makevar> in no way affects what
+	  <para><makevar>PRI_LANG</makevar> does not affect which
 	    documents can, or even will, be built.  Its main use is
 	    creating links to commonly referenced documents into the
-	    FreeBSD documentation install root.</para>
+	    &os; documentation install root.</para>
 	</note>
       </sect3>
 
@@ -332,7 +293,7 @@ PRI_LANG?=	en_US.ISO8859-1
 	<title>Conditionals</title>
 
 	<para>The <literal>.if defined(DOC)</literal> line is an
-	  example of a <application>make</application> conditional
+	  example of a &man.make.1; conditional
 	  which, like in other programs, defines behavior if some
 	  condition is true or if it is false.
 	  <literal>defined</literal> is a function which returns
@@ -351,9 +312,8 @@ PRI_LANG?=	en_US.ISO8859-1
     <sect2>
       <title><filename>doc.subdir.mk</filename></title>
 
-      <para>This is too long to explain by inspection, you should be
-	able to work it out with the knowledge gained from the
-	previous chapters, and a little help given here.</para>
+      <para>This file is too long to explain in detail.  These
+	notes describe the most important features.</para>
 
       <sect3>
 	<title>Variables</title>
@@ -389,8 +349,8 @@ PRI_LANG?=	en_US.ISO8859-1
 	  <literal><replaceable>target</replaceable>:
 	      <replaceable>dependency1 dependency2
 	      ...</replaceable></literal> tuples, where to build
-	  <literal>target</literal>, you need to build the given
-	  dependencies first.</para>
+	  <literal>target</literal>, the given
+	  dependencies must be built first.</para>
 
 	<para>After that descriptive tuple, instructions on how to
 	  build the target may be given, if the conversion process