path: root/en_US.ISO8859-1/books/fdp-primer/doc-build
diff options
authorWarren Block <wblock@FreeBSD.org>2013-07-20 01:21:45 +0000
committerWarren Block <wblock@FreeBSD.org>2013-07-20 01:21:45 +0000
commit93bfc7e929245e741dd369bcae2374cc322bf9da (patch)
tree412f71fee36df93d36a092e00a3f55919dd49080 /en_US.ISO8859-1/books/fdp-primer/doc-build
parent32622975a26e9f7dacea7ad04ee67fb0474b25dd (diff)
Update, simplify, and clarify the doc-build chapter.
Notes: svn path=/head/; revision=42328
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/doc-build')
1 files changed, 41 insertions, 81 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 05d5abbea4..e83d4afa21 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
@@ -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>
- <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>
- <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>
- <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>
- <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>
- <note>
- <para>It is unlikely you will have any trouble finding these
- last two, they are mentioned for completeness only.</para>
- </note>
<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>
@@ -150,13 +116,13 @@ COMPAT_SYMLINK = en
.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
@@ -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>
@@ -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
<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>
<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>
@@ -321,10 +282,10 @@ PRI_LANG?= en_US.ISO8859-1
- <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>
@@ -332,7 +293,7 @@ PRI_LANG?= en_US.ISO8859-1
<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
- <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>
@@ -389,8 +349,8 @@ PRI_LANG?= en_US.ISO8859-1
<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