Configuration and Customization

Configuration and Customization
Prev	Chapter 5. The Documentation Build	Next

At this time, most of the documentation in the Juggler Project is written using DocBook. Because of that, the settings for building documents from DocBook files are centralized in the file juggler/doc/docbook.mk. This file is parameterized to the extreme so that including makefiles can override its default settings easily. Usually, makefiles that include docbook.mk direct the build to use OpenJade, Saxon, or Xalan to process the DocBook input and PassiveTeX, FOP, or XEP to create PDF files. Further configuration can be done that chooses different versions or installations of the DocBook style sheets, Saxon, Xalan, FOP, etc. The following is the makefile used to generate HTML and PDF versions of this document:

default: html

docs: html chunk-html pdf                                            
install-docs: install-html install-chunk-html install-pdf            

NAME=		build.system                                                  

XML_FILES=	$(NAME).xml                                               
HTML_FILES=	$(NAME).html                                             
PDF_FILES=	$(NAME).pdf                                               

XSLT_TOOL=	Saxon                                                     

# Fill these in!!  Together, they make up the installation prefix.
webroot=	$(HOME)/public_html/jugglerweb                              
instdir=	docs/juggler.build.system                                   

prefix=		$(webroot)/$(instdir)                                       
INSTALL_FILES=	$(webroot)/base_style.css                             

NEED_DB_IMAGES=	1                                                    

$(NAME).html: $(NAME).xml                                            
$(NAME).pdf: $(NAME).xml $(NAME).fo                                  

include ../docbook.mk

	These are the required targets that all makefiles in the documentation build must have. Refer to the section called “Required Makefile Targets” for more information on these targets.
	This variable lists the base name of the source document. Since the generated documents differ only in final extension, this variable is used internally as the basis for the name of the source file and the generated documents. If there are multiple source documents, multiple variables (such as `$(NAME1)`, `$(NAME2)`, etc.) would be used.
	This variable lists all the DocBook XML source files that will be used as input to the XSLT processor. Each source file should have corresponding output files, also listed in this makefile.
	The source document can be rendered as HTML, and so this variable is used to list the output file. All HTML output files must be listed in this variable. The names must reflect the non-chunked output file names. Chunked HTML output is handled separately since the file names cannot be listed easily in this context.
	Similar to `$(HTML_FILES)`, this lists the PDF file(s) that can be rendered from the XML input. This has the same semantics as `$(HTML_FILES)`.
	The variable `$(XSLT_TOOL)` is used to tell `docbook.mk` which XSLT processor should be used. The default tool is Xalan, but Saxon can be used instead, as shown above.
	These variables deal with the installation process. The critical variables are `$(webroot)` and `$(prefix)`. The variable `$(webroot)` will be overridden by the calling makefile (the top-level documentation makefile) to provide an alternate base directory as necessary. Setting it here provides a good default value to use when writing documentation and testing rendering. The `$(prefix)` variable is what tells `docbook.mk` where the document(s) will be installed. It must be set in order for an installation to succeed. Finally, `$(INSTALL_FILES)` provides any extra files that must be installed. In this case, we want to copy over the common stylesheet used by the rest of the VR Juggler website.
	Defining the variable `$(NEED_DB_IMAGES)` informs `docbook.mk` that the DocBook images are needed by rendered versions of the source document(s). Symlinks will be created as part of the rendering process, and the images directory will be copied over during installation.
	These lines simply list dependencies as a way to help make(1) in doing its job effectively. Here, the `$(NAME)` variable again plays a useful role.
	Finally, the last line (and it should always be the last line) includes the `docbook.mk` makefile stub. All of the settings above have an effect on the way that the targets defined in `docbook.mk` behave.