aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml531
1 files changed, 0 insertions, 531 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
deleted file mode 100644
index e55650a560..0000000000
--- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
+++ /dev/null
@@ -1,531 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved.
-
- Redistribution and use in source (SGML DocBook) and 'compiled' forms
- (SGML HTML, PDF, PostScript, RTF and so forth) with or without
- modification, are permitted provided that the following conditions
- are met:
-
- 1. Redistributions of source code (SGML DocBook) must retain the above
- copyright notice, this list of conditions and the following
- disclaimer as the first lines of this file unmodified.
-
- 2. Redistributions in compiled form (transformed to other DTDs,
- converted to PDF, PostScript, RTF and other formats) must reproduce
- the above copyright notice, this list of conditions and the
- following disclaimer in the documentation and/or other materials
- provided with the distribution.
-
- THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
- IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
- INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
- (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
- SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
- STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
- ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGE.
-
--->
-<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 xml:id="doc-build-rendering">
- <title>Rendering DocBook into Output</title>
-
- <para>Different types of output can be produced from a single
- DocBook source file. The type of output desired is set with the
- <varname>FORMATS</varname> variable. A list of known formats is
- stored in <varname>KNOWN_FORMATS</varname>:</para>
-
- <screen xml:id="doc-build-rendering-known-formats">&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
-&prompt.user; <userinput>make -V KNOWN_FORMATS</userinput></screen>
-
- <table xml:id="doc-build-rendering-common-formats" frame="none">
- <title>Common Output Formats</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry><varname>FORMATS</varname> Value</entry>
- <entry>File Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><literal>html</literal></entry>
- <entry><acronym>HTML</acronym>, one file</entry>
- <entry>A single <filename>book.html</filename> or
- <filename>article.html</filename>.</entry>
- </row>
-
- <row>
- <entry><literal>html-split</literal></entry>
- <entry><acronym>HTML</acronym>, multiple files</entry>
- <entry>Multiple <acronym>HTML</acronym> files, one for
- each chapter or section, for use on a typical web
- site.</entry>
- </row>
-
- <row>
- <entry><literal>pdf</literal></entry>
- <entry><acronym>PDF</acronym></entry>
- <entry>Portable Document Format</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>The default output format can vary by document, but is
- usually <literal>html-split</literal>. Other formats are chosen
- by setting <varname>FORMATS</varname> to a specific value.
- Multiple output formats can be created at a single time by
- setting <varname>FORMATS</varname> to a list of formats.</para>
-
- <example xml:id="doc-build-formats-example-html">
- <title>Build a Single HTML Output File</title>
-
- <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
-&prompt.user; <userinput>make FORMATS=html</userinput></screen>
- </example>
-
- <example xml:id="doc-build-formats-example-html-split-pdf">
- <title>Build HTML-Split and <acronym>PDF</acronym> Output
- Files</title>
-
- <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
-&prompt.user; <userinput>make FORMATS="html-split pdf"</userinput></screen>
- </example>
- </sect1>
-
- <sect1 xml:id="doc-build-toolset">
- <title>The &os; Documentation Build Toolset</title>
-
- <para>These are the tools used to build and install the
- <acronym>FDP</acronym> documentation.</para>
-
- <itemizedlist>
- <listitem>
- <para>The primary build tool is &man.make.1;, specifically
- <application>Berkeley Make</application>.</para>
- </listitem>
-
- <listitem>
- <para>Package building is handled by &os;'s
- &man.pkg-create.8;.</para>
- </listitem>
-
- <listitem>
- <para>&man.gzip.1; is used to create compressed versions of
- the document. &man.bzip2.1; archives are also supported.
- &man.tar.1; is used for package building.</para>
- </listitem>
-
- <listitem>
- <para>&man.install.1; is used to install the
- documentation.</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1 xml:id="doc-build-makefiles">
-
- <title>Understanding <filename>Makefile</filename>s in the
- Documentation Tree</title>
-
- <para>There are three main types of <filename>Makefile</filename>s
- in the &os; Documentation Project tree.</para>
-
- <itemizedlist>
- <listitem>
- <para><link linkend="sub-make">Subdirectory
- <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
- documents that are 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
- <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
- </listitem>
- </itemizedlist>
-
- <sect2 xml:id="sub-make">
- <title>Subdirectory <filename>Makefile</filename>s</title>
-
- <para>These <filename>Makefile</filename>s usually take the form
- of:</para>
-
- <programlisting>SUBDIR =articles
-SUBDIR+=books
-
-COMPAT_SYMLINK = en
-
-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 <varname>SUBDIR</varname>,
- <varname>COMPAT_SYMLINK</varname>, and
- <varname>DOC_PREFIX</varname>.</para>
-
- <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 <varname>SUBDIR</varname> statement shows how a
- value is appended to the current value of a variable. The
- <varname>SUBDIR</varname> variable is now <literal>articles
- books</literal>.</para>
-
- <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
- <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? <varname>SUBDIR</varname>
- mentions which subdirectories below this one the build process
- should pass any work on to.</para>
-
- <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><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. <varname>.CURDIR</varname> is a &man.make.1;
- builtin variable with the path to the current
- directory.</para>
-
- <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>
-
- <sect2 xml:id="doc-make">
- <title>Documentation <filename>Makefile</filename>s</title>
-
- <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>
-
- <programlisting>MAINTAINER=nik@FreeBSD.org
-
-DOC?= book
-
-FORMATS?= html-split html
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-# SGML content
-SRCS= book.xml
-
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
-
- <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><varname>DOC</varname> is the name (sans the
- <filename>.xml</filename> extension) of the main document
- 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><varname>FORMATS</varname> indicates the default formats
- that should be built for this document.
- <varname>INSTALL_COMPRESSED</varname> is the default list of
- compression techniques that should be used in the document
- 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 <varname>DOC_PREFIX</varname> and include statements
- should be familiar already.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="make-includes">
- <title>&os; Documentation Project
- <application>Make</application> Includes</title>
-
- <para>&man.make.1; includes are best explained by inspection of
- the code. Here are the system include files:</para>
-
- <itemizedlist>
- <listitem>
- <para><filename>doc.project.mk</filename> is the main project
- 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>
- </listitem>
-
- <listitem>
- <para><filename>doc.install.mk</filename> provides variables
- that affect ownership and installation of documents.</para>
- </listitem>
-
- <listitem>
- <para><filename>doc.docbook.mk</filename> is included if
- <varname>DOCFORMAT</varname> is <literal>docbook</literal>
- and <varname>DOC</varname> is set.</para>
- </listitem>
- </itemizedlist>
-
- <sect2 xml:id="includes-doc-project-mk">
- <title><filename>doc.project.mk</filename></title>
-
- <para>By inspection:</para>
-
- <programlisting>DOCFORMAT?= docbook
-MAINTAINER?= doc@FreeBSD.org
-
-PREFIX?= /usr/local
-PRI_LANG?= en_US.ISO8859-1
-
-.if defined(DOC)
-.if ${DOCFORMAT} == "docbook"
-.include "doc.docbook.mk"
-.endif
-.endif
-
-.include "doc.subdir.mk"
-.include "doc.install.mk"</programlisting>
-
- <sect3 xml:id="doc-project-mk-variables">
-
- <title>Variables</title>
-
- <para><varname>DOCFORMAT</varname> and
- <varname>MAINTAINER</varname> are assigned default values,
- if these are not set by the document make file.</para>
-
- <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><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><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>
- </note>
- </sect3>
-
- <sect3 xml:id="doc-project-mk-conditionals">
- <title>Conditionals</title>
-
- <para>The <literal>.if defined(DOC)</literal> line is an
- 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 whether the variable given is defined or not.</para>
-
- <para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
- tests whether the <varname>DOCFORMAT</varname> variable is
- <literal>"docbook"</literal>, and in this case, includes
- <filename>doc.docbook.mk</filename>.</para>
-
- <para>The two <literal>.endif</literal>s close the two above
- conditionals, marking the end of their application.</para>
- </sect3>
- </sect2>
-
- <sect2 xml:id="includes-doc-subdir-mk">
- <title><filename>doc.subdir.mk</filename></title>
-
- <para>This file is too long to explain in detail. These notes
- describe the most important features.</para>
-
- <sect3 xml:id="doc-subdir-mk-variables">
- <title>Variables</title>
-
- <itemizedlist>
- <listitem>
- <para><varname>SUBDIR</varname> is a list of
- subdirectories that the build process should go further
- down into.</para>
- </listitem>
-
- <listitem>
- <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
- <varname>PRI_LANG</varname>).</para>
- </listitem>
-
- <listitem>
- <para><varname>COMPAT_SYMLINK</varname> is described in
- the
- <link linkend="sub-make">Subdirectory Makefile</link>
- section.</para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3 xml:id="doc-subdir-mk-targets-macro">
- <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</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
- 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>
-
- <programlisting>_SUBDIRUSE: .USE
-.for entry in ${SUBDIR}
- @${ECHO} "===&gt; ${DIRPRFX}${entry}"
- @(cd ${.CURDIR}/${entry} &amp;&amp; \
- ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
-.endfor</programlisting>
-
- <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>
-
- <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
- <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, <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 <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>
-
- <sect4 xml:id="doc-subdir-mk-provided-targets">
- <title>Provided Targets</title>
-
- <itemizedlist>
- <listitem>
- <para><buildtarget>install</buildtarget> and
- <buildtarget>package</buildtarget> both go down the
- directory tree calling the real versions of themselves
- in the subdirectories
- (<buildtarget>realinstall</buildtarget> and
- <buildtarget>realpackage</buildtarget>
- respectively).</para>
- </listitem>
-
- <listitem>
- <para><buildtarget>clean</buildtarget> removes files
- created by the build process (and goes down the
- directory tree too).
- <buildtarget>cleandir</buildtarget> does the same, and
- also removes the object directory, if any.</para>
- </listitem>
- </itemizedlist>
- </sect4>
- </sect3>
-
- <sect3 xml:id="doc-subdir-mk-conditionals">
- <title>More on Conditionals</title>
-
- <itemizedlist>
- <listitem>
- <para><literal>exists</literal> is another condition
- function which returns true if the given file
- exists.</para>
- </listitem>
-
- <listitem>
- <para><literal>empty</literal> returns true if the given
- variable is empty.</para>
- </listitem>
-
- <listitem>
- <para><literal>target</literal> returns true if the given
- target does not already exist.</para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3 xml:id="doc-subdir-mk-looping">
- <title>Looping Constructs in <command>make
- (.for)</command></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>
-
- <programlisting>_SUBDIRUSE: .USE
-.for entry in ${SUBDIR}
- @${ECHO} "===&gt; ${DIRPRFX}${entry}"
- @(cd ${.CURDIR}/${entry} &amp;&amp; \
- ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
-.endfor</programlisting>
-
- <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 <varname>entry</varname> being replaced with the value
- of the current element.</para>
- </sect3>
- </sect2>
- </sect1>
-</chapter>