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,8 +43,6 @@
 #----------------------------------------------------------------------
 # Config...
 
-.EXPORT_ALL_VARIABLES:
-
 # NOTE: this makes things run consistently on different systems including 
 # 		things like Android...
 SHELL := bash
@@ -58,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))
 
@@ -86,8 +85,7 @@ endif
 
 # markdown dialect...
 #
-# XXX still needs some tweaking...
-MD_FORMAT ?= markdown_github
+MD_FORMAT ?= gfm
 
 
 # debug output...
@@ -123,6 +121,7 @@ DIST_NORMAL_FILES = \
 	README.md \
 	LICENSE \
 	Makefile \
+	DEPENDS.txt \
 	$(MODULE).cls \
 	$(MODULE).pdf
 DIST_FILES = \
@@ -173,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...
@@ -223,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 \
@@ -239,6 +224,15 @@ LN := cp -l
 		> $@
 
 
+# list of dependencies...
+#
+DEPENDS.txt: $(MODULE).cls
+	make depends \
+		| grep -v make \
+		| sed -e 's/^/hard /' \
+		> $@
+
+
 
 #----------------------------------------------------------------------
 # Info targets...
@@ -248,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
 
@@ -287,18 +298,35 @@ ctan-dist: dist
 	cp -f $(DIST_DIR)/$(DIST_NAME).zip $(DIST_DIR)/$(MODULE).zip
 
 
-
 .PHONY: tag
 tag:
 	@echo "Will create and publish git tag:"
 	@echo "    v$(VERSION)"
 	@echo "Last 5 tags:"
 	@git tag -l 'v[0-9]*'\
+		| sort -V \
 		| tail -n 5 \
 		| sed 's/^/    /' \
 		| tac
-	@echo "Note that this must be done after a commit."
-	@read -p "(press any key to continue or ctrl-c to cancel)"
+#	# check if we need to bug the user about committing and/or pushing stuff...
+	@\
+		UNCOMITTED=$$(git status --porcelain=v1 2> /dev/null | grep -v '??' | wc -l) ;\
+		UNPUSHED=$$(git log origin..HEAD | wc -l) ;\
+		if ! [ $$UNCOMITTED = 0 ] ; then \
+			echo ;\
+			echo "WARNING: Uncommited changes found!" ;\
+		fi ;\
+		if ! [ $$UNPUSHED = 0 ] ; then \
+			[ $$UNCOMITTED = 0 ] \
+				&& echo ;\
+			echo "WARNING: Unpushed commits found!" ;\
+		fi ;\
+		if ! [ $$UNCOMITTED = 0 ] || ! [ $$UNPUSHED = 0 ] ; then \
+			echo ;\
+			echo "Note that this must be done after a commit and a push." ;\
+			echo "(press any key to continue or ctrl-c to cancel)" ;\
+			read ;\
+		fi ;\
 	git tag "v$(VERSION)"
 	git push origin "v$(VERSION)"
 
@@ -308,7 +336,7 @@ tag:
 
 
 .PHONY: all
-all: pdf
+all: pdf dep 
 
 
 # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -390,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/block2cover.tex

@@ -6,6 +6,11 @@
 	blockwidth=240mm, blockheight=220mm,
 	bleed=4mm,
 	bindingoffset=5mm,
+	spinewidth=15mm,
+	coverboardgrow=3mm,
+	spinefold=5mm,
+	spinefold=5mm,
+	coverflap=17mm,
 	% image block configuration...
 	imageblockwidth=0.98, imageblockheight=0.98,
 	imageblockoffsettop=-0.1,
@@ -18,15 +23,7 @@
 %
 % This can be usefull when having a single setup file for multiple book
 % elemnts like page blocks, covers, endpapers and dust jackets...
-\def\layoutmode{cover}
-\setlength\spinewidth{15mm}
-\setlength\coverboardgrow{3mm}
-\setlength\spinefold{5mm}
-\setlength\spinefold{5mm}
-\setlength\coverflap{17mm}
-
-\ReInitPages
-
+\ChangeLayout{cover}
 
 
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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/00-text-only/text.txt

@@ -0,0 +1 @@
+page 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

@@ -0,0 +1,58 @@
+
+%----------------------------------------------------------------------
+
+\documentclass[
+	layoutmode=block,
+	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}
+
+\usepackage{lipsum}
+
+
+\begin{document} %-----------------------------------------------------
+
+\cleartoleftpage
+
+% NOTE: this is just a trivial example, we are not formatting the text 
+%		block here in any way nor are we pedantic about lengths...
+\newlength\textblockmargin
+\setlength\textblockmargin{2mm}
+
+% text at left...
+\begin{spreadtopages}%
+	\begin{inlinecell}{0.25\cellwidth}{\cellheight}%
+		\lipsum
+	\end{inlinecell}%
+	\hspace{\textblockmargin}%
+	\begin{inlinecell}{0.75\cellwidth - \textblockmargin + \bleed}{\cellheight}%
+		\imagecell[fill]{}{landscape}%
+	\end{inlinecell}
+\end{spreadtopages}
+
+% text at right...
+\begin{spreadtopages}%
+	\hspace{-\bleed}%
+	\begin{inlinecell}{0.75\cellwidth - \textblockmargin + \bleed}{\cellheight}%
+		\imagecell[fill]{}{landscape}%
+	\end{inlinecell}%
+	\hspace{\textblockmargin}%
+	\begin{inlinecell}{0.25\cellwidth}{\cellheight}%
+		\lipsum
+	\end{inlinecell}
+\end{spreadtopages}
+
+
+\end{document} %-------------------------------------------------------
+%                                                  vim:set ts=4 sw=4 :

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-template.tex

