aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer
diff options
context:
space:
mode:
authorWarren Block <wblock@FreeBSD.org>2012-02-15 04:27:21 +0000
committerWarren Block <wblock@FreeBSD.org>2012-02-15 04:27:21 +0000
commite8247723589010d038f44746a396839ffa573860 (patch)
tree9a83c7ac7b9af4f57e365686da02d99e478d5de7 /en_US.ISO8859-1/books/fdp-primer
parentb041378752b5dae5d3585ed261be8c6bfd09050f (diff)
downloaddoc-e8247723589010d038f44746a396839ffa573860.tar.gz
doc-e8247723589010d038f44746a396839ffa573860.zip
Whitespace-only changes. Wrap long lines and fix indentation.
Notes
Notes: svn path=/head/; revision=38460
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml236
1 files changed, 126 insertions, 110 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
index 38b62abc46..5ad49d1772 100644
--- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
@@ -33,27 +33,29 @@
<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>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>
+ <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">SGML tools chapter</link>.</para>
+ addition to those mentioned in the
+ <link linkend="tools">SGML 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>
+ <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
@@ -97,34 +99,36 @@
</itemizedlist>
<note>
- <para>It is unlikely you will have any trouble finding these last two, they
- are mentioned for completeness only.</para>
+ <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">
<title>Understanding Makefiles in the Documentation tree</title>
- <para>There are three main types of <filename>Makefile</filename>s
+ <para>There are three main types of <filename>Makefile</filename>s
in the FreeBSD Documentation Project tree.</para>
<itemizedlist>
<listitem>
<para><link linkend="sub-make">Subdirectory
- <filename>Makefile</filename>s</link> simply pass
+ <filename>Makefile</filename>s</link> simply pass
commands to those directories below them.</para>
</listitem>
<listitem>
<para><link linkend="doc-make">Documentation
- <filename>Makefile</filename>s</link> describe the
- document(s) that should be produced from this directory.</para>
+ <filename>Makefile</filename>s</link> describe the
+ document(s) that should be produced from this
+ directory.</para>
</listitem>
<listitem>
- <para><link linkend="make-includes"><application>Make</application>
- includes</link> are the glue that perform the document production,
- and are usually of the form
+ <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>
</listitem>
</itemizedlist>
@@ -132,7 +136,8 @@
<sect2 id="sub-make">
<title>Subdirectory Makefiles</title>
- <para>These <filename>Makefile</filename>s usually take the form of:</para>
+ <para>These <filename>Makefile</filename>s usually take the form
+ of:</para>
<programlisting>SUBDIR =articles
SUBDIR+=books
@@ -142,8 +147,8 @@ 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>In quick summary, the first four non-empty lines define
+ the <application>make</application> variables,
<makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>,
and <makevar>DOC_PREFIX</makevar>.</para>
@@ -155,35 +160,37 @@ DOC_PREFIX?= ${.CURDIR}/..
<para>The second <makevar>SUBDIR</makevar> statement shows how a
value is appended to the current value of a variable. The
<makevar>SUBDIR</makevar> variable is now <literal>articles
- books</literal>.</para>
+ books</literal>.</para>
<para>The <makevar>DOC_PREFIX</makevar> 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 <filename>Makefile</filename> thinks it is - the user
- can override this and provide the correct value.</para>
+ 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
+ <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>
mentions which subdirectories below this one the build process
should pass any work on to.</para>
<para><makevar>COMPAT_SYMLINK</makevar> 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 the
- FreeBSD 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 to the current directory.</para>
-
- <para>The final line includes the FreeBSD Documentation Project's
- project-wide <application>make</application> system file
- <filename>doc.project.mk</filename> which is the glue which
- converts these variables into build instructions.</para>
-
+ 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
+ the FreeBSD 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
+ to the current directory.</para>
+
+ <para>The final line includes the FreeBSD Documentation
+ Project's project-wide <application>make</application> system
+ file <filename>doc.project.mk</filename> which is the glue
+ which converts these variables into build instructions.</para>
</sect2>
+
<sect2 id="doc-make">
<title>Documentation Makefiles</title>
@@ -209,10 +216,10 @@ DOC_PREFIX?= ${.CURDIR}/../../..
.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
- <para>The <makevar>MAINTAINER</makevar> variable is a very
+ <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
+ Project, whereby you gain the responsibility for maintaining
it.</para>
<para><makevar>DOC</makevar> is the name (sans the
@@ -231,7 +238,7 @@ DOC_PREFIX?= ${.CURDIR}/../../..
desired in the build.</para>
<note>
- <para>We covered optional variable assignments in the
+ <para>We covered optional variable assignments in the
<link linkend="sub-make">previous section</link>.</para>
</note>
@@ -249,13 +256,14 @@ DOC_PREFIX?= ${.CURDIR}/../../..
<itemizedlist>
<listitem>
<para><filename>doc.project.mk</filename> is the main project
- include file, which includes all the following include files, as
- necessary.</para>
+ include file, which includes all the following include
+ files, as necessary.</para>
</listitem>
<listitem>
<para><filename>doc.subdir.mk</filename> handles traversing of
- the document tree during the build and install processes.</para>
+ the document tree during the build and install
+ processes.</para>
</listitem>
<listitem>
@@ -294,35 +302,37 @@ PRI_LANG?= en_US.ISO8859-1
<title>Variables</title>
- <para><makevar>DOCFORMAT</makevar> and <makevar>MAINTAINER</makevar>
- are assigned default values, if these are not set by the
- document make file.</para>
+ <para><makevar>DOCFORMAT</makevar> and
+ <makevar>MAINTAINER</makevar> 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
- <link linkend="tools">documentation building tools</link> are
- installed. For normal package and port installation, this is
- <filename>/usr/local</filename>.</para>
+ <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
- language and encoding is natural amongst users these documents are
- being built for. US English is the default.</para>
+ 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> in no way affects what documents
- can, or even will, be built. Its main use is creating links to
- commonly referenced documents into the FreeBSD documentation
- install root.</para>
+ <para><makevar>PRI_LANG</makevar> in no way affects what
+ documents can, or even will, be built. Its main use is
+ creating links to commonly referenced documents into the
+ FreeBSD documentation install root.</para>
</note>
</sect3>
<sect3>
<title>Conditionals</title>
-
- <para>The <literal>.if defined(DOC)</literal> line is an example of
- a <application>make</application> 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 whether the variable given is defined or not.</para>
+
+ <para>The <literal>.if defined(DOC)</literal> line is an
+ example of a <application>make</application> 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
+ whether the variable given is defined or not.</para>
<para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
tests whether the <makevar>DOCFORMAT</makevar> variable is
@@ -338,17 +348,17 @@ PRI_LANG?= en_US.ISO8859-1
<title>doc.subdir.mk</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>
+ able to work it out with the knowledge gained from the
+ previous chapters, and a little help given here.</para>
<sect3>
<title>Variables</title>
<itemizedlist>
<listitem>
- <para><makevar>SUBDIR</makevar> is a list of subdirectories
- that the build process should go further down
- into.</para>
+ <para><makevar>SUBDIR</makevar> is a list of
+ subdirectories that the build process should go further
+ down into.</para>
</listitem>
<listitem>
@@ -360,7 +370,8 @@ PRI_LANG?= en_US.ISO8859-1
</listitem>
<listitem>
- <para><makevar>COMPAT_SYMLINK</makevar> is described in the
+ <para><makevar>COMPAT_SYMLINK</makevar> is described in
+ the
<link linkend="sub-make">Subdirectory Makefile</link>
section.</para>
</listitem>
@@ -370,17 +381,18 @@ PRI_LANG?= en_US.ISO8859-1
<sect3>
<title>Targets and macros</title>
- <para>Dependencies are described by
+ <para>Dependencies are described by
<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>
+ <replaceable>dependency1 dependency2
+ ...</replaceable></literal> tuples, where to build
+ <literal>target</literal>, you need to build the given
+ dependencies first.</para>
- <para>After that descriptive tuple, instructions on how to build
- the target may be given, if the conversion process between the
- target and its dependencies are not previously defined, or if
- this particular conversion is not the same as the default
- conversion method.</para>
+ <para>After that descriptive tuple, instructions on how to
+ build the target may be given, if the conversion process
+ between the target and its dependencies are not previously
+ defined, or if this particular conversion is not the same as
+ the default conversion method.</para>
<para>A special dependency <literal>.USE</literal> defines
the equivalent of a macro.</para>
@@ -392,27 +404,29 @@ 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 a
- macro which will execute the given commands when it is listed
- as a dependency.</para>
+ <para>In the above, <maketarget>_SUBDIRUSE</maketarget> is now
+ a macro which will execute the given commands when it is
+ listed as a dependency.</para>
- <para>What sets this macro apart from other targets? 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 contains the name of the target currently
- being built.</para>
+ <para>What sets this macro apart from other targets?
+ 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
+ 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
- executed the instruction
- <command>rm -f ${CLEANFILES}</command>. In effect, this causes
- <maketarget>clean</maketarget> 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>
+ <para>In the above, <maketarget>clean</maketarget> will use
+ the <maketarget>_SUBDIRUSE</maketarget> macro after it has
+ executed the instruction
+ <command>rm -f ${CLEANFILES}</command>. In effect, this
+ causes <maketarget>clean</maketarget> 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>
<sect4>
<title>Provided targets</title>
@@ -425,14 +439,15 @@ PRI_LANG?= en_US.ISO8859-1
in the subdirectories
(<maketarget>realinstall</maketarget> and
<maketarget>realpackage</maketarget>
- respectively).</para>
+ respectively).</para>
</listitem>
<listitem>
- <para><maketarget>clean</maketarget> removes files created
- by the build process (and goes down the directory tree
- too). <maketarget>cleandir</maketarget> does the same,
- and also removes the object directory, if any.</para>
+ <para><maketarget>clean</maketarget> removes files
+ created by the build process (and goes down the
+ directory tree too).
+ <maketarget>cleandir</maketarget> does the same, and
+ also removes the object directory, if any.</para>
</listitem>
</itemizedlist>
</sect4>
@@ -444,7 +459,8 @@ PRI_LANG?= en_US.ISO8859-1
<itemizedlist>
<listitem>
<para><literal>exists</literal> is another condition
- function which returns true if the given file exists.</para>
+ function which returns true if the given file
+ exists.</para>
</listitem>
<listitem>
@@ -462,10 +478,10 @@ PRI_LANG?= en_US.ISO8859-1
<sect3>
<title>Looping constructs in make (.for)</title>
- <para><literal>.for</literal> provides a way to repeat a set of
- instructions for each space-separated element in a variable.
- It does this by assigning a variable to contain the current
- element in the list being examined.</para>
+ <para><literal>.for</literal> provides a way to repeat a set
+ of instructions for each space-separated element in a
+ variable. It does this by assigning a variable to contain
+ the current element in the list being examined.</para>
<programlisting>_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
@@ -478,8 +494,8 @@ PRI_LANG?= en_US.ISO8859-1
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 of
- the current element.</para>
+ with <makevar>entry</makevar> being replaced with the value
+ of the current element.</para>
</sect3>
</sect2>
</sect1>