Doc/Manual/Makefile

# Makefile for generating the SWIG documentation
#
# Note that the htmldoc package needs to be installed. wkhtmltopdf patched with qt is also required
# and the prebuilt binaries can be installed from https://wkhtmltopdf.org/downloads.html.
#
# The .html files are first processed and updated with chapter numbering and anchor names
# are added to the HTML headings using the python scripts. The htmldoc program is then
# used to generate the single page HTML version of the documentation.
# wkhtmltopdf is used to generate the pdf document from the single page html file.
# HTML TIDY (package also known as tidy) is also required and is used as an aid to HTML
# validation.
#
# Additional html validation can be done using the validate target.
# Additional link checking can be done using the linkchecker1 and linkchecker2 target.
#

# Note the # and " are escaped
HTMLDOC_OPTIONS = "--book --toclevels 4 --no-numbered --toctitle \"Table of Contents\" --title --titleimage swig16.png --linkcolor \#0000ff --linkstyle underline --size Universal --left 0.50in --right 0.50in --top 0.50in --bottom 0.50in --header .t. --footer h.1 --nup 1 --tocheader .t. --tocfooter ..i --portrait --color --no-pscommands --no-xrxcomments --compression=1 --jpeg=0 --fontsize 10.0 --fontspacing 1.2 --headingfont Helvetica --bodyfont Times --headfootsize 10.0 --headfootfont Helvetica --charset iso-8859-1 --links --no-embedfonts --pagemode outline --pagelayout single --firstpage c1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all  --owner-password \"\"  --user-password \"\" --browserwidth 680"

.PHONY: maketoc check generate all maintainer-clean validate test

all: maketoc check generate

maketoc:
	python maketoc.py

# Use this to regenerate CCache.html should this ever be needed
CCache.html: ../../CCache/ccache.yo
	yodl2html -o CCache.html ../../CCache/ccache.yo

# Tabs in the html files will stop the build as wkhtmltopdf does not expand them correctly - replace them with the appropriate number of tabs
# Use htmltidy to warn about some HTML errors. Note that it is not used to clean/tidy the HTML,
# it is just used as a primitive HTML checker.
# CCache.html is generated by yodl2html and has a few insignificant problems, so we don't put it through tidy
check:
	all="index.html Sections.html `sed '/^#/d' chapters | grep -v CCache.html`" && for a in $$all; do echo "Check for tabs $$a" && if grep -P '\t' $$a; then echo "Please delete the tabs from the lines above" && exit 1; fi; done && for a in $$all; do echo "HTML tidy check $$a" && tidy -errors --gnu-emacs yes -quiet $$a; done;

# Note wkhtmltopdf limitations for generating pdf docs:
#  1) <H1><a name="X"></a>Text</H1> style links don't work and need changing to
#     <H1><a name="X">Text</a></H1>
#  2) Tabs in <pre> elements should be expanded to 8 spaces by default, but
#     are expanded to just one space and css tab-size is not working.
#  3) <pre> <tt> <code> elements do not always select a fixed-width font - try installing the
#     Courier font to fix - these have been added to style.css.
generate: SWIGDocumentation.html
	wkhtmltopdf --version | grep "with patched qt" || (echo "wkhtmltopdf is not the patched qt version and so cannot be used - download it from https://wkhtmltopdf.org/downloads.html" && false)
	wkhtmltopdf --margin-top 20mm --margin-bottom 20mm --margin-left 10mm --margin-right 10mm --header-font-size 6 --footer-font-size 6 --header-spacing 6 --footer-spacing 6 --header-center '[doctitle]' --footer-left '[subsection]' --footer-right '[page]' --allow . SWIGDocumentation.html SWIGDocumentation.pdf

SWIGDocumentation.html: swightml.book
	htmldoc --batch swightml.book || true
	python fixstyle.py SWIGDocumentation.html

swightml.book: chapters Sections.html
	echo "#HTMLDOC 1.8.24" > swightml.book
	echo -t html -f SWIGDocumentation.html $(HTMLDOC_OPTIONS) >> swightml.book
	echo "Sections.html" >> swightml.book
	cat chapters >> swightml.book

maintainer-clean: clean-baks
	rm -f swightml.book
	rm -f SWIGDocumentation.html
	rm -f SWIGDocumentation.pdf
	rm -rf linkchecker-tmp

clean-baks:
	rm -f *.bak

test:
	grep "href=\".*\.html\"" index.html
	grep "href=\".*\.html\"" Sections.html
	all=`sed '/^#/d' chapters`; for a in $$all; do grep -l "href=\".*\.html\"" $$a; done;

# Validating using the WDG offline validator - http://www.htmlhelp.com/tools/validator/offline/
validate:
	all=`sed '/^#/d' chapters`; for a in $$all; do validate --emacs $$a; done;

# Link checking using linkchecker of the index.html only file (including anchors)
linkchecker1:
	@echo -----------------------------------------------------------------------
	@echo Note linkchecker versions prior to 6.1 do not work properly wrt anchors
	@echo -----------------------------------------------------------------------
	linkchecker --config=./linkchecker.config --anchors index.html

# Check for links which don't work including those generated from the individual .html files into SWIGDocumentation.html
linkchecker2:
	rm -rf linkchecker-tmp
	mkdir linkchecker-tmp
	cp SWIGDocumentation.html linkchecker-tmp
	cp *.png linkchecker-tmp
	(cd linkchecker-tmp && linkchecker --config=../linkchecker.config -F text --no-warnings SWIGDocumentation.html)

# Simple check for relative links (there shouldn't be any), they don't translate properly creating the .pdf doc
# with wkhtmltopdf. For example, href="SWIG.html" needs to be href="SWIG.html#SWIG"
linkchecker3:
	@echo "The following list should just contain SWIGDocumentation.html and SWIGDocumentation.pdf,"
	@echo "as all links should have an anchor (with a #) or be a full url beginning http."
	grep 'href="' *.html | sed -e 's/.*href="\(.*\)">.*$$/\1/' | grep -v "#" | grep -v "^http" | grep -v "^style.css"