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
new file mode 100644
index 0000000000..910bf3cf22
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
@@ -0,0 +1,501 @@
+
+
+
+ The Documentation Build Process
+
+ This chapter's main purpose is to clearly explain how
+ the documentation build process is organised, 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 SGML 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.
+
+
+
+
+ The FreeBSD Documentation Build Toolset
+
+ Here are your tools. Use them every way you can.
+
+
+
+ The primary build tool you will need is
+ make, but 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.
+
+
+
+ gzip is needed to create
+ compressed versions of the document.
+ bzip2 compression and
+ zip archives are also supported.
+ tar is supported, but package
+ building demands it.
+
+
+
+ install is the default method
+ to install the documentation. There are alternatives,
+ however.
+
+
+
+ It is unlikely you will not be able to find these last two, they
+ are mentioned for completeness.
+
+
+
+
+ Understanding Makefiles in the Documentation tree
+
+ There are three main types of Makefiles
+ in the FreeBSD Documentation Project tree.
+
+
+
+ Subdirectory
+ Makefiles simply pass
+ commands to those directories below them.
+
+
+
+ Documentation
+ Makefiles describe the
+ document(s) that should be produced from this directory.
+
+
+
+ Make
+ includes are the glue that perform the document production,
+ and are usually of the form
+ doc.xxx.mk.
+
+
+
+ Make syntax is quickly revised as
+ the we explore these types.
+
+
+ Subdirectory Makefiles
+
+ These directories usually take the form of:
+
+ SUBDIR =articles
+SUBDIR+=books
+
+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,
+ SUBDIR, COMPAT_SYMLINK,
+ and DOC_PREFIX.
+
+ The first SUBDIR statement, as well as
+ the COMPAT_SYMLINK statement, shows how to
+ assign a value to a variable, overriding any previous
+ value.
+
+ The second SUBDIR statement shows how a
+ value is appended to the current value of a variable. The
+ SUBDIR variable is now articles
+ books.
+
+ The DOC_PREFIX assignment shows how a
+ value is assigned to the variable, but only if it is not already
+ defined. This is useful if DOC_PREFIX is not
+ where this Makefile thinks it is - the user
+ can override this and provide the correct value.
+
+ Now what does it all mean? SUBDIR
+ mentions which subdirectories below this one the build process
+ should pass any work on to.
+
+ COMPAT_SYMLINK is specific to
+ compatibility symlinks (amazingly enough) for languages to their
+ official encoding (doc/en would 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 easy to
+ find, and is also easily overridable, to allow for flexibility.
+ .CURDIR is a make
+ builtin variable with the path to the current directory.
+
+ The final line includes the FreeBSD Documentation Project's
+ project-wide make system file
+ doc.project.mk which is the glue which
+ converts these variables into build instructions.
+
+
+
+ Documentation Makefiles
+
+ These Makefiles set a bunch of
+ make variables that describe how to
+ build the documentation contained in that directory.
+
+ Here is an example:
+
+ 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"
+
+ 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
+ it.
+
+ DOC is the name (sans the
+ .sgml extension) of the main document
+ created by this directory. SRCS 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.
+
+ FORMATS indicates the default formats
+ that should be built for this document.
+ INSTALL_COMPRESSED is the default list of
+ compression techniques that should be used in the document
+ build. INSTALL_ONLY_COMPRESS, empty by
+ 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 make includes
+
+ This is best explained by inspection of the code. Here are
+ the system include files:
+
+
+
+ doc.project.mk is the main project
+ include file, which includes all the following include files, as
+ necessary.
+
+
+
+ doc.subdir.mk handles traversing of
+ the document tree during the build and install processes.
+
+
+
+ doc.install.mk provides variables
+ that affect ownership and installation of documents.
+
+
+
+ doc.docbook.mk is included if
+ DOCFORMAT is docbook
+ and DOC is set.
+
+
+
+
+ doc.project.mk
+
+ By inspection:
+
+ 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"
+
+
+
+ Variables
+
+ DOCFORMAT and MAINTAINER
+ are assigned default values, if these are not set by the
+ document make file.
+
+ PREFIX is the prefix under which the
+ documentation building tools are
+ installed. For normal package and port installation, this is
+ /usr/local.
+
+ PRI_LANG should be set to whatever
+ language and encoding is natural amongst users these documents are
+ being built for. US English is the default.
+
+
+ PRI_LANG 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.
+
+
+
+
+ Conditionals
+
+ The .if defined(DOC) line is an example of
+ a make conditional which, like in
+ other programs, defines behaviour if some condition is true or
+ if it is false. defined is a function which
+ returns whether the variable given is defined or not.
+
+ .if ${DOCFORMAT} == "docbook", next,
+ tests whether the DOCFORMAT variable is
+ "docbook", and in this case, includes
+ doc.docbook.mk.
+
+ The two .endifs close the two above
+ conditionals, marking the end of their application.
+
+
+
+
+ doc.subdir.mk
+
+ 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.
+
+
+ Variables
+
+
+
+ SUBDIR is a list of subdirectories
+ that the build process should go further down
+ into.
+
+
+
+ ROOT_SYMLINKS 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
+ PRI_LANG).
+
+
+
+ COMPAT_SYMLINK is described in the
+ Subdirectory Makefile
+ section.
+
+
+
+
+
+ Targets and macros
+
+ Dependencies are described by
+ target:
+ dependency1 dependency2 ...
+ tuples, where to build target, you need to build
+ the given dependencies first.
+
+ 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.
+
+ A special dependency .USE defines
+ the equivalent of a macro.
+
+_SUBDIRUSE: .USE
+.for entry in ${SUBDIR}
+ @${ECHO} "===> ${DIRPRFX}${entry}"
+ @(cd ${.CURDIR}/${entry} && \
+ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
+.endfor
+
+ In the above, _SUBDIRUSE is now a
+ macro which will execute the given commands when it is listed
+ as a dependency.
+
+ What sets this macro apart from other targets? Basically,
+ it is executed after the instructions
+ given in the build procedure it is listed as a dependency to,
+ and it doesn't adjust .TARGET, which is the
+ variable which contains the name of the target currently
+ being built.
+
+clean: _SUBDIRUSE
+ rm -f ${CLEANFILES}
+
+ In the above, clean will use the
+ _SUBDIRUSE macro after it has
+ executed the instruction
+ rm -f ${CLEANFILES}. In effect, this causes
+ clean to go further and further down
+ the directory tree, deleting built files as it goes
+ down, not on the way back up.
+
+
+ Provided targets
+
+
+
+ install and
+ package both go down the
+ directory tree calling the real versions of themselves
+ in the subdirectories.
+ (realinstall and
+ realpackage
+ respectively)
+
+
+
+ clean removes files created
+ by the build process (and goes down the directory tree
+ too). cleandir does the same,
+ and also removes the object directory, if any.
+
+
+
+
+
+
+ More on conditionals
+
+
+
+ exists is another condition
+ function which returns true if the given file exists.
+
+
+
+ empty returns true if the given
+ variable is empty.
+
+
+
+ target returns true if the given
+ target does not already exist.
+
+
+
+
+
+ Looping constructs in make (.for)
+
+ .for 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.
+
+_SUBDIRUSE: .USE
+.for entry in ${SUBDIR}
+ @${ECHO} "===> ${DIRPRFX}${entry}"
+ @(cd ${.CURDIR}/${entry} && \
+ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
+.endfor
+
+ In the above, if SUBDIR is empty, no
+ action is taken; if it has one or more elements, the
+ instructions between .for and
+ .endfor would repeat for every element,
+ with entry being replaced with the value of
+ the current element.
+
+
+
+
+
+
+
diff --git a/en_US.ISO_8859-1/books/fdp-primer/doc-build/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/doc-build/chapter.sgml
new file mode 100644
index 0000000000..910bf3cf22
--- /dev/null
+++ b/en_US.ISO_8859-1/books/fdp-primer/doc-build/chapter.sgml
@@ -0,0 +1,501 @@
+
+
+
+ The Documentation Build Process
+
+ This chapter's main purpose is to clearly explain how
+ the documentation build process is organised, 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 SGML 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.
+
+
+
+
+ The FreeBSD Documentation Build Toolset
+
+ Here are your tools. Use them every way you can.
+
+
+
+ The primary build tool you will need is
+ make, but 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.
+
+
+
+ gzip is needed to create
+ compressed versions of the document.
+ bzip2 compression and
+ zip archives are also supported.
+ tar is supported, but package
+ building demands it.
+
+
+
+ install is the default method
+ to install the documentation. There are alternatives,
+ however.
+
+
+
+ It is unlikely you will not be able to find these last two, they
+ are mentioned for completeness.
+
+
+
+
+ Understanding Makefiles in the Documentation tree
+
+ There are three main types of Makefiles
+ in the FreeBSD Documentation Project tree.
+
+
+
+ Subdirectory
+ Makefiles simply pass
+ commands to those directories below them.
+
+
+
+ Documentation
+ Makefiles describe the
+ document(s) that should be produced from this directory.
+
+
+
+ Make
+ includes are the glue that perform the document production,
+ and are usually of the form
+ doc.xxx.mk.
+
+
+
+ Make syntax is quickly revised as
+ the we explore these types.
+
+
+ Subdirectory Makefiles
+
+ These directories usually take the form of:
+
+ SUBDIR =articles
+SUBDIR+=books
+
+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,
+ SUBDIR, COMPAT_SYMLINK,
+ and DOC_PREFIX.
+
+ The first SUBDIR statement, as well as
+ the COMPAT_SYMLINK statement, shows how to
+ assign a value to a variable, overriding any previous
+ value.
+
+ The second SUBDIR statement shows how a
+ value is appended to the current value of a variable. The
+ SUBDIR variable is now articles
+ books.
+
+ The DOC_PREFIX assignment shows how a
+ value is assigned to the variable, but only if it is not already
+ defined. This is useful if DOC_PREFIX is not
+ where this Makefile thinks it is - the user
+ can override this and provide the correct value.
+
+ Now what does it all mean? SUBDIR
+ mentions which subdirectories below this one the build process
+ should pass any work on to.
+
+ COMPAT_SYMLINK is specific to
+ compatibility symlinks (amazingly enough) for languages to their
+ official encoding (doc/en would 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 easy to
+ find, and is also easily overridable, to allow for flexibility.
+ .CURDIR is a make
+ builtin variable with the path to the current directory.
+
+ The final line includes the FreeBSD Documentation Project's
+ project-wide make system file
+ doc.project.mk which is the glue which
+ converts these variables into build instructions.
+
+
+
+ Documentation Makefiles
+
+ These Makefiles set a bunch of
+ make variables that describe how to
+ build the documentation contained in that directory.
+
+ Here is an example:
+
+ 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"
+
+ 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
+ it.
+
+ DOC is the name (sans the
+ .sgml extension) of the main document
+ created by this directory. SRCS 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.
+
+ FORMATS indicates the default formats
+ that should be built for this document.
+ INSTALL_COMPRESSED is the default list of
+ compression techniques that should be used in the document
+ build. INSTALL_ONLY_COMPRESS, empty by
+ 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 make includes
+
+ This is best explained by inspection of the code. Here are
+ the system include files:
+
+
+
+ doc.project.mk is the main project
+ include file, which includes all the following include files, as
+ necessary.
+
+
+
+ doc.subdir.mk handles traversing of
+ the document tree during the build and install processes.
+
+
+
+ doc.install.mk provides variables
+ that affect ownership and installation of documents.
+
+
+
+ doc.docbook.mk is included if
+ DOCFORMAT is docbook
+ and DOC is set.
+
+
+
+
+ doc.project.mk
+
+ By inspection:
+
+ 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"
+
+
+
+ Variables
+
+ DOCFORMAT and MAINTAINER
+ are assigned default values, if these are not set by the
+ document make file.
+
+ PREFIX is the prefix under which the
+ documentation building tools are
+ installed. For normal package and port installation, this is
+ /usr/local.
+
+ PRI_LANG should be set to whatever
+ language and encoding is natural amongst users these documents are
+ being built for. US English is the default.
+
+
+ PRI_LANG 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.
+
+
+
+
+ Conditionals
+
+ The .if defined(DOC) line is an example of
+ a make conditional which, like in
+ other programs, defines behaviour if some condition is true or
+ if it is false. defined is a function which
+ returns whether the variable given is defined or not.
+
+ .if ${DOCFORMAT} == "docbook", next,
+ tests whether the DOCFORMAT variable is
+ "docbook", and in this case, includes
+ doc.docbook.mk.
+
+ The two .endifs close the two above
+ conditionals, marking the end of their application.
+
+
+
+
+ doc.subdir.mk
+
+ 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.
+
+
+ Variables
+
+
+
+ SUBDIR is a list of subdirectories
+ that the build process should go further down
+ into.
+
+
+
+ ROOT_SYMLINKS 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
+ PRI_LANG).
+
+
+
+ COMPAT_SYMLINK is described in the
+ Subdirectory Makefile
+ section.
+
+
+
+
+
+ Targets and macros
+
+ Dependencies are described by
+ target:
+ dependency1 dependency2 ...
+ tuples, where to build target, you need to build
+ the given dependencies first.
+
+ 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.
+
+ A special dependency .USE defines
+ the equivalent of a macro.
+
+_SUBDIRUSE: .USE
+.for entry in ${SUBDIR}
+ @${ECHO} "===> ${DIRPRFX}${entry}"
+ @(cd ${.CURDIR}/${entry} && \
+ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
+.endfor
+
+ In the above, _SUBDIRUSE is now a
+ macro which will execute the given commands when it is listed
+ as a dependency.
+
+ What sets this macro apart from other targets? Basically,
+ it is executed after the instructions
+ given in the build procedure it is listed as a dependency to,
+ and it doesn't adjust .TARGET, which is the
+ variable which contains the name of the target currently
+ being built.
+
+clean: _SUBDIRUSE
+ rm -f ${CLEANFILES}
+
+ In the above, clean will use the
+ _SUBDIRUSE macro after it has
+ executed the instruction
+ rm -f ${CLEANFILES}. In effect, this causes
+ clean to go further and further down
+ the directory tree, deleting built files as it goes
+ down, not on the way back up.
+
+
+ Provided targets
+
+
+
+ install and
+ package both go down the
+ directory tree calling the real versions of themselves
+ in the subdirectories.
+ (realinstall and
+ realpackage
+ respectively)
+
+
+
+ clean removes files created
+ by the build process (and goes down the directory tree
+ too). cleandir does the same,
+ and also removes the object directory, if any.
+
+
+
+
+
+
+ More on conditionals
+
+
+
+ exists is another condition
+ function which returns true if the given file exists.
+
+
+
+ empty returns true if the given
+ variable is empty.
+
+
+
+ target returns true if the given
+ target does not already exist.
+
+
+
+
+
+ Looping constructs in make (.for)
+
+ .for 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.
+
+_SUBDIRUSE: .USE
+.for entry in ${SUBDIR}
+ @${ECHO} "===> ${DIRPRFX}${entry}"
+ @(cd ${.CURDIR}/${entry} && \
+ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
+.endfor
+
+ In the above, if SUBDIR is empty, no
+ action is taken; if it has one or more elements, the
+ instructions between .for and
+ .endfor would repeat for every element,
+ with entry being replaced with the value of
+ the current element.
+
+
+
+
+
+
+