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

@@ -44,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

Makefile

@@ -43,9 +43,6 @@
 #----------------------------------------------------------------------
 # Config...
 
-.EXPORT_ALL_VARIABLES:
-
-
 # NOTE: this makes things run consistently on different systems including 
 # 		things like Android...
 SHELL := bash
@@ -88,8 +85,7 @@ endif
 
 # markdown dialect...
 #
-# XXX still needs some tweaking...
-MD_FORMAT ?= markdown_github
+MD_FORMAT ?= gfm
 
 
 # debug output...
@@ -176,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...
@@ -245,14 +226,10 @@ LN := cp -l
 
 # list of dependencies...
 #
-# NOTE: grep's -z flag generates a bunch if nulls that we need to clean 
-# 		out via tr.
 DEPENDS.txt: $(MODULE).cls
-	cat $< \
-		| grep -Ezo '\s*\\RequirePackage(\[[^]]*\])?\{[^}]*\}' \
-		| sed -e 's/.*{\(.*\)}/hard \1\n/' \
-		| grep -a hard \
-		| tr -d '\000' \
+	make depends \
+		| grep -v make \
+		| sed -e 's/^/hard /' \
 		> $@
 
 
@@ -265,6 +242,20 @@ 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...

README.md

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

examples/book/web.tex

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

examples/cliptocell-test.tex

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

examples/cover-template.tex

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

examples/cover.tex

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

examples/custom-spread.tex

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

examples/demo.tex

