diff options
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.xml | 531 |
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} "===> ${DIRPRFX}${entry}" - @(cd ${.CURDIR}/${entry} && \ - ${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} "===> ${DIRPRFX}${entry}" - @(cd ${.CURDIR}/${entry} && \ - ${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> |