@@ -0,0 +1,31 @@
+%----------------------------------------------------------------------
+
+\documentclass[
+	layoutmode=jacket,
+	spinewidth=20mm,
+	spinefold=7mm,
+	coverboardgrow=3mm,
+	jacketflap=50mm,
+	jacketwrap=1mm,
+	% 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/jacket.tex

@@ -22,7 +22,29 @@
 
 \begin{document}
 
-\GenerateTemplate
+\begin{page}
+	\begin{frontcover}
+        \begin{cliptocell}[0mm \bleed]
+			\imagecell[fill, clearance=-\bleed]{}{landscape}
+		\end{cliptocell}
+	\end{frontcover}
+	\begin{backcover}
+        \begin{cliptocell}[0mm \bleed]
+			\imagecell[fill, clearance=-\bleed]{}{landscape}
+		\end{cliptocell}
+	\end{backcover}
+	\begin{spine}
+        \begin{cliptocell}[0mm \bleed]
+			\imagecell[fill, clearance=-\bleed]{}{landscape}
+		\end{cliptocell}
+	\end{spine}
+	\begin{frontflap}
+		Some text
+	\end{frontflap}
+	\begin{backflap}
+		Some text
+	\end{backflap}
+\end{page}
 
 \end{document}
 

examples/spread generation/Makefile

@@ -8,14 +8,14 @@
 # 	$ SPREAD=1 make
 #
 # For more info use:
-# 	make-images.sh --help
+# 	make-spreads.sh --help
 #
 #
 
-MAKESPREADS := ../../scripts/make-images.sh
+MAKESPREADS := ../../scripts/make-spreads.sh
 
 
-spreads.tex: spreads
+spreads.tex: spreads $(wildcard spreads/*/*)
 	$(MAKESPREADS) $< $(SPREAD) > $@
 
 dist:

examples/spread generation/spreads/-03-disabled/01.txt

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

examples/spread generation/spreads/-03-disabled/02.txt

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

examples/spread generation/spreads/00-text-only/text.txt

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

examples/spread generation/spreads/01-image-text/02-block.txt

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

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

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

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

@@ -0,0 +1,453 @@
+
+Support scripts
+===============
+
+<!-- TOC depthfrom:2 -->
+
+- [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)
+	- [Templates](#templates)
+	- [Image captions](#image-captions)
+	- [Environment variables and configuration](#environment-variables-and-configuration)
+- [cls2tex.sh](#cls2texsh)
+
+<!-- /TOC -->
+
+
+---
+
+`make-spreads.sh`
+----------------
+
+Generate LaTeX block of pages/spreads from a directory tree.
+
+This was initially intended as a means to convert the exported directory 
+tree from an image viewer where image/text sequencing was done, but it 
+can also be used standalone.
+
+Goals:
+- Decouple layout, sequencing, images, processing and different texts 
+  to enable different people to work on them independently and in 
+  parallel,
+- Simplify editing the page/spread sequence,
+- Automate the build process.
+
+
+A typical project tree:
+```
+book/
+├── templates/  . . . . . . . . . . . . Global templates.
+│   ├── imagepage.tex . . . . . . . . . Single page image template,
+│   ├── textpage.tex  . . . . . . . . . Single page text template,
+│   │                                   These are used to build spreads 
+│   │                                   when no explicit template matches.
+│   ├── blank-image.tex
+│   ├── image-blank.tex
+│   ├── image-image.tex
+│   ├── fullbleed.tex
+│   └── ...
+├── spreads/  . . . . . . . . . . . . . Main block layout.
+│   ├── 00/ . . . . . . . . . . . . . . A basic spread.
+│   │   ├── tweaks.tex                  The spread template is built
+│   │   └── 0-DSC02432.jpg              automatically with tweaks.tex
+│   │                                   prepended.
+│   ├── 01/
+│   │   ├── 0-DSC02439.jpg
+│   │   └── 1-intro.txt
+│   ├── 02/
+│   │   ├── fullbleed.tpl . . . . . . . Explicitly use a global template.
+│   │   └── 1-DSC02511.jpg
+│   ├── 03/
+│   │   ├── 0-DSC02509-0.jpg
+│   │   └── 1-DSC02506-0.jpg
+│   └── ...
+├── captions/ . . . . . . . . . . . . . Image captions.
+│   ├── DSC02432.txt
+│   ├── DSC02439.txt
+│   ├── DSC02511.txt
+│   └── ...
+├── setup.tex . . . . . . . . . . . . . Book block setup.
+│                                       This is included by all top level
+│                                       .tex files like block.tex, 
+│                                       cover.tex, ...etc.
+├── block.tex . . . . . . . . . . . . . Block skeletal layout.
+│                                       This usually includes the titles, 
+│                                       technical pages and sources the
+│                                       ./block-spreads.tex.
+├── block-spreads.tex . . . . . . . . . The generated block content.
+├── cover.tex . . . . . . . . . . . . . Cover layout.
+├── jacket.tex  . . . . . . . . . . . . Dust jacket layout.
+└── ...
+```
+
+For a full example see: ../examples/book
+
+Generate the block:
+```shell
+$ make-spreads.sh ./spreads > block-spreads.tex
+```
+
+Note that `make-spreads.sh` does not force a specific layout outside of 
+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.
+
+
+For runtime help see:
+```shell
+$ make-spreads.sh --help
+```
+
+
+### Theory of operation
+
+<!-- XXX spreads vs. pages -->
+
+The system is designed to minimize the effort in laying out pages, so
+when designing a book the focus should be on global templates and on
+helping `make-spreads.sh` build them rather than trying to layout each
+spread individually.
+
+There are several ways to arrive at a book layout starting from the
+concept, through the edit, sequencing, structuring and the graphic
+design, we here will focus on the stage of the process where a body of
+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,
+- 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 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 
+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 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 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 
+should work with it without overwhelming it.
+
+Have answers, good, now it's time to build those mock layouts and make
+them into basic templates.
+
+It would be simplest to start work with the basic templates provided by
+`photobook` (see: ../examples/spread templates/templates/) and rework 
+them when or if needed.
+
+The templates are split into two levels:
+- Page templates  
+  These are typical pages that makeup a spread, usually an
+  image page (`imagepage.tex`), a text page (`textpage.tex`), and an
+  optional empty page (`emptypage.tex`), `make-spreads.sh` can combine 
+  them to build spreads automatically.
+- Spread templates  
+  These typeset a spread and can be either automatically inferred from
+  the structure or manually selected.
+
+
+#### Automatic template inferencing
+
+If no explicit template is defined (see next section) `make-spreads.sh` 
+will try and infer a template based on the number of images in the 
+spread directory, if that is not possible the it will build a spread
+from page templates based on the sequence of first two image/text files.
+
+For example with the default settings and the templates defined above:
+
+```
+├── 01/
+│   ├── 0-DSC02439.jpg
+│   └── 1-intro.txt
+```
+
+Will use `imagepage.tex` and `textpage.tex` templates to build the spread,
+while the following:
+
+```
+├── 03/
+│   ├── 0-DSC02509-0.jpg
+│   └── 1-DSC02506-0.jpg
+```
+
+Will use `image-image.tex`.
+
+Note that if a spread template is not found `make-spreads.sh` fallback to 
+page templates, e.g. if we delete `image-image.tex` then `imagepage.tex` 
+will be used for both pages of the spread instead.
+
+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.
+
+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
+
+A template can be selected manually by providing a file in the form:
+
+```bnf
+<template-name>.tpl
+```
+
+The content of this file is ignored and `templates/<template-name>.tex`
+will be used for that spread.
+
+Example:
+```
+├── 02/
+│   ├── fullbleed.tpl
+│   └── 1-DSC02511.jpg
+```
+
+Here `templates/fullbleed.tex` will be used.
+
+
+#### Template tweaking
+
+If the file `tweaks.tex` is present in the spread directory its contents
+are included in the built block at the start of that spread.
+
+This can be useful to _tweak_ the spread, for example to set page/font 
+color, tweak image positioning in some of the `photobook`'s template 
+spread macros (see: tweaking section in photobook.pdf).
+
+Example:
+```
+├── 00/
+│   ├── tweaks.tex
+│   └── 0-DSC02432.jpg
+```
+
+Note that this can both apply to a single spread as well as a set of 
+spreads, of example page or text colors are not reset automatically
+and will affect all subsequent spreads until manually reset (in a 
+different spread's `tweaks.tex` file), while `photobook`'s tweaks apply 
+only to a single page.
+
+
+#### Manual spread layouts 
+
+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
+
+A template is a LaTeX file with zero or more special fields defined.
+
+Field types:
+- `${IMAGE}` / `${IMAGE<number>}`  
+  Filled with image path.
+- `${CAPTION}` / `${CAPTION<number>}`  
+  Filled with caption file content
+- `${TEXT}` / `${TEXT<number>}`  
+  Filled with text file content
+
+Each field can be used more than once, the field value will be copied to
+each instance.
+
+Multiple fields of the same type can be provided and each will be filled
+with corresponding data in order, e.g. the third image filed will get
+the third image path. Note that we are talking of field order and not
+field number, this removes the need to constantly keep the field/file
+numbers matched when adding and removing files/fields, all one needs to
+do is keep the order the same.
+
+If a field is not filled it will be empty in the resulting `.tex`.
+
+Example template `templates/fullbleed.tex`:
+```
+\ImageSpreadFill{${CAPTION}}{${IMAGE0}}
+```
+
+
+### Image captions
+
+In general image captions are decoupled from the main layout to enable
+writers and editors to work on them externally.
+
+```bnf
+captions/
+├── <image-name>.txt
+└── ...
+```
+
+The captions folder name/location is controlled by the `$CAPTION_DIR` 
+environment variable.
+
+
+Inline captions are also supported:
+```bnf
+spreads/
+├── <spread>/
+│   ├── ...
+│   ├── 00-<image-name>.<ext>
+│   ├── 00-<image-name>.txt . . . . . . Local image caption
+│   └── ...
+└── ...
+```
+An inline caption must have the same filename as the corresponding image
+but with a .txt extension.
+
+
+### Environment variables and configuration
+
+All the configuration options can be given in a configuration file as
+well as environment variables.
+
+Environment variables take precedence over the configuration file.
+
+The default `make-images.cfg` would look something like:
+```shell
+# if non-empty make-spreads.sh will add image paths to pdf notes...
+ANOTATE_IMAGE_PATHS=
+
+# file extensions to treat as text (separated with "|")
+TEXT_FORMATS=txt
+
+# file extensions to treat as images (separated with "|")
+IMAGE_FORMATS=jpeg|jpg|png|pdf|svg|eps
+
+# default directory spread definitions are located in...
+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...
+CAPTION_DIR=captions/
+
+# root template directory...
+TEMPLATE_DIR=templates/
+
+# empty page template...
+EMPTY_PAGE=emptypage
+
+# text page template...
+TEXT_PAGE=textpage
+
+# image page template...
+IMAGE_PAGE=imagepage
+
+# spread templates...
+IMAGE_SPREAD=(
+        #
+        #   +------- number of found images
+        #  /     +-- template name
+        # /     /
+        [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:
+```shell
+$ make-spreads.sh -c <path> ..
+```
+
+
+---
+
+`cls2tex.sh`
+------------
+
+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
+
+Usage:
+  cls2tex.sh [OPTIONS] [[INPUT] OUTPUT]
+
+Options:
+  -h | --help         Show this message and exit
+  -p | --prefix PREFIX
+                      Set the doc comment PREFIX (default: "%")
+  -s | --strip        Strip docs out
+  -n | --no-msg       Don't add the "generated with" message to output
+
+This will:
+  - read the INPUT
+  - keep lines starting with \def\<module-name>@[A-Z]\+
+  - keep lines starting with '%%'
+  - %%%%% Text -> \subsection{Text}
+  - %%%% Text -> \section{Text}
+  - %% >> code -> \begin{verbatim}code\end{verbatim}
+  - write the result to OUTPUT
+
+If no OUTPUT is given cls2tex.sh will write to stdout. If no INPUT
+is given cls2tex.sh will read stdin.
+
+PREFIX can replace the second "%" in the above patterns to make it
+possible to integrate multiple layers of documentation in one file
+and to integrate them in various ways, for example, in the photobook
+document class documentation "M" prefix is used to indicate
+meta-command docs, this enables us to document them in the relevant
+location (i.e. at the implementation) in source but move the docs to
+a unified location in docs, effectively decoupling the source and doc
+structure when needed.
+
+Strip mode is the reverse of of the default, it will strip out docs
+and empty lines, keeping only the actual code and code comments.
+
+NOTE: stripping will not remove non-doc comments.
+NOTE: the idea of keeping latex docs in a latex file is far simpler
+      than all the stuff crammed into .dtx, at least for my needs:
+          - keep the code readable
+          - keep the docs readable
+      in both the repo and in installed form, so .dtx is not used.
+```
+
+<!-- vim:set ts=4 sw=4 nowrap : -->

scripts/cls2tex.sh

@@ -26,12 +26,12 @@ 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
-	echo "If no OUTPUT is given $SCRIPT_NAME will read stdout. If no INPUT"
+	echo "If no OUTPUT is given $SCRIPT_NAME will write to stdout. If no INPUT"
 	echo "is given $SCRIPT_NAME will read stdin."
 	echo
 	echo "PREFIX can replace the second \"%\" in the above patterns to make it"
@@ -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,12 +126,13 @@ if [ -z $STRIP_DOC ] ; then
 	printmsg "Documentation" \
 		> "$OUTPUT"
 	cat "$INPUT" \
-		| egrep '(^%'$PREFIX'|^\\edef\\'$MODULE'@[A-Z][A-Z]+)' \
-		| sed 's/^\(\\edef\\\)'$MODULE'@/%'$PREFIX'\1/' \
-		| sed 's/%'$PREFIX'%%%% \(.*\)/%'$PREFIX'\\subsubsection{\1}\\label{subsubsec:\1}/' \
-		| sed 's/%'$PREFIX'%%% \(.*\)/%'$PREFIX'\\subsection{\1}\\label{subsec:\1}/' \
-		| sed 's/%'$PREFIX'%% \(.*\)/%'$PREFIX'\\section{\1}\\label{sec:\1}/' \
-		| sed 's/%'$PREFIX'\s\+>>\s\+\(.*\)/%'$PREFIX'\\begin{verbatim} \1 \\end{verbatim}/' \
+		| 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}/' \
+			-e 's/%'$PREFIX'%%% \(.*\)/%'$PREFIX'\\subsection{\1}\\label{subsec:\1}/' \
+			-e 's/%'$PREFIX'%% \(.*\)/%'$PREFIX'\\section{\1}\\label{sec:\1}/' \
+			-e 's/%'$PREFIX'\s\+>>\s\+\(.*\)/%'$PREFIX'\\begin{verbatim} \1 \\end{verbatim}/' \
 		| cut -c 3- - \
 		>> "$OUTPUT"
 
@@ -145,12 +141,12 @@ else
 	printmsg "Stripped code" \
 		> "$OUTPUT"
 	cat "$INPUT" \
-		| egrep -v '%'$PREFIX'' \
-		| egrep -v '^(\s*%)?\s*$' \
+		| grep -Ev '%'$PREFIX'' \
+		| grep -Ev '^(\s*%)?\s*$' \
 		>> "$OUTPUT"
 fi
 
 
 
 #----------------------------------------------------------------------
-#                                           vim:set ts=4 sw=4 nowrap :
+#                                            vim:set ts=4 sw=4 nowrap :

scripts/make-images.sh

@@ -1,449 +0,0 @@
-#!/bin/bash
-shopt -s nullglob extglob
-
-#----------------------------------------------------------------------
-#
-# Template structure:
-#	templates/
-#		imagepage.tex
-#		textpage.tex
-#		...
-#	$IMAGE_DIR/
-#		$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}
-#					${CAPTION0}
-#					${IMAGE1}
-#					${CAPTION1}
-#				NOTE: if images are included, hi-res source
-#					substitution is not done here.
-#			<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}
-#					${IMAGE1}
-#					${CAPTION1}
-#			imagepage.tex
-#				image page template.
-#				fields:
-#					${IMAGE}
-#					${CAPTION}
-#			textpage.tex
-#				text page template.
-#				fields:
-#					${TEXT}
-#			<spread-template-name>-imagepage.tpl
-#			<spread-template-name>-textpage.tpl
-#				indicates the image/text page template to use.
-#				ignored if explicit templates are given.
-#				image fields:
-#					${IMAGE}
-#					${CAPTION}
-#				text fields:
-#					${TEXT}
-#			00-<image>.png
-#				image.
-#				if $IMAGE_HIRES_DIR is set then this will 
-#				resolve to:
-#					$IMAGE_HIRES_DIR/<image>
-#				XXX hi-res substitution currently disabled.
-#			01-<text>.txt
-#				text.
-#			...
-#		...
-#
-#
-#
-# Env variables:
-#	IMAGE_HIRES_DIR=<path>
-#		sets the path to which the hi-res images are resolved.
-#
-#
-#
-#
-# XXX TODO:
-#		- revise printed comments...
-#		- add real arg handling...
-#		- add abbility to apply template to a specific page in spread...
-#			...something like:
-#				<template-name>-left.tpl
-#				<template-name>-right.tpl
-#
-#
-#
-#----------------------------------------------------------------------
-
-# defaults...
-
-CFG_FILE=`basename $0`.cfg
-
-TEMPLATE_PATH=templates/
-
-IMAGE_DIR=pages/
-
-#IMAGE_HIRES_DIR=
-
-
-# Default timplates
-#SINGLE_IMAGE=blank-image
-SINGLE_IMAGE=imagebleedleft
-DOUBLE_IMAGE=image-image
-
-
-# load config...
-[ -e $CFG_FILE ] && source $CFG_FILE
-
-
-
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
-printhelp(){
-	echo "Usage: `basename $0` [ARGUMENTS] [PATH]"
-	echo "       `basename $0` [ARGUMENTS] PATH FROM [COUNT]"
-	echo
-	echo "Generate LaTeX layout from directory structure."
-	echo
-	echo "Arguments:"
-	echo "  -h --help   - print this help and exit."
-	echo "  --templates=PATH"
-	echo "              - path to search for templates (default: $TEMPLATE_PATH)."
-	echo "  --single-image-tpl=NAME"
-	echo "              - single image default template (default: $SINGLE_IMAGE)."
-	echo "  --double-image-tpl=NAME"
-	echo "              - double image default template (default: $DOUBLE_IMAGE)."
-	echo
-	echo "Parameters:"
-	echo "  PATH        - path to root pages directory (default: $IMAGE_DIR)"
-	echo "  FROM        - spread to start from (default: 0)"
-	echo "  COUNT       - number of spreads to generate (default: 1)"
-	echo
-	echo "Environment:"
-	echo "  \$IMAGE_HIRES_DIR "
-	echo "              - source directory for replacement hi-res images."
-	echo "  \$ANOTATE_IMAGE_PATHS "
-	echo "              - if true add image paths in anotations."
-	echo
-	echo "Configuration defaults can be stored in a config file: $CFG_FILE"
-	echo
-	echo "NOTE: COUNT is relevant iff FROM is given, otherwise all available "
-	echo "        spreads are generated."
-	echo
-	echo "Examples:"
-	echo "  $ `basename $0` ./pages > pages.tex"
-	echo "              - generate a layout fron the contents of ./pages"
-	echo
-	echo "  $ IMAGE_HIRES_DIR=images/hi-res `basename $0` ./pages"
-	echo "              - generate a layout fron the contents of ./pages and "
-	echo "                replaceing local images with images in ./images/hi-res"
-	echo
-}
-
-
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-# handle arguments...
-
-while true ; do
-	case $1 in
-		-h|--help)
-			printhelp
-			exit
-			;;
-
-		--templates)
-			TEMPLATE_PATH=$2
-			shift
-			shift
-			;;
-		--single-image-tpl)
-			SINGLE_IMAGE=$2
-			shift
-			shift
-			;;
-		--double-image-tpl)
-			DOUBLE_IMAGE=$2
-			shift
-			shift
-			;;
-
-		# handle unknown options...
-		-*|--*)
-			echo "Error: unknown option \"$1\""
-			exit
-			;;
-
-		*)
-			break
-			;;
-	esac
-done
-
-
-if [ -z $1 ] ; then
-	IMAGE_DIR=pages/
-else
-	IMAGE_DIR=$1/
-fi
-
-
-# calculate spread index range...
-# XXX add support for negative indexing...
-FROM=$2
-COUNT=$( [ -z $3 ] && echo 1 || echo $3 )
-STOP=$(( FROM + COUNT ))
-
-
-
-#----------------------------------------------------------------------
-
-# XXX should we report images w/o captions???
-getCaption(){
-	local C=`basename "${1%.*}"`
-	#C="${C/[0-9]-}"
-	C="captions/${C}.txt"
-
-	if [ -e "${C}" ] ; then
-		C=`cat "${C}" | sed 's/\\\/\\\\\\\/g'`
-	else
-		C=""
-	fi
-
-	echo ${C[*]}
-}
-
-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_PATH/${TEMPLATE[0]%-${TYPE}.*}.tex"
-		fi
-	fi
-	if [ -z $TEMPLATE ] ; then
-		 TEMPLATE="$TEMPLATE_PATH/${TYPE}.tex"
-	fi
-	echo $TEMPLATE
-}
-
-anotatePath(){
-	if [ -z "$1" ] || [ -z "$ANOTATE_IMAGE_PATHS" ] ; then
-		return
-	fi
-	path=$(basename ${1%.*})
-	# NOTE: did not figure out how to make a verbatim comment in latex 
-	#		so here we are, doing it in shell...
-	path=${path//_/\\_}
-	#echo "\\pdfmargincomment{Image: $path}%"
-	echo "\\pdfcommentcell{Image: $path}%"
-}
-
-
-#----------------------------------------------------------------------
-
-
-echo %----------------------------------------------------------------------
-echo %
-echo % WARNING: This file is auto-generated by make-images.sh and will be 
-echo "%          overwritten on next run..."
-echo %
-echo "% Image source (preview): \"$IMAGE_DIR\""
-echo "% Image source (hi-res): \"$IMAGE_HIRES_DIR\""
-echo %
-echo %----------------------------------------------------------------------
-echo %
-#echo % set image source directory...
-#echo "\\graphicspath{{${IMAGE_DIR}}}"
-#echo %
-#echo %----------------------------------------------------------------------
-#echo %
-#
-#cd ${IMAGE_DIR}
-
-l=$(ls "$IMAGE_DIR/" | wc -l)
-c=0
-
-for spread in "${IMAGE_DIR}"/* ; do
-	# skip non-spreads...
-	if ! [ -d "$spread" ] ; then
-		continue
-	fi
-
-	c=$(( c + 1 ))
-
-	# if $FROM is given print only stuff in range...
-	[ -z $FROM ] \
-		|| if (( $(( c - 1 )) < $FROM )) || (( $c > $STOP )) ; then
-			continue
-		fi
-
-	# if we are building only a specific spread...
-	##if ! [ -z $SPREAD ] && [[ "$spread" != "$IMAGE_DIR/$SPREAD" ]]; then
-	##	continue
-	##fi
-
-	if ! [ -z $SKIP_FIRST ] ; then
-		echo %
-		echo %
-		echo % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-	fi
-	SKIP_FIRST=1
-	# skip temporarily disabled...
-	if [ -z ${spread/-*/} ] ; then
-		echo "% spread: ${spread/-/}: skipped..." | tee >(cat >&2)
-		echo %
-		continue
-	else
-		printf "Spread ($c/$l): ${spread/-/}                         \r" >&2
-		echo "% spread: ${spread/-/}"
-	fi
-
-
-	# auto layout / templates...
-	# NOTE: to use a specific template just `touch <template-name>.tpl`
-	#	in the spread directory...
-
-	# layout tweaks...
-	tweaks=($spread/*tweak.tex)
-	if ! [ -z ${tweaks} ] ; then
-		echo "% tweaks: ${tweaks[0]}"
-		cat ${tweaks[0]}
-	fi
-
-
-	# NOTE: we also get *.txt files here...
-	items=($spread/*.!(tex|tpl|bak))
-
-	# get hi-res image paths...
-	if ! [ -z $IMAGE_HIRES_DIR ] ; then
-		C=0
-		for img in "${items[@]}" ; do
-			# skip non-images...
-			if [[ "$img" == "${img/.txt/}" ]] ; then
-				#new="../$IMAGE_HIRES_DIR/`basename ${img/[0-9]-/}`"
-				new="$IMAGE_HIRES_DIR/`basename ${img/[0-9]-/}`"
-				# ignore file ext for availability test...
-				# NOTE: the first match may be an unsupported format...
-				new="${new%.*}"
-				new=($new.*)
-				if [ -e "${new[0]}" ] ; then
-					items[$C]=${new[0]}
-				else
-					echo %
-					echo "% WARNING: hi-res image not found for: \"${img}\" -> \"${new}\"" | tee >(cat >&2)
-					echo %
-				fi
-			fi
-			C=$(( C + 1 ))
-		done
-	fi
-
-
-	# manual layout...
-	layout=($spread/*layout.tex)
-	if ! [ -z $layout ] ; then
-		TEMPLATE=${layout[0]}
-
-	# templates and partial templates...
-	else
-		# spread template...
-		TEMPLATE=($spread/*.tpl)
-		# skip page template refs: *-imagepage.tpl / *-textpage.tpl
-		# 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 '.*-(imagepage|textpage)\.tpl'`)
-		fi
-		# no template explicitly defined -> match auto-template...
-		AUTO=
-		if [ -z $layout ] && [ -z $TEMPLATE ] ; then
-			AUTO=" (auto)"
-			if [ ${#items[@]} == 1 ] ; then
-				TEMPLATE=$SINGLE_IMAGE
-
-			# multiple items...
-			else 
-				C=0
-				for img in "${items[@]}" ; do
-					C=$(( C + 1 ))
-					P=`[ $C == 1 ] && echo "left" || echo "right"`
-
-					# image...
-					if [ "${img/.txt/}" == "${img}" ] ; then
-						echo %
-						echo "% $P page (image)..."
-						TEMPLATE=`getTemplate "$spread" "imagepage"`
-						echo % page template: $TEMPLATE
-						anotatePath "${img}"
-						CAPTION=`getCaption "${img}"`
-						cat "${TEMPLATE}" \
-							| sed "s%\${IMAGE0\?}%${img%.*}%" \
-							| sed "s%\${CAPTION0\?}%${CAPTION}%"
-
-					# text...
-					else
-						echo %
-						echo "% $P page (text)..."
-						TEMPLATE=`getTemplate "$spread" "textpage"`
-						echo % page template: $TEMPLATE
-						cat "${TEMPLATE}" \
-							| sed "s%\${TEXT}%${img}%"
-					fi
-
-					# reset for next page...
-					TEMPLATE=
-					# only two pages at a time...
-					[ $C == 2 ] && break
-				done
-			fi
-		fi
-		# formatting done...
-		[ -z $TEMPLATE ] && continue
-
-		# format...
-		TEMPLATE=${TEMPLATE/$spread\//}
-		TEMPLATE=${TEMPLATE/[0-9]-/}
-		# get...
-		TEMPLATE="$TEMPLATE_PATH/${TEMPLATE[0]%.*}.tex"
-	fi
-
-	# captions...
-	CAPTION0=`getCaption "${items[0]}"`
-	CAPTION1=`getCaption "${items[1]}"`
-
-	echo "% template: (template${AUTO}: $TEMPLATE)"
-	anotatePath "${items[0]}"
-
-	# fill the template...
-	cat "${TEMPLATE}" \
-		| sed "s%\${IMAGE0\?}%${items[0]%.*}%" \
-		| sed "s%\${CAPTION0\?}%${CAPTION0}%" \
-		| sed "s%\${IMAGE1}%${items[1]%.*}%" \
-		| sed "s%\${CAPTION1}%${CAPTION1}%"
-done
-
-echo %
-echo %
-echo %
-echo %----------------------------------------------------------------------
-echo
-
-echo "Spread created: $c of $l                                         " >&2
-
-
-
-#----------------------------------------------------------------------
-# vim:set ts=4 sw=4 :

scripts/make-spreads.cfg.example

@@ -0,0 +1,39 @@
+# if non-empty make-spreads.sh will add image paths to pdf notes...
+ANOTATE_IMAGE_PATHS=
+
+# file extensions to treat as text (separated with "|")
+TEXT_FORMATS=txt
+
+# file extensions to treat as images (separated with "|")
+IMAGE_FORMATS=jpeg|jpg|png|pdf|svg|eps
+
+# default directory spread definitions are located in...
+SPREADS_DIR=spreads/
+
+# if non-empty link link images to matching ones from this directory...
+IMAGE_HIRES_DIR=
+
+# directory where external captions are stored...
+CAPTION_DIR=captions/
+
+# root template directory...
+TEMPLATE_DIR=templates/
+
+# empty page template...
+EMPTY_PAGE=emptypage
+
+# text page template...
+TEXT_PAGE=textpage
+
+# image page template...
+IMAGE_PAGE=imagepage
+
+# spread templates...
+IMAGE_SPREAD=(
+        #
+        #   +------- number of found images
+        #  /     +-- template name
+        # /     /
+        [0]=text-spread
+        [2]=image-image
+)

scripts/make-spreads.sh

@@ -0,0 +1,755 @@
+#!/usr/bin/env bash
+shopt -s nullglob extglob
+
+#----------------------------------------------------------------------
+#
+# For docs see README.md
+#
+#
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+#
+# XXX DOC:
+#		$spread/
+#			...
+#			imagepage.tex
+#				image page template.
+#				fields:
+#					${IMAGE}
+#					${CAPTION}
+#					${TEXT0}
+#					...
+#			textpage.tex
+#				text page template.
+#				fields:
+#					${TEXT}
+#					...
+#			<spread-template-name>-imagepage.tpl
+#			<spread-template-name>-textpage.tpl
+#				indicates the image/text page template to use.
+#				ignored if explicit templates are given.
+#			...
+#
+#
+#
+#----------------------------------------------------------------------
+# load config...
+
+CONFIG=${CONFIG:=$(basename ${0%.*}).cfg}
+# prepend CFG_ to settings in config...
+# NOTE: this is done to prevent them overriding the environment...
+[ -e $CONFIG ] \
+	&& eval $(cat "$CONFIG" \
+		| sed -e 's/^\(\s*\)\([A-Z_]\+=\)/\1CFG_\2/')
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# defaults...
+#
+# NOTE: all of these options can be either set in the $CONFIG file or 
+#		set in the script env.
+# NOTE: env takes priority over $CONFIG
+
+# if set add pdf annotations of paths to each image...
+ANOTATE_IMAGE_PATHS=${ANOTATE_IMAGE_PATHS:=$CFG_ANOTATE_IMAGE_PATHS}
+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}
+SPREADS_DIR=${SPREADS_DIR:=spreads/}
+
+IMAGE_HIRES_DIR=${IMAGE_HIRES_DIR:=$CFG_IMAGE_HIRES_DIR}
+IMAGE_HIRES_DIR=${IMAGE_HIRES_DIR:=}
+
+CAPTION_DIR=${CAPTION_DIR:=$CFG_CAPTION_DIR}
+CAPTION_DIR=${CAPTION_DIR:=captions/}
+
+TEMPLATE_DIR=${TEMPLATE_DIR:=$CFG_TEMPLATE_DIR}
+TEMPLATE_DIR=${TEMPLATE_DIR:=templates/}
+
+# Default templates
+# NOTE: if a template is not found we will try and build a spread from 
+#		page components...
+
+# page templates...
+EMPTY_PAGE=${EMPTY_PAGE:=$CFG_EMPTY_PAGE}
+EMPTY_PAGE=${EMPTY_PAGE:=emptypage}
+
+TEXT_PAGE=${TEXT_PAGE:=$CFG_TEXT_PAGE}
+TEXT_PAGE=${TEXT_PAGE:=textpage}
+
+IMAGE_PAGE=${IMAGE_PAGE:=$CFG_IMAGE_PAGE}
+IMAGE_PAGE=${IMAGE_PAGE:=imagepage}
+
+# dynamic spread templates...
+# 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
+		IMAGE_SPREAD=()
+		for i in ${!CFG_IMAGE_SPREAD[@]} ; do
+			IMAGE_SPREAD[$i]=${CFG_IMAGE_SPREAD[$i]}
+		done
+	else
+		IMAGE_SPREAD=(
+			[0]=text-spread
+			[2]=image-image
+		)
+	fi
+fi
+
+
+
+#----------------------------------------------------------------------
+
+printhelp(){
+	echo "Usage: `basename $0` [ARGUMENTS] [PATH]"
+	echo "       `basename $0` [ARGUMENTS] PATH INDEX"
+	echo "       `basename $0` [ARGUMENTS] PATH FROM COUNT"
+	echo
+	echo "Generate LaTeX layout from directory structure."
+	echo
+	echo "Arguments:"
+	echo "  -h --help   - print this help and exit."
+	echo "  -c PATH     - load configuration from PATH."
+	echo "  -a --annotate"
+	echo "              - add annotations with image paths to pages."
+	echo "  --templates PATH"
+	echo "              - path to search for templates (default: $TEMPLATE_DIR)."
+	echo "  --single-image-tpl NAME"
+	echo "              - single image default template (default: ${IMAGE_SPREAD[1]})."
+	echo "  --double-image-tpl NAME"
+	echo "              - double image default template (default: ${IMAGE_SPREAD[2]})."
+	echo "  --text-spread-tpl NAME"
+	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)"
+	echo "  INDEX       - index of spread to generate"
+	echo "  FROM        - spread to start from"
+	echo "  COUNT       - number of spreads to generate"
+	echo
+	echo "Environment:"
+	echo "  \$IMAGE_HIRES_DIR "
+	echo "              - source directory for replacement hi-res images."
+	echo "  \$ANOTATE_IMAGE_PATHS "
+	echo "              - if true add image paths in anotations."
+	echo "  \$CONFIG     - sets the config file name (default: $CONFIG)"
+	echo "  \$TEXT_FORMATS "
+	echo "              - list of file extensions treated as text (default: $TEXT_FORMATS)."
+	echo "  \$IMAGE_FORMATS "
+	echo "              - list of file extensions treated as images"
+	echo "                (default: $IMAGE_FORMATS)."
+	echo
+	echo "Configuration defaults can be stored in a config file: $CONFIG"
+	echo
+	echo "NOTE: COUNT is relevant iff FROM is given, otherwise all available "
+	echo "        spreads are generated."
+	echo
+	echo "Examples:"
+	echo "  $ `basename $0` ./pages > pages.tex"
+	echo "              - generate a layout fron the contents of ./pages"
+	echo
+	echo "  $ IMAGE_HIRES_DIR=images/hi-res `basename $0` ./pages"
+	echo "              - generate a layout fron the contents of ./pages and "
+	echo "                replaceing local images with images in ./images/hi-res"
+	echo
+}
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# handle arguments...
+
+while true ; do
+	case $1 in
+		-h|--help)
+			printhelp
+			exit
+			;;
+		-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\"" >&2
+			exit
+			;;
+
+		*)
+			break
+			;;
+	esac
+done
+
+
+if [ -z $1 ] ; then
+	SPREADS_DIR=spreads/
+else
+	SPREADS_DIR=$1/
+fi
+
+
+# calculate spread index range...
+# XXX add support for negative indexing...
+FROM=$2
+COUNT=$( [ -z $3 ] && echo 1 || echo $3 )
+STOP=$(( FROM + COUNT ))
+
+
+# prep format regexps...
+TEXT_FORMATS='.*\.('$TEXT_FORMATS')$'
+IMAGE_FORMATS='.*\.('$IMAGE_FORMATS')$'
+
+
+
+#----------------------------------------------------------------------
+
+# Get image caption...
+# usage:
+#	getCaption SPREAD IMAGE
+getCaption(){
+	local spread=$1
+	local name=`basename "${2%.*}"`
+
+	local captions=(
+		"$CAPTION_DIR/${name}.txt"
+		"${spread}/${name}.txt"
+	)
+
+	local caption
+	for caption in "${captions[@]}" ; do
+		if [ -e "${caption}" ] ; then
+			echo ${caption}
+			return
+		fi
+	done
+}
+
+
+# Read/print caption text...
+# usage:
+#	readCaption PATH
+readCaption(){
+	[ -z "$1" ] \
+		&& return 1
+	cat "$1" \
+		| sed -e 's/\\/\\\\\\/g'
+}
+
+
+# Get template...
+# usage:
+#	getTemplate SPREAD TYPE
+#
+getTemplate(){
+	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
+
+	# local template...
+	template=($spread/*-$name.tex)
+	if [ ${#template[@]} != 0 ] ; then
+		template=${template[0]}
+	else
+		template=($spread/$name.tex)
+	fi
+	# global template...
+	if [ -z $template ] \
+			|| ! [ -e "$template" ] ; then
+		 template="$TEMPLATE_DIR/${name}.tex"
+	fi
+	# check if the thing exists...
+	if ! [ -e $template ] ; then
+		return 1
+	fi
+	echo $template
+}
+
+
+# Get template slots (cached)...
+# usage:
+#	templateSlots TEMPLATE
+declare -A TEMPLATE_INDEX
+templateSlots(){
+	# cache the vars...
+	#if [ ${TEMPLATE_INDEX[$1]+_} ] ; then
+	if [ -z ${TEMPLATE_INDEX[$1]} ] ; then
+		TEMPLATE_INDEX[$1]=$(cat "$1" \
+			| grep -o '\${[A-Z0-9_]\+}' \
+			| sed 's/\${\(.*\)}/\1/g' \
+			| sort -V)
+	fi
+	echo ${TEMPLATE_INDEX[$1]}
+}
+
+
+# Populate template image/text slots
+# 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"
+	[ -e "$tpl" ] \
+		|| return 1
+	local slots=( $(templateSlots "${tpl}") )
+	local text=$(cat "${tpl}")
+
+	# items/img/txt...
+	shift 2
+	local items=("$@")
+	if [ ${#items[@]} = 0 ] ; then
+		items=( $spread/* )
+	fi
+	local img=()
+	local txt=()
+	local elem
+	for elem in "${items[@]}" ; do
+		if [[ "${elem,,}" =~ $IMAGE_FORMATS ]] ; then
+			img+=("$elem")
+		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
+	local index=()
+	local captions=()
+	local name
+	# pass 1: images...
+	# NOTE: we are doing this in three passes as caption and image slots
+	#		can be included in the template in any order but the captions
+	#		need all the images to be fully populated/indexed (passes 1 
+	#		and 2), and text is done as a separate pass to prevent it 
+	#		from competing with captions.
+	local i=0
+	for var in ${slots[@]} ; do
+		name=${var//[0-9]/}
+		if [ ${name} != "IMAGE" ] ; then
+			continue
+		fi
+
+		val=${img[$i]}
+		# index images for caption retrieval...
+		index[${var/$name/}]="$val"
+		# warn if no image found for slot...
+		if [ -z ${val} ] ; then
+			echo %
+			{
+				echo "% WARNING: image #${i} requested but not found"
+				echo "%     in: ${tpl}"
+				echo "%     by: ${spread}"
+			} | tee >(cat >&2)
+			echo %
+		fi
+		i=$(( i + 1 ))
+
+		val=${val//\//\\/}
+		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
+			continue
+		fi
+
+		# get global caption...
+		val=$(getCaption "$spread" "${index[${var/$name/}]}" "${txt[@]}")
+
+		if [ -n "${val}" ] ; then
+			# clear the used texts... (XXX test)
+			for i in "${!txt[@]}" ; do
+				[ "$val" = "${txt[$i]}" ] \
+					&& unset "txt[$i]"
+			done
+			val=$(readCaption "${val}")
+		fi
+
+		text=$(echo "${text}" | \
+			sed "s/\${${var}}/${val}/g")
+	done
+
+	# pass 3: texts...
+	for var in ${slots[@]} ; do
+		name=${var//[0-9]/}
+		if [ ${name} = "CAPTION" ] || [ ${name} = "IMAGE" ] ; then
+			continue
+		fi
+
+		val=
+		for i in ${!txt[@]} ; do
+			# NOTE: we do not care as much if not text is found...
+			val=${txt[$i]}
+			unset "txt[$i]"
+			# we only need the first text...
+			break
+		done
+
+		val=${val//\//\\/}
+		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 "${text}"
+	return
+}
+
+
+# Handle/print spread...
+# usage:
+#	handleSpread SPREAD
+#
+# closure: $GRAPHICX_PATH, $IMAGE_HIRES_DIR, $IMAGE_SPREAD
+handleSpread(){
+	local spread="$1"
+	# skip non-spreads...
+	[ -d "$spread" ] \
+		|| return 1
+
+	# auto layout / templates...
+	# NOTE: to use a specific template just `touch <template-name>.tpl`
+	#	in the spread directory...
+
+	# layout tweaks...
+	local tweaks=($spread/*tweak.tex)
+	if ! [ -z ${tweaks} ] ; then
+		echo "% tweaks: ${tweaks[0]}"
+		cat ${tweaks[0]}
+	fi
+
+	# collect images and text...
+	# NOTE: we are filling these manually to support configurable 
+	#		image/text patterns...
+	local img=()
+	local txt=()
+	local items=()
+	for elem in "$spread"/* ; do
+		if [[ "${elem,,}" =~ $IMAGE_FORMATS ]] ; then
+			img+=("$elem")
+			items+=("$elem")
+		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...
+	elif ! [ -z $IMAGE_HIRES_DIR ] ; then
+		local C=0
+		for image in "${img[@]}" ; do
+			# skip non-images...
+			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}\" -> \"${target}\"" \
+					| tee >(cat >&2)
+				echo %
+			fi
+			C=$(( C + 1 ))
+		done
+	fi
+
+	# manual layout...
+	local template
+	local layout=( $spread/*layout.tex )
+	if ! [ -z $layout ] ; then
+		template=${layout[0]}
+
+	# templates and partial templates...
+	else
+		local template=( $spread/*.tpl )
+		# skip page template refs: *-imagepage.tpl / *-textpage.tpl
+		# XXX this will also eat 0-imagepage.tpl / 20-textpage.tpl -- do a better pattern...
+		if ! [ -z $template ] ; then
+			template=(`ls "$spread/"*.tpl \
+				| grep -E -v '.*-('${IMAGE_PAGE}'|'${TEXT_PAGE}')\.tpl'`)
+		fi
+		# no template explicitly defined -> match auto-template...
+		if [ -z $layout ] && [ -z $template ] ; then
+			# N images...
+			if [ -z $template ] && [ -n "${IMAGE_SPREAD[${#img[@]}]}" ] ; then
+				template=$(getTemplate "$spread" "${IMAGE_SPREAD[${#img[@]}]}")
+			fi
+			# build spread from pages...
+			if [ -z $template ] ; then
+				local C=0
+				local P
+				local elem
+				# only one page in spread...
+				# NOTE since the right page is more important we prioritize 
+				#		it over the left page, placing the blank left...
+				if [ ${#items[@]} = 1 ] ; then
+					C=1
+					echo "%"
+					echo "% empty page..."
+					template=$(getTemplate "$spread" "$EMPTY_PAGE")
+					if [ -z "$teplate" ] ; then
+						echo "\\null"
+						echo "\\newpage"
+					else
+						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")
+
+					# image...
+					if [[ "${elem,,}" =~ $IMAGE_FORMATS ]] ; then
+						echo %
+						echo "% $P page (image)..."
+						template=`getTemplate "$spread" "$IMAGE_PAGE"`
+						populateTemplate "$spread" "$template" 
+					# text...
+					else
+						echo %
+						echo "% $P page (text)..."
+						template=$(getTemplate "$spread" "$TEXT_PAGE")
+						populateTemplate "$spread" "$template" 
+					fi
+					# reset for next page...
+					template=
+					# ignore the rest of the items when we are done 
+					# creating two pages...
+					if [ $C == 2 ] ; then
+						populateTemplate_img=
+						populateTemplate_txt=
+						return
+					fi
+				done
+			fi
+		fi
+		# formatting done...
+		[ -z $template ] \
+			&& return
+
+		# 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 $?
+}
+
+
+# Add pdf notes with image path used in template
+# usage:
+#	anotatePath PATH
+#
+anotatePath(){
+	if [ -z "$1" ] || [ -z "$ANOTATE_IMAGE_PATHS" ] ; then
+		return
+	fi
+	path=$(basename ${1%.*})
+	# NOTE: did not figure out how to make a verbatim comment in latex 
+	#		so here we are, doing it in shell...
+	path=${path//_/\\_}
+	#echo "\\pdfmargincomment{Image: $path}%"
+	echo "\\pdfcommentcell{Image: $path}%"
+}
+
+
+
+#----------------------------------------------------------------------
+# generate the template...
+
+echo %----------------------------------------------------------------------
+echo %
+echo % WARNING: This file is auto-generated by make-spreads.sh and will be 
+echo "%          overwritten on next run..."
+echo %
+echo "% Image source (preview): \"$SPREADS_DIR\""
+echo "% Image source (hi-res): \"$IMAGE_HIRES_DIR\""
+echo %
+echo %----------------------------------------------------------------------
+echo %
+
+l=$(ls "$SPREADS_DIR/" | wc -l)
+c=0
+d=0
+SPREADS=("$(ls "${SPREADS_DIR}" | sort -n)")
+for spread in ${SPREADS[@]} ; do
+	spread="${SPREADS_DIR}/${spread}"
+
+	# skip non-spreads...
+	if ! [ -d "$spread" ] ; then
+		l=$(( l - 1 ))
+		continue
+	# skip temporarily disabled...
+	elif [[ "${spread}" =~ [\\\/]-.*$ ]] ; then
+		SKIP_FIRST=1
+		echo "% spread: ${spread}: skipped..." | tee >(cat >&2)
+		continue
+	fi
+
+	c=$(( c + 1 ))
+
+	# if $FROM is given print only stuff in range...
+	[ -z $FROM ] \
+		|| if (( $(( c - 1 )) < $FROM )) || (( $c > $STOP )) ; then
+			continue
+		fi
+
+	# if we are building only a specific spread...
+	##if ! [ -z $SPREAD ] && [[ "$spread" != "$SPREADS_DIR/$SPREAD" ]]; then
+	##	continue
+	##fi
+
+	if ! [ -z $SKIP_FIRST ] ; then
+		echo %
+		echo %
+		echo % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+	fi
+	SKIP_FIRST=1
+
+	printf "Spread ($c/$l): ${spread}                         \r" >&2
+	echo "% spread: ${spread}"
+	handleSpread "$spread"
+
+	d=$(( d + 1 ))
+done
+
+echo %
+echo %
+echo %
+echo %----------------------------------------------------------------------
+echo
+
+echo "Spread created: $d of $l                                         " >&2
+
+
+
+#----------------------------------------------------------------------
+#                                            vim:set ts=4 sw=4 nowrap :

talks/20230225 - Presentation at Orlov's/Makefile

@@ -57,10 +57,14 @@ endif
 %.pdf: %.tex $(SETUP)
 	-$(CMD) $< $(STDERR)
 
+# XXX need to figure this out with patterns...
+photobook-slides-en.pdf: $(COMPONENTS) 
 
-photobook-slides.pdf: $(COMPONENTS) 
+photobook-slides-ru.pdf: $(COMPONENTS) 
 
-photobook-slides-web.pdf: photobook-slides.pdf
+photobook-web-en.pdf: photobook-slides-en.pdf
+
+photobook-web-ru.pdf: photobook-slides-ru.pdf
 
 
 #----------------------------------------------------------------------
@@ -72,10 +76,10 @@ photobook-slides-web.pdf: photobook-slides.pdf
 all: web
 
 .PHONY: slides
-slides: photobook-slides.pdf $(IMAGES)
+slides: photobook-slides-en.pdf photobook-slides-ru.pdf $(IMAGES)
 
 .PHONY: web
-web: photobook-slides-web.pdf slides 
+web: photobook-web-en.pdf photobook-web-ru.pdf slides 
 
 .PHONY: components
 components: $(COMPONENTS)

talks/20230225 - Presentation at Orlov's/README.md

@@ -15,11 +15,11 @@ $ make all sweep
 ```
 
 Generated pdf's:
-- `photobook-slides.pdf`  
+- `photobook-slides-en.pdf` / `photobook-slides-ru.pdf`  
   The actual slides used for the talk. These require a pdf viewer that
   supports "book mode" and the "two-page view", and preferably good enough 
   maners not to ignore the settings set in the file.
-- `photobook-slides-web.pdf`  
+- `photobook-web-en.pdf` / `photobook-web-ru.pdf`  
   Compatibility version that sets one spread per page. This should work
   on any pdf viewer.
 

talks/20230225 - Presentation at Orlov's/hello-world.tex

@@ -1,5 +1,5 @@
 \documentclass[a5paper]{book}
-% Что-бы было видно страницу на сером фоне
+% make the page visible on a gray backdrop...
 \usepackage{xcolor}
 \usepackage{pagecolor}
 \pagecolor{white}

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

@@ -0,0 +1,656 @@
+%----------------------------------------------------------------------
+
+\documentclass[
+	layoutmode=block,
+	% make the spread 16x9...
+	blockwidth=96mm, blockheight=108mm,
+	bleed=0mm,
+	bindingoffset=0mm,
+	% image block configuration...
+	imageblockwidth=0.98, imageblockheight=0.98,
+	imageblockoffsettop=0mm,
+	% misc...
+	12pt,final,openany
+]{photobook}
+
+%\usepackage{xcolor}
+%\usepackage{pagecolor}
+\usepackage{anyfontsize}
+\usepackage{ragged2e}
+\usepackage{hyperref}
+\usepackage{cprotect}
+
+%\usepackage{listings}
+\usepackage{fancyvrb}
+
+\usepackage{ccicons}
+\usepackage{lipsum}
+
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\setlength\parindent{0pt}
+
+\writeimagelistfalse
+
+\pagestyle{empty}
+
+\pagecolor{white}
+
+
+%\fontsize{30pt}{36pt}\selectfont
+
+% fonts...
+\usepackage{fontspec}
+\setmainfont[Mapping=tex-text]{Open Sans}
+\setsansfont[Mapping=tex-text]{Open Sans}
+%\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}
+
+\def\captionsize{%
+	\fontsize{4pt}{5pt}\selectfont}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% Macros/templates...
+
+\def\TEX{%
+	{\fontfamily{lmr}\selectfont \TeX}}
+\def\LATEX{%
+	{\fontfamily{lmr}\selectfont \LaTeX}}
+
+\newcommand\PageFushRight[1]{
+	\begin{page}
+		\begin{cell}{2mm,2mm}{\paperwidth - 4mm}{\paperheight - 4mm}
+			\begin{flushright}
+				#1
+			\end{flushright}
+		\end{cell}
+	\end{page}}
+\newcommand\PageFushLeft[1]{
+	\begin{page}
+		\begin{cell}{2mm,2mm}{\paperwidth - 4mm}{\paperheight - 4mm}
+			\begin{flushleft}
+				#1
+			\end{flushleft}
+		\end{cell}
+	\end{page}}
+
+\newcommand\PageFushRightC[1]{
+	\begin{page}
+		\begin{cell}{2mm,2mm}{\paperwidth - 4mm}{\paperheight - 4mm}
+			\null
+			\vfill
+			\begin{flushright}
+				#1
+			\end{flushright}
+			\vfill
+			\null
+		\end{cell}
+	\end{page}}
+\newcommand\PageFushLeftC[1]{
+	\begin{page}
+		\begin{cell}{2mm,2mm}{\paperwidth - 4mm}{\paperheight - 4mm}
+			\null
+			\vfill
+			\begin{flushleft}
+				#1
+			\end{flushleft}
+			\vfill
+			\null
+		\end{cell}
+	\end{page}}
+
+
+
+
+\begin{document} %-----------------------------------------------------
+
+% cover...
+
+\ImagePageClear[clearance=28mm]{%
+	\begin{minipage}{\cellwidth}
+		\vspace{-1mm}
+		\begin{center}
+			\color{lightgray}
+			\hspace{-1.7mm}This is not a presentation, it's a well camoflaged book
+		\end{center}
+	\end{minipage}}{images/DSC00182}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% title...
+
+\ImageSpread[clearance=40mm]{}{images/latex}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% history...
+
+\PageFushRight{
+	\null
+	\vfill
+	\vspace{-12mm}
+	\section*{1978: TeX}%
+	\vspace{-4mm}
+	Donald Knuth
+
+	\section*{1984: LaTeX}%
+	\vspace{-4mm}
+	Leslie Lamport
+	\vfill
+	\fontsize{4pt}{5pt}\selectfont
+	\textbf{2021: photobook}
+
+	\fontsize{3.5pt}{4.5pt}\selectfont
+	Alex A. Naanou}
+
+\PageFushLeft{
+	\null
+	\vfill
+	\vspace{12mm}
+	\section*{1982: PostScript}%
+	\vspace{-4mm}
+	%John Warnock, Chuck Geschke, Doug Brotz, Ed Taft, Bill Paxton
+	Adobe Systems
+
+	\section*{1993: PDF}%
+	\vspace{-4mm}
+	Adobe Inc.
+	\vfill
+	\null}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% hello world...
+
+\begin{page}%
+\scriptsize%
+\vfill%
+\begin{center}%
+\BVerbatimInput{hello-world.tex}
+\end{center}%
+\vfill%
+\end{page}
+%
+\pagecolor{lightgray}
+\ImagePageClear{}{hello-world}
+\pagecolor{white}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% text layout...
+
+\begin{spreadtopages}
+	\vfill
+	\begin{center}
+		\section*{Text $+$ Boxes $\longrightarrow$ Pages}
+	\end{center}
+	\vfill
+\end{spreadtopages}
+\newpage
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% layout example...
+
+% left page...
+\begin{page}
+\fontsize{5pt}{5.5pt}\selectfont
+\vfill
+\begin{center}
+\begin{BVerbatim}
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus
+elit, vestibulum ut, placerat ac, adipiscing vitae, felis. Curabitur
+dictum gravida mauris. Nam arcu libero, nonummy eget, consectetuer
+id, vulputate a, magna. Donec vehicula augue eu neque. Pellentesque
+habitant morbi tristique senectus et netus et malesuada fames ac
+turpis egestas. Mauris ut leo. Cras viverra metus rhoncus sem. Nulla et
+lectus vestibulum urna fringilla ultrices. Phasellus eu tellus sit amet
+tortor gravida placerat. Integer sapien est, iaculis in, pretium quis,
+viverra ac, nunc. Praesent eget sem vel leo ultrices bibendum. Aenean
+faucibus. Morbi dolor nulla, malesuada eu, pulvinar at, mollis ac,
+nulla. Curabitur auctor semper nulla. Donec varius orci eget risus.
+Duis nibh mi, congue eu, accumsan eleifend, sagittis quis, diam. Duis
+eget orci sit amet orci dignissim rutrum.
+
+Nam dui ligula, fringilla a, euismod sodales, sollicitudin vel,
+wisi. Morbi auctor lorem non justo. Nam lacus libero, pretium at, lobortis
+vitae, ultricies et, tellus. Donec aliquet, tortor sed accumsan bibendum,
+erat ligula aliquet magna, vitae ornare odio metus a mi. Morbi ac orci et
+nisl hendrerit mollis. Suspendisse ut massa. Cras nec ante. Pellentesque
+a nulla. Cum sociis natoque penatibus et magnis dis parturient montes,
+nascetur ridiculus mus. Aliquam tincidunt urna. Nulla ullamcorper
+vestibulum turpis. Pellentesque cursus luctus mauris.
+\newpage
+\end{BVerbatim}
+\end{center}
+\vfill
+\null
+\end{page}
+
+% right page...
+{\tiny%
+	Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus
+	elit, vestibulum ut, placerat ac, adipiscing vitae, felis. Curabitur
+	dictum gravida mauris. Nam arcu libero, nonummy eget, consectetuer
+	id, vulputate a, magna. Donec vehicula augue eu neque. Pellentesque
+	habitant morbi tristique senectus et netus et malesuada fames ac
+	turpis egestas. Mauris ut leo. Cras viverra metus rhoncus sem. Nulla et
+	lectus vestibulum urna fringilla ultrices. Phasellus eu tellus sit amet
+	tortor gravida placerat. Integer sapien est, iaculis in, pretium quis,
+	viverra ac, nunc. Praesent eget sem vel leo ultrices bibendum. Aenean
+	faucibus. Morbi dolor nulla, malesuada eu, pulvinar at, mollis ac,
+	nulla. Curabitur auctor semper nulla. Donec varius orci eget risus.
+	Duis nibh mi, congue eu, accumsan eleifend, sagittis quis, diam. Duis
+	eget orci sit amet orci dignissim rutrum.
+
+	Nam dui ligula, fringilla a, euismod sodales, sollicitudin vel,
+	wisi. Morbi auctor lorem non justo. Nam lacus libero, pretium at, lobortis
+	vitae, ultricies et, tellus. Donec aliquet, tortor sed accumsan bibendum,
+	erat ligula aliquet magna, vitae ornare odio metus a mi. Morbi ac orci et
+	nisl hendrerit mollis. Suspendisse ut massa. Cras nec ante. Pellentesque
+	a nulla. Cum sociis natoque penatibus et magnis dis parturient montes,
+	nascetur ridiculus mus. Aliquam tincidunt urna. Nulla ullamcorper
+	vestibulum turpis. Pellentesque cursus luctus mauris.
+	\newpage}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% build...
+
+\begin{spreadtopages}
+	\vfill
+	\begin{center}
+		\section*{.tex $\longrightarrow$ .pdf}
+		\vspace{1.5em}
+		\hspace{1mm}
+		\includegraphics[keepaspectratio, height=0.5\cellheight]{images/commandline}
+		\hspace{4mm}
+		\includegraphics[keepaspectratio, height=0.5\cellheight]{images/TeXWorks}
+	\end{center}
+	\vfill
+\end{spreadtopages}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% Advantages / disadvanages
+
+\newcommand\seppoints{%
+	\par
+	\vspace{0.1em}}
+\PageFushRightC{
+	\section*{Advantages}
+	Simple templating
+	\seppoints
+	Handling large projects
+	\seppoints
+	Full support for everything needed
+	\seppoints
+	Documentation
+	\seppoints
+	Free and open source
+}
+\PageFushLeftC{
+	\vspace{-0.5em}
+	\section*{Disadvantages}
+	Not WYSIWYG
+	\seppoints
+	Harder to create graphics
+	\seppoints
+	Not as efficient for smaller tasks
+}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% Alternatives...
+
+\PageFushRightC{
+	\section*{Alternatives}
+	\vspace{1em}
+	\subsection*{Adobe:}
+	\vspace{-.7em}
+	InDesign / Illustrator / Photoshop / DPS }
+\PageFushLeftC{
+	\vspace{-0.5em}
+	\subsection*{OpenSource:}
+	\vspace{-.7em}
+	Scribus / Inkscape / Krita / Blender }
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% photobook...
+
+\begin{spreadtopages}
+	\vfill
+	\begin{center}
+		\fontsize{42pt}{45pt}\selectfont
+		photobook
+	\end{center}
+	\vfill
+\end{spreadtopages}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% differences to native LaTeX...
+
+\PageFushRightC{
+	\section*{in photobook}
+	\vspace{-7mm}
+	we can do:}
+
+\PageFushLeftC{
+		Bleeds
+
+		Pages
+
+		Spreads
+
+		Foldouts
+
+		Endpapers
+
+		Covers
+
+		Jackets
+}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\begin{page}
+\vfill
+\begin{center}
+\begin{BVerbatim}
+\documentclass{photobook}
+\end{BVerbatim}
+\end{center}
+\vfill
+\null
+\end{page}
+
+\begin{page}%
+\begin{Verbatim}[tabsize=4]
+\documentclass[
+	layoutmode=block,
+	blockwidth=96mm, 
+	blockheight=108mm,
+	bleed=0mm,
+	bindingoffset=0mm,
+	imageblockwidth=0.98, 
+	imageblockheight=0.98,
+]{photobook}
+\end{Verbatim}
+\end{page}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\begin{page}%
+\vfill%
+\begin{center}%
+\scriptsize%
+\begin{BVerbatim}
+\ImagePageClear{Park}{images/DSC03759}
+\end{BVerbatim}
+\end{center}%
+\vfill%
+\null%
+\end{page}
+
+\ImagePageClear{Park}{images/DSC03759}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\begin{page}%
+\vfill%
+\begin{center}%
+\scriptsize%
+\begin{BVerbatim}
+\ImagePageFit{}{images/DSC02091}
+\end{BVerbatim}
+\end{center}%
+\vfill%
+\null%
+\end{page}
+
+\ImagePageFit{}{images/DSC02091}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\cprotEnv\begin{spreadtopages}%
+\normalsize
+\vfill%
+\begin{center}%
+\begin{BVerbatim}
+\ImageSpread{"Копейка под домом"}{images/DSC05647}
+\end{BVerbatim}
+\end{center}%
+\vfill%
+\null%
+\end{spreadtopages}
+
+\ImageSpread{"Копейка под домом"}{images/DSC05647}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\cprotEnv\begin{spreadtopages}%
+\normalsize
+\vfill%
+\begin{center}%
+\begin{BVerbatim}
+\ImageSpreadFitL{New year}{images/DSC03603a}
+\end{BVerbatim}
+\end{center}%
+\vfill%
+\null%
+\end{spreadtopages}
+
+\ImageSpreadFitL{New year}{images/DSC03603a}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+\cprotEnv\begin{spreadtopages}%
+\normalsize
+\vfill%
+\begin{center}%
+\begin{BVerbatim}
+\tweakimageoffsettop{5mm}
+\ImageSpreadFill{%
+	\color{lightgray}%
+	Pechatniki}{images/DSC06650}
+\end{BVerbatim}
+\end{center}%
+\vfill%
+\null%
+\end{spreadtopages}
+
+\tweakimageoffsettop{5mm}
+\ImageSpreadFill{%
+	\color{lightgray}%
+	Pechatniki}{images/DSC06650}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% templates...
+
+\begin{spreadtopages}
+	\vfill
+	\begin{center}
+		\section*{Template Templates}
+	\end{center}
+	\vfill
+\end{spreadtopages}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% cover...
+
+\begin{page}%
+\scriptsize%
+\vfill%
+\begin{center}%
+\begin{BVerbatim}
+\documentclass[
+	layoutmode=cover,
+	spinewidth=5mm,
+	spinefold=2mm,
+	coverflap=17mm,
+	coverboardgrow=0.5mm,
+	...
+]{photobook}
+\begin{document}
+
+\GenerateTemplate
+
+\end{document}
+\end{BVerbatim}
+\end{center}%
+\vfill%
+\null%
+\end{page}
+
+\pagecolor{lightgray}
+\ImagePageClear{}{photobook-cover}
+\pagecolor{white}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% jacket...
+
+\begin{page}%
+\scriptsize%
+\vfill%
+\begin{center}%
+\begin{BVerbatim}
+\documentclass[
+	layoutmode=jacket,
+	...
+	jacketflap=50mm,
+	jacketwrap=0.5mm,
+	...
+]{photobook}
+\begin{document}
+
+\GenerateTemplate
+
+\end{document}
+\end{BVerbatim}
+\end{center}%
+\vfill%
+\null%
+\end{page}
+
+\pagecolor{lightgray}
+\ImagePageClear{}{photobook-jacket}
+\pagecolor{white}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% endpaper...
+
+\begin{page}%
+\scriptsize%
+\vfill%
+\begin{center}%
+\begin{BVerbatim}
+\documentclass[
+	layoutmode=endpaper,
+	...
+]{photobook}
+\begin{document}
+
+\GenerateTemplate
+
+\end{document}
+\end{BVerbatim}
+\end{center}%
+\vfill%
+\null%
+\end{page}
+
+\pagecolor{lightgray}
+\ImagePageClear{}{photobook-endpaper}
+\pagecolor{white}
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% the future...
+
+\PageFushRightC{
+	Template for book boxes
+
+	More examples
+
+	Text book
+
+	Fixing bugs
+
+	Polishing and cleanup }
+\PageFushLeftC{
+	\section*{:The future} }
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% links...
+
+\newcommand\link[2]{
+	#1
+
+	\url{#2}
+	\vspace{1em}
+	\par}
+\PageFushRightC{
+	\link{\TEX Live}{https://www.tug.org/texlive/}
+	\link{\LATEX}{https://www.latex-project.org/} }
+\PageFushLeftC{
+	\link{photobook}{https://ctan.org/pkg/photobook}
+	\link{\TEX\space Wikipedia}{https://ru.wikipedia.org/wiki/TeX}
+	\link{\LATEX\space Wikipedia}{https://ru.wikipedia.org/wiki/LaTeX} }
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+% back cover / copyright...
+
+\cleartoleftpage
+\begin{pagecell}
+	\begin{center}
+		\null
+		\vfill
+		\par
+		\begin{minipage}{0.8\cellwidth}
+			\fontsize{3.3pt}{4pt}\selectfont
+			\ccbyncnd\space
+			All {\it photographs} are by Alex A. Naanou, and licenced under 
+			the Creative Commons, Attribution-NonCommercial-NoDerivatives 4.0 \\
+			(CC BY-NC-ND 4.0) \\
+			\url{https://creativecommons.org/licenses/by-nc-nd/4.0/} \\
+			\par
+			\ccCopy\space
+			The {\it source code} of this book is licensed under the New BSD License 
+			(BSD-3-clause) \\
+			\url{https://opensource.org/license/bsd-3-clause/} \\
+			\par
+			\ccPublicDomain\space
+			The {\it code listed} in this book can be treated as {\it Public Domain}. \\
+			\url{https://en.wikipedia.org/wiki/Public_domain} \\
+			\par
+			This book was designed and laid out using open source fonts and software
+			including: 
+				\href{https://fonts.google.com/specimen/Open+Sans}{Open Sans},
+				\href{https://ctan.org/pkg/photobook}{photobook} and 
+				\href{https://www.latex-project.org/}{\LATEX.} \\
+		\end{minipage}
+		\vspace{2em}
+	\end{center}
+\end{pagecell}
+
+
+
+%----------------------------------------------------------------------
+\end{document} %                                    vim:set ts=4 sw=4 :

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}
 

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

@@ -14,7 +14,7 @@
 
 \begin{document} % - - - - - - - - - - - - - - - - - - - - - - - - - - 
 
-\includepdf[pages={{},1-}, nup=2x1, delta=0.3mm 0.3mm]{photobook-slides}
+\includepdf[pages={{},1-}, nup=2x1, delta=0.3mm 0.3mm]{photobook-slides-en}
 
 
 %----------------------------------------------------------------------

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

@@ -0,0 +1,21 @@
+%----------------------------------------------------------------------
+
+\documentclass[
+	layoutmode=endpaper,
+	% make the spread 16x9...
+	blockwidth=96mm, blockheight=108mm,
+	bleed=0mm,
+	bindingoffset=0mm,
+	% misc...
+	12pt,final,openany
+]{photobook}
+
+\pagecolor{black}
+
+\begin{document} % - - - - - - - - - - - - - - - - - - - - - - - - - - 
+
+\includepdf[pages={{},1-}, nup=2x1, delta=0.3mm 0.3mm]{photobook-slides-ru}
+
+
+%----------------------------------------------------------------------
+\end{document} %                                    vim:set ts=4 sw=4 :