@@ -28,8 +28,8 @@
 
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-\edef\TestImage{DSC00403-2}
-\edef\TestImageV{DSC00403-2vert}
+\edef\TestImage{landscape}
+\edef\TestImageV{portrait}
 
 
 \newcommand\Chapter[1]{

examples/endpaper-template.tex

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

examples/endpaper.tex

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

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

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

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

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

examples/jacket.tex

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

examples/spread-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
 

photobook.cls

@@ -38,16 +38,30 @@
 %
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 %
+%
+% XXX ASAP: imagecell: photobook@imagecell@left and photobook@imagecell@top
+%		should explicitly account for clearence@left and clearence@top resp.
+% XXX ASAP: imagecell: clearance should have the same semantics as cliptocell 
+%		offsts... 
+%		(CLEARANCE)
+% XXX ASAP should cover/jacket/endpaper/spread cells set default cliptocell 
+%		bleeds???
+% XXX ASAP: should \blockwidth include \bindingoffset (current) or not???
+%		...currently I think that no, as \blockwidth indicates the outer 
+%		width of the block, and this poses the question:
+%			should \pagewidth include \bindingoffset???
 % XXX ASAP should cover/jacket/endpaper/spread templates/cells account
 %		for \bindingoffset (likely no) and/or \gutteroffset ???
 %		...especially relevant to endpaper/spread...
 % XXX ASAP revise how bleeds are handled by cells...
+%		...all cells should ignore bleeds unless explicitly stated 
+%		otherwise -- needs testing...
+%
 %
 % XXX captions behave in an odd way...
 %		the internal (macro) minipage for some reason does not affect text 
 %		justification while adding a minipage in the macro argument works
 %		as expected -- some odd input mode???
-% XXX Q: should \blockwidth include \bindingoffset (current) or not???
 % XXX revise \clearcaption / \captionclearpage...
 % XXX unify API -- see CellContent env...
 % XXX make this loadable both as a class and as a package...
@@ -75,12 +89,25 @@
 %			cell/cell* depend on absolute mode being set globally
 %
 %
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+%
+% Work around an issue with calc's \ratio{..}{..} breaking into an 
+% "Arythmetic overflow" when working with large images.
+% (see Issues section for more info)
+%
+% NOTE: if the error persists just make this smaller but note that the 
+%		smaller this gets the greater the error can be for very small 
+%		images
+%
+\def\CalcOverflowFactor{0.1}%
+
+
 %----------------------------------------------------------------------
 
 %%% NOTE: \def\<module-name>@[A-Z]+ macros will be visible to both the 
 %%%		code and the generated docs...
-\edef\photobook@FILEVERSION{v0.1.18}
-\edef\photobook@FILEDATE{2023-04-11}
+\edef\photobook@FILEVERSION{v0.1.31}
+\edef\photobook@FILEDATE{2024-07-19}
 
 
 %% \documentclass{ltxdoc}
@@ -118,8 +145,8 @@
 %%% \newcommand\DescribeGlobal[1]{%
 %%%	\DescribeMacro{#1}}
 %%
-%% \newcommand\LEGACY[1][]{\fbox{LEGACY #1}}
-%% \newcommand\EXPERIMENTAL[1][]{\fbox{EXPERIMENTAL #1}}
+%% \newcommand\LEGACY[1][]{\fbox{LEGACY\ifstrempty{#1}{}{ #1}}}
+%% \newcommand\EXPERIMENTAL[1][]{\fbox{EXPERIMENTAL\ifstrempty{#1}{}{ #1}}}
 %%
 %%% sections to new pages...
 %% \newcommand\sectionbreak{\Needspace{5\baselineskip}}
@@ -235,26 +262,27 @@
 %% \begin{minipage}{\textwidth}
 %% \begin{verbatim}
 %%
+%%   <-------------------------------------------------> paperwidth
 %%   <---> bleed                                   <---> bleed
-%%                                                 
-%%   + - - - - - - - - - - - - - - - - - - - - - - + - +   ^
-%%   .                                             .   .   | bleed
-%%   .   +-----------------------------------------+-----  v   .   .  ---
-%%   .   |                           ^       .  .  =   .
-%%   .   |   .   .   .   .   .   .   |   .   .  .  =   .               ^
-%%   .   |<-- blockwidth ------------------------->=   .               |
-%%   .   |   .                       |   .   .  .  =   .               |
-%%   .   |                           |       .  .  =   .       textheight
-%%   .   |   .             Page      |   .   .  .  =   .               |
-%%   .   |                      blockheight  .  .  =   .               |
-%%   .   |   .                       |   .   .  <--> bindingoffset     |
-%%   .   |                           |       .  .  =   .               |
-%%   .   |   .   .   .   .   .   .   |   .   <--> gutteroffset         v
-%%   .   |                           v       .  .  =   .
-%%   .   +-----------------------------------------+-----  ^   .   .  ---
-%%   .   .                                         .   .   | bleed
-%%   + - - - - - - - - - - - - - - - - - - - - - - + - +   v
-%%       .                                         .
+%%                                                              paperheight v
+%%   + - - - - - - - - - - - - - - - - - - - - - - + - +   ^   .   .   .   ---
+%%   .                                             .   .   | bleed          .
+%%   .   +-----------------------------------------+-----  v   .   .  ---    
+%%   .   |                           ^       .  .  =   .                    .
+%%   .   |   .   .   .   .   .   .   |   .   .  .  =   .               ^     
+%%   .   |<-- blockwidth ------------------------->=   .               |    .
+%%   .   |   .                       |   .   .  .  =   .               |     
+%%   .   |                           |       .  .  =   .       textheight   .
+%%   .   |   .             Page      |   .   .  .  =   .               |     
+%%   .   |                      blockheight  .  .  =   .               |    .
+%%   .   |   .                       |   .   .  <--> bindingoffset     |     
+%%   .   |                           |       .  .  =   .               |    .
+%%   .   |   .   .   .   .   .   .   |   .   <--> gutteroffset         v     
+%%   .   |                           v       .  .  =   .                    .
+%%   .   +-----------------------------------------+-----  ^   .   .  ---    
+%%   .   .                                         .   .   | bleed          .
+%%   + - - - - - - - - - - - - - - - - - - - - - - + - +   v   .   .   .   ---
+%%       .                                         .                        ^
 %%       |   <-- textwidth -------------->    .    |
 %%                                                 ^ gutter
 %%
@@ -265,6 +293,9 @@
 %% account for |\gutteroffset|, namely macros that do not display content 
 %% with bleeds.
 %%
+%% Also note that bleeds are included in \href{https://ctan.org/pkg/geometry}{geometry}'s 
+%% |\paperwidth| and |\paperheight|.
+%%
 % NOTE: if blockwidth/blockheight are set they will force recalculations 
 %		and overriding of the paperwidth/paperheight if they were changed
 %		by the user code anywhere between \documentclass[..]{photobook}
@@ -377,9 +408,10 @@
 %%
 %%          blockwidth            blockwidth
 %%       <--------------->     <--------------->
-%%     <-> coverboardgrow                      <-> coverboardgrow
-%%   <-> coverflap                             . <-> coverflap
-%%   . . .                                     . . .
+%%     <-> coverboardgrow.     .               <-> coverboardgrow
+%%   <-> coverflap       .     .               . <-> coverflap
+%%   . . .               .     .               . . .
+%%   .xx .               xx   xx               . xx.    ] fold marks
 %%   +-------------------++---++-------------------+    ---
 %%   | + - - - - - - - - ++ - ++ - - - - - - - - + |    --^ coverflap                
 %%   | . + - - - - - - - ++ - ++ - - - - - - - + . |    --^ coverboardgrow  
@@ -391,6 +423,7 @@
 %%   | . + - - - - - - - ++ - ++ - - - - - - - + . |    --v coverboardgrow  
 %%   | + - - - - - - - - ++ - ++ - - - - - - - - + |    --v coverflap                 
 %%   +-------------------++---++-------------------+    ---
+%%    xx                 xx   xx                 xx     ] fold marks
 %%                        .   .
 %%                       ^.   .^ spinefold
 %%                        .   .
@@ -416,8 +449,9 @@
 %%   .   .                                           .   .
 %%   .   .     blockwidth            blockwidth      .   .
 %%   .   .  <--------------->     <--------------->  .   .
-%%   .   .<-> coverboardgrow                      <-> coverboardgrow
-%%   .   .  .                                     .  .   .
+%%   .   .<-> coverboardgrow.     .               <-> coverboardgrow
+%%   .   .  .               .     .               .  .   .
+%%   .   xx .               .x   x.               . xx   .    ] fold marks
 %%   +---++-----------------++---++-----------------++---+    ---
 %%   |   .. + - - - - - - - ++ - ++ - - - - - - - + ..   |    --^ coverboardgrow
 %%   |   .. .               ..   ..               . ..   |     ^
@@ -427,6 +461,7 @@
 %%   |   .. .               ..   ..               . ..   |     v
 %%   |   .. + - - - - - - - ++ - ++ - - - - - - - + ..   |    --v coverboardgrow
 %%   +---++-----------------++---++-----------------++---+    --- 
+%%       xx                  x   x                  xx        ] fold marks
 %%       ..                  .   .                  ..
 %%       ^ jacketwrap        .   .                  ^ jacketwrap
 %%                          ^.   .^ spinefold
@@ -900,7 +935,7 @@
 
 %% \DescribeMacro{\imageblockoffsettop=<ratio>}
 %
-%% The ration by which the image is raised in |\ImagePage{..}| and 
+%% The ratio by which the image is raised in |\ImagePage{..}| and 
 %% derived templates.
 %%
 \edef\imageblockoffsettop{\photobook@imageblockoffsettop}
@@ -942,7 +977,13 @@
 %% \DescribeMacro{\cellheight=<len>}
 %% \DescribeMacro{\celloffsetleft=<len>}
 %% \DescribeMacro{\celloffsettop=<len>}
-%% \DescribeMacro{\clearance=<len>}
+% XXX EXPERIMENTAL CLEARANCE
+%%% \DescribeMacro{\clearanceleft=<len>}
+%%% \DescribeMacro{\clearancetop=<len>}
+%%% \DescribeMacro{\clearanceright=<len>}
+%%% \DescribeMacro{\clearancebottom=<len>}
+% XXX revise...
+%%% \DescribeMacro{\clearances=<len's>}
 %
 %% Cell geometry. 
 %%
@@ -963,8 +1004,15 @@
 \setlength\celloffsetleft{0pt}
 \newlength\celloffsettop
 \setlength\celloffsettop{0pt}
-\newlength\clearance
-\setlength\clearance{0pt}
+\newlength\clearanceleft
+\setlength\clearanceleft{0pt}
+\newlength\clearancetop
+\setlength\clearancetop{0pt}
+\newlength\clearanceright
+\setlength\clearanceright{0pt}
+\newlength\clearancebottom
+\setlength\clearancebottom{0pt}
+\def\clearances{0pt}
 
 
 %% \DescribeMacro{\clearfoldoutgutter=<len>}
@@ -1069,6 +1117,7 @@
 		% layout: cover...
 		\ifcoverlayout
 			\pagestyle{empty}%
+			% XXX should spinefolds be panels???
 			\setsepchar{,}%
 			\readlist*\pagefoldpanels{%
 				\the\coverflap,
@@ -1102,12 +1151,12 @@
 				\the\jacketwrap,
 				\the\dimexpr
 					\coverboardgrow
+					+ \spinefold
 					+ \pageblockwidth \relax,
-				\the\spinefold,
 				\the\spinewidth,
-				\the\spinefold,
 				\the\dimexpr
 					\coverboardgrow
+					+ \spinefold
 					+ \pageblockwidth \relax,
 				\the\jacketwrap,
 				\the\photobook@jacketflapfront@active}%
@@ -1124,6 +1173,7 @@
 		% layout: spread/endpaper...
 		\ifspreadlayout
 			\pagestyle{empty}%
+			\setsepchar{,}%
 			\readlist*\pagefoldpanels{%
 				\the\pageblockwidth,
 				\the\pageblockwidth}%
@@ -1454,6 +1504,9 @@
 %%
 %% Note that this may span more than one page if there is enough stuff 
 %% packed in.
+%% Also note that items within the page environment are placed in the 
+%% same way as in any normal page, for absolute placement use either
+%% specific cells/environments like |papercell| or more generic |call|.
 %%
 \newenvironment{page}{%
 	% XXX do we need \null here???
@@ -1537,8 +1590,8 @@
 	\end{adjustbox}}
 
 
-%M \DescribeEnv{CellContent}
-%M \DescribeEnv{CellContent*}
+%M \DescribeEnv{MinipageCellContent}
+%M \DescribeEnv{MinipageCellContent*}
 %
 %M \EXPERIMENTAL
 %M
@@ -1575,7 +1628,11 @@
 %% \DescribeMacro{\cellparentheight=<len>}
 %% \DescribeMacro{\celloffsettop=<len>}
 %% \DescribeMacro{\celloffsetleft=<len>}
-%% \DescribeMacro{\clearance=<len>}
+% XXX EXPERIMENTAL CLEARANCE
+%%% \DescribeMacro{\clearanceleft=<len>}
+%%% \DescribeMacro{\clearancetop=<len>}
+%%% \DescribeMacro{\clearanceright=<len>}
+%%% \DescribeMacro{\clearancebottom=<len>}
 %%
 %% A cell defines a set of contextual lengths:
 %%
@@ -1707,7 +1764,10 @@
 		\setlength\cellheight{\photobook@protect@h}%
 		\setlength\celloffsettop{0pt}%
 		\setlength\celloffsetleft{0pt}%
-		\setlength\clearance{0pt}%
+		\setlength\clearanceleft{0pt}%
+		\setlength\clearancetop{0pt}%
+		\setlength\clearanceright{0pt}%
+		\setlength\clearancebottom{0pt}%
 		%
 		\begin{MinipageCellContent}[\photobook@minipagecell@parentvalign]{minipagecell}%
 }{%
@@ -1817,6 +1877,9 @@
 %
 %% \EXPERIMENTAL
 %%
+%% This a cell wrapper for |adjustbox|.
+%%
+% XXX DOC
 \newenvironment{adjustcell*}[4][t]{%
 	\begin{adjustbox}{#2}%
 		\vspace{0pt}%
@@ -1959,18 +2022,130 @@
 	\end{inlinecell*}%
 	\end{turn}}
 
+
 %% \DescribeEnv{cliptocell}
+%% \DescribeEnv{setcliptocellbleeds}
 %
 %% Clip content to parent cell.
 %%
-\newenvironment{cliptocell}{%
-	\begin{clipbox*}{0cm {\height - \cellheight} {\cellwidth} {\height}}%
-	\begin{minipage}[t][\cellheight][t]{\cellwidth}% 
-		\ignorespaces%
-}{%
-	\end{minipage}%
-	\end{clipbox*}}
+%%	>> \begin{cliptocell} ... \end{cliptocell}
+%%
+%% Clip content to cell plus offsets (bleeds) from each side
+%%
+%%	>> \begin{cliptocell}[<size>] ... \end{cliptocell}
+%%	>> \begin{cliptocell}[<horizontal> <vertical>] ... \end{cliptocell}
+%%	>> \begin{cliptocell}[<left> <bottom> <right> <top>] ... \end{cliptocell}
+%%
+%% Offset order, i.e. left-bottom-right-top is made consistent with 
+%% \href{https://ctan.org/pkg/graphicx}{graphicx} and 
+%% \href{https://ctan.org/pkg/trimclip}{trimclip} modules and represents 
+%% the bottom-left and top-right viewport point offsets from the parent 
+%% cell.
+%%
+%% |cliptocell| does not affect the cell content positioning in any way.
+%%
+%% This is designed to simplify filling template cells and adding bleeds 
+%% to certain sides and clipping flush to others, for example for cells 
+%% of a dust jacket or a foldout, but |cliptocell| is not limited to 
+%% this one use-case.
+%%
+\newlength\photobook@cliptocell@left
+\setlength\photobook@cliptocell@left{0mm}%
+\newlength\photobook@cliptocell@top
+\setlength\photobook@cliptocell@top{0mm}%
+\newlength\photobook@cliptocell@right
+\setlength\photobook@cliptocell@right{0mm}%
+\newlength\photobook@cliptocell@bottom
+\setlength\photobook@cliptocell@bottom{0mm}%
 
+\def\cliptocellbleeds{{0mm} {0mm} {0mm} {0mm}}%
+\def\cliptocellclearances{{0mm} {0mm} {0mm} {0mm}}%
+
+%% Set the default bleeds for |cliptocell| environments
+%%
+%%	>> \setcliptocellbleeds{<size>}
+%%	>> \setcliptocellbleeds{<horizontal> <vertical>}
+%%	>> \setcliptocellbleeds{<left> <bottom> <right> <top>}
+%%
+%% This will only affect |cliptocell| environments on the same level, 
+%% without affecting the nested |cliptocell|s.
+%%
+%%% \DescribeEnv{cliptocellbleeds=<left> <bottom> <right> <top>}
+%%% \DescribeEnv{cliptocellclearances=<left> <bottom> <right> <top>}
+%%%
+%%% Set by |\setcliptocellbleeds{..}| and contain bleeds and clearances (negative 
+%%% clipping bleeds) respectively, usable by imagecell and others.
+%%%
+%%% XXX still testing....
+\newcommand\setcliptocellbleeds[1]{
+	\setsepchar{ }%
+	\readlist*\photobook@cliptocell@bleeds{#1}%
+	\setsepchar{,}%
+	% args: size
+	\ifnum \photobook@cliptocell@bleedslen = 1%
+		\setlength\photobook@cliptocell@left{%
+			\photobook@cliptocell@bleeds[1]}%
+		\setlength\photobook@cliptocell@bottom{%
+			\photobook@cliptocell@bleeds[1]}%
+		\setlength\photobook@cliptocell@right{%
+			\photobook@cliptocell@bleeds[1]}%
+		\setlength\photobook@cliptocell@top{%
+			\photobook@cliptocell@bleeds[1]}\fi%
+	% args: horizontal vertical
+	\ifnum \photobook@cliptocell@bleedslen = 2%
+		\setlength\photobook@cliptocell@left{%
+			\photobook@cliptocell@bleeds[1]}%
+		\setlength\photobook@cliptocell@bottom{%
+			\photobook@cliptocell@bleeds[2]}%
+		\setlength\photobook@cliptocell@right{%
+			\photobook@cliptocell@bleeds[1]}%
+		\setlength\photobook@cliptocell@top{%
+			\photobook@cliptocell@bleeds[2]}\fi%
+	% args: left bottom right top
+	\ifnum \photobook@cliptocell@bleedslen = 4%
+		\setlength\photobook@cliptocell@left{%
+			\photobook@cliptocell@bleeds[1]}%
+		\setlength\photobook@cliptocell@bottom{%
+			\photobook@cliptocell@bleeds[2]}%
+		\setlength\photobook@cliptocell@right{%
+			\photobook@cliptocell@bleeds[3]}%
+		\setlength\photobook@cliptocell@top{%
+			\photobook@cliptocell@bleeds[4]}\fi%
+	% NOTE: trailing spaces here are significant...
+	% XXX should we use \the here?
+	%		...it makes things printable...
+	\def\cliptocellbleeds{%
+		{\the\photobook@cliptocell@left} %
+		{\the\photobook@cliptocell@bottom} %
+		{\the\photobook@cliptocell@right} %
+		{\the\photobook@cliptocell@top}}%
+	\def\cliptocellclearances{%
+		{-\the\photobook@cliptocell@left} %
+		{-\the\photobook@cliptocell@bottom} %
+		{-\the\photobook@cliptocell@right} %
+		{-\the\photobook@cliptocell@top}}}
+
+\newenvironment{cliptocell}[1][0mm]{%
+	\begingroup%
+		\setcliptocellbleeds{#1}
+		% NOTE: the spaces at the end of each line here are significant!!
+		\begin{trimbox}{{\photobook@cliptocell@left} %
+				{\photobook@cliptocell@bottom} %
+				{\photobook@cliptocell@right} %
+				{\photobook@cliptocell@top}}%
+		\begin{clipbox*}{{-\photobook@cliptocell@left} %
+				{\height - \cellheight - \photobook@cliptocell@bottom} %
+				{\cellwidth + \photobook@cliptocell@right} %
+				{\height + \photobook@cliptocell@top}}%
+		% set defaults for nested cells...
+		\setcliptocellbleeds{0mm}%
+		\begin{minipage}[t][\cellheight][t]{\cellwidth}% 
+			\ignorespaces%
+	}{%
+		\end{minipage}%
+		\end{clipbox*}%
+		\end{trimbox}%
+	\endgroup}
 
 
 %% \DescribeMacro{\imagecell\{..\}}
@@ -2061,7 +2236,9 @@
 %% Image |clearance|. This sets the amount of clearance around an image 
 %% (default: |0pt|).
 %%
-%%	>> \imagecell[clearance=-4mm]{}{<image>}
+%%	>> \imagecell[clearance=<size>]{}{<image>}
+%%	>> \imagecell[clearance=<horizontal> <vertical>]{}{<image>}
+%%	>> \imagecell[clearance=<left> <bottom> <top> <right>]{}{<image>}
 %%
 %% \begin{minipage}{\textwidth}
 %% \begin{verbatim}
@@ -2165,8 +2342,15 @@
 \def\photobook@imagecell@captiontop{0pt}
 \def\photobook@imagecell@captionleft{0pt}
 
-\newlength\photobook@imagecell@clearance
-\setlength\photobook@imagecell@clearance{0pt}
+% XXX EXPERIMENTAL
+\newlength\photobook@imagecell@clearance@left
+\setlength\photobook@imagecell@clearance@left{0pt}
+\newlength\photobook@imagecell@clearance@top
+\setlength\photobook@imagecell@clearance@top{0pt}
+\newlength\photobook@imagecell@clearance@right
+\setlength\photobook@imagecell@clearance@right{0pt}
+\newlength\photobook@imagecell@clearance@bottom
+\setlength\photobook@imagecell@clearance@bottom{0pt}
 
 % NOTE: these feel like a hack...
 \newlength\photobook@imagecell@imgratio
@@ -2181,15 +2365,19 @@
 \define@boolkey{imagecell@args}{center}[true]{%
 	\def\photobook@imagecell@top{\dimexpr 
 		+0.5\cellheight 
+		+0.5\photobook@imagecell@clearance@top
+		-0.5\photobook@imagecell@clearance@bottom
 		-0.5\ht\photobook@imagebox \relax}%
 	\def\photobook@imagecell@left{\dimexpr 
 		+0.5\cellwidth 
+		+0.5\photobook@imagecell@clearance@left
+		-0.5\photobook@imagecell@clearance@right
 		-0.5\wd\photobook@imagebox \relax}}%
 % left/right...
 % shortdands...
 \newcommand\photobook@imagecell@LEFT{%
 	\def\photobook@imagecell@left{\dimexpr%
-		+\photobook@imagecell@clearance \relax}%
+		+\photobook@imagecell@clearance@left \relax}%
 	\def\photobook@imagecell@captionleft{
 		% XXX not sure why this branch is needed...
 		\ifKV@imagecell@args@fit
@@ -2197,12 +2385,14 @@
 		\else%
 			\dimexpr%
 				+\cellwidth 
-				-\photobook@imagecell@clearance
+				-\photobook@imagecell@clearance@left
+				%-\photobook@imagecell@clearance
 				-\wd\photobook@imagebox \relax\fi}}%
 \newcommand\photobook@imagecell@RIGHT{%
 	\def\photobook@imagecell@left{\dimexpr 
 		+\cellwidth 
-		-\photobook@imagecell@clearance
+		-\photobook@imagecell@clearance@right
+		%-\photobook@imagecell@clearance
 		-\wd\photobook@imagebox \relax}
 	% XXX not sure why 0.5 but it seems to work...
 	\def\photobook@imagecell@captionleft{%
@@ -2226,7 +2416,7 @@
 % top/bottom...
 \define@boolkey{imagecell@args}{top}[true]{%
 	\def\photobook@imagecell@top{%
-		\photobook@imagecell@clearance}%
+		\photobook@imagecell@clearance@top}%
 	\def\photobook@imagecell@captiontop{%
 		-\dimexpr 
 			+\cellheight 
@@ -2235,15 +2425,53 @@
 	\def\photobook@imagecell@top{%
 		\dimexpr 
 			+\cellheight 
-			-\photobook@imagecell@clearance
+			-\photobook@imagecell@clearance@bottom
+			%-\photobook@imagecell@clearance
 			-\ht\photobook@imagebox \relax}%
 	\def\photobook@imagecell@captiontop{%
 		\dimexpr
 			\photobook@imagecell@top 
-			+\photobook@imagecell@clearance \relax}}%
+			+\photobook@imagecell@clearance@bottom \relax}}%
 % clearance=<len>...
+% clearance=<horizontal> <vertical>...
+% clearance=<left> <bottom> <right> <top>...
 \define@key{imagecell@args}{clearance}{%
-	\setlength\photobook@imagecell@clearance{#1}}%
+	% XXX EXPERIMENTAL
+	% XXX this is essentially the same as \photobook@cliptocell@bleeds -- unite...
+	\def\photobook@imagecell@clearances{#1}%
+	\setsepchar{ }%
+	\readlist*\photobook@imagecell@clearencelist{#1}%
+	\setsepchar{,}%
+	%% args: size
+	\ifnum \photobook@imagecell@clearencelistlen = 1%
+		\setlength\photobook@imagecell@clearance@left{%
+			\photobook@imagecell@clearencelist[1]}%
+		\setlength\photobook@imagecell@clearance@bottom{%
+			\photobook@imagecell@clearencelist[1]}%
+		\setlength\photobook@imagecell@clearance@right{%
+			\photobook@imagecell@clearencelist[1]}%
+		\setlength\photobook@imagecell@clearance@top{%
+			\photobook@imagecell@clearencelist[1]}\fi%
+	% args: horizontal vertical
+	\ifnum \photobook@imagecell@clearencelistlen = 2%
+		\setlength\photobook@imagecell@clearance@left{%
+			\photobook@imagecell@clearencelist[1]}%
+		\setlength\photobook@imagecell@clearance@bottom{%
+			\photobook@imagecell@clearencelist[2]}%
+		\setlength\photobook@imagecell@clearance@right{%
+			\photobook@imagecell@clearencelist[1]}%
+		\setlength\photobook@imagecell@clearance@top{%
+			\photobook@imagecell@clearencelist[2]}\fi%
+	% args: left bottom right top
+	\ifnum \photobook@imagecell@clearencelistlen = 4%
+		\setlength\photobook@imagecell@clearance@left{%
+			\photobook@imagecell@clearencelist[1]}%
+		\setlength\photobook@imagecell@clearance@bottom{%
+			\photobook@imagecell@clearencelist[2]}%
+		\setlength\photobook@imagecell@clearance@right{%
+			\photobook@imagecell@clearencelist[3]}%
+		\setlength\photobook@imagecell@clearance@top{%
+			\photobook@imagecell@clearencelist[4]}\fi}%
 
 % offsettop=<len> / offsetleft=<len>...
 % XXX DOC!!!
@@ -2291,10 +2519,12 @@
 					keepaspectratio, 
 					width=\photobook@imagecell@scale\dimexpr 
 						\cellwidth 
-						- ((\photobook@imagecell@clearance) * 2) \relax,
+						- \photobook@imagecell@clearance@left 
+						- \photobook@imagecell@clearance@right \relax,
 					height=\photobook@imagecell@scale\dimexpr 
 						\cellheight 
-						- ((\photobook@imagecell@clearance) * 2) \relax]{#3}}%
+						- \photobook@imagecell@clearance@top 
+						- \photobook@imagecell@clearance@bottom \relax]{#3}}%
 		% fill...
 		\else\ifKV@imagecell@args@fill%
 			% preload image to get its proportions...
@@ -2303,8 +2533,9 @@
 			% NOTE: here we calculate image/cell eccentricity to decide 
 			%		to fit to width or heigh of cell...
 			% NOTE: did I say that I "love" how LaTeX does basic math??
+			% NOTE: \ratio{..}{..} here can break, see Issues for more info...
 			\setlength\photobook@imagecell@imgratio{%
-				1pt * \ratio{\wd\photobook@imagebox}{\ht\photobook@imagebox}}%
+				1pt * \ratio{\CalcOverflowFactor\wd\photobook@imagebox}{\CalcOverflowFactor\ht\photobook@imagebox}}%
 			\setlength\photobook@imagecell@cellratio{%
 				1pt * \ratio{\cellwidth}{\cellheight}}%
 			\ifdim \photobook@imagecell@imgratio < \photobook@imagecell@cellratio%
@@ -2312,15 +2543,17 @@
 					\includegraphics[%
 						keepaspectratio, 
 						width=\photobook@imagecell@scale\dimexpr 
-							+ \cellwidth
-							- ((\photobook@imagecell@clearance) * 2) \relax]{#3}}%
+							\cellwidth
+							- \photobook@imagecell@clearance@left
+							- \photobook@imagecell@clearance@right \relax]{#3}}%
 			\else%
 				\sbox{\photobook@imagebox}{%
 					\includegraphics[%
 						keepaspectratio, 
 						height=\photobook@imagecell@scale\dimexpr 
-							+ \cellheight 
-							- ((\photobook@imagecell@clearance) * 2) \relax]{#3}}%
+							\cellheight 
+							- \photobook@imagecell@clearance@top
+							- \photobook@imagecell@clearance@bottom \relax]{#3}}%
 		\fi\fi\fi%
 		%
 		\setlength\celloffsetleft{%
@@ -2363,7 +2596,11 @@
 			\maxdim{\celloffsetleft}{0pt}}%
 		\setlength\celloffsettop{%
 			\maxdim{\celloffsettop}{0pt}}%
-		\setlength\clearance{\photobook@imagecell@clearance}%
+		\setlength\clearanceleft{\photobook@imagecell@clearance@left}
+		\setlength\clearancetop{\photobook@imagecell@clearance@top}
+		\setlength\clearanceright{\photobook@imagecell@clearance@right}
+		\setlength\clearancebottom{\photobook@imagecell@clearance@bottom}
+		\def\clearances{\photobook@imagecell@clearences}
 		% clear parent...
 		% XXX might be a good idea to put this into a special reusable cell...
 		\ifphotobook@imagecell@captionclearparent%
@@ -2822,8 +3059,13 @@
 						- \photobook@captionblockcell@spacing
 						- \cellwidth 
 						- \clearcaption 
+						% XXX EXPERIMENTAL CLEARANCE
 						% XXX this is only present in images...
-						- \clearance \relax%
+						- \clearanceleft
+						%- \clearanceright
+						% XXX LEGACY CLEARANCE
+						%- \clearance 
+					\relax%
 				\else%
 					\photobook@captionblockcell@width\fi}%
 			\setlength\cellparentwidth{%
@@ -2949,10 +3191,6 @@
 %% but will not affect this either in size (block size) or in position 
 %% (top-left).
 %%
-%\newenvironment{pagecell}{%
-%	\begin{cell*}{\bleed,\bleed}{\pageblockwidth}{\pageblockheight}%
-%}{%
-%	\end{cell*}}
 \newenvironment{pagecell}{%
 	\begin{cell*}{%
 			\bleed + \ifnumodd{\thepage}{\bindingoffset}{0pt},%
@@ -3473,6 +3711,7 @@
 	\begingroup%
 		\setsepchar{ }%
 		\readlist*\photobook@foldout@args{#1}%
+		\setsepchar{,}%
 		%
 		% defaults...
 		\setcounter{photobook@foldoutpanel}{1}
@@ -3611,6 +3850,7 @@
 	% parse args...
 	\setsepchar{-}%
 	\readlist*\photobook@foldoutcell@panels{#1}%
+	\setsepchar{,}%
 	%
 	% auto advance panel...
 	\ifnum \photobook@foldoutcell@panels[1] = 0%
@@ -3812,7 +4052,9 @@
 %%%%% Endpaper cells
 %
 %% \DescribeEnv{leftside}
+%% \DescribeEnv{leftside*}
 %% \DescribeEnv{rightside}
+%% \DescribeEnv{rightside*}
 %
 %% \begin{minipage}{\textwidth}
 %% \begin{verbatim}
@@ -3828,21 +4070,43 @@
 %% \end{verbatim}
 %% \end{minipage}
 %%
+%% The non-star versions will clip to bleeds except for the gutter side 
+%% that has no bleeds.
+%%
+%% The star versions will not clip.
+%%
 
 % XXX for some reason naming these anything starting with endpaper will
 %		make LaTeX complain that that is already defined...
 %		...collision with bools???
-\newenvironment{leftside}{%
-	\begin{pagecell}%
+\newenvironment{leftside*}{%
+	\begin{cell*}%
+			{\bleed, \bleed}%
+			{\pageblockwidth}{\pageblockheight}%
 }{%
-	\end{pagecell}}
+	\end{cell*}}
+\newenvironment{leftside}{%
+	\begin{leftside*}%
+	\begin{cliptocell}[{\bleed} {\bleed} 0mm {\bleed}]%
+		\setcliptocellbleeds{{\bleed} {\bleed} 0mm {\bleed}}%
+}{%
+	\end{cliptocell}
+	\end{leftside*}}
 
-\newenvironment{rightside}{%
+\newenvironment{rightside*}{%
 	\begin{cell*}%
 			{\bleed + \pageblockwidth, \bleed}%
 			{\pageblockwidth}{\pageblockheight}%
 }{%
 	\end{cell*}}
+\newenvironment{rightside}{%
+	\begin{rightside*}%
+	\begin{cliptocell}[0mm {\bleed} {\bleed} {\bleed}]%
+		\setcliptocellbleeds{0mm {\bleed} {\bleed} {\bleed}}%
+}{%
+	\end{cliptocell}
+	\end{rightside*}}
+
 
 
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -4021,6 +4285,14 @@
 
 % XXX Document metadata -- move to globals...
 % XXX Use LaTeX generic metadata...
+%% \DescribeMacro{BookType=<text>}
+%
+%% Used in page macro text to indicate the type of document built, by default
+%% this is set to |book| for the most common case but can be set to anything
+%% (e.g. |brochure|, |magazine|, |presentation|, ...etc.)
+%%
+\def\BookType{book}
+
 %% \DescribeMacro{BookTitle=<text>}
 \def\BookTitle{}
 %% \DescribeMacro{BookVersion=<text>}
@@ -4045,8 +4317,8 @@
 	Copyright \textcopyright \ \BookYear \ \BookAuthors; All Rights Reserved.
 
 	\ifx \License \empty%
-		No part of this book may be reproduced in any form without written permission
-		of the author except for use for brief quotation in a book review.
+		No part of this \BookType\ may be reproduced in any form without written permission
+		of the author except for use for brief quotation in a review.
 	\else%
 		\License\fi}
 
@@ -4056,7 +4328,7 @@
 \def\BookFonts{}
 %% \DescribeMacro{SoftwareNotice=<text>}
 \def\SoftwareNotice{%
-	This book was designed and laid out using open source 
+	This \BookType\ was designed and laid out using open source 
 	\ifx \BookFonts \empty\else
 		fonts and\fi 
 	software including: 
@@ -4595,8 +4867,9 @@
 		% align center -> check if image fits vertically...
 		\ifphotobook@ImagePageFit@centered\else%
 			\sbox{\photobook@imagebox}{\includegraphics{#3}}%
+			% NOTE: \ratio{..}{..} here can break, see Issues for more info...
 			\setlength\photobook@ImagePageFit@imgratio{%
-				1pt * \ratio{\wd\photobook@imagebox}{\ht\photobook@imagebox}}%
+				1pt * \ratio{\CalcOverflowFactor\wd\photobook@imagebox}{\CalcOverflowFactor\ht\photobook@imagebox}}%
 			% NOTE: subtracting \bindingoffset from \cellwidth here makes sure that
 			%		we avoid offsetting images close enough in ratio to the page and
 			%		messing up bleeds...
@@ -4611,7 +4884,8 @@
 			%\clearpage%
 			\begin{page}%
 			% NOTE: this does not account for \bindingoffset...
-			\begin{pagecell}%
+			% XXX should this be a page or a paper cell???
+			\begin{papercell}%
 				\imagecell[%
 					center, 
 					clearance=-\bleed, 
@@ -4620,7 +4894,7 @@
 					offsetleft=\imageoffsetleft,
 					captionclearparent=\captionclearpage,
 					#1]{#2}{#3}%
-			\end{pagecell}%
+			\end{papercell}%
 			\end{page}%
 		% special case: centered vertical image -> account for \bindingoffset...
 		\else%
@@ -5201,6 +5475,10 @@
 %%
 %% This is a no-op for |layoutmode=block|.
 %%
+%% To change text color set |\textcolor{<color>}| the usual way and for
+%% line and fill colors use |\textblockrulecolour{<color>}| and 
+%% |\textblockcolour{<colour>}| respecitvely.
+%%
 % XXX should digits/rounding be configurable???
 \newcommand\photobook@TemplateCell[2][mm]{
 	\begin{center}
@@ -5424,7 +5702,7 @@
 %% \DescribeMacro{\TEX}
 %% \DescribeMacro{\LATEX}
 %
-%% Convenience macros to display \TeX and \LaTeX in the correct font.
+%% Convenience macros to display \TeX\ and \LaTeX\ in the correct font.
 %%
 \def\TEX{%
 	{\fontfamily{lmr}\selectfont \TeX}}
@@ -5433,6 +5711,26 @@
 
 
 
+%----------------------------------------------------------------------
+%%%% Issues
+%
+%% \subsection*{Large images can cause ``Arythmetic overflow"}
+%
+%% \DescribeMacro{\CalcOverflowFactor=0.1}
+%
+%% If the issue occurs set |\CalcOverflowFactor| to a smaller value. 
+%% But note, a value too small can lead to errors in the affected macros, 
+%% a good value is between 0.1 and 0.01.
+%%
+%% Also note that it is recommended to pre-size images the print outside 
+%% of \LaTeX.
+%%
+%% Affected macros: |\imagecell[fill]{..}{..}|, |\ImagePageFit|.
+%%
+% The issue occurs in the calc's |\ratio{..}{..}| macro when calculating 
+% image proportions.
+%
+%
 %----------------------------------------------------------------------
 % Index...
 %

scripts/README.md

@@ -137,7 +137,7 @@ or multiples, ...etc.? At this stage this is about the presentation,
 the flow of the work and not about the actual design. How many typical 
 spreads (i.e. spread templates) should it have? A good number should be 
 small-ish, for example 3-4 spread templates is a good number, if you 
-count 10+ then you might be overcomplicating tings, but note, there are 
+count 10+ then you might be overcomplicating things, but note, there are 
 no rules, a book where each spread is individually and manually layed out 
 may work as well as a book with just a single template spread, but in 
 general for a photo book the focus is on the project and the layout 
@@ -344,6 +344,8 @@ IMAGE_FORMATS=jpeg|jpg|png|pdf|svg|eps
 SPREADS_DIR=spreads/
 
 # if non-empty link link images to matching ones from this directory...
+# NOTE: this is ignored if --graphicx-path is passed or GRAPHICX_PATH 
+#		is set.
 IMAGE_HIRES_DIR=
 
 # directory where external captions are stored...
@@ -370,6 +372,10 @@ IMAGE_SPREAD=(
         [0]=text-spread
         [2]=image-image
 )
+
+# if set (or --graphicx-path is passed) the images are identified by their
+# basename so as to let graphicx package resolve the paths internally.
+GRAPHICX_PATH=1
 ```
 
 An explicit configuration file can be manually specified:

scripts/cls2tex.sh

@@ -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
 			;;
 

scripts/make-spreads.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 shopt -s nullglob extglob
 
 #----------------------------------------------------------------------
@@ -56,9 +56,11 @@ ANOTATE_IMAGE_PATHS=${ANOTATE_IMAGE_PATHS:=}
 # supported formats/extensions...
 TEXT_FORMATS=${TEXT_FORMATS:=$CFG_TEXT_FORMATS}
 TEXT_FORMATS=${TEXT_FORMATS:=txt}
+TEXT_FORMATS=${TEXT_FORMATS,,}
 
 IMAGE_FORMATS=${IMAGE_FORMATS:=$CFG_IMAGE_FORMATS}
 IMAGE_FORMATS=${IMAGE_FORMATS:=jpeg|jpg|png|pdf|svg|eps}
+IMAGE_FORMATS=${IMAGE_FORMATS,,}
 
 
 SPREADS_DIR=${SPREADS_DIR:=$CFG_SPREADS_DIR}
@@ -130,6 +132,9 @@ printhelp(){
 	echo "              - text spread default template (default: ${IMAGE_SPREAD[0]})."
 	echo "  --captions PATH"
 	echo "              - path to search for captions (default: $CAPTION_DIR)."
+	echo "  --graphicx-path"
+	echo "              - reference images by their basenames and let graphicx manage"
+	echo "                searching."
 	echo
 	echo "Parameters:"
 	echo "  PATH        - path to root pages directory (default: $SPREADS_DIR)"
@@ -177,38 +182,50 @@ while true ; do
 		-a|--annotate)
 			ANOTATE_IMAGE_PATHS=1
 			shift
+			continue
 			;;
 		-c)
 			$CONFIG="$2"
 			[ -e "$CONFIG" ] \
 				&& source "$CONFIG"
 			shift 2
+			continue
 			;;
 
 		--templates)
 			TEMPLATE_DIR=$2
 			shift 2
+			continue
 			;;
 		--single-image-tpl)
 			IMAGE_SPREAD[1]=$2
 			shift 2
+			continue
 			;;
 		--double-image-tpl)
 			IMAGE_SPREAD[2]=$2
 			shift 2
+			continue
 			;;
 		--text-spread-tpl)
 			IMAGE_SPREAD[0]=$2
 			shift 2
+			continue
 			;;
 		--captions)
 			CAPTION_DIR=$2
 			shift 2
+			continue
+			;;
+		--graphicx-path)
+			GRAPHICX_PATH=1
+			shift
+			continue
 			;;
 
 		# handle unknown options...
 		-*|--*)
-			echo "Error: unknown option \"$1\""
+			echo "Error: unknown option \"$1\"" >&2
 			exit
 			;;
 
@@ -341,6 +358,12 @@ templateSlots(){
 # usage:
 #	populateTemplate SPREAD TEMPLATE ITEMS...
 #
+# closure: $populateTemplate_img, $populateTemplate_txt
+#
+# NOTE: this is the least hacky/ugly but could not figure out a better 
+#		way to update a list from within a function...
+populateTemplate_img=
+populateTemplate_txt=
 populateTemplate(){
 	local spread="$1"
 	local tpl="$2"
@@ -359,12 +382,22 @@ populateTemplate(){
 	local txt=()
 	local elem
 	for elem in "${items[@]}" ; do
-		if [[ "$elem" =~ $IMAGE_FORMATS ]] ; then
+		if [[ "${elem,,}" =~ $IMAGE_FORMATS ]] ; then
 			img+=("$elem")
-		elif [[ "$elem" =~ $TEXT_FORMATS ]] ; then
+		elif [[ "${elem,,}" =~ $TEXT_FORMATS ]] ; then
 			txt+=("$elem")
 		fi
 	done
+	local global_img=
+	if ! [ -z $populateTemplate_img ] ; then 
+		global_img=1
+		img=(${populateTemplate_img[@]})
+	fi
+	local global_txt=
+	if ! [ -z $populateTemplate_txt ] ; then
+		global_txt=1
+		txt=(${populateTemplate_txt[@]})
+	fi
 
 	local var
 	local val
@@ -403,6 +436,9 @@ populateTemplate(){
 		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
@@ -447,6 +483,9 @@ populateTemplate(){
 		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
@@ -459,7 +498,7 @@ populateTemplate(){
 # usage:
 #	handleSpread SPREAD
 #
-# closure: $IMAGE_HIRES_DIR, $IMAGE_SPREAD
+# closure: $GRAPHICX_PATH, $IMAGE_HIRES_DIR, $IMAGE_SPREAD
 handleSpread(){
 	local spread="$1"
 	# skip non-spreads...
@@ -484,30 +523,41 @@ handleSpread(){
 	local txt=()
 	local items=()
 	for elem in "$spread"/* ; do
-		if [[ "$elem" =~ $IMAGE_FORMATS ]] ; then
+		if [[ "${elem,,}" =~ $IMAGE_FORMATS ]] ; then
 			img+=("$elem")
 			items+=("$elem")
-		elif [[ "$elem" =~ $TEXT_FORMATS ]] ; then
+		elif [[ "${elem,,}" =~ $TEXT_FORMATS ]] ; then
 			txt+=("$elem")
 			items+=("$elem")
 		fi
 	done
 
+	# graphicx paths...
+	if ! [ -z $GRAPHICX_PATH ] ; then
+		local C=0
+		for image in "${img[@]}" ; do
+			local new=`basename ${image}`
+			new="${new#+([0-9])-}"
+			img[$C]=$new
+			C=$(( C + 1 ))
+		done
 	# get hi-res image paths...
-	if ! [ -z $IMAGE_HIRES_DIR ] ; then
+	elif ! [ -z $IMAGE_HIRES_DIR ] ; then
 		local C=0
 		for image in "${img[@]}" ; do
 			# skip non-images...
-			local new="$IMAGE_HIRES_DIR/`basename ${image/[0-9]-/}`"
+			local new=`basename ${image}`
+			new="$IMAGE_HIRES_DIR/${new#+([0-9])-}"
 			# ignore file ext for availability test...
 			# NOTE: the first match may be an unsupported format...
 			new="${new%.*}"
+			local target=$new
 			new=($new.*)
 			if [ -e "${new[0]}" ] ; then
 				img[$C]=${new[0]}
 			else
 				echo %
-				echo "% WARNING: hi-res image not found for: \"${image}\" -> \"${new}\"" \
+				echo "% WARNING: hi-res image not found for: \"${image}\" -> \"${target}\"" \
 					| tee >(cat >&2)
 				echo %
 			fi
@@ -528,7 +578,7 @@ handleSpread(){
 		# XXX this will also eat 0-imagepage.tpl / 20-textpage.tpl -- do a better pattern...
 		if ! [ -z $template ] ; then
 			template=(`ls "$spread/"*.tpl \
-				| egrep -v '.*-('${IMAGE_PAGE}'|'${TEXT_PAGE}')\.tpl'`)
+				| grep -E -v '.*-('${IMAGE_PAGE}'|'${TEXT_PAGE}')\.tpl'`)
 		fi
 		# no template explicitly defined -> match auto-template...
 		if [ -z $layout ] && [ -z $template ] ; then
@@ -556,43 +606,37 @@ handleSpread(){
 						cat "${template}"
 					fi
 				fi
+				populateTemplate_img=("${img[@]}")
+				populateTemplate_txt=("${txt[@]}")
+
 				for elem in "${items[@]}" ; do
 					C=$(( C + 1 ))
 					P=$([ $C == 1 ] \
 						&& echo "left" \
 						|| echo "right")
 
-					# XXX need to use populateTemplate here...
-					#		...to do this need to somehow remove the used
-					#		slots/files from list...
-
 					# image...
-					if [[ "$elem" =~ $IMAGE_FORMATS ]] ; then
+					if [[ "${elem,,}" =~ $IMAGE_FORMATS ]] ; then
 						echo %
 						echo "% $P page (image)..."
 						template=`getTemplate "$spread" "$IMAGE_PAGE"`
-						echo % template: $template
-						anotatePath "${elem}"
-						local caption=$(getCaption "$spread" "${elem}")
-						caption=$(readCaption "$caption")
-						cat "${template}" \
-							| sed -e "s%\${IMAGE0\?}%${elem%.*}%" \
-								-e "s%\${CAPTION0\?}%${caption}%"
+						populateTemplate "$spread" "$template" 
 					# text...
 					else
 						echo %
 						echo "% $P page (text)..."
 						template=$(getTemplate "$spread" "$TEXT_PAGE")
-						echo % template: $template
-						cat "${template}" \
-							| sed "s%\${TEXT}%${elem}%"
+						populateTemplate "$spread" "$template" 
 					fi
 					# reset for next page...
 					template=
 					# ignore the rest of the items when we are done 
 					# creating two pages...
-					[ $C == 2 ] \
-						&& return
+					if [ $C == 2 ] ; then
+						populateTemplate_img=
+						populateTemplate_txt=
+						return
+					fi
 				done
 			fi
 		fi
@@ -612,6 +656,8 @@ handleSpread(){
 		fi
 	fi
 
+	populateTemplate_img=
+	populateTemplate_txt=
 	populateTemplate "$spread" "$template" "${img[@]}" "${txt[@]}"
 
 	return $?

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

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

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

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