- Rename .sgml files to .xml

- Reflect the rename in referencing files

Approved by:	doceng (implicit)

1 files changed, 507 insertions, 0 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
new file mode 100644
index 0000000000..7b969da21a
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
@@ -0,0 +1,507 @@
+<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
+<!-- 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.
+
+     $FreeBSD$
+-->
+
+<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>
+
+  <sect1 id="doc-build-toolset">
+    <title>The FreeBSD Documentation Build Toolset</title>
+
+    <para>Here are your tools.  Use them every way you can.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>The primary build tool you will need is
+	  <application>make</application>, but specifically
+	  <application>Berkeley Make</application>.</para>
+      </listitem>
+
+      <listitem>
+	<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>
+      </listitem>
+
+      <listitem>
+	<para><application>gzip</application> is needed 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>
+      </listitem>
+
+      <listitem>
+	<para><application>install</application> is the default method
+	  to install the documentation.  There are alternatives,
+	  however.</para>
+      </listitem>
+    </itemizedlist>
+
+    <note>
+      <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 <filename>Makefile</filename>s in the
+      Documentation Tree</title>
+
+    <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
+	  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>
+      </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 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>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>
+
+      <para>The first <makevar>SUBDIR</makevar> statement, as well as
+	the <makevar>COMPAT_SYMLINK</makevar> statement, shows how to
+	assign a value to a variable, overriding any previous
+	value.</para>
+
+      <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>
+
+      <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>
+
+      <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>
+    </sect2>
+
+    <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
+	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 <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
+	it.</para>
+
+      <para><makevar>DOC</makevar> is the name (sans the
+	<filename>.xml</filename> extension) of the main document
+	created by this directory.  <makevar>SRCS</makevar> 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
+	that should be built for this document.
+	<makevar>INSTALL_COMPRESSED</makevar> is the default list of
+	compression techniques that should be used in the document
+	build.  <makevar>INSTALL_ONLY_COMPRESS</makevar>, empty by
+	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>
+    </sect2>
+  </sect1>
+
+  <sect1 id="make-includes">
+    <title>FreeBSD Documentation Project
+      <application>Make</application> Includes</title>
+
+    <para>This is 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
+	  <makevar>DOCFORMAT</makevar> is <literal>docbook</literal>
+	  and <makevar>DOC</makevar> is set.</para>
+      </listitem>
+    </itemizedlist>
+
+    <sect2>
+      <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>
+
+	<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>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>
+
+	<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>
+
+	<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>
+	</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><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
+	  tests whether the <makevar>DOCFORMAT</makevar> 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>
+      <title><filename>doc.subdir.mk</filename></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>
+
+      <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>
+	  </listitem>
+
+	  <listitem>
+	    <para><makevar>ROOT_SYMLINKS</makevar> 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>
+	  </listitem>
+
+	  <listitem>
+	    <para><makevar>COMPAT_SYMLINK</makevar> is described in
+	      the
+	      <link linkend="sub-make">Subdirectory Makefile</link>
+	      section.</para>
+	  </listitem>
+	</itemizedlist>
+      </sect3>
+
+      <sect3>
+	<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>, 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>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, <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>
+
+	<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>
+
+	<sect4>
+	  <title>Provided Targets</title>
+
+	  <itemizedlist>
+	    <listitem>
+	      <para><maketarget>install</maketarget> and
+		<maketarget>package</maketarget> both go down the
+		directory tree calling the real versions of themselves
+		in the subdirectories
+		(<maketarget>realinstall</maketarget> and
+		<maketarget>realpackage</maketarget>
+		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>
+	    </listitem>
+	  </itemizedlist>
+	</sect4>
+      </sect3>
+
+      <sect3>
+	<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>
+	<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 <makevar>SUBDIR</makevar> 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
+	  of the current element.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+</chapter>