- Definitively upgrade to DocBook 5.0

1 files changed, 56 insertions, 58 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
index 95ab3e73a0..1f95722816 100644
--- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
@@ -30,14 +30,13 @@
 
      $FreeBSD$
 -->
-
-<chapter id="doc-build">
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="doc-build">
   <title>The Documentation Build Process</title>
 
   <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">
+  <sect1 xml:id="doc-build-toolset">
     <title>The &os; Documentation Build Toolset</title>
 
     <para>These are the tools used to build and install the
@@ -67,7 +66,7 @@
     </itemizedlist>
   </sect1>
 
-  <sect1 id="doc-build-makefiles">
+  <sect1 xml:id="doc-build-makefiles">
 
     <title>Understanding <filename>Makefile</filename>s in the
       Documentation Tree</title>
@@ -90,15 +89,14 @@
       </listitem>
 
       <listitem>
-	<para><link
-	    linkend="make-includes"><application>Make</application>
+	<para><link linkend="make-includes"><application>Make</application>
 	  includes</link> are the glue that perform the document
 	  production, and are usually of the form
-	  <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
+	  <filename>doc.xxx.mk</filename>.</para>
       </listitem>
     </itemizedlist>
 
-    <sect2 id="sub-make">
+    <sect2 xml:id="sub-make">
       <title>Subdirectory <filename>Makefile</filename>s</title>
 
       <para>These <filename>Makefile</filename>s usually take the form
@@ -113,40 +111,40 @@ DOC_PREFIX?= ${.CURDIR}/..
 .include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
 
       <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>
+	variables <varname>SUBDIR</varname>,
+	<varname>COMPAT_SYMLINK</varname>, and
+	<varname>DOC_PREFIX</varname>.</para>
 
-      <para>The <makevar>SUBDIR</makevar> statement and
-	<makevar>COMPAT_SYMLINK</makevar> statement show how to
+      <para>The <varname>SUBDIR</varname> statement and
+	<varname>COMPAT_SYMLINK</varname> statement show how to
 	assign a value to a variable, overriding any previous
 	value.</para>
 
-      <para>The second <makevar>SUBDIR</makevar> statement shows how a
+      <para>The second <varname>SUBDIR</varname> statement shows how a
 	value is appended to the current value of a variable.  The
-	<makevar>SUBDIR</makevar> variable is now <literal>articles
+	<varname>SUBDIR</varname> variable is now <literal>articles
 	  books</literal>.</para>
 
-      <para>The <makevar>DOC_PREFIX</makevar> assignment shows how a
+      <para>The <varname>DOC_PREFIX</varname> assignment shows how a
 	value is assigned to the variable, but only if it is not
 	already defined.  This is useful if
-	<makevar>DOC_PREFIX</makevar> is not where this
+	<varname>DOC_PREFIX</varname> is not where this
 	<filename>Makefile</filename> thinks it is - the user can
 	override this and provide the correct value.</para>
 
-      <para>What does it all mean?  <makevar>SUBDIR</makevar>
+      <para>What does it all mean?  <varname>SUBDIR</varname>
 	mentions which subdirectories below this one the build process
 	should pass any work on to.</para>
 
-      <para><makevar>COMPAT_SYMLINK</makevar> is specific to
+      <para><varname>COMPAT_SYMLINK</varname> is specific to
 	compatibility symlinks (amazingly enough) for languages to
 	their official encoding (<filename>doc/en</filename> would
 	point to <filename>en_US.ISO-8859-1</filename>).</para>
 
-      <para><makevar>DOC_PREFIX</makevar> is the path to the root of
+      <para><varname>DOC_PREFIX</varname> is the path to the root of
 	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 &man.make.1;
+	flexibility.  <varname>.CURDIR</varname> is a &man.make.1;
 	builtin variable with the path to the current
 	directory.</para>
 
@@ -156,7 +154,7 @@ DOC_PREFIX?= ${.CURDIR}/..
 	converts these variables into build instructions.</para>
     </sect2>
 
-    <sect2 id="doc-make">
+    <sect2 xml:id="doc-make">
       <title>Documentation <filename>Makefile</filename>s</title>
 
       <para>These <filename>Makefile</filename>s set &man.make.1;
@@ -181,32 +179,32 @@ DOC_PREFIX?= ${.CURDIR}/../../..
 
 .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
 
