now all images are correct + tiny tweak...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

.editorconfig

@@ -0,0 +1,7 @@
+root = true
+
+[**]
+indent_style = tab
+tab_width = 4
+charset = utf-8
+end_of_line = lf

.github/workflows/make-dist.yml

@@ -18,9 +18,18 @@ jobs:
       uses: xu-cheng/texlive-action/full@v1
       with:
         run: |
-          apk add make git zip
+          apk add make git zip grep
           git config --global --add safe.directory '*'
           echo "VERSION=$(make version)" >> $GITHUB_ENV
+          # XXX not sure about this...
+          #COMMENT="$(git log -1 --pretty=%B | grep -v "Signed-off-by:")"
+          #COMMENT="${COMMENT//'%'/'%25'}"
+          #COMMENT="${COMMENT//$'\n'/'%0A'}"
+          #COMMENT="${COMMENT//$'\n'/'%0D'}"
+          #echo 'COMMENT<<EOF' >> $GITHUB_ENV
+          #echo "${COMMENT}" >> $GITHUB_ENV
+          #echo 'EOF' >> $GITHUB_ENV
+          # XXX if comment is multi-line it breaks the CTAN announcement...
           echo 'COMMENT<<EOF' >> $GITHUB_ENV
           git log -1 --pretty=%B | grep -v "Signed-off-by:" >> $GITHUB_ENV
           echo 'EOF' >> $GITHUB_ENV
@@ -35,13 +44,13 @@ jobs:
           photobook.pdf
         
     - name: Artifacts - build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: build artifacts
         path: photobook.pdf
 
     - name: Artifacts - dist
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: dist artifacts
         path: dist/photobook-*.zip
@@ -69,6 +78,9 @@ jobs:
               defining a set of parameters, meta-macros, macros and
               environments with reasonable defaults to help typeset,
               build and print books mainly based on visual/image content.
+            # XXX multi-line comments will break things...
+            #     ...another potential cause is an empty line in a commit, 
+            #     need more testing...
             announcement: >
               ${{ env.COMMENT }}
                

Makefile

@@ -43,10 +43,6 @@
 #----------------------------------------------------------------------
 # Config...
 
-.EXPORT_ALL_VARIABLES:
-
-#.ONESHELL:
-
 # NOTE: this makes things run consistently on different systems including 
 # 		things like Android...
 SHELL := bash
@@ -60,8 +56,9 @@ MODULE := photobook
 VERSION = $(strip $(shell \
 	cat $(MODULE).cls \
 		| grep 'VERSION{' \
-	 	| sed 's/.*{\(.*\)}.*/\1/' \
-		| sed 's/v//'))
+	 	| sed \
+			-e 's/.*{\(.*\)}.*/\1/' \
+			-e 's/v//'))
 DATE = $(strip $(shell date "+%Y%m%d%H%M"))
 COMMIT = $(strip $(shell git rev-parse HEAD))
 
@@ -88,8 +85,7 @@ endif
 
 # markdown dialect...
 #
-# XXX still needs some tweaking...
-MD_FORMAT ?= markdown_github
+MD_FORMAT ?= gfm
 
 
 # debug output...
@@ -125,6 +121,7 @@ DIST_NORMAL_FILES = \
 	README.md \
 	LICENSE \
 	Makefile \
+	DEPENDS.txt \
 	$(MODULE).cls \
 	$(MODULE).pdf
 DIST_FILES = \
@@ -175,26 +172,11 @@ LN := cp -l
 # 			- |..|	- verbatim does not work...
 # 			- ||	- parts of doc omitted...
 #			- verbatim blocks get merged sometimes...
+#			- does not resolve \jobname in include...
 #			- ...
 #		...not sure if this can be tweaked...
-#%.md: %.tex
-#	pandoc -t $(MD_FORMAT) -s $< -o $@
-
-# XXX EXPERIMENTAL...
-# XXX revise:
-#		...for this to work we need to replace:
-#			\documentclass{ltxdoc}
-#		to:
-#			\documentclass[markdownextra]{internet}
-# XXX install the internet class...
-#			https://github.com/loopspace/latex-to-internet
-#		...needs testing...
 %.md: %.tex
-	cat $< \
-		| sed 's/documentclass{ltxdoc}/documentclass[markdownextra]{internet}/' \
-		> $<.tmp
-	mv $<{.tmp,}
-	$(TEX) $< $(STDERR)
+	pandoc -t $(MD_FORMAT) -s $< -o $@
 
 
 # meta-section...
@@ -225,6 +207,7 @@ LN := cp -l
 # strip docs out...
 #
 # XXX can we unify these???
+# 		....not sure how...
 %-stripped.tex: %.tex
 	$(DOC) --strip $< \
 		$(DOC) --prefix M --strip \
@@ -241,6 +224,15 @@ LN := cp -l
 		> $@
 
 
+# list of dependencies...
+#
+DEPENDS.txt: $(MODULE).cls
+	make depends \
+		| grep -v make \
+		| sed -e 's/^/hard /' \
+		> $@
+
+
 
 #----------------------------------------------------------------------
 # Info targets...
@@ -250,10 +242,27 @@ version:
 	@echo $(VERSION)
 
 
+# NOTE: grep's -z flag generates a bunch if nulls that we need to clean 
+# 		out via tr.
+# XXX this is a bit ugly -- adding/removing "hard" and then adding it 
+# 		again for DEPENDS.txt...
+.PHONY: depends
+depends: $(MODULE).cls
+	@cat $< \
+		| grep -Ezo '\s*\\RequirePackage(\[[^]]*\])?\{[^}]*\}' \
+		| sed -e 's/.*{\(.*\)}/hard \1\n/' \
+		| grep -a hard \
+		| tr -d '\000' \
+		| cut -d " " -f 2
+
+
 
 #----------------------------------------------------------------------
 # Main targets...
 
+.PHONY: dep
+dep: DEPENDS.txt
+
 .PHONY: pdf
 pdf: $(MODULE).pdf
 
@@ -295,6 +304,7 @@ tag:
 	@echo "    v$(VERSION)"
 	@echo "Last 5 tags:"
 	@git tag -l 'v[0-9]*'\
+		| sort -V \
 		| tail -n 5 \
 		| sed 's/^/    /' \
 		| tac
@@ -326,7 +336,7 @@ tag:
 
 
 .PHONY: all
-all: pdf
+all: pdf dep 
 
 
 # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -408,7 +418,7 @@ sweep:
 
 .PHONY: clean
 clean: sweep
-	rm -rf $(DIST_DIR) $(BUILD_DIR) $(MODULE).md *.pdf
+	rm -rf $(DIST_DIR) $(BUILD_DIR) $(MODULE).md DEPENDS.txt *.pdf
 
 
 

README.md

