Date: Sat, 20 Jul 2013 01:21:45 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42328 - head/en_US.ISO8859-1/books/fdp-primer/doc-build Message-ID: <201307200121.r6K1LjZb037008@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sat Jul 20 01:21:45 2013 New Revision: 42328 URL: http://svnweb.freebsd.org/changeset/doc/42328 Log: Update, simplify, and clarify the doc-build chapter. Modified: head/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml Fri Jul 19 19:32:30 2013 (r42327) +++ head/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml Sat Jul 20 01:21:45 2013 (r42328) @@ -34,75 +34,41 @@ <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> + <para>This chapter covers organization of the + documentation build process + and how &man.make.1; is used to control + it.</para> <sect1 id="doc-build-toolset"> - <title>The FreeBSD Documentation Build Toolset</title> + <title>The &os; Documentation Build Toolset</title> - <para>Here are your tools. Use them every way you can.</para> + <para>These are the tools used to build and install the <acronym>FDP</acronym> documentation.</para> <itemizedlist> <listitem> - <para>The primary build tool you will need is - <application>make</application>, but specifically + <para>The primary build tool is + &man.make.1;, 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> + <para>Package building is handled by &os;'s + &man.pkg.create.1;.</para> </listitem> <listitem> - <para><application>gzip</application> is needed to create + <para>&man.gzip.1; is used 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> + &man.bzip2.1; archives are also supported. + &man.tar.1; is used for package + building.</para> </listitem> <listitem> - <para><application>install</application> is the default method - to install the documentation. There are alternatives, - however.</para> + <para>&man.install.1; is used + to install the documentation.</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"> @@ -111,7 +77,7 @@ Documentation Tree</title> <para>There are three main types of <filename>Makefile</filename>s - in the FreeBSD Documentation Project tree.</para> + in the &os; Documentation Project tree.</para> <itemizedlist> <listitem> @@ -150,13 +116,13 @@ 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>The first four non-empty lines define + the &man.make.1; 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 + <para>The <makevar>SUBDIR</makevar> statement and + <makevar>COMPAT_SYMLINK</makevar> statement show how to assign a value to a variable, overriding any previous value.</para> @@ -172,7 +138,7 @@ DOC_PREFIX?= ${.CURDIR}/.. <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> + <para>What does it all mean? <makevar>SUBDIR</makevar> mentions which subdirectories below this one the build process should pass any work on to.</para> @@ -182,14 +148,14 @@ DOC_PREFIX?= ${.CURDIR}/.. 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 + the &os; 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 + &man.make.1; 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 + <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> @@ -197,8 +163,8 @@ DOC_PREFIX?= ${.CURDIR}/.. <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 + <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> @@ -219,10 +185,10 @@ 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 + <para>The <makevar>MAINTAINER</makevar> variable + allows committers to claim + ownership of a document in the &os; Documentation + Project, and take responsibility for maintaining it.</para> <para><makevar>DOC</makevar> is the name (sans the @@ -240,21 +206,16 @@ DOC_PREFIX?= ${.CURDIR}/../../.. 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 + <title>&os; Documentation Project <application>Make</application> Includes</title> - <para>This is best explained by inspection of the code. Here are + <para>&man.make.1; includes are best explained by inspection of the code. Here are the system include files:</para> <itemizedlist> @@ -321,10 +282,10 @@ PRI_LANG?= en_US.ISO8859-1 default.</para> <note> - <para><makevar>PRI_LANG</makevar> in no way affects what + <para><makevar>PRI_LANG</makevar> does not affect which documents can, or even will, be built. Its main use is creating links to commonly referenced documents into the - FreeBSD documentation install root.</para> + &os; documentation install root.</para> </note> </sect3> @@ -332,7 +293,7 @@ PRI_LANG?= en_US.ISO8859-1 <title>Conditionals</title> <para>The <literal>.if defined(DOC)</literal> line is an - example of a <application>make</application> conditional + 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 @@ -351,9 +312,8 @@ PRI_LANG?= en_US.ISO8859-1 <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> + <para>This file is too long to explain in detail. These + notes describe the most important features.</para> <sect3> <title>Variables</title> @@ -389,8 +349,8 @@ PRI_LANG?= en_US.ISO8859-1 <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> + <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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307200121.r6K1LjZb037008>