################################################################################ # # File: $Id$ # # Standard variables and rules for building a particular document within a # section of the handbook (e.g., a single tutorial). Altering these # definitions will affect ALL DOCUMENT MAKEFILES FOR ALL PAPERS!! If you # need to do something specific for a particular paper, include a custom # rule in its makefile. DON'T add it here! # ################################################################################ ################################################################################ # # Run one-time initialisation stuff, _unless_ NOINIT is defined. Any # "parent" makefile that's already done the same one-time initialisation # and calls this one should define NOINIT (the value doesn't matter) to # switch off one-time initialisation in this makefile. Thus if the # "parent" makefile calls this makefile several times, things like the # content checking will only happen once for a single invocation of the # "parent" makefile. # # When running this makefile standalone, _don't_ define NOINIT, and # everything will still work as expected. # ifndef NOINIT include $(GLOBAL_HANDBOOK_INCLUDE)/remove_content_marker_files.make endif ################################################################################ # # Include variables defining the current paper. # include $(LOCAL_HANDBOOK_INCLUDE)/paper_variables.make ################################################################################ # # We make quite a lot of reference to files in the handbook directory, # so set a variable to point to it. PAPER_ROOT is defined in the include # file paper_variables.make. # HANDBOOK_ROOT:=$(PAPER_ROOT)/Handbook ################################################################################ # # Include XSLT functions. # include $(GLOBAL_HANDBOOK_INCLUDE)/xslt_functions.make ################################################################################ # # Defines which section we are currently building. This is actually the # path to the main folder for the section. Normally this is passed in as # an argument to make from a higher-level makefile (i.e., "make # SECTION=path/to/section"). # # Hmm, sh seems to convert uppercase letters in my paths to lowercase. # I'm not sure whether this will break anything or not... # # I _can_ confirm that having spaces anywhere in the parent path causes # serious breakage, because notdir returns bogus results in such cases. # All of the make functions assume whitespace delimitation, and there # doesn't seem to be any obvious way to work around this other than # eliminating spaces from the parent path (quoting the result of the # shell function below makes no difference). Fortunately, this is pretty # easy to do :) # # SECTION?=$(notdir $(shell cd ..; pwd)) ################################################################################ # # Set up the context for the current document. # # We use the same base name for both the directory and the document, which # makes life very easy :) # BASE_NAME:=$(notdir $(CURDIR)) # # SOURCE_XML is the original source XML, from which DERIVED_XML is # generated (the derived source has the includes for questions, etc., # inserted). # SOURCE_XML:=$(BASE_NAME).xml DERIVED_XML:=$(SOURCE_XML:.xml=-derived.xml) # # Define the names of the output files. # WEB_QUESTIONS_HTML:=$(BASE_NAME)-questions.html WEB_ANSWERS_HTML:=$(BASE_NAME)-answers.html PRINT_QUESTIONS_TEX:=$(WEB_QUESTIONS_HTML:.html=.tex) PRINT_ANSWERS_TEX:=$(WEB_ANSWERS_HTML:.html=.tex) PRINT_QUESTIONS_PDF_1UP:=$(PRINT_QUESTIONS_TEX:.tex=.pdf) PRINT_ANSWERS_PDF_1UP:=$(PRINT_ANSWERS_TEX:.tex=.pdf) PRINT_QUESTIONS_PDF_2UP:=$(PRINT_QUESTIONS_TEX:.tex=-2up.pdf) PRINT_ANSWERS_PDF_2UP:=$(PRINT_ANSWERS_TEX:.tex=-2up.pdf) # # Groupings of various web- and print-related files, for easy reference. # Feel free to add to these as necessary :) # DERIVED_WEB_FILES:=$(WEB_QUESTIONS_HTML) $(WEB_ANSWERS_HTML) DERIVED_PRINT_FILES:=$(PRINT_QUESTIONS_TEX) $(PRINT_ANSWERS_TEX) \ $(PRINT_QUESTIONS_PDF_1UP) $(PRINT_ANSWERS_PDF_1UP) \ $(PRINT_QUESTIONS_PDF_2UP) $(PRINT_ANSWERS_PDF_2UP) ################################################################################ # # Extract the list of included filenames from the source template. Hooray # for the shell function and Perl! Include file paths are delimited by # <@INC[ ]@>. All paths are relative to $(PAPER_ROOT). We don't use # $(PAPER_ROOT)/$(SECTION), because some of the include directories may be # in relatively arbitrary locations. # CONTENT_SRC:=$(shell perl -ne 'print "$(PAPER_ROOT)/$$1\n" if /<\@INC\[([^]]+)\]@>/;' $(SOURCE_XML)) ################################################################################ # # Directory to install files into on web server. # INSTALL_DIRECTORY:=$(HANDBOOK_INSTALL_ROOT)/$(SUBJECT_CODE)$(PAPER_NUMBER)/www/$(SECTION)/$(BASE_NAME) ################################################################################ # # Files to be installed on web server. # QUESTION_INSTALL_FILES:=$(WEB_QUESTIONS_HTML) $(PRINT_QUESTIONS_PDF_1UP) \ $(PRINT_QUESTIONS_PDF_2UP) $(wildcard *.png) ANSWER_INSTALL_FILES:=$(WEB_ANSWERS_HTML) $(PRINT_ANSWERS_PDF_1UP) \ $(PRINT_ANSWERS_PDF_2UP) ################################################################################ # # Lists of files for cleaning up. Add to these (using +=) as necessary in # derived makefiles. Note that ALL_CLEAN_FILES comprises files that need # to be deleted _in addition_ to those listed in WEB_CLEAN_FILES and # PRINT_CLEAN_FILES (that is, it's the list of additional files for the # "clean" target, which depends on "web-clean" and "print-clean" anyway). # WEB_CLEAN_FILES:=$(DERIVED_WEB_FILES) *-web*.png PRINT_CLEAN_FILES:=$(DERIVED_PRINT_FILES) *-print*.png *.pdf ALL_CLEAN_FILES:=$(DERIVED_XML) ################################################################################ # # List of possible targets. If you need to add to this for a specific # case, use TARGETS+=xxx in the actual makefile. # TARGETS:=all content targets debug install-questions install-answers \ web web-questions web-answers \ print print-questions print-answers \ questions answers \ clean web-clean print-clean .PHONY: $(TARGETS) ################################################################################ # # Build everything. # all: web print ################################################################################ # # Build questions or answers only. # questions: web-questions print-questions answers: web-answers print-answers ################################################################################ # # Build web version only. # web: web-questions web-answers web-questions: content $(WEB_QUESTIONS_HTML) $(WEB_QUESTIONS_HTML): $(DERIVED_XML) @announce "Building $@ from $<" $(call xslt,$<,xml2html.xsl,$(call xslt_parameter,department,'$(SUBJECT_CODE)'),$(call xslt_parameter,paper,'$(PAPER_NUMBER)'),$(call xslt_parameter,standalone,'no'),$(call xslt_parameter,showanswers,'no'),$(call xslt_parameter,base-path,'.'),$(call xslt_parameter,image-format,'png')) > $@ web-answers: content $(WEB_ANSWERS_HTML) $(WEB_ANSWERS_HTML): $(DERIVED_XML) @announce "Building $@ from $<" $(call xslt,$<,xml2html.xsl,$(call xslt_parameter,department,'$(SUBJECT_CODE)'),$(call xslt_parameter,paper,'$(PAPER_NUMBER)'),$(call xslt_parameter,standalone,'no'),$(call xslt_parameter,showanswers,'yes'),$(call xslt_parameter,base-path,'.'),$(call xslt_parameter,image-format,'png')) > $@ ################################################################################ # # Build print version only. We add code to the LaTeX source to mark the # first and last pages of the document, so that an individual PDF for this # document can be generated later. \markfirstpage and \marklastpage are # macros defined in handbook_template.tex that write the current physical # page number to the .aux file. # print: print-questions print-answers print-questions: content $(PRINT_QUESTIONS_TEX) $(PRINT_QUESTIONS_TEX): $(DERIVED_XML) @announce "Building $@ from $<" @echo "\\markfirstpage{$(SECTION)/$(BASE_NAME)/$(@:.tex=.pdf)}" > $@ $(call xslt,$<,xml2latex.xsl,$(call xslt_parameter,department,'$(SUBJECT_CODE)'),$(call xslt_parameter,paper,'$(PAPER_NUMBER)'),$(call xslt_parameter,standalone,'no'),$(call xslt_parameter,showanswers,'no'),$(call xslt_parameter,base-path,'sections/$(SECTION)/$(BASE_NAME)'),$(call xslt_parameter,image-format,'pdf')) >> $@ @echo "\\marklastpage{$(SECTION)/$(BASE_NAME)/$(@:.tex=.pdf)}" >> $@ %-questions.pdf: %-questions.tex @announce "Generating $@" @$(if $(wildcard $(HANDBOOK_ROOT)/handbook.pdf),,$(error $(HANDBOOK_ROOT)/handbook.pdf is missing)) @gs -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile=$@ \ -dFirstPage=$(shell grep '$@.1up.first' $(HANDBOOK_ROOT)/handbook.aux | cut -d= -f2) \ -dLastPage=$(shell grep '$@.1up.last' $(HANDBOOK_ROOT)/handbook.aux | cut -d= -f2) $(HANDBOOK_ROOT)/handbook.pdf %-questions-2up.pdf: %-questions.tex @announce "Generating $@" @$(if $(wildcard $(HANDBOOK_ROOT)/handbook-2up.pdf),,$(error $(HANDBOOK_ROOT)/handbook-2up.pdf is missing)) @gs -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile=$@ \ -dFirstPage=$(shell grep '$(@:-2up.pdf=.pdf).2up.first' $(HANDBOOK_ROOT)/handbook.aux | cut -d= -f2) \ -dLastPage=$(shell grep '$(@:-2up.pdf=.pdf).2up.last' $(HANDBOOK_ROOT)/handbook.aux | cut -d= -f2) $(HANDBOOK_ROOT)/handbook-2up.pdf print-answers: content $(PRINT_ANSWERS_TEX) $(PRINT_ANSWERS_TEX): $(DERIVED_XML) @announce "Building $@ from $<" @echo "\\markfirstpage{$(SECTION)/$(BASE_NAME)/$(@:.tex=.pdf)}" > $@ $(call xslt,$<,xml2latex.xsl,$(call xslt_parameter,department,'$(SUBJECT_CODE)'),$(call xslt_parameter,paper,'$(PAPER_NUMBER)'),$(call xslt_parameter,standalone,'no'),$(call xslt_parameter,showanswers,'yes'),$(call xslt_parameter,base-path,'sections/$(SECTION)/$(BASE_NAME)'),$(call xslt_parameter,image-format,'pdf')) >> $@ @echo "\\marklastpage{$(SECTION)/$(BASE_NAME)/$(@:.tex=.pdf)}" >> $@ %-answers.pdf: %-answers.tex @announce "Generating $@" @$(if $(wildcard $(HANDBOOK_ROOT)/handbook-answers.pdf),,$(error $(HANDBOOK_ROOT)/handbook-answers.pdf is missing)) @gs -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile=$@ \ -dFirstPage=$(shell grep '$@.1up.first' $(HANDBOOK_ROOT)/handbook-answers.aux | cut -d= -f2) \ -dLastPage=$(shell grep '$@.1up.last' $(HANDBOOK_ROOT)/handbook-answers.aux | cut -d= -f2) $(HANDBOOK_ROOT)/handbook-answers.pdf %-answers-2up.pdf: %-answers.tex @announce "Generating $@" @$(if $(wildcard $(HANDBOOK_ROOT)/handbook-answers-2up.pdf),,$(error $(HANDBOOK_ROOT)/handbook-answers-2up.pdf is missing)) @gs -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile=$@ \ -dFirstPage=$(shell grep '$(@:-2up.pdf=.pdf).2up.first' $(HANDBOOK_ROOT)/handbook-answers.aux | cut -d= -f2) \ -dLastPage=$(shell grep '$(@:-2up.pdf=.pdf).2up.last' $(HANDBOOK_ROOT)/handbook-answers.aux | cut -d= -f2) $(HANDBOOK_ROOT)/handbook-answers-2up.pdf ################################################################################ # # Generate the derived XML source from the original XML template. The Big # Ugly Regexp matches any file include directive (<@INC[ ]@>) and the # script then simply inserts the content of that file into the output # stream. This saves us having to fool around with XML document includes, # which basically just don't work for us because they expect the included # document to be a valid XML document. We really just want to include XML # fragments. XInclude 1.0 supports this, but it's only just been finalised # at the time of writing (January 2005). # $(DERIVED_XML): $(SOURCE_XML) @announce "Generating $@" @echo "<!-- THIS FILE IS AUTOMATICALLY GENERATED. DO NOT EDIT! -->" > $@ @echo >> $@ @perl -ne 'if (/^(.*)<\@INC\[([^]]+)\]@>(.*)$$/) { print "$$1\n" . `cat $(PAPER_ROOT)/$$2` . "\n$$3\n"; } else { print; }' $< >> $@ ################################################################################ # # If any of the content files change, touch the XML template to # ensure that the document gets fully rebuilt. # $(SOURCE_XML): $(CONTENT_SRC) @touch $@ ################################################################################ # # Build the individual content files, etc., as necessary. Note above that # all the primary targets depend on the "content" target, _before_ # anything else. This ensures that the content gets rebuilt (if necessary) # before anything else happens. # # This may seem redundant, given that SOURCE_XML depends on CONTENT_SRC in # the rule above. However, this rule only works if we change one of the # actual content files. What if instead, we change a graphic associated # with one of the content files, without changing the content file itself? # In this case, make assumes that nothing needs to be done, because the # content file is older than the target, and this makefile knows nothing # about any dependencies that the content file might have (that's dealt # with by the makefile in the appropriate content directory). This is the # main downside of having independent makefiles. # # So, the slightly convoluted workaround using the empty "content" target # ensures that the content files will always be checked, regardless of # whether they've changed. If any of their prerequisites for a particular # content file change, then the content file itself will be touched, thus # activating the SOURCE_XML rule above. This process is particularly # important to ensure that associated graphics get rebuilt when they # change. # # All that aside, however, the _real_ trick is to ensure that this rule is # only executed once. If we do a "make", this rule would nominally get # executed four times (once for each of the targets that depend on # "content"). The first time through the rule, therefore, we create a # marker file called "content-checked". If this file exists, the rule # isn't executed. These marker files are cleaned up by a one-off find # command when the makefile is first run (see the include file # one-time-init.make). # # Note: using the wildcard function to test for the existence of the # marker file doesn't work when the makefile is run standalone, because # the function result is expanded at the time the makefile is _loaded_, # _before_ the one-time initialisation has a change to kick in and delete # the file. This has the rather bizarre side-effect of the makefile only # re-checking the content on every second run, and means that we can't use # make conditionals to control rule execution. The solution is to prefix # every command in the rule with "test ! -f" to check whether the marker # file exists. # # Ack! The tribulations of not using a monolithic makefile... # content: # Of course, there's little point in doing anything if there's no content! ifneq ($(strip $(CONTENT_SRC)),) @if test ! -f content-checked; then \ announce "Checking content for $(BASE_NAME)"; \ fi # Sanity check: do the content files referenced from the original source # actually exist? The "cat</dev/null" is included because there needs to # be something in the body of the if --- you can't just leave it empty. We # can use the wildcard function here because these files should already # exist --- if they don't, then by definition the filename is wrong! @if test ! -f content-checked; then \ $(foreach f,$(CONTENT_SRC),$(if $(wildcard $f),,$(error Content file $f referenced from $(SOURCE_XML) does not exist)) cat</dev/null;) \ fi # Remake each individual content file. @if test ! -f content-checked; then \ $(foreach f,$(CONTENT_SRC),$(MAKE) -C $(dir $f) $(notdir $f) BUILD_DIR=$(CURDIR);) \ fi # Create the marker file so that this rule doesn't get executed again. @if test ! -f content-checked; then \ touch content-checked; \ fi endif ################################################################################ # # Install the appropriate files on the web server. This relies on the # environment variable HANDBOOK_INSTALL_DIRECTORY being defined, and # (assuming that this variable points to a directory on the network) the # appropriate share has been mounted. # # !!! How do we get it to also install any extra files that we require # for a particular content file (e.g., the SQL code for Tutorial 3)? !!! # install-questions: $(QUESTION_INSTALL_FILES) @test -d $(HANDBOOK_INSTALL_ROOT) ifneq ($(strip $(QUESTION_INSTALL_FILES)),) cp $(QUESTION_INSTALL_FILES) $(INSTALL_DIRECTORY) endif install-answers: $(ANSWER_INSTALL_FILES) @test -d $(HANDBOOK_INSTALL_ROOT) ifneq ($(strip $(ANSWER_INSTALL_FILES)),) cp $(ANSWER_INSTALL_FILES) $(INSTALL_DIRECTORY) endif ################################################################################ # # Clean up. # clean: web-clean print-clean ifneq ($(strip $(ALL_CLEAN_FILES)),) -rm -f $(ALL_CLEAN_FILES) endif web-clean: ifneq ($(strip $(WEB_CLEAN_FILES)),) -rm -f $(WEB_CLEAN_FILES) endif print-clean: ifneq ($(strip $(PRINT_CLEAN_FILES)),) -rm -f $(PRINT_CLEAN_FILES) endif ################################################################################ # # Debugging information, mostly lists of the generated variables. # debug: @announce Externally defined variables @echo "TEACHING_SHARED = [$(TEACHING_SHARED)]" @echo "ALL_PAPERS_ROOT = [$(ALL_PAPERS_ROOT)]" @echo "HANDBOOK_INSTALL_ROOT = [$(HANDBOOK_INSTALL_ROOT)]" @echo "NOINIT = [$(NOINIT)]" @announce Internally defined variables @echo "GLOBAL_HANDBOOK_INCLUDE = [$(GLOBAL_HANDBOOK_INCLUDE)]" @echo "LOCAL_HANDBOOK_INCLUDE = [$(LOCAL_HANDBOOK_INCLUDE)]" @echo "SUBJECT_CODE = [$(SUBJECT_CODE)]" @echo "PAPER_NUMBER = [$(PAPER_NUMBER)]" @echo "PAPER_ROOT = [$(PAPER_ROOT)]" @echo "HANDBOOK_ROOT = [$(HANDBOOK_ROOT)]" @echo "SECTION = [$(SECTION)]" @echo "BASE_NAME = [$(BASE_NAME)]" @echo "SOURCE_XML = [$(SOURCE_XML)]" @echo "DERIVED_XML = [$(DERIVED_XML)]" @echo "WEB_QUESTIONS_HTML = [$(WEB_QUESTIONS_HTML)]" @echo "WEB_ANSWERS_HTML = [$(WEB_ANSWERS_HTML)]" @echo "PRINT_QUESTIONS_TEX = [$(PRINT_QUESTIONS_TEX)]" @echo "PRINT_ANSWERS_TEX = [$(PRINT_ANSWERS_TEX)]" @echo "PRINT_QUESTIONS_PDF_1UP = [$(PRINT_QUESTIONS_PDF_1UP)]" @echo "PRINT_ANSWERS_PDF_1UP = [$(PRINT_ANSWERS_PDF_1UP)]" @echo "PRINT_QUESTIONS_PDF_2UP = [$(PRINT_QUESTIONS_PDF_2UP)]" @echo "PRINT_ANSWERS_PDF_2UP = [$(PRINT_ANSWERS_PDF_2UP)]" @echo "DERIVED_WEB_FILES = [$(DERIVED_WEB_FILES)]" @echo "DERIVED_PRINT_FILES = [$(DERIVED_PRINT_FILES)]" @echo "CONTENT_SRC = [$(CONTENT_SRC)]" @echo "QUESTION_INSTALL_FILES = [$(QUESTION_INSTALL_FILES)]" @echo "ANSWER_INSTALL_FILES = [$(ANSWER_INSTALL_FILES)]" @echo "WEB_CLEAN_FILES = [$(WEB_CLEAN_FILES)]" @echo "PRINT_CLEAN_FILES = [$(PRINT_CLEAN_FILES)]" @echo "ALL_CLEAN_FILES = [$(ALL_CLEAN_FILES)]" ################################################################################ # # Print out the list of targets. Handy for when you forget! # targets: @echo $(TARGETS)