From owner-svn-doc-all@FreeBSD.ORG Sat Jul 20 01:21:46 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 95425A11; Sat, 20 Jul 2013 01:21:46 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id 752AAAF5; Sat, 20 Jul 2013 01:21:46 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6K1Lj1c037009; Sat, 20 Jul 2013 01:21:45 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6K1LjZb037008; Sat, 20 Jul 2013 01:21:45 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307200121.r6K1LjZb037008@svn.freebsd.org> From: Warren Block Date: Sat, 20 Jul 2013 01:21:45 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 20 Jul 2013 01:21:46 -0000 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 @@ The Documentation Build Process - This chapter's main purpose is to clearly explain - how the documentation build process is - organized, and how to affect modifications - to this process. - - After you have finished reading this chapter you - should: - - - - Know what you need to build the FDP documentation, in - addition to those mentioned in the - XML tools chapter. - - - - Be able to read and understand the - make instructions that are present - in each document's Makefiles, as well as - an overview of the doc.project.mk - includes. - - - - Be able to customize the build process by using - make variables and - make targets. - - + This chapter covers organization of the + documentation build process + and how &man.make.1; is used to control + it. - The FreeBSD Documentation Build Toolset + The &os; Documentation Build Toolset - Here are your tools. Use them every way you can. + These are the tools used to build and install the FDP documentation. - The primary build tool you will need is - make, but specifically + The primary build tool is + &man.make.1;, specifically Berkeley Make. - Package building is handled by FreeBSD's - pkg_create. If you are not using - FreeBSD, you will either have to live without packages, or - compile the source yourself. + Package building is handled by &os;'s + &man.pkg.create.1;. - gzip is needed to create + &man.gzip.1; is used to create compressed versions of the document. - bzip2 compression and - zip archives are also supported. - tar is supported, but package - building demands it. + &man.bzip2.1; archives are also supported. + &man.tar.1; is used for package + building. - install is the default method - to install the documentation. There are alternatives, - however. + &man.install.1; is used + to install the documentation. - - - It is unlikely you will have any trouble finding these - last two, they are mentioned for completeness only. - @@ -111,7 +77,7 @@ Documentation Tree There are three main types of Makefiles - in the FreeBSD Documentation Project tree. + in the &os; Documentation Project tree. @@ -150,13 +116,13 @@ COMPAT_SYMLINK = en DOC_PREFIX?= ${.CURDIR}/.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" - In quick summary, the first four non-empty lines define - the make variables, + The first four non-empty lines define + the &man.make.1; variables SUBDIR, COMPAT_SYMLINK, and DOC_PREFIX. - The first SUBDIR statement, as well as - the COMPAT_SYMLINK statement, shows how to + The SUBDIR statement and + COMPAT_SYMLINK statement show how to assign a value to a variable, overriding any previous value. @@ -172,7 +138,7 @@ DOC_PREFIX?= ${.CURDIR}/.. Makefile thinks it is - the user can override this and provide the correct value. - Now what does it all mean? SUBDIR + What does it all mean? SUBDIR mentions which subdirectories below this one the build process should pass any work on to. @@ -182,14 +148,14 @@ DOC_PREFIX?= ${.CURDIR}/.. point to en_US.ISO-8859-1). DOC_PREFIX 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. .CURDIR is a - make builtin variable with the path + &man.make.1; builtin variable with the path to the current directory. - The final line includes the FreeBSD Documentation - Project's project-wide make system + The final line includes the &os; Documentation + Project's project-wide &man.make.1; system file doc.project.mk which is the glue which converts these variables into build instructions. @@ -197,8 +163,8 @@ DOC_PREFIX?= ${.CURDIR}/.. Documentation <filename>Makefile</filename>s - These Makefiles set a bunch of - make variables that describe how to + These Makefiles set + &man.make.1; variables that describe how to build the documentation contained in that directory. Here is an example: @@ -219,10 +185,10 @@ DOC_PREFIX?= ${.CURDIR}/../../.. .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk" - The MAINTAINER 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 + The MAINTAINER variable + allows committers to claim + ownership of a document in the &os; Documentation + Project, and take responsibility for maintaining it. DOC 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. - - We covered optional variable assignments in the - previous section. - - The DOC_PREFIX and include statements should be familiar already. - FreeBSD Documentation Project + <title>&os; Documentation Project <application>Make</application> Includes - This is best explained by inspection of the code. Here are + &man.make.1; includes are best explained by inspection of the code. Here are the system include files: @@ -321,10 +282,10 @@ PRI_LANG?= en_US.ISO8859-1 default. - PRI_LANG in no way affects what + PRI_LANG 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. + &os; documentation install root. @@ -332,7 +293,7 @@ PRI_LANG?= en_US.ISO8859-1 Conditionals The .if defined(DOC) line is an - example of a make 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. defined is a function which returns @@ -351,9 +312,8 @@ PRI_LANG?= en_US.ISO8859-1 <filename>doc.subdir.mk</filename> - 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. + This file is too long to explain in detail. These + notes describe the most important features. Variables @@ -389,8 +349,8 @@ PRI_LANG?= en_US.ISO8859-1 target: dependency1 dependency2 ... tuples, where to build - target, you need to build the given - dependencies first. + target, the given + dependencies must be built first. After that descriptive tuple, instructions on how to build the target may be given, if the conversion process