################################################################################
#
# File: $Id$
#
# Standard variables and rules for building everything associated with a
# content file, including graphics and supporting files. Only content
# files that have such supporting files need to have (custom) rules
# defined for them, all other content files will be handled by make's
# default behaviour.
#
# Note that all versions of the graphics for a content file will be
# generated, regardless of whether we are building the web or print
# versions. This may seem a little wasteful, but there are two points to
# consider here:
# 
# 	1. At the time this makefile is executed, we have no easy way
# 	   to determine which "build mode" we are in. (It could be done
# 	   with exported variables from the parent makefile, but see below.)
# 
# 	2. This makefile will only be executed once for the document in
# 	   question anyway, because once make has processed the parent
# 	   file, that file will be considered "up-to-date", and make will
# 	   therefore not come back to it again, even though both the print
# 	   and web targets depend on it.
# 
# So, even if we just were clever enough to set up conditionals based on
# the "build mode", if we just went "make", we would almost certainly find
# that make would build either the web graphics only, or the print
# graphics only, but not both. We therefore leave this file as is, and
# build both web and print graphics regardless. It doesn't take that much
# longer anyway, especially since we won't be regenerating all of the
# graphics for _everything_ when only one file has changed :)
#
################################################################################


################################################################################
#
# Path to the build directory. This must be passed in from the calling
# environment. We don't default to the current directory because it makes
# it more difficult to clean up.
#
BUILD_DIR?=$(error The variable BUILD_DIR has not been defined)


################################################################################
#
# Paths. All original graphics should normally be in ./graphics/source,
# and derived versions should normally be placed in ./graphics. If you
# want something different, write your own rules, you deviant!
#
vpath %-web.png $(BUILD_DIR)
vpath %-web-zoom.png $(BUILD_DIR)
# vpath %-web-hires.png $(BUILD_DIR)
vpath %-print.pdf $(BUILD_DIR)
vpath %.eps graphics


################################################################################
#
# List of possible targets. If you need to add to this for a specific
# case, use TARGETS+=xxx in the actual makefile.
#
TARGETS:=all clean web-clean print-clean targets debug

.PHONY: $(TARGETS)


################################################################################
#
# Default rule, for those who are misguided enough to try running a bare
# "make" on the makefile.
#
all:
	$(error You need to call this makefile with the name of a specific content file as the target)


################################################################################
#
# Build correctly cropped EPS (for printing) from original source EPS.
#
%-print.pdf: %.eps
	@announce "Generating $@ (print)"
	@ps2pdf -dEPSCrop -dNOCACHE $< $@
	@mv $@ $(BUILD_DIR)


################################################################################
#
# Build correctly cropped PNGs for web display from the original source
# EPS.
#
# It might seem to make more sense to generate the PNGs from the print
# EPS, which has already been appropriately cropped. However, the results
# of directory searches using vpath are rather unpredictable when the
# source file is not guaranteed to exist. If we depended on %-print.eps,
# which is generated by the rule above, it's not guaranteed that the file
# will exist at the time that make performs its directory search (which
# seems to be done statically). The source EPS isn't generated and can
# thus be guaranteed to always exist. Give me guaranteed correct operation
# over efficiency any day! :)
#
# Build 96 DPI version for normal web display
#
%-web.png: %.eps
	@announce "Generating $@ (web)"
	@gs -dNOPAUSE -dBATCH -dSAFER -sDEVICE=png16m -dEPSCrop -r96 \
		-dTextAlphaBits=4 -dGraphicsAlphaBits=4 -sOutputFile=$@ $<
	@mv $@ $(BUILD_DIR)

#
# Build 144 DPI version for zoomed web display
#
%-web-zoom.png: %.eps
	@announce "Generating $@ (zoomed web)"
	@gs -dNOPAUSE -dBATCH -dSAFER -sDEVICE=png16m -dEPSCrop -r144 \
		-dTextAlphaBits=4 -dGraphicsAlphaBits=4 -sOutputFile=$@ $<
	@mv $@ $(BUILD_DIR)

#
# Are 600 DPI versions even needed?? They don't seem to be used anywhere...
#
# %-web-hires.png: %.eps
# 	@announce "Generating $@ (600 dpi)"
# 	@gs -dNOPAUSE -dBATCH -dSAFER -sDEVICE=png16m -dEPSCrop -r600 \
# 		-dTextAlphaBits=4 -dGraphicsAlphaBits=4 -sOutputFile=$@ $<
# 	@mv $@ $(BUILD_DIR)


################################################################################
#
# Clean up. These targets are probably no longer needed, as the build
# versions are now generated in the build directory. There should
# consequently be no extraneous files floating around in the content
# directory that need to be cleaned.
#
# clean: web-clean print-clean
# 
# web-clean:
# 	rm -f *.png
# 
# print-clean:
# 	rm -f *.pdf


################################################################################
#
# Debugging information, mostly lists of the generated variables.
#
debug:
	@announce Externally defined variables
	@echo "TEACHING_SHARED = [$(TEACHING_SHARED)]"
	@echo "BUILD_DIR = [$(BUILD_DIR)]"
	@announce Internally defined variables
	@echo "GLOBAL_HANDBOOK_INCLUDE = [$(GLOBAL_HANDBOOK_INCLUDE)]"
	@echo "LOCAL_HANDBOOK_INCLUDE = [$(LOCAL_HANDBOOK_INCLUDE)]"


################################################################################
#
# Print out the list of targets. Handy for when you forget!
#
targets:
	@echo $(TARGETS)