diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml | 236 |
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> |