-      <para>The <makevar>MAINTAINER</makevar> variable allows
+      <para>The <varname>MAINTAINER</varname> 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
+      <para><varname>DOC</varname> is the name (sans the
 	<filename>.xml</filename> extension) of the main document
-	created by this directory.  <makevar>SRCS</makevar> lists all
+	created by this directory.  <varname>SRCS</varname> lists all
 	the individual files that make up the document.  This should
 	also include important files in which a change should result
 	in a rebuild.</para>
 
-      <para><makevar>FORMATS</makevar> indicates the default formats
+      <para><varname>FORMATS</varname> indicates the default formats
 	that should be built for this document.
-	<makevar>INSTALL_COMPRESSED</makevar> is the default list of
+	<varname>INSTALL_COMPRESSED</varname> is the default list of
 	compression techniques that should be used in the document
-	build.  <makevar>INSTALL_ONLY_COMPRESS</makevar>, empty by
+	build.  <varname>INSTALL_ONLY_COMPRESS</varname>, empty by
 	default, should be non-empty if only compressed documents are
 	desired in the build.</para>
 
-      <para>The <makevar>DOC_PREFIX</makevar> and include statements
+      <para>The <varname>DOC_PREFIX</varname> and include statements
 	should be familiar already.</para>
     </sect2>
   </sect1>
 
-  <sect1 id="make-includes">
+  <sect1 xml:id="make-includes">
     <title>&os; Documentation Project
       <application>Make</application> Includes</title>
 
@@ -233,8 +231,8 @@ DOC_PREFIX?= ${.CURDIR}/../../..
 
       <listitem>
 	<para><filename>doc.docbook.mk</filename> is included if
-	  <makevar>DOCFORMAT</makevar> is <literal>docbook</literal>
-	  and <makevar>DOC</makevar> is set.</para>
+	  <varname>DOCFORMAT</varname> is <literal>docbook</literal>
+	  and <varname>DOC</varname> is set.</para>
       </listitem>
     </itemizedlist>
 
@@ -262,22 +260,22 @@ PRI_LANG?=	en_US.ISO8859-1
 
 	<title>Variables</title>
 
-	<para><makevar>DOCFORMAT</makevar> and
-	  <makevar>MAINTAINER</makevar> are assigned default values,
+	<para><varname>DOCFORMAT</varname> and
+	  <varname>MAINTAINER</varname> are assigned default values,
 	  if these are not set by the document make file.</para>
 
-	<para><makevar>PREFIX</makevar> is the prefix under which the
+	<para><varname>PREFIX</varname> is the prefix under which the
 	  <link linkend="tools">documentation building tools</link>
 	  are installed.  For normal package and port installation,
 	  this is <filename>/usr/local</filename>.</para>
 
-	<para><makevar>PRI_LANG</makevar> should be set to whatever
+	<para><varname>PRI_LANG</varname> should be set to whatever
 	  language and encoding is natural amongst users these
 	  documents are being built for.  US English is the
 	  default.</para>
 
 	<note>
-	  <para><makevar>PRI_LANG</makevar> does not affect which
+	  <para><varname>PRI_LANG</varname> does not affect which
 	    documents can, or even will, be built.  Its main use is
 	    creating links to commonly referenced documents into the
 	    &os; documentation install root.</para>
@@ -294,7 +292,7 @@ PRI_LANG?=	en_US.ISO8859-1
 	  returns whether the variable given is defined or not.</para>
 
 	<para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
-	  tests whether the <makevar>DOCFORMAT</makevar> variable is
+	  tests whether the <varname>DOCFORMAT</varname> variable is
 	  <literal>"docbook"</literal>, and in this case, includes
 	  <filename>doc.docbook.mk</filename>.</para>
 
@@ -314,21 +312,21 @@ PRI_LANG?=	en_US.ISO8859-1
 
 	<itemizedlist>
 	  <listitem>
-	    <para><makevar>SUBDIR</makevar> is a list of
+	    <para><varname>SUBDIR</varname> is a list of
 	      subdirectories that the build process should go further
 	      down into.</para>
 	  </listitem>
 
 	  <listitem>
-	    <para><makevar>ROOT_SYMLINKS</makevar> is the name of
+	    <para><varname>ROOT_SYMLINKS</varname> is the name of
 	      directories that should be linked to the document
 	      install root from their actual locations, if the current
 	      language is the primary language (specified by
-	      <makevar>PRI_LANG</makevar>).</para>
+	      <varname>PRI_LANG</varname>).</para>
 	  </listitem>
 
 	  <listitem>
-	    <para><makevar>COMPAT_SYMLINK</makevar> is described in
+	    <para><varname>COMPAT_SYMLINK</varname> is described in
 	      the
 	      <link linkend="sub-make">Subdirectory Makefile</link>
 	      section.</para>
@@ -340,9 +338,9 @@ PRI_LANG?=	en_US.ISO8859-1
 	<title>Targets and Macros</title>
 
 	<para>Dependencies are described by
-	  <literal><replaceable>target</replaceable>:
-	      <replaceable>dependency1 dependency2
-	      ...</replaceable></literal> tuples, where to build
+	  <literal>target:
+	      dependency1 dependency2
+	      ...</literal> tuples, where to build
 	  <literal>target</literal>, the given
 	  dependencies must be built first.</para>
 
@@ -362,7 +360,7 @@ PRI_LANG?=	en_US.ISO8859-1
 	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
 .endfor</programlisting>
 
-	<para>In the above, <maketarget>_SUBDIRUSE</maketarget> is now
+	<para>In the above, <buildtarget>_SUBDIRUSE</buildtarget> is now
 	  a macro which will execute the given commands when it is
 	  listed as a dependency.</para>
 
@@ -370,18 +368,18 @@ PRI_LANG?=	en_US.ISO8859-1
 	  Basically, it is executed <emphasis>after</emphasis> the
 	  instructions given in the build procedure it is listed as a
 	  dependency to, and it does not adjust
-	  <makevar>.TARGET</makevar>, which is the variable which
+	  <varname>.TARGET</varname>, which is the variable which
 	  contains the name of the target currently being
 	  built.</para>
 
 	<programlisting>clean: _SUBDIRUSE
 	rm -f ${CLEANFILES}</programlisting>
 
-	<para>In the above, <maketarget>clean</maketarget> will use
-	  the <maketarget>_SUBDIRUSE</maketarget> macro after it has
+	<para>In the above, <buildtarget>clean</buildtarget> will use
+	  the <buildtarget>_SUBDIRUSE</buildtarget> macro after it has
 	  executed the instruction
 	  <command>rm -f ${CLEANFILES}</command>.  In effect, this
-	  causes <maketarget>clean</maketarget> to go further and
+	  causes <buildtarget>clean</buildtarget> to go further and
 	  further down the directory tree, deleting built files as it
 	  goes <emphasis>down</emphasis>, not on the way back
 	  up.</para>
@@ -391,20 +389,20 @@ PRI_LANG?=	en_US.ISO8859-1
 
 	  <itemizedlist>
 	    <listitem>
-	      <para><maketarget>install</maketarget> and
-		<maketarget>package</maketarget> both go down the
+	      <para><buildtarget>install</buildtarget> and
+		<buildtarget>package</buildtarget> both go down the
 		directory tree calling the real versions of themselves
 		in the subdirectories
-		(<maketarget>realinstall</maketarget> and
-		<maketarget>realpackage</maketarget>
+		(<buildtarget>realinstall</buildtarget> and
+		<buildtarget>realpackage</buildtarget>
 		respectively).</para>
 	    </listitem>
 
 	    <listitem>
-	      <para><maketarget>clean</maketarget> removes files
+	      <para><buildtarget>clean</buildtarget> removes files
 		created by the build process (and goes down the
 		directory tree too).
-		<maketarget>cleandir</maketarget> does the same, and
+		<buildtarget>cleandir</buildtarget> does the same, and
 		also removes the object directory, if any.</para>
 	    </listitem>
 	  </itemizedlist>
@@ -449,11 +447,11 @@ PRI_LANG?=	en_US.ISO8859-1
 	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
 .endfor</programlisting>
 
-	<para>In the above, if <makevar>SUBDIR</makevar> is empty, no
+	<para>In the above, if <varname>SUBDIR</varname> is empty, no
 	  action is taken; if it has one or more elements, the
 	  instructions between <literal>.for</literal> and
 	  <literal>.endfor</literal> would repeat for every element,
-	  with <makevar>entry</makevar> being replaced with the value
+	  with <varname>entry</varname> being replaced with the value
 	  of the current element.</para>
       </sect3>
     </sect2>