@@ -4,8 +4,59 @@ photobook
 [LaTeX](https://www.latex-project.org/) document class for making photo books.
 
 
-## Build requirements for docs
+Available on:
+- CTAN: https://ctan.org/pkg/photobook
+- GitHub: https://github.com/flynx/photobook
 
+
+## Install / Build
+
+The simplest way to install is to use either 
+[TeX Live](https://www.tug.org/texlive/)'s or [MiKTeX](https://miktex.org/)'s 
+standard way to install modules.
+
+
+Installing from source:
+```shell
+# get the source...
+$ git clone https://github.com/flynx/photobook.git
+
+# if desired, install in the user context...
+$ cd ./photobook
+$ make install
+```
+
+The `photobook` document class requires a set of modules to be installed
+for it to function, the full list is included in the docs and can be 
+generated and printed by calling:
+```shell
+$ make depends
+```
+
+For more info on `make` targets see the: [./Makefile](./Makefile)
+
+
+
+# Documentation
+
+Pre-built documentation can be found in the 
+[Github releases](https://github.com/flynx/photobook/releases/latest) or on
+[CTAN](http://mirrors.ctan.org/macros/latex/contrib/photobook/photobook.pdf).
+
+
+A full book (dummy) example is included in [./examples/book/](./examples/book/) 
+and can be used as a reference / starting point.
+
+
+
+## Building documentation
+
+Building the reference from source is done by:
+```shell
+$ make pdf 
+```
+
+Build requirements for docs:
 - LaTeX tool chain (including: `lualatex`, `latexmk`, ..)  
   The simplest way to get started is [TeX Live](https://www.tug.org/texlive/), 
   either a full install or for specific modules see the _Packages_ section 
@@ -17,33 +68,14 @@ photobook
 
 
 
-## Build / Install
-
-The package is available on: 
-- CTAN: https://ctan.org/pkg/photobook
-- GitHub: https://github.com/flynx/photobook
-
-
-To install from source:
-```shell
-# get the source...
-$ git clone https://github.com/flynx/photobook.git
-
-# if desired, install in the user context...
-$ cd ./photobook
-$ make install
-```
-
-If only building the docs is required without installing:
-```shell
-$ make pdf 
-```
-
-For more info on `make` targets see the: [./Makefile](./Makefile)
-
-
 ## Notes
 
+- The main reference is maintained inline with the source [photobook.cls](./photobook.cls) 
+  thus it is both human-readable next to the code it documents and is 
+  used to build the `photobook.pdf`.
+  Extracting the documentation source (`photobook*.tex`) is done 
+  by [make](./Makefile) via [cls2tex.sh](scripts/README.md#cls2texsh) when 
+  building the docs, see them for more info.
 - There is a bug in default captions not being typeset correctly if too 
   long, a workaround is to place them in a `minipage` like this:
   ```latex
@@ -72,3 +104,4 @@ Copyright (c) 2021-2023, Alex A. Naanou,
 All rights reserved.
 
 
+<!-- vim:set ts=4 sw=4 nowrap : -->

examples/book/Makefile

@@ -0,0 +1,151 @@
+#----------------------------------------------------------------------
+#
+#
+#
+#----------------------------------------------------------------------
+# make config...
+
+.SECONDEXPANSION:
+
+.DEFAULT_GOAL := all
+
+#SHELL := bash
+
+ifeq ($(DEBUG),)
+	STDERR := > /dev/null
+endif
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# config...
+
+DIST_DIR := dist/PRINT
+SPREAD_DIR := spreads
+TEMPLATE_DIR := templates
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# sources...
+
+SETUP := \
+	setup.tex
+
+TEMPLATE_FILES := \
+	$(wildcard $(TEMPLATE_DIR)/*)
+
+SPREADS := \
+	spreads.tex
+
+COMPONENTS := \
+	cover.pdf jacket.pdf endpaper.pdf \
+	block.pdf
+
+# things that we need that does not need to be built my this Makefile,
+# this could include custom graphics, manual layouts, ...etc.
+EXTRAS :=
+
+
+
+#----------------------------------------------------------------------
+# config/commands...
+
+MD = @mkdir -p
+
+# primary engine, everything works...
+# NOTE: several hacks had to be made -- see setup.tex
+CMD = lualatex
+#ARGS = -output-driver="xdvipdfmx -q -E -V 3"
+
+MAKESPREADS := ../../scripts/make-spreads.sh
+
+
+
+#----------------------------------------------------------------------
+# components and rules...
+
+# generic latex -> pdf...
+%.pdf: %.tex $(SETUP)
+	-$(CMD) $< $(STDERR)
+
+
+spreads.tex: $(SPREAD_DIR) $(wildcard $(SPREAD_DIR)/*/*) $(TEMPLATE_FILES)
+	$(MAKESPREADS) $< $(SPREAD) > $@
+
+# in case we need multiple chapters/sections, i.e. sets of spreads...
+# XXX needs testing -- % in the wildcard function...
+%-spreads.tex: $(SPREAD_DIR)/% $(wildcard $(SPREAD_DIR)/%/*/*) $(TEMPLATE_FILES)
+	$(MAKESPREADS) $< $(SPREAD) > $@
+
+
+block.pdf: $(SPREADS) 
+
+
+# XXX need to also include covers and endpapers (optionally?)
+# XXX this is broken...
+##web.tex: setup.tex
+##	{ \
+##		echo "% This file is generated via make web.tex" \
+##		echo "% see the Makefile for info" \
+##		echo "% do not edit directly" \
+##		echo \
+##		echo "\input{setup}"  \
+##		echo \
+##		echo "\setlength\bleed{0mm}" \
+##		echo "\setlength\bindingoffset{0mm}" \
+##		echo \
+##		echo "\ChangeLayout{endpaper}" \
+##		echo \
+##		echo "\pagecolor{black}" \
+##		echo \
+##		echo "\begin{document}" \
+##		echo "\includepdf[pages={{},1-}, nup=2x1, delta=0.3mm 0.3mm]{block}" \
+##		echo "\end{document}" \
+##		echo \
+##	} > $@ 
+
+
+
+#----------------------------------------------------------------------
+# production targets...
+
+.PHONY: all
+all: $(COMPONENTS) $(EXTRAS)
+
+
+
+#----------------------------------------------------------------------
+# packageing...
+
+.PHONY: dist
+dist: $(COMPONENTS) $(EXTRAS)
+	$(MD) $(DIST_DIR)
+	cp $? $(DIST_DIR)
+
+
+
+#----------------------------------------------------------------------
+# utility trgets...
+
+.PHONY: sweep
+sweep:
+	-rm -f *.out *.aux *.log *.upa ; true
+
+
+.PHONY: clean
+clean: sweep
+	-rm -rf *.pdf PRINT *.image-list $(SPREADS) ; true
+
+
+.PHONY: clean-dist
+clean-dist:
+	-rm -rf dist ; true
+
+
+.PHONY: clean-all
+clean-all: clean clean-dist
+
+
+
+
+#----------------------------------------------------------------------
+#

examples/book/README.md

@@ -0,0 +1,81 @@
+Full book example
+=================
+
+This directory contains a full book example.
+
+```
+book/
+├── templates/  . . . . . . . . . . . . Templates used to buld spreads
+│   └── ...                             (used by: make-spreads.sh)
+├── spreads/  . . . . . . . . . . . . . Spread layout
+│   └── ...                             (used by: make-spreads.sh)
+├── captions/ . . . . . . . . . . . . . Image captions
+│   └── ...                             (used by: make-spreads.sh)
+├── hi-res/ . . . . . . . . . . . . . . High resolution graphics
+│   └── ...                             (used by: make-spreads.sh)
+├── Makefile
+├── setup.tex . . . . . . . . . . . . . Book setup and configuration
+│                                       This file contains all the book
+│                                       geometry, colors and other 
+│                                       settings common to all comoponents 
+│                                       of the book.
+├── block.tex . . . . . . . . . . . . . General page block layout.
+├── spreads.tex . . . . . . . . . . . . Book spereads
+│                                       (generated by: make-spreads.sh)
+├── cover.tex
+├── endpaper.tex 
+├── jacket.tex
+└── ... 
+```
+
+Note that this is by no means the only or most optomal project 
+structure, but it is a good enough starting point that evolved through 
+several, big and small project to start the next one from (at least 
+for me, subjectively).
+
+
+
+Building
+--------
+
+To build all components:
+```shell
+$ make all
+```
+
+To build a specific component:
+```shell
+$ make block.pdf
+``` 
+
+`block.pdf` in this case.
+
+<!-- XXX add basic introspection to Makefike??? -->
+
+
+Structure
+---------
+
+### `setup.tex`
+
+### `spreads.tex`
+
+### `cover.tex` / `jacket.tex` / `endpaper.tex` / ..
+
+### `web.tex`
+
+<!-- XXX this is quite generic, can we generate it? -->
+
+
+
+Workflow
+--------
+
+XXX
+
+
+For information about building spreads see: 
+[make-spreads.sh](../../scripts/README.md)
+
+
+<!-- vim:set ts=4 sw=4 nowrap : -->

examples/book/block.tex

@@ -0,0 +1,28 @@
+%----------------------------------------------------------------------
+
+\input{setup}
+
+
+\begin{document} %-----------------------------------------------------
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% XXX half title...
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\BookInfoPage
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% XXX intro...
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% XXX title...
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\input{spreads}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\BookSoftwareInfoPage
+
+
+\end{document} %-------------------------------------------------------
+%                                                  vim:set ts=4 sw=4 :

examples/book/cover.tex

@@ -0,0 +1,17 @@
+%----------------------------------------------------------------------
+
+\input{setup}
+
+\ChangeLayout{cover}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\begin{document}
+
+\GenerateTemplate
+
+\end{document}
+
+
+%----------------------------------------------------------------------
+%                                                  vim:set ts=4 sw=4 :

examples/book/endpaper.tex

@@ -0,0 +1,17 @@
+%----------------------------------------------------------------------
+
+\input{setup}
+
+\ChangeLayout{endpaper}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\begin{document}
+
+\GenerateTemplate
+
+\end{document}
+
+
+%----------------------------------------------------------------------
+%                                                  vim:set ts=4 sw=4 :

examples/book/jacket.tex

@@ -0,0 +1,17 @@
+%----------------------------------------------------------------------
+
+\input{setup}
+
+\ChangeLayout{jacket}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\begin{document}
+
+\GenerateTemplate
+
+\end{document}
+
+
+%----------------------------------------------------------------------
+%                                                  vim:set ts=4 sw=4 :

examples/book/setup.tex

@@ -0,0 +1,42 @@
+
+%----------------------------------------------------------------------
+
+\documentclass[
+	layoutmode=block,
+	% page size...
+	blockwidth=240mm, blockheight=220mm,
+	bleed=4mm,
+	gutteroffset=5mm,
+	bindingoffset=1mm,
+	% cover...
+	coverboardgrow=3mm,
+	coverflap=17mm,
+	spinewidth=15mm,
+	spinefold=5mm,
+	spinefold=5mm,
+	% jacket...
+	jacketflap=50mm,
+	jacketwrap=1mm,
+	% image block configuration...
+	imageblockwidth=0.98, imageblockheight=0.98,
+	imageblockoffsettop=-0.1,
+	% misc...
+	9pt,final,openany
+]{photobook}
+
+
+\def\BookTitle{Info page demo}
+\def\BookVersion{1.0}
+\def\BookAuthors{John J. Smith}
+\def\ByNotice{%
+	Graphics: none
+
+	Text: almost none}
+\def\ThanksTo{%
+	Everyone}
+\def\ISBN{000-0-0000000-0-0}
+\def\Edition{I 500}
+
+
+%----------------------------------------------------------------------
+%                                                  vim:set ts=4 sw=4 :

examples/book/spreads/-03-disabled/01.txt

@@ -0,0 +1 @@
+Some text

examples/book/spreads/-03-disabled/02.txt

@@ -0,0 +1 @@
+Some text

examples/book/spreads/00-text-only/text.txt

@@ -0,0 +1 @@
+page text

examples/book/spreads/01-image-text/02-block.txt

@@ -0,0 +1 @@
+Some text

examples/book/spreads/02-two-images-local-caption/02-pic.txt

@@ -0,0 +1 @@
+caption text

examples/book/templates/blank-image.tex

@@ -0,0 +1,2 @@
+\cleardoublepage
+\ImagePage{${CAPTION0}}{${IMAGE0}}

examples/book/templates/fullbleed.tex

@@ -0,0 +1 @@
+\ImageSpreadFill{${CAPTION}}{${IMAGE0}}

examples/book/templates/image-blank.tex

@@ -0,0 +1,2 @@
+\ImagePage{${CAPTION0}}{${IMAGE0}}
+\emptypage

examples/book/templates/image-image.tex

@@ -0,0 +1,2 @@
+\ImagePage{${CAPTION0}}{${IMAGE0}}
+\ImagePage{${CAPTION1}}{${IMAGE1}}

examples/book/templates/imagepage.tex

@@ -0,0 +1 @@
+\ImagePage{${CAPTION}}{${IMAGE}}

examples/book/templates/textpage.tex

@@ -0,0 +1,4 @@
+\parbox{\textwidth}{%
+	\setlength{\parskip}{1em}
+	\input{${TEXT}} }
+\newpage

examples/book/web.tex

@@ -0,0 +1,28 @@
+%----------------------------------------------------------------------
+%
+%
+%
+%
+%----------------------------------------------------------------------
+
+\input{setup}
+
+\setlength\bleed{0mm}
+\ChangeLayout{spread}
+\pagestyle{empty}
+
+
+
+\begin{document} %-----------------------------------------------------
+
+
+\includepdfmerge{jacket.pdf}
+
+\includepdfmerge{cover.pdf}
+
+\pdfspreadstopages{block}
+
+
+
+\end{document} %-------------------------------------------------------
+%                                                  vim:set ts=4 sw=4 :

examples/cliptocell-test.tex

@@ -0,0 +1,93 @@
+%----------------------------------------------------------------------
+
+\documentclass[
+	layoutmode=block,
+	% page size...
+	blockwidth=240mm, blockheight=220mm,
+	bleed=4mm,
+	gutteroffset=5mm,
+	bindingoffset=0mm,
+	% image block configuration...
+	imageblockwidth=0.98, imageblockheight=0.98,
+	imageblockoffsettop=0,
+	% misc...
+	9pt,final,openany
+]{photobook}
+
+\usepackage{lipsum}
+\usepackage{ragged2e}
+
+
+
+% XXX for some reason this is not in the top/left corner...
+% XXX bug in photobook???
+\newcommand\CaptionBox[1][Caption]{%
+	\setlength\fboxsep{0pt}%
+	\fbox{%
+		\setlength\fboxsep{1pt}%
+		\colorbox{white}{\tiny #1}}}
+
+
+\begin{document} %-----------------------------------------------------
+
+\setlength\parindent{0em}
+\newlength\cellsize
+\setlength\cellsize{25mm}
+\renewcommand\fbox{\fcolorbox{red}{white}}
+
+\begin{page}%
+	|cliptocell| bleeds
+	\par%
+	\vspace{6mm}%
+	\setlength\fboxsep{0pt}%
+	\fbox{%
+		\begin{inlinecell*}{\cellsize}{\cellsize}%
+			\imagecell[fill, clearance=-6mm]{\CaptionBox[no clip]}{landscape}%
+		\end{inlinecell*}}%
+	\hspace{1cm}%
+	\fbox{%
+		\begin{inlinecell*}{\cellsize}{\cellsize}%
+			\begin{cliptocell}%
+				\imagecell[fill, clearance=-6mm]{\CaptionBox[default=0pt]}{landscape}%
+			\end{cliptocell}%
+		\end{inlinecell*}}%
+	\hspace{1cm}%
+	\fbox{%
+		\begin{inlinecell*}{\cellsize}{\cellsize}%
+			\begin{cliptocell}[5mm]%
+				\imagecell[fill, clearance=-6mm]{\CaptionBox[5mm]}{landscape}%
+			\end{cliptocell}%
+		\end{inlinecell*}}%
+	\hspace{1cm}%
+	\fbox{%
+		\begin{inlinecell*}{\cellsize}{\cellsize}%
+			\begin{cliptocell}[1mm 5mm]%
+				\imagecell[fill, clearance=-6mm]{\CaptionBox[1mm 5mm]}{landscape}%
+			\end{cliptocell}%
+		\end{inlinecell*}}%
+	\hspace{1cm}%
+	\fbox{%
+		\begin{inlinecell*}{\cellsize}{\cellsize}%
+			\begin{cliptocell}[1mm 2mm 3mm 4mm]%
+				\imagecell[fill, clearance=-6mm]{\CaptionBox[1mm 2mm 3mm 4mm]}{landscape}%
+			\end{cliptocell}%
+		\end{inlinecell*}}%
+\end{page}%
+
+\begin{page}%
+	% XXX this is padded by 1mm for some reason -- not sure if it's the
+	% 		image or the enclosing cell...
+	\fbox{%
+		\begin{inlinecell*}{\cellsize}{\cellsize}%
+			\imagecell[fit]{}{landscape}%
+		\end{inlinecell*}}%
+	\hspace{1cm}%
+	\fbox{%
+		\begin{inlinecell*}{\cellsize}{\cellsize}%
+			\imagecell[fit, clearance=-1mm -2mm -3mm -4mm]{}{landscape}%
+		\end{inlinecell*}}%
+\end{page}%
+
+
+\end{document} %-------------------------------------------------------
+%                                                   vim:set ts=4 sw=4 :

examples/cover-template.tex

@@ -0,0 +1,30 @@
+%----------------------------------------------------------------------
+
+\documentclass[
+	layoutmode=cover,
+	spinewidth=20mm,
+	spinefold=7mm,
+	coverboardgrow=3mm,
+	coverflap=17mm,
+	% page size...
+	blockwidth=240mm, blockheight=220mm,
+	bleed=4mm,
+	bindingoffset=5mm,
+	% image block configuration...
+	imageblockwidth=0.98, imageblockheight=0.98,
+	imageblockoffsettop=-0.1,
+	% misc...
+	9pt,final,openany
+]{photobook}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\begin{document}
+
+\GenerateTemplate
+
+\end{document}
+
+
+%----------------------------------------------------------------------
+%                                                  vim:set ts=4 sw=4 :

examples/cover.tex

@@ -21,7 +21,40 @@
 
 \begin{document}
 
-\GenerateTemplate
+\begin{page}
+	\begin{frontcover}
+        % NOTE: in the real world there is no need to extend the bleeds
+        %       all the way to the end of the flaps, they need to go
+        %       only 2-4 millimeters under the endpaper to account for
+        %       cut and alignment errors...
+        \begin{cliptocell}[0mm {\coverflap} {\coverflap} {\coverflap}]
+			\imagecell[fill, clearance=-\coverflap]{}{landscape}
+			% title...
+			\begin{zinlinecell}
+				\begin{center}
+					\vfill
+					\color{white}
+					\Huge TITLE TEXT
+					\vfill
+				\end{center}
+			\end{zinlinecell}
+		\end{cliptocell}
+	\end{frontcover}
+	\begin{spine}
+		\begin{cliptocell}[0mm \coverflap]
+			\imagecell[fill, clearance=-\coverflap]{}{landscape}
+		\end{cliptocell}
+	\end{spine}
+	\begin{backcover}
+        \begin{cliptocell}[{\coverflap} {\coverflap} 0mm {\coverflap}]
+			\imagecell[fill, clearance=-\coverflap]{}{landscape}
+		\end{cliptocell}
+	\end{backcover}
+
+	\textblockrulecolour{white}
+	\textcolor{white}
+	\GenerateTemplate
+\end{page}
 
 \end{document}
 

examples/custom-spread.tex

@@ -37,7 +37,7 @@
 	\end{inlinecell}%
 	\hspace{\textblockmargin}%
 	\begin{inlinecell}{0.75\cellwidth - \textblockmargin + \bleed}{\cellheight}%
-		\imagecell[fill]{}{DSC00403-2}%
+		\imagecell[fill]{}{landscape}%
 	\end{inlinecell}
 \end{spreadtopages}
 
@@ -45,7 +45,7 @@
 \begin{spreadtopages}%
 	\hspace{-\bleed}%
 	\begin{inlinecell}{0.75\cellwidth - \textblockmargin + \bleed}{\cellheight}%
-		\imagecell[fill]{}{DSC00403-2}%
+		\imagecell[fill]{}{landscape}%
 	\end{inlinecell}%
 	\hspace{\textblockmargin}%
 	\begin{inlinecell}{0.25\cellwidth}{\cellheight}%

examples/demo.tex

@@ -5,7 +5,8 @@
 	% page size...
 	blockwidth=240mm, blockheight=220mm,
 	bleed=4mm,
-	bindingoffset=5mm,
+	gutteroffset=5mm,
+	bindingoffset=0mm,
 	% image block configuration...
 	imageblockwidth=0.98, imageblockheight=0.98,
 	imageblockoffsettop=0,
@@ -27,8 +28,8 @@
 
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-\edef\TestImage{DSC00403-2}
-\edef\TestImageV{DSC00403-2vert}
+\edef\TestImage{landscape}
+\edef\TestImageV{portrait}
 
 
 \newcommand\Chapter[1]{

examples/endpaper-template.tex

@@ -0,0 +1,27 @@
+%----------------------------------------------------------------------
+
+\documentclass[
+	layoutmode=endpaper,
+	% page size...
+	blockwidth=240mm, blockheight=220mm,
+	bleed=4mm,
+	bindingoffset=5mm,
+	% image block configuration...
+	imageblockwidth=0.98, imageblockheight=0.98,
+	imageblockoffsettop=-0.1,
+	% misc...
+	9pt,final,openany
+]{photobook}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\begin{document}
+
+\GenerateTemplate
+
+\end{document}
+
+
+%----------------------------------------------------------------------
+%                                                  vim:set ts=4 sw=4 :

examples/endpaper.tex

@@ -14,14 +14,52 @@
 ]{photobook}
 
 
+\begin{document} % - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+% the simplest way to fill...
+\ImagePageFill{}{landscape}
+
+
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-\begin{document}
+% manual...
+% NOTE: to fill the page the image cell needs to be placed relative to
+% 		the page (papercell / pagecell) and not the text (page env)
+\begin{page}
+\begin{papercell}
+	\imagecell[fill, clearance=-\bleed]{}{landscape}
+\end{papercell}
+\end{page}
+
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+% control #1 -- works fine...
+\begin{page}
+\begin{leftside}
+	\imagecell[fit]{}{landscape}
+\end{leftside}
+\begin{rightside}
+	\imagecell[fit]{}{landscape}
+\end{rightside}
+\end{page}
+
+
+\begin{page}
+\begin{leftside}
+	\imagecell[fill, right, clearance=\cliptocellclearances]{}{landscape}
+\end{leftside}
+\begin{rightside}
+	\imagecell[fill, left, clearance=\cliptocellclearances]{}{landscape}
+\end{rightside}
+\end{page}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
 \GenerateTemplate
 
-\end{document}
 
-
-%----------------------------------------------------------------------
-%                                                  vim:set ts=4 sw=4 :
+\end{document} %-------------------------------------------------------
+%												   vim:set ts=4 sw=4 :

examples/images/Johannes Vermeer - The Girl With The Pearl Earring (1665).svg

@@ -0,0 +1,130 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   version="1.1"
+   id="svg1"
+   width="3840"
+   height="5495"
+   viewBox="0 0 3840 5495"
+   sodipodi:docname="Johannes Vermeer - The Girl With The Pearl Earring (1665).svg"
+   inkscape:version="1.4.2 (ebf0e940d0, 2025-05-08)"
+   inkscape:export-filename="Johannes Vermeer - The Girl With The Pearl Earring (1665).png"
+   inkscape:export-xdpi="50"
+   inkscape:export-ydpi="50"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <defs
+     id="defs1">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath2">
+      <path
+         style="fill:none;stroke:#ffffff;stroke-width:15.1181;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         d="M 1920,0 0,2747.5 1920,5495 3840,2747.5 Z"
+         id="path3" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath6">
+      <rect
+         style="fill:none;stroke:#ffffff;stroke-width:60.4724;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         id="rect7"
+         width="500"
+         height="500"
+         x="318.06506"
+         y="257.89059" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="namedview1"
+     pagecolor="#ffffff"
+     bordercolor="#000000"
+     borderopacity="0.25"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     showguides="true"
+     inkscape:zoom="0.11632839"
+     inkscape:cx="1916.9868"
+     inkscape:cy="2750.8331"
+     inkscape:window-width="2048"
+     inkscape:window-height="1115"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="g1" />
+  <g
+     inkscape:groupmode="layer"
+     inkscape:label="Image"
+     id="g1">
+    <image
+       width="3840"
+       height="5495"
+       preserveAspectRatio="none"
+       xlink:href="Johannes%20Vermeer%20-%20The%20Girl%20With%20The%20Pearl%20Earring%20(1665).jpg"
+       id="image1"
+       sodipodi:insensitive="true"
+       style="display:inline" />
+    <g
+       id="g5"
+       inkscape:label="large diamond">
+      <path
+         style="fill:none;stroke:#000000;stroke-width:60.47244094;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke;stroke-linejoin:miter;stroke-miterlimit:10;stroke-linecap:square"
+         d="M 1920,0 0,2747.5 1920,5495 3840,2747.5 Z"
+         id="path1"
+         clip-path="none"
+         inkscape:label="black diamond" />
+      <path
+         style="fill:none;stroke:#ffffff;stroke-width:30.23622047;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke;stroke-linejoin:miter;stroke-miterlimit:10;stroke-linecap:square"
+         d="M 1920,0 0,2747.5 1920,5495 3840,2747.5 Z"
+         id="path4"
+         clip-path="url(#clipPath2)"
+         inkscape:label="white diamond" />
+    </g>
+    <g
+       id="g9"
+       inkscape:label="small diamond">
+      <rect
+         style="fill:none;stroke:#000000;stroke-width:60.4724;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         id="rect8"
+         width="500"
+         height="500"
+         x="250"
+         y="-250"
+         clip-path="none"
+         transform="rotate(45)" />
+      <rect
+         style="fill:none;stroke:#ffffff;stroke-width:60.4724;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         id="rect5"
+         width="500"
+         height="500"
+         x="318.06506"
+         y="257.89059"
+         clip-path="url(#clipPath6)"
+         transform="rotate(45,647.11071,171.7835)" />
+    </g>
+    <use
+       x="0"
+       y="0"
+       xlink:href="#g9"
+       id="use9"
+       transform="translate(3132.8932)" />
+    <use
+       x="0"
+       y="0"
+       xlink:href="#g9"
+       id="use10"
+       transform="translate(3132.8932,4787.8932)" />
+    <use
+       x="0"
+       y="0"
+       xlink:href="#g9"
+       id="use11"
+       transform="translate(2.0565886e-5,4789.4527)" />
+  </g>
+</svg>

examples/images/Katsushika Hokusai - The Great Wave off Kanagawa.svg

@@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   version="1.1"
+   id="svg1"
+   width="2000"
+   height="1350"
+   viewBox="0 0 2000 1350"
+   sodipodi:docname="Katsushika Hokusai - The Great Wave off Kanagawa.svg"
+   inkscape:version="1.4.2 (ebf0e940d0, 2025-05-08)"
+   inkscape:export-filename="Katsushika Hokusai - The Great Wave off Kanagawa.png"
+   inkscape:export-xdpi="96"
+   inkscape:export-ydpi="96"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <defs
+     id="defs1">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath6">
+      <rect
+         style="fill:none;stroke:#ffffff;stroke-width:60.4724;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         id="rect7"
+         width="500"
+         height="500"
+         x="318.06506"
+         y="257.89059" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1">
+      <rect
+         style="fill:none;stroke:#ffffff;stroke-width:60.4724;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         id="rect1"
+         width="500"
+         height="500"
+         x="318.06506"
+         y="257.89059" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath3">
+      <rect
+         style="fill:none;stroke:#ffffff;stroke-width:60.4724;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         id="rect3"
+         width="500"
+         height="500"
+         x="318.06506"
+         y="257.89059" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath4">
+      <path
+         style="fill:none;stroke:#ffffff;stroke-width:15.1181;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         d="M 1920,0 0,2747.5 1920,5495 3840,2747.5 Z"
+         id="path3" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath5">
+      <use
+         x="0"
+         y="0"
+         xlink:href="#g2"
+         id="use5" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="namedview1"
+     pagecolor="#ffffff"
+     bordercolor="#000000"
+     borderopacity="0.25"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:zoom="0.66962963"
+     inkscape:cx="1000.5531"
+     inkscape:cy="675"
+     inkscape:window-width="2048"
+     inkscape:window-height="1115"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="g1" />
+  <g
+     inkscape:groupmode="layer"
+     inkscape:label="Image"
+     id="g1">
+    <image
+       width="2000"
+       height="1350"
+       preserveAspectRatio="none"
+       xlink:href="Katsushika%20Hokusai%20-%20The%20Great%20Wave%20off%20Kanagawa.jpg"
+       id="image1"
+       style="display:inline" />
+    <g
+       id="g5"
+       inkscape:label="large diamond"
+       transform="matrix(0.52086102,0,0,0.24566116,-0.05316214,0.04597332)"
+       style="display:inline">
+      <path
+         style="display:inline;fill:none;stroke:#000000;stroke-width:60.4724;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         d="M 1920,0 0,2747.5 1920,5495 3840,2747.5 Z"
+         id="path1"
+         clip-path="none"
+         inkscape:label="black" />
+      <g
+         id="g3"
+         clip-path="url(#clipPath5)"
+         inkscape:label="white"
+         style="display:inline">
+        <g
+           inkscape:label="Clip"
+           id="g2">
+          <path
+             style="display:inline;fill:none;stroke:#ffffff;stroke-width:30.2362;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+             d="M 1920,0 0,2747.5 1920,5495 3840,2747.5 Z"
+             id="path4"
+             clip-path="none"
+             inkscape:label="white diamond" />
+        </g>
+      </g>
+    </g>
+    <g
+       id="g9"
+       inkscape:label="small diamond"
+       transform="matrix(0.31062245,0,0,0.31062245,3.6225648,2.1883219)"
+       style="display:inline">
+      <rect
+         style="fill:none;stroke:#000000;stroke-width:60.4724;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         id="rect8"
+         width="500"
+         height="500"
+         x="250"
+         y="-250"
+         clip-path="none"
+         transform="rotate(45)" />
+      <rect
+         style="fill:none;stroke:#ffffff;stroke-width:60.4724;stroke-linecap:square;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1;paint-order:markers fill stroke"
+         id="rect5"
+         width="500"
+         height="500"
+         x="318.06506"
+         y="257.89059"
+         clip-path="url(#clipPath6)"
+         transform="rotate(45,647.11071,171.7835)" />
+    </g>
+    <use
+       x="0"
+       y="0"
+       xlink:href="#g9"
+       id="use9"
+       transform="translate(1776.7342,-2.1240179)" />
+    <use
+       x="0"
+       y="0"
+       xlink:href="#g9"
+       id="use10"
+       transform="translate(1776.7342,1128.1684)" />
+    <use
+       x="0"
+       y="0"
+       xlink:href="#g9"
+       id="use11"
+       transform="translate(-3.6225648,1128.1684)"
+       style="display:inline" />
+  </g>
+</svg>

examples/jacket.tex

@@ -24,18 +24,18 @@
 
 \begin{page}
 	\begin{frontcover}
-		\begin{cliptocell}
-			\imagecell[fill]{}{DSC00403-2}
+        \begin{cliptocell}[0mm \bleed]
+			\imagecell[fill, clearance=-\bleed]{}{landscape}
 		\end{cliptocell}
 	\end{frontcover}
 	\begin{backcover}
-		\begin{cliptocell}
-			\imagecell[fill]{}{DSC00403-2}
+        \begin{cliptocell}[0mm \bleed]
+			\imagecell[fill, clearance=-\bleed]{}{landscape}
 		\end{cliptocell}
 	\end{backcover}
 	\begin{spine}
-		\begin{cliptocell}
-			\imagecell[fill]{}{DSC00403-2}
+        \begin{cliptocell}[0mm \bleed]
+			\imagecell[fill, clearance=-\bleed]{}{landscape}
 		\end{cliptocell}
 	\end{spine}
 	\begin{frontflap}

examples/spread generation/Makefile

@@ -15,7 +15,7 @@
 MAKESPREADS := ../../scripts/make-spreads.sh
 
 
-spreads.tex: spreads
+spreads.tex: spreads $(wildcard spreads/*/*)
 	$(MAKESPREADS) $< $(SPREAD) > $@
 
 dist:

examples/spread generation/spreads/06-maual-layout/layout.tex

@@ -0,0 +1,6 @@
+
+Manual template
+
+\newpage
+
+\ImagePage{${CAPTION}}{${IMAGE}}

examples/spread generation/templates/fullbleed.tex

@@ -0,0 +1 @@
+\ImageSpreadFill{${CAPTION}}{${IMAGE0}}

examples/spread-as-background.tex

@@ -19,8 +19,8 @@
 
 \setlength\parindent{0pt}
 
-\edef\TestImage{DSC00403-2}
-\edef\TestImageV{DSC00403-2vert}
+\edef\TestImage{landscape}
+\edef\TestImageV{portrait}
 
 \writeimagelistfalse
 

examples/test.tex

@@ -19,8 +19,8 @@
 
 \setlength\parindent{0pt}
 
-\edef\TestImage{DSC00403-2}
-\edef\TestImageV{DSC00403-2vert}
+\edef\TestImage{landscape}
+\edef\TestImageV{portrait}
 
 \writeimagelistfalse
 

examples/text-image-spread.tex

@@ -0,0 +1,44 @@
+%----------------------------------------------------------------------
+
+\documentclass[
+	layoutmode=block,
+	% page size...
+	blockwidth=240mm, blockheight=220mm,
+	bleed=4mm,
+	gutteroffset=5mm,
+	bindingoffset=0mm,
+	% image block configuration...
+	imageblockwidth=0.98, imageblockheight=0.98,
+	imageblockoffsettop=0,
+	% misc...
+	9pt,final,openany
+]{photobook}
+
+\usepackage{lipsum}
+\usepackage{ragged2e}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\edef\TestImage{landscape}
+
+
+
+%----------------------------------------------------------------------
+\begin{document}
+
+% force what's next to left page of spread...
+\cleartoleftpage
+
+% text...
+\begin{page}
+	\lipsum[1-3]
+\end{page}
+
+% image...
+\ImagePage{}{\TestImage}
+
+
+
+%----------------------------------------------------------------------
+\end{document} %                                    vim:set ts=4 sw=4 :

examples/two-image-page.tex

@@ -19,8 +19,8 @@
 
 \setlength\parindent{0pt}
 
-\edef\TestImage{DSC00403-2}
-\edef\TestImageV{DSC00403-2vert}
+\edef\TestImage{landscape}
+\edef\TestImageV{portrait}
 
 \writeimagelistfalse
 

scripts/README.md

@@ -4,9 +4,9 @@ Support scripts
 
 <!-- TOC depthfrom:2 -->
 
-- [make-spreads.sh](#make-imagessh)
-	- [The process](#the-process)
-		- [Automatic template inferenceing](#automatic-template-inferenceing)
+- [make-spreads.sh](#make-spreadssh)
+	- [Theory of operation](#theory-of-operation)
+		- [Automatic template inferencing](#automatic-template-inferencing)
 		- [Manual template selection](#manual-template-selection)
 		- [Template tweaking](#template-tweaking)
 		- [Manual spread layouts](#manual-spread-layouts)
@@ -50,7 +50,7 @@ book/
 │   ├── image-image.tex
 │   ├── fullbleed.tex
 │   └── ...
-├── spreads/  . . . . . . . . . . . . . . Main block layout.
+├── spreads/  . . . . . . . . . . . . . Main block layout.
 │   ├── 00/ . . . . . . . . . . . . . . A basic spread.
 │   │   ├── tweaks.tex                  The spread template is built
 │   │   └── 0-DSC02432.jpg              automatically with tweaks.tex
@@ -77,23 +77,22 @@ book/
 ├── block.tex . . . . . . . . . . . . . Block skeletal layout.
 │                                       This usually includes the titles, 
 │                                       technical pages and sources the
-│                                       ./block-pages.tex.
-├── block-pages.tex . . . . . . . . . . The generated block content.
+│                                       ./block-spreads.tex.
+├── block-spreads.tex . . . . . . . . . The generated block content.
 ├── cover.tex . . . . . . . . . . . . . Cover layout.
 ├── jacket.tex  . . . . . . . . . . . . Dust jacket layout.
 └── ...
 ```
 
-<!-- XXX
-For a live example see: ../examples/book -->
+For a full example see: ../examples/book
 
 Generate the block:
 ```shell
-$ make-spreads.sh ./pages > block-pages.tex
+$ make-spreads.sh ./spreads > block-spreads.tex
 ```
 
 Note that `make-spreads.sh` does not force a specific layout outside of 
-the `pages` directory, all paths are configurable. The way the root 
+the `spreads` directory, all paths are configurable. The way the root 
 files are structured in this example is just one way to organize a 
 book's source code with minimal code duplication.
 
@@ -104,7 +103,7 @@ $ make-spreads.sh --help
 ```
 
 
-### The process
+### Theory of operation
 
 <!-- XXX spreads vs. pages -->
 
@@ -121,24 +120,24 @@ work is starting to look like a book.
 When starting work on a layout it is good to at least have a basic
 understanding of the book's:
 - structure and how it may change,
-- core templates,
+- general look (i.e. core templates),
 - exceptions from the above.
 
 In most cases all of the above will change in one way or another during
 the project's lifespan, and the main goal of this stage is to make this 
-change as simple as possible -- it's all about providing the freedom to 
-make changes instead of growing work invested and thus making change 
-more and more expensive.
+change as efgortless as possible -- it's all about providing the freedom 
+to make changes instead of growing the work invested and thus making 
+change more and more expensive.
 
 The first question is what is the _structure_ of the book we are making?
 Will it have chapters? How many? Text? how much, how should it be 
-structured? How are we going to deal with the title? How are we going 
+placed? How are we going to deal with the title? How are we going 
 to present the images, full bleed, no bleeds, small, big, one per page 
-or multiple images, ...etc.? At this stage this is about the presentation 
+or multiples, ...etc.? At this stage this is about the presentation, 
 the flow of the work and not about the actual design. How many typical 
 spreads (i.e. spread templates) should it have? A good number should be 
 small-ish, for example 3-4 spread templates is a good number, if you 
-count 10+ then you might be overcomplicating tings, but note, there are 
+count 10+ then you might be overcomplicating things, but note, there are 
 no rules, a book where each spread is individually and manually layed out 
 may work as well as a book with just a single template spread, but in 
 general for a photo book the focus is on the project and the layout 
@@ -196,7 +195,18 @@ If only one image/text file is provided then `make-spreads.sh` will set it
 on the right page of the spread using the appropriate page template and
 leave the left page blank.
 
-<!-- XXX do we need a `blankpage.tex` template??? -->
+A black page uses `blankpage.tex` template if available, otherwise a
+trivial blank page is used:
+```latex
+\null
+\newpage
+```
+
+<!-- XXX
+Template search order:
+- spread directory
+- template directory
+-->
 
 
 #### Manual template selection
@@ -250,6 +260,8 @@ If `layout.tex` is present it will be included as the page layout/template.
 Any paths in the `layout.tex` should be relative to the location the
 built block .tex file will be located, usually to the project root.
 
+Template field substitution is done as for all other templates.
+
 
 ### Templates
 
@@ -298,7 +310,7 @@ environment variable.
 
 Inline captions are also supported:
 ```bnf
-pages/
+spreads/
 ├── <spread>/
 │   ├── ...
 │   ├── 00-<image-name>.<ext>
@@ -332,6 +344,8 @@ IMAGE_FORMATS=jpeg|jpg|png|pdf|svg|eps
 SPREADS_DIR=spreads/
 
 # if non-empty link link images to matching ones from this directory...
+# NOTE: this is ignored if --graphicx-path is passed or GRAPHICX_PATH 
+#		is set.
 IMAGE_HIRES_DIR=
 
 # directory where external captions are stored...
@@ -358,6 +372,10 @@ IMAGE_SPREAD=(
         [0]=text-spread
         [2]=image-image
 )
+
+# if set (or --graphicx-path is passed) the images are identified by their
+# basename so as to let graphicx package resolve the paths internally.
+GRAPHICX_PATH=1
 ```
 
 An explicit configuration file can be manually specified:
@@ -374,11 +392,19 @@ $ make-spreads.sh -c <path> ..
 Extract the documentation from photobook.cls which is used to build the 
 photobook.pdf reference manual.
 
+This makes it possible to keep the documentation and code it describes
+in the same place/file.
+
+The format is in part inspired by LaTeX's [.dtx](http://tug.ctan.org/info/dtxtut/dtxtut.pdf) 
+format but is far simpler and retains human readability with less effort.
+
+
 ```shell
 $ cls2tex.sh --help
 ```
 
 The `--help` says it all:
+<!-- :r !cl2tex.sh --help -->
 ```
 Generate docs from latex package/class
 
@@ -396,8 +422,8 @@ This will:
   - read the INPUT
   - keep lines starting with \def\<module-name>@[A-Z]\+
   - keep lines starting with '%%'
-  - %%%%% Text -> \subsection(Text)
-  - %%%% Text -> \section(Text)
+  - %%%%% Text -> \subsection{Text}
+  - %%%% Text -> \section{Text}
   - %% >> code -> \begin{verbatim}code\end{verbatim}
   - write the result to OUTPUT
 
@@ -424,4 +450,4 @@ NOTE: the idea of keeping latex docs in a latex file is far simpler
       in both the repo and in installed form, so .dtx is not used.
 ```
 
-
+<!-- vim:set ts=4 sw=4 nowrap : -->

scripts/cls2tex.sh

@@ -26,8 +26,8 @@ printhelp(){
 	echo "  - read the INPUT"
 	echo "  - keep lines starting with \\def\\<module-name>@[A-Z]\\+"
 	echo "  - keep lines starting with '%%'"
-	echo "  - %%%%% Text -> \\subsection(Text)"
-	echo "  - %%%% Text -> \\section(Text)"
+	echo "  - %%%%% Text -> \\subsection{Text}"
+	echo "  - %%%% Text -> \\section{Text}"
 	echo "  - %% >> code -> \\begin{verbatim}code\\end{verbatim}"
 	echo "  - write the result to OUTPUT"
 	echo
@@ -54,13 +54,6 @@ printhelp(){
 	echo "      in both the repo and in installed form, so .dtx is not used."
 }
 
-# Usage: printerror MESSAGE...
-printerror(){
-	echo Error: $@
-	echo
-	printusage
-}
-
 # Usage: printmsg TEXT
 printmsg(){
 	# print message...
@@ -88,21 +81,23 @@ while true ; do
 			;;
 		-p|--prefix)
 			PREFIX=$2
-			shift
-			shift
+			shift 2
+			continue
 			;;
 		-s|--strip)
 			STRIP_DOC=1
 			shift
+			continue
 			;;
 		-n|--no-msg)
 			NO_MSG=1
 			shift
+			continue
 			;;
 
 		# handle unknown options...
 		-*|--*)
-			printerror "unknown option \"$1\""
+			echo "Error: unknown option: \"$1\"" >&2
 			exit
 			;;
 
@@ -131,7 +126,7 @@ if [ -z $STRIP_DOC ] ; then
 	printmsg "Documentation" \
 		> "$OUTPUT"
 	cat "$INPUT" \
-		| egrep '(^%'$PREFIX'|^\\edef\\'$MODULE'@[A-Z][A-Z]+)' \
+		| grep -E '(^%'$PREFIX'|^\\edef\\'$MODULE'@[A-Z][A-Z]+)' \
 		| sed \
 			-e 's/^\(\\edef\\\)'$MODULE'@/%'$PREFIX'\1/' \
 			-e 's/%'$PREFIX'%%%% \(.*\)/%'$PREFIX'\\subsubsection{\1}\\label{subsubsec:\1}/' \
@@ -146,8 +141,8 @@ else
 	printmsg "Stripped code" \
 		> "$OUTPUT"
 	cat "$INPUT" \
-		| egrep -v '%'$PREFIX'' \
-		| egrep -v '^(\s*%)?\s*$' \
+		| grep -Ev '%'$PREFIX'' \
+		| grep -Ev '^(\s*%)?\s*$' \
 		>> "$OUTPUT"
 fi
 

scripts/make-spreads.sh

@@ -1,76 +1,16 @@
-#!/bin/bash
+#!/usr/bin/env bash
 shopt -s nullglob extglob
 
 #----------------------------------------------------------------------
-# 
-# TIP: It is better to think of a visual book as a set of spreads 
-#		rather than a set of pages, hence the focus on spreads in the 
-#		code below.
-#		The main unit of a "visual" book is a spread, it's the thing 
-#		you see when you hold the book open, and the main workflow 
-#		when building a book is creating spreads and ordering them so 
-#		a single page is almost never treated as an independent unit.
-# TIP: it is not recommended to use too many templates, the layout 
-#		should be and feel structured and this structure should not be 
-#		too complex for the average reader to get comfortable in.
-# 
+#
+# For docs see README.md
+#
 #
 # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-# 
-# Template structure:
-#	$TEMPLATE_DIR/
-#		spread.tex
-#		imagepage.tex
-#		textpage.tex
-#		...
-#	$CAPTION_DIR/
-#		<image>.txt
-#			image caption.
-#			this is separated to decouple caption writing from the 
-#			changes to the layout/sequencing and this drastically 
-#			simplify the work with writers.
-#			For this reason this takes priority over local captions (XXX revise).
-#		...
-#	$SPREADS_DIR/
+#
+# XXX DOC:
 #		$spread/
-#			tweaks.tex
-#				template tweaks.
-#				loaded before the templates are handled.
-#			layout.tex
-#				manual layout of spread.
-#				if given rest of directory contents are 
-#				ignored.
-#				fields:
-#					${IMAGE0}
-#						replaced with image path
-#					${CAPTION0}
-#						replaced with content of caption file if found
-#						and empty otherwise.
-#					${TEXT0}
-#						replaced with the content of a text file if 
-#						found and empty otherwise.
-#					...
-#				NOTE: if images are included, hi-res source
-#					substitution is not done here.
-#				NOTE: fields are ordered and matched according to their
-#					position and not their number, e.g. in the following 
-#					sequence:
-#						IMAGE, IMAGE10, IMAGE20, ..,
-#						CAPTION2, CAPTION7, CAPTION12, ..
-#					IMAGE10 will be filled with the second found image 
-#					and CAPTION7 will be filled with the second found 
-#					caption.
-#			<spread-template-name>.tpl
-#				indicates the spread template to use.
-#				if given the rest of the .tex files in 
-#				directory are ignored.
-#				resolves to:
-#					templates/<spread-template-name>.tex
-#				fields:
-#					${IMAGE0}
-#					${CAPTION0}
-#					${TEXT0}
-#					...
+#			...
 #			imagepage.tex
 #				image page template.
 #				fields:
@@ -87,46 +27,7 @@ shopt -s nullglob extglob
 #			<spread-template-name>-textpage.tpl
 #				indicates the image/text page template to use.
 #				ignored if explicit templates are given.
-#				fields:
-#					${IMAGE}
-#					${CAPTION}
-#					${TEXT}
-#					...
-#			00-<image>.png
-#				image.
-#				if $IMAGE_HIRES_DIR is set then this will 
-#				resolve to:
-#					$IMAGE_HIRES_DIR/<image>
-#				supported formats:
-#					.jpeg, .png, .pdf, .svg, .eps 
-#					(see $IMAGE_FORMATS)
-#			00-<image>.txt
-#				local image caption text.
-#				NOTE: this must be named the same as the image.
-#			01-<text>.txt
-#				text.
 #			...
-#		...
-#
-#
-# Env variables:
-#	ANOTATE_IMAGE_PATHS=
-#	TEXT_FORMATS=<ext>|..
-#	IMAGE_FORMATS=<ext>|..
-#	SPREADS_DIR=<path>
-#	IMAGE_HIRES_DIR=<path>
-#		sets the path to which the hi-res images are resolved.
-#	CAPTION_DIR=<path>
-#	TEMPLATE_DIR=<path>
-#	EMPTY_PAGE=<name>
-#	TEXT_PAGE=<name>
-#	IMAGE_PAGE=<name>
-#	IMAGE_SPREAD=<array>
-#
-#
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-#
-# XXX 
 #
 #
 #
@@ -155,9 +56,11 @@ ANOTATE_IMAGE_PATHS=${ANOTATE_IMAGE_PATHS:=}
 # supported formats/extensions...
 TEXT_FORMATS=${TEXT_FORMATS:=$CFG_TEXT_FORMATS}
 TEXT_FORMATS=${TEXT_FORMATS:=txt}
+TEXT_FORMATS=${TEXT_FORMATS,,}
 
 IMAGE_FORMATS=${IMAGE_FORMATS:=$CFG_IMAGE_FORMATS}
 IMAGE_FORMATS=${IMAGE_FORMATS:=jpeg|jpg|png|pdf|svg|eps}
+IMAGE_FORMATS=${IMAGE_FORMATS,,}
 
 
 SPREADS_DIR=${SPREADS_DIR:=$CFG_SPREADS_DIR}
@@ -190,7 +93,7 @@ IMAGE_PAGE=${IMAGE_PAGE:=imagepage}
 # NOTE: the index here corresponds to the number of images found in a 
 #		spread directory...
 if [ ${#IMAGE_SPREAD[@]} = 0 ] ; then
-	if ! [ ${#CFG_IMAGE_SPREAD[@]} = 0 ] ; then
+	if [ ${#CFG_IMAGE_SPREAD[@]} != 0 ] ; then
 		IMAGE_SPREAD=()
 		for i in ${!CFG_IMAGE_SPREAD[@]} ; do
 			IMAGE_SPREAD[$i]=${CFG_IMAGE_SPREAD[$i]}
@@ -229,6 +132,9 @@ printhelp(){
 	echo "              - text spread default template (default: ${IMAGE_SPREAD[0]})."
 	echo "  --captions PATH"
 	echo "              - path to search for captions (default: $CAPTION_DIR)."
+	echo "  --graphicx-path"
+	echo "              - reference images by their basenames and let graphicx manage"
+	echo "                searching."
 	echo
 	echo "Parameters:"
 	echo "  PATH        - path to root pages directory (default: $SPREADS_DIR)"
@@ -276,38 +182,50 @@ while true ; do
 		-a|--annotate)
 			ANOTATE_IMAGE_PATHS=1
 			shift
+			continue
 			;;
 		-c)
 			$CONFIG="$2"
 			[ -e "$CONFIG" ] \
 				&& source "$CONFIG"
 			shift 2
+			continue
 			;;
 
 		--templates)
 			TEMPLATE_DIR=$2
 			shift 2
+			continue
 			;;
 		--single-image-tpl)
 			IMAGE_SPREAD[1]=$2
 			shift 2
+			continue
 			;;
 		--double-image-tpl)
 			IMAGE_SPREAD[2]=$2
 			shift 2
+			continue
 			;;
 		--text-spread-tpl)
 			IMAGE_SPREAD[0]=$2
 			shift 2
+			continue
 			;;
 		--captions)
 			CAPTION_DIR=$2
 			shift 2
+			continue
+			;;
+		--graphicx-path)
+			GRAPHICX_PATH=1
+			shift
+			continue
 			;;
 
 		# handle unknown options...
 		-*|--*)
-			echo "Error: unknown option \"$1\""
+			echo "Error: unknown option \"$1\"" >&2
 			exit
 			;;
 
@@ -378,24 +296,44 @@ readCaption(){
 #	getTemplate SPREAD TYPE
 #
 getTemplate(){
-	local SPREAD=$1
-	local TYPE=$2
-	local TEMPLATE=($SPREAD/*-$TYPE.tex)
-	if [ -z $TEMPLATE ] ; then
-		TEMPLATE=($SPREAD/*-$TYPE.tpl)
-		if ! [ -z $TEMPLATE ] ; then
-			TEMPLATE=${TEMPLATE/$SPREAD\//}
-			TEMPLATE=${TEMPLATE/[0-9]-/}
-			TEMPLATE="$TEMPLATE_DIR/${TEMPLATE[0]%-${TYPE}.*}.tex"
+	local spread=$1
+	local name=$2
+	local template
+
+	if [[ $name =~ .*\.tex ]] ; then 
+		# already an existing template...
+		if [ -e "$name" ] ; then
+			echo $name
+			return
 		fi
+		# normalize...
+		name=${name%.tex}
+	# normalize template name...
+	elif [[ $name =~ .*\.tpl ]] ; then
+		name=$( echo $name \
+			| sed \
+				-e 's/.tpl$//' \
+				-e "s%$spread/%%" \
+				-e 's/^[0-9]\+-//' )
 	fi
-	if [ -z $TEMPLATE ] ; then
-		 TEMPLATE="$TEMPLATE_DIR/${TYPE}.tex"
+
+	# local template...
+	template=($spread/*-$name.tex)
+	if [ ${#template[@]} != 0 ] ; then
+		template=${template[0]}
+	else
+		template=($spread/$name.tex)
 	fi
-	if ! [ -e $TEMPLATE ] ; then
-		return
+	# global template...
+	if [ -z $template ] \
+			|| ! [ -e "$template" ] ; then
+		 template="$TEMPLATE_DIR/${name}.tex"
 	fi
-	echo $TEMPLATE
+	# check if the thing exists...
+	if ! [ -e $template ] ; then
+		return 1
+	fi
+	echo $template
 }
 
 
@@ -420,6 +358,12 @@ templateSlots(){
 # usage:
 #	populateTemplate SPREAD TEMPLATE ITEMS...
 #
+# closure: $populateTemplate_img, $populateTemplate_txt
+#
+# NOTE: this is the least hacky/ugly but could not figure out a better 
+#		way to update a list from within a function...
+populateTemplate_img=
+populateTemplate_txt=
 populateTemplate(){
 	local spread="$1"
 	local tpl="$2"
@@ -438,12 +382,22 @@ populateTemplate(){
 	local txt=()
 	local elem
 	for elem in "${items[@]}" ; do
-		if [[ "$elem" =~ $IMAGE_FORMATS ]] ; then
+		if [[ "${elem,,}" =~ $IMAGE_FORMATS ]] ; then
 			img+=("$elem")
-		elif [[ "$elem" =~ $TEXT_FORMATS ]] ; then
+		elif [[ "${elem,,}" =~ $TEXT_FORMATS ]] ; then
 			txt+=("$elem")
 		fi
 	done
+	local global_img=
+	if ! [ -z $populateTemplate_img ] ; then 
+		global_img=1
+		img=(${populateTemplate_img[@]})
+	fi
+	local global_txt=
+	if ! [ -z $populateTemplate_txt ] ; then
+		global_txt=1
+		txt=(${populateTemplate_txt[@]})
+	fi
 
 	local var
 	local val
@@ -459,7 +413,7 @@ populateTemplate(){
 	local i=0
 	for var in ${slots[@]} ; do
 		name=${var//[0-9]/}
-		if ! [ ${name} = "IMAGE" ] ; then
+		if [ ${name} != "IMAGE" ] ; then
 			continue
 		fi
 
@@ -479,14 +433,17 @@ populateTemplate(){
 		i=$(( i + 1 ))
 
 		val=${val//\//\\/}
-		text=$(echo -e "${text}" | \
+		text=$(echo "${text}" | \
 			sed "s/\${${var}}/${val%.*}/g")
 	done
+	if ! [ -z $global_img ] ; then
+		populateTemplate_img=("${populateTemplate_img[@]:$i}")
+	fi
 
 	# pass 2: captions...
 	for var in ${slots[@]} ; do
 		name=${var//[0-9]/}
-		if ! [ ${name} = "CAPTION" ] ; then
+		if [ ${name} != "CAPTION" ] ; then
 			continue
 		fi
 
@@ -502,7 +459,7 @@ populateTemplate(){
 			val=$(readCaption "${val}")
 		fi
 
-		text=$(echo -e "${text}" | \
+		text=$(echo "${text}" | \
 			sed "s/\${${var}}/${val}/g")
 	done
 
@@ -523,14 +480,17 @@ populateTemplate(){
 		done
 
 		val=${val//\//\\/}
-		text=$(echo -e "${text}" | \
+		text=$(echo "${text}" | \
 			sed "s/\${${var}}/${val}/g")
 	done
+	if ! [ -z $global_txt ] ; then
+		populateTemplate_txt=("${txt[@]}")
+	fi
 
 	# print out the filled template...
 	echo % template: $tpl
-	echo -e "${text}"
-	return 0
+	echo "${text}"
+	return
 }
 
 
@@ -538,7 +498,7 @@ populateTemplate(){
 # usage:
 #	handleSpread SPREAD
 #
-# closure: $IMAGE_HIRES_DIR, $IMAGE_SPREAD
+# closure: $GRAPHICX_PATH, $IMAGE_HIRES_DIR, $IMAGE_SPREAD
 handleSpread(){
 	local spread="$1"
 	# skip non-spreads...
@@ -563,30 +523,41 @@ handleSpread(){
 	local txt=()
 	local items=()
 	for elem in "$spread"/* ; do
-		if [[ "$elem" =~ $IMAGE_FORMATS ]] ; then
+		if [[ "${elem,,}" =~ $IMAGE_FORMATS ]] ; then
 			img+=("$elem")
 			items+=("$elem")
-		elif [[ "$elem" =~ $TEXT_FORMATS ]] ; then
+		elif [[ "${elem,,}" =~ $TEXT_FORMATS ]] ; then
 			txt+=("$elem")
 			items+=("$elem")
 		fi
 	done
 
+	# graphicx paths...
+	if ! [ -z $GRAPHICX_PATH ] ; then
+		local C=0
+		for image in "${img[@]}" ; do
+			local new=`basename ${image}`
+			new="${new#+([0-9])-}"
+			img[$C]=$new
+			C=$(( C + 1 ))
+		done
 	# get hi-res image paths...
-	if ! [ -z $IMAGE_HIRES_DIR ] ; then
+	elif ! [ -z $IMAGE_HIRES_DIR ] ; then
 		local C=0
 		for image in "${img[@]}" ; do
 			# skip non-images...
-			local new="$IMAGE_HIRES_DIR/`basename ${image/[0-9]-/}`"
+			local new=`basename ${image}`
+			new="$IMAGE_HIRES_DIR/${new#+([0-9])-}"
 			# ignore file ext for availability test...
 			# NOTE: the first match may be an unsupported format...
 			new="${new%.*}"
+			local target=$new
 			new=($new.*)
 			if [ -e "${new[0]}" ] ; then
 				img[$C]=${new[0]}
 			else
 				echo %
-				echo "% WARNING: hi-res image not found for: \"${image}\" -> \"${new}\"" \
+				echo "% WARNING: hi-res image not found for: \"${image}\" -> \"${target}\"" \
 					| tee >(cat >&2)
 				echo %
 			fi
@@ -607,7 +578,7 @@ handleSpread(){
 		# XXX this will also eat 0-imagepage.tpl / 20-textpage.tpl -- do a better pattern...
 		if ! [ -z $template ] ; then
 			template=(`ls "$spread/"*.tpl \
-				| egrep -v '.*-('${IMAGE_PAGE}'|'${TEXT_PAGE}')\.tpl'`)
+				| grep -E -v '.*-('${IMAGE_PAGE}'|'${TEXT_PAGE}')\.tpl'`)
 		fi
 		# no template explicitly defined -> match auto-template...
 		if [ -z $layout ] && [ -z $template ] ; then
@@ -635,63 +606,61 @@ handleSpread(){
 						cat "${template}"
 					fi
 				fi
+				populateTemplate_img=("${img[@]}")
+				populateTemplate_txt=("${txt[@]}")
+
 				for elem in "${items[@]}" ; do
 					C=$(( C + 1 ))
 					P=$([ $C == 1 ] \
 						&& echo "left" \
 						|| echo "right")
 
-					# XXX need to use populateTemplate here...
-					#		...to do this need to somehow remove the used
-					#		slots/files from list...
-
 					# image...
-					if [[ "$elem" =~ $IMAGE_FORMATS ]] ; then
+					if [[ "${elem,,}" =~ $IMAGE_FORMATS ]] ; then
 						echo %
 						echo "% $P page (image)..."
 						template=`getTemplate "$spread" "$IMAGE_PAGE"`
-						echo % template: $template
-						anotatePath "${elem}"
-						local caption=$(getCaption "$spread" "${elem}")
-						caption=$(readCaption "$caption")
-						cat "${template}" \
-							| sed -e "s%\${IMAGE0\?}%${elem%.*}%" \
-								-e "s%\${CAPTION0\?}%${caption}%"
+						populateTemplate "$spread" "$template" 
 					# text...
 					else
 						echo %
 						echo "% $P page (text)..."
 						template=$(getTemplate "$spread" "$TEXT_PAGE")
-						echo % template: $template
-						cat "${template}" \
-							| sed "s%\${TEXT}%${elem}%"
+						populateTemplate "$spread" "$template" 
 					fi
 					# reset for next page...
 					template=
 					# ignore the rest of the items when we are done 
 					# creating two pages...
-					[ $C == 2 ] \
-						&& return 0
+					if [ $C == 2 ] ; then
+						populateTemplate_img=
+						populateTemplate_txt=
+						return
+					fi
 				done
 			fi
 		fi
 		# formatting done...
 		[ -z $template ] \
-			&& return 0
+			&& return
 
-		# format template path...
-		template=${template/$spread\//}
-		template=${template/[0-9]-/}
-		# get...
-		template="${template[0]%.*}.tex"
-		if ! [ -e "$template" ] ; then
-			template="$TEMPLATE_DIR/${template[0]%.*}.tex"
+		# resolve the template path...
+		local p=$template
+		template=$(getTemplate "$spread" "$template")
+
+		# not found...
+		if [ -z $template ] ; then
+			echo "%"
+			echo "% ERROR: could not resolve template: $p" | tee >(cat >&2)
+			echo "%"
 		fi
 	fi
 
+	populateTemplate_img=
+	populateTemplate_txt=
 	populateTemplate "$spread" "$template" "${img[@]}" "${txt[@]}"
 
-	return 0
+	return $?
 }
 
 

talks/20230225 - Presentation at Orlov's/photobook-slides-en.tex

@@ -45,7 +45,7 @@
 \usepackage{fontspec}
 \setmainfont[Mapping=tex-text]{Open Sans}
 \setsansfont[Mapping=tex-text]{Open Sans}
-\setmonofont[Mapping=tex-text, Scale=0.8]{Courier New}
+%\setmonofont[Mapping=tex-text, Scale=0.8]{Courier New}
 \newfontfamily\titlefont[Mapping=tex-text]{Open Sans Light}
 \newfontfamily\sectiontitlefont[Mapping=tex-text]{Open Sans Light}
 

talks/20230225 - Presentation at Orlov's/photobook-slides-ru.tex

@@ -42,10 +42,13 @@
 %\fontsize{30pt}{36pt}\selectfont
 
 % fonts...
+%\usepackage{ascii}
+%\usepackage[default,oldstyle,scale=0.95]{opensans}
+%\usepackage[T1]{fontenc}
 \usepackage{fontspec}
 \setmainfont[Mapping=tex-text]{Open Sans}
 \setsansfont[Mapping=tex-text]{Open Sans}
-\setmonofont[Mapping=tex-text, Scale=0.8]{Courier New}
+%\setmonofont[Mapping=tex-text, Scale=0.8]{Courier New}
 \newfontfamily\titlefont[Mapping=tex-text]{Open Sans Light}
 \newfontfamily\sectiontitlefont[Mapping=tex-text]{Open Sans Light}