aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/doc-build
diff options
context:
space:
mode:
authorGabor Kovesdan <gabor@FreeBSD.org>2013-11-07 15:39:28 +0000
committerGabor Kovesdan <gabor@FreeBSD.org>2013-11-07 15:39:28 +0000
commit24d129e8d1984a0b46a543bc523b63d216813bb0 (patch)
tree7dd0501c857c6f2139f4a71191c93bf19136412a /en_US.ISO8859-1/books/fdp-primer/doc-build
parent35f1d6c78be90eb13320d655cd68f94333a0ab26 (diff)
downloaddoc-24d129e8d1984a0b46a543bc523b63d216813bb0.tar.gz
doc-24d129e8d1984a0b46a543bc523b63d216813bb0.zip
- Definitively upgrade to DocBook 5.0
Notes
Notes: svn path=/projects/db5/; revision=43125
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/doc-build')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml114
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>