From 2e3f17940fc3a9a6554f88a4ecf232a4cdb9d67e Mon Sep 17 00:00:00 2001 From: Nik Clayton Date: Fri, 23 Jun 2000 00:37:15 +0000 Subject: Bring in a chapter about the doc build process. This has been hanging around my tree for ages, and I've lost the details from the original submitter. I *think* it was Neil Blakey-Milner but I could be wrong. --- .../books/fdp-primer/doc-build/chapter.sgml | 501 +++++++++++++++++++++ 1 file changed, 501 insertions(+) create mode 100644 en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml (limited to 'en_US.ISO8859-1/books/fdp-primer/doc-build') 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. + + + + + + + -- cgit v1.2.3