diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml | 501 |
1 files changed, 0 insertions, 501 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 deleted file mode 100644 index 910bf3cf22..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml +++ /dev/null @@ -1,501 +0,0 @@ -<!-- 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. - - $Id: chapter.sgml,v 1.1 2000-06-23 00:37:15 nik Exp $ ---> - -<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 organised</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">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> - </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> - <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 not be able to find these last two, they - are mentioned for completeness.</para> - </note> - </sect1> - - <sect1> - <title>Understanding Makefiles 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> - - <para><application>Make</application> syntax is quickly revised as - the we explore these types.</para> - - <sect2 id="sub-make"> - <title>Subdirectory Makefiles</title> - - <para>These directories 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 overridable, 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> - - <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.sgml - -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>.sgml</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 make 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>doc.project.mk</title> - - <para>By inspection:</para> - - <programlisting>DOCFORMAT?= docbook -MAINTAINER?= doc@FreeBSD.org - -PREFIX?= /usr/local -PRI_LANG?= en_US.ISO_8859-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. It's 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 behaviour 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>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> - - <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 it's 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, <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 doesn't 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 make (.for)</title> - - <para><literal>.for</literal> provides a way to repeat a set of - instructions for each space-seperated 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 <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> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - |