texlive[66551] Master/texmf-dist: photobook (11mar23)

commits+karl at tug.org commits+karl at tug.org
Sat Mar 11 22:12:22 CET 2023


Revision: 66551
          http://tug.org/svn/texlive?view=revision&revision=66551
Author:   karl
Date:     2023-03-11 22:12:22 +0100 (Sat, 11 Mar 2023)
Log Message:
-----------
photobook (11mar23)

Modified Paths:
--------------
    trunk/Master/texmf-dist/doc/latex/photobook/photobook.pdf
    trunk/Master/texmf-dist/doc/latex/photobook/scripts/cls2tex.sh
    trunk/Master/texmf-dist/tex/latex/photobook/photobook.cls

Added Paths:
-----------
    trunk/Master/texmf-dist/doc/latex/photobook/scripts/README.md
    trunk/Master/texmf-dist/doc/latex/photobook/scripts/make-spreads.sh

Removed Paths:
-------------
    trunk/Master/texmf-dist/doc/latex/photobook/scripts/make-images.sh

Modified: trunk/Master/texmf-dist/doc/latex/photobook/photobook.pdf
===================================================================
(Binary files differ)

Added: trunk/Master/texmf-dist/doc/latex/photobook/scripts/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/photobook/scripts/README.md	                        (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/photobook/scripts/README.md	2023-03-11 21:12:22 UTC (rev 66551)
@@ -0,0 +1,423 @@
+
+Support scripts
+===============
+
+<!-- TOC depthfrom:2 -->
+
+- [make-spreads.sh](#make-imagessh)
+	- [The process](#the-process)
+		- [Automatic template inferenceing](#automatic-template-inferenceing)
+		- [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 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-pages.tex.
+├── block-pages.tex . . . . . . . . . . The generated block content.
+├── cover.tex . . . . . . . . . . . . . Cover layout.
+├── jacket.tex  . . . . . . . . . . . . Dust jacket layout.
+└── ...
+```
+
+<!-- XXX
+For a live example see: ../examples/book -->
+
+Generate the block:
+```shell
+$ make-spreads.sh ./pages > block-pages.tex
+```
+
+Note that `make-spreads.sh` does not force a specific layout outside of 
+the `pages` directory, all paths are configurable. The way the root 
+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
+```
+
+
+### The process
+
+<!-- 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,
+- core templates,
+- exceptions from the above.
+
+In most cases all of the above will change in one way or another during
+the project's lifespan, and the main goal of this stage is to make this 
+change as simple as possible -- it's all about providing the freedom to 
+make changes instead of growing work invested and thus making change 
+more and more expensive.
+
+The first question is what is the _structure_ of the book we are making?
+Will it have chapters? How many? Text? how much, how should it be 
+structured? How are we going to deal with the title? How are we going 
+to present the images, full bleed, no bleeds, small, big, one per page 
+or multiple images, ...etc.? At this stage this is about the presentation 
+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 
+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.
+
+<!-- XXX do we need a `blankpage.tex` template??? -->
+
+
+#### 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.
+
+
+### 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
+pages/
+├── <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.
+
+<!-- XXX this is not true at the moment, not sure if this is a bug or a feature...
+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...
+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
+)
+```
+
+
+---
+
+`cls2tex.sh`
+------------
+
+Extract the documentation from photobook.cls which is used to build the 
+photobook.pdf reference manual.
+
+```shell
+$ cls2tex.sh --help
+```
+
+The `--help` says it all:
+```
+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.
+```
+
+


Property changes on: trunk/Master/texmf-dist/doc/latex/photobook/scripts/README.md
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/latex/photobook/scripts/cls2tex.sh
===================================================================
--- trunk/Master/texmf-dist/doc/latex/photobook/scripts/cls2tex.sh	2023-03-11 21:11:59 UTC (rev 66550)
+++ trunk/Master/texmf-dist/doc/latex/photobook/scripts/cls2tex.sh	2023-03-11 21:12:22 UTC (rev 66551)
@@ -31,7 +31,7 @@
 	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"
@@ -132,11 +132,12 @@
 		> "$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}/' \
+		| 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"
 
@@ -153,4 +154,4 @@
 
 
 #----------------------------------------------------------------------
-#                                           vim:set ts=4 sw=4 nowrap :
+#                                            vim:set ts=4 sw=4 nowrap :

Deleted: trunk/Master/texmf-dist/doc/latex/photobook/scripts/make-images.sh
===================================================================
--- trunk/Master/texmf-dist/doc/latex/photobook/scripts/make-images.sh	2023-03-11 21:11:59 UTC (rev 66550)
+++ trunk/Master/texmf-dist/doc/latex/photobook/scripts/make-images.sh	2023-03-11 21:12:22 UTC (rev 66551)
@@ -1,450 +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
-#		- add multiple images/captions...
-#
-#
-#
-#----------------------------------------------------------------------
-
-# 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 :

Added: trunk/Master/texmf-dist/doc/latex/photobook/scripts/make-spreads.sh
===================================================================
--- trunk/Master/texmf-dist/doc/latex/photobook/scripts/make-spreads.sh	                        (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/photobook/scripts/make-spreads.sh	2023-03-11 21:12:22 UTC (rev 66551)
@@ -0,0 +1,756 @@
+#!/bin/bash
+shopt -s nullglob extglob
+
+#----------------------------------------------------------------------
+# 
+# TIP: It is better to think of a visual book as a set of spreads 
+#		rather than a set of pages, hence the focus on spreads in the 
+#		code below.
+#		The main unit of a "visual" book is a spread, it's the thing 
+#		you see when you hold the book open, and the main workflow 
+#		when building a book is creating spreads and ordering them so 
+#		a single page is almost never treated as an independent unit.
+# TIP: it is not recommended to use too many templates, the layout 
+#		should be and feel structured and this structure should not be 
+#		too complex for the average reader to get comfortable in.
+# 
+#
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# 
+# Template structure:
+#	templates/
+#		spread.tex
+#		imagepage.tex
+#		textpage.tex
+#		...
+#	captions/
+#		<image>.txt
+#			image caption.
+#			this is separated to decouple caption writing from the 
+#			changes to the layout/sequencing and this drastically 
+#			simplify the work with writers.
+#			For this reason this takes priority over local captions (XXX revise).
+#		...
+#	$SPREADS_DIR/
+#		$spread/
+#			tweaks.tex
+#				template tweaks.
+#				loaded before the templates are handled.
+#			layout.tex
+#				manual layout of spread.
+#				if given rest of directory contents are 
+#				ignored.
+#				fields:
+#					${IMAGE0}
+#						replaced with image path
+#					${CAPTION0}
+#						replaced with content of caption file if found
+#						and empty otherwise.
+#					${TEXT0}
+#						replaced with the content of a text file if 
+#						found and empty otherwise.
+#					...
+#				NOTE: if images are included, hi-res source
+#					substitution is not done here.
+#				NOTE: fields are ordered and matched according to their
+#					position and not their number, e.g. in the following 
+#					sequence:
+#						IMAGE, IMAGE10, IMAGE20, ..,
+#						CAPTION2, CAPTION7, CAPTION12, ..
+#					IMAGE10 will be filled with the second found image 
+#					and CAPTION7 will be filled with the second found 
+#					caption.
+#			<spread-template-name>.tpl
+#				indicates the spread template to use.
+#				if given the rest of the .tex files in 
+#				directory are ignored.
+#				resolves to:
+#					templates/<spread-template-name>.tex
+#				fields:
+#					${IMAGE0}
+#					${CAPTION0}
+#					${TEXT0}
+#					...
+#			imagepage.tex
+#				image page template.
+#				fields:
+#					${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.
+#				fields:
+#					${IMAGE}
+#					${CAPTION}
+#					${TEXT}
+#					...
+#			00-<image>.png
+#				image.
+#				if $IMAGE_HIRES_DIR is set then this will 
+#				resolve to:
+#					$IMAGE_HIRES_DIR/<image>
+#				supported formats:
+#					.jpeg, .png, .pdf, .svg, .eps 
+#					(see $IMAGE_FORMATS)
+#			00-<image>.txt
+#				local image caption text.
+#				NOTE: this must be named the same as the image.
+#			01-<text>.txt
+#				text.
+#			...
+#		...
+#
+#
+# Env variables:
+#	ANOTATE_IMAGE_PATHS=
+#	TEXT_FORMATS=<ext>|..
+#	IMAGE_FORMATS=<ext>|..
+#	SPREADS_DIR=<path>
+#	IMAGE_HIRES_DIR=<path>
+#		sets the path to which the hi-res images are resolved.
+#	CAPTION_DIR=<path>
+#	TEMPLATE_DIR=<path>
+#	EMPTY_PAGE=<name>
+#	TEXT_PAGE=<name>
+#	IMAGE_PAGE=<name>
+#	IMAGE_SPREAD=<array>
+#
+#
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+#
+# XXX 
+#
+#
+#
+#----------------------------------------------------------------------
+
+# load config...
+CONFIG=${CONFIG:=$(basename ${0%.*}).cfg}
+[ -e $CONFIG ] \
+	&& source "$CONFIG"
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# 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:=}
+
+# supported formats/extensions...
+TEXT_FORMATS=${TEXT_FORMATS:=txt}
+IMAGE_FORMATS=${IMAGE_FORMATS:=jpeg|jpg|png|pdf|svg|eps}
+
+SPREADS_DIR=${SPREADS_DIR:=spreads/}
+IMAGE_HIRES_DIR=${IMAGE_HIRES_DIR:=}
+CAPTION_DIR=${CAPTION_DIR:=captions/}
+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:=emptypage}
+TEXT_PAGE=${TEXT_PAGE:=textpage}
+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
+	IMAGE_SPREAD=(
+		[0]=text-spread
+		[2]=image-image
+	)
+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 "  -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
+	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
+			;;
+
+		--templates)
+			TEMPLATE_DIR=$2
+			shift
+			shift
+			;;
+		--single-image-tpl)
+			IMAGE_SPREAD[1]=$2
+			shift
+			shift
+			;;
+		--double-image-tpl)
+			IMAGE_SPREAD[2]=$2
+			shift
+			shift
+			;;
+		--text-spread-tpl)
+			IMAGE_SPREAD[0]=$2
+			shift
+			shift
+			;;
+		--captions)
+			CAPTION_DIR=$2
+			shift
+			shift
+			;;
+
+		# handle unknown options...
+		-*|--*)
+			echo "Error: unknown option \"$1\""
+			exit
+			;;
+
+		*)
+			break
+			;;
+	esac
+done
+
+
+if [ -z $1 ] ; then
+	SPREADS_DIR=pages/
+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 TYPE=$2
+	local TEMPLATE=($SPREAD/*-$TYPE.tex)
+	if [ -z $TEMPLATE ] ; then
+		TEMPLATE=($SPREAD/*-$TYPE.tpl)
+		if ! [ -z $TEMPLATE ] ; then
+			TEMPLATE=${TEMPLATE/$SPREAD\//}
+			TEMPLATE=${TEMPLATE/[0-9]-/}
+			TEMPLATE="$TEMPLATE_DIR/${TEMPLATE[0]%-${TYPE}.*}.tex"
+		fi
+	fi
+	if [ -z $TEMPLATE ] ; then
+		 TEMPLATE="$TEMPLATE_DIR/${TYPE}.tex"
+	fi
+	if ! [ -e $TEMPLATE ] ; then
+		return
+	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...
+#
+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 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 -e "${text}" | \
+			sed "s/\${${var}}/${val%.*}/g")
+	done
+
+	# 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 -e "${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 -e "${text}" | \
+			sed "s/\${${var}}/${val}/g")
+	done
+
+	# print out the filled template...
+	echo % template: $tpl
+	echo -e "${text}"
+	return 0
+}
+
+
+# Handle/print spread...
+# usage:
+#	handleSpread SPREAD
+#
+# closure: $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
+
+	# get hi-res image paths...
+	if ! [ -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]-/}`"
+			# ignore file ext for availability test...
+			# NOTE: the first match may be an unsupported format...
+			new="${new%.*}"
+			new=($new.*)
+			if [ -e "${new[0]}" ] ; then
+				img[$C]=${new[0]}
+			else
+				echo %
+				echo "% WARNING: hi-res image not found for: \"${image}\" -> \"${new}\"" \
+					| 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 \
+				| egrep -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
+				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
+						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}%"
+					# text...
+					else
+						echo %
+						echo "% $P page (text)..."
+						template=$(getTemplate "$spread" "$TEXT_PAGE")
+						echo % template: $template
+						cat "${template}" \
+							| sed "s%\${TEXT}%${elem}%"
+					fi
+					# reset for next page...
+					template=
+					# ignore the rest of the items when we are done 
+					# creating two pages...
+					[ $C == 2 ] \
+						&& return 0
+				done
+			fi
+		fi
+		# formatting done...
+		[ -z $template ] \
+			&& return 0
+
+		# format template path...
+		template=${template/$spread\//}
+		template=${template/[0-9]-/}
+		# get...
+		template="${template[0]%.*}.tex"
+		if ! [ -e "$template" ] ; then
+			template="$TEMPLATE_DIR/${template[0]%.*}.tex"
+		fi
+	fi
+
+	populateTemplate "$spread" "$template" "${img[@]}" "${txt[@]}"
+
+	return 0
+}
+
+
+# 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 :


Property changes on: trunk/Master/texmf-dist/doc/latex/photobook/scripts/make-spreads.sh
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+LF
\ No newline at end of property
Modified: trunk/Master/texmf-dist/tex/latex/photobook/photobook.cls
===================================================================
--- trunk/Master/texmf-dist/tex/latex/photobook/photobook.cls	2023-03-11 21:11:59 UTC (rev 66550)
+++ trunk/Master/texmf-dist/tex/latex/photobook/photobook.cls	2023-03-11 21:12:22 UTC (rev 66551)
@@ -33,6 +33,8 @@
 %		to edit it directly, edit the source instead.
 %
 %
+% XXC FEATURE image spread: add ability to push image sides outward to
+%		account for gutter.,,
 % XXX revise \clearcaption / \captionclearpage...
 % XXX unify API -- see CellContent env...
 % XXX make this loadable both as a class and as a package...
@@ -65,6 +67,9 @@
 %			- \CopyrightNotice
 %			- ...
 %		- info
+% XXX DOC add notes about external libs section:
+%		- textpos
+%			cell/cell* depend on absolute mode being set globally
 %
 %
 %----------------------------------------------------------------------
@@ -71,8 +76,8 @@
 
 %%% NOTE: \def\<module-name>@[A-Z]+ macros will be visible to both the 
 %%%		code and the generated docs...
-\edef\photobook at FILEVERSION{v0.1.9}
-\edef\photobook at FILEDATE{2023-03-01}
+\edef\photobook at FILEVERSION{v0.1.10}
+\edef\photobook at FILEDATE{2023-03-11}
 
 
 %% \documentclass{ltxdoc}
@@ -705,6 +710,8 @@
 \newlength\coverflap
 \setlength\coverflap{\photobook at coverflap}
 
+\newlength\photobook at coverflap@active
+
 %% \DescribeMacro{\jacketwrap=<len>}
 %% \DescribeMacro{\jacketflap=<len>}
 %% \DescribeMacro{\jacketflapfront=<len>}
@@ -721,6 +728,11 @@
 \newlength\jacketflapback
 \setlength\jacketflapback{\photobook at jacketflapback}
 
+\newlength\photobook at jacketwrap@active
+\newlength\photobook at jacketflap@active
+\newlength\photobook at jacketflapfront@active
+\newlength\photobook at jacketflapback@active
+
 %% \DescribeMacro{\blockwidth=<len>}
 %% \DescribeMacro{\blockheight=<len>}
 %
@@ -987,17 +999,28 @@
 			\def\pdfpagelayout{SinglePage}\fi
 	\else
 		\def\pdfpagelayout{\photobook at pdfpagelayout}\fi
-	% items to ignore in different layouts...
-	\ifcoverlayout\else
-		\setlength\coverflap{0pt}\fi
-	\ifjacketlayout\else
-		\setlength\jacketwrap{0pt}
-		\setlength\jacketflap{0pt}\fi
-	% flaps...
-	\ifdim\jacketflapfront=0pt
-		\setlength\jacketflapfront{\jacketflap}\fi
-	\ifdim\jacketflapback=0pt
-		\setlength\jacketflapback{\jacketflap}\fi
+	% keep user settings but respect the current layout...
+	\ifcoverlayout
+		\setlength\photobook at coverflap@active{\coverflap}
+	\else
+		\setlength\photobook at coverflap@active{0pt}\fi
+	\ifjacketlayout
+		\setlength\photobook at jacketwrap@active{\jacketwrap}
+		\setlength\photobook at jacketflap@active{\jacketflap}
+		% flaps...
+		\ifdim\jacketflapfront=0pt
+			\setlength\photobook at jacketflapfront@active{\photobook at jacketflap@active}
+		\else
+			\setlength\photobook at jacketflapfront@active{\jacketflapfront}\fi
+		\ifdim\jacketflapback=0pt
+			\setlength\photobook at jacketflapback@active{\photobook at jacketflap@active}
+		\else
+			\setlength\photobook at jacketflapback@active{\jacketflapback}\fi
+	\else
+		\setlength\photobook at jacketwrap@active{0pt}
+		\setlength\photobook at jacketflap@active{0pt}
+		\setlength\photobook at jacketflapfront@active{0pt}
+		\setlength\photobook at jacketflapback@active{0pt}\fi
 	% block size...
 	\ifdim\blockwidth=0pt
 		% layout: block...
@@ -1041,7 +1064,7 @@
 			\pagestyle{empty}%
 			\setsepchar{,}%
 			\readlist*\pagefoldpanels{%
-				\the\jacketflapback,
+				\the\photobook at jacketflapback@active,
 				\the\jacketwrap,
 				\the\dimexpr
 					\coverboardgrow
@@ -1053,7 +1076,7 @@
 					\coverboardgrow
 					+ \pageblockwidth \relax,
 				\the\jacketwrap,
-				\the\jacketflapfront}%
+				\the\photobook at jacketflapfront@active}%
 			\photobook at setpagefold{out}
 			\setlength\blockwidth{
 				\dimexpr 
@@ -1062,8 +1085,8 @@
 					+ \spinewidth
 					+ 2\spinefold
 					+ 2\jacketwrap
-					+ \jacketflapfront
-					+ \jacketflapback \relax}\fi
+					+ \photobook at jacketflapfront@active
+					+ \photobook at jacketflapback@active \relax}\fi
 		% layout: endpaper...
 		\ifendpaperlayout
 			\pagestyle{empty}%
@@ -1386,6 +1409,7 @@
 %% packed in.
 %%
 \newenvironment{page}{%
+	% XXX do we need \null here???
 	\null%
 	\ignorespaces%
 }{%
@@ -1695,6 +1719,14 @@
 %
 %%	>> \begin{cell*}{<left>, <top>}{<width>}{<height>} ... \end{cell*}
 %%
+%% |cell| and |cell*| are absolutely positioned either relative to 
+%% the current page or to the closest savecell.
+%%
+% XXX should this have an explicit absolute/relative option???
+% XXX handle textpos's absolute option internally (+arg) ???
+%		- save external state
+%		- set internal state
+%		- reset bac to saved
 % XXX SYNTAX: place the second arg in braces...
 %		\begin{cell*}(<left>, <top>){<width>}{<height>}
 %\newenvironment{cell*}[3]{%
@@ -1772,6 +1804,11 @@
 %% |\gsavecell{..}| is the same as |\savecell{..}| but creates a global 
 %% cell.
 %%
+%% Note that both |\gsavecell{..}| and |\savecell{..}| make the nested
+%% |cell| and |cell*| position relative to the cell and not the page.
+%% This is done by setting |\TPoptions{absolute=false}| for the cell
+%% content which will also affect |textpos|'s macros.
+%%
 % XXX can/should we make this an env???
 % XXX should this be split into \newsavecell{..} and \scell{..} ???
 % XXX can we use root cells inside this???
@@ -3793,15 +3830,15 @@
 \newenvironment{frontcover}{%
 	\begin{cell*}{
 				\bleed 
-					+ \jacketflapback 
-					+ \coverflap 
-					+ \jacketwrap 
+					+ \photobook at jacketflapback@active
+					+ \photobook at coverflap@active
+					+ \photobook at jacketwrap@active
 					+ \coverboardgrow 
 					+ \pageblockwidth 
 					+ 2\spinefold 
 					+ \spinewidth,
 				\bleed 
-					+ \coverflap }%
+					+ \photobook at coverflap@active }%
 			{ \pageblockwidth + \coverboardgrow }%
 			{ \pageblockheight + 2\coverboardgrow }%
 }{%
@@ -3810,11 +3847,11 @@
 \newenvironment{backcover}{%
 	\begin{cell*}{
 				\bleed 
-					+ \jacketflapback 
-					+ \coverflap 
-					+ \jacketwrap,
+					+ \photobook at jacketflapback@active
+					+ \photobook at coverflap@active
+					+ \photobook at jacketwrap@active,
 				\bleed 
-					+ \coverflap }%
+					+ \photobook at coverflap@active }%
 			{ \pageblockwidth + \coverboardgrow }%
 			{ \pageblockheight + 2\coverboardgrow }%
 }{%
@@ -3826,14 +3863,14 @@
 \newenvironment{spine}{%
 	\begin{cell*}{
 				\bleed 
-					+ \jacketflapback 
-					+ \coverflap 
-					+ \jacketwrap 
+					+ \photobook at jacketflapback@active
+					+ \photobook at coverflap@active
+					+ \photobook at jacketwrap@active
 					+ \coverboardgrow 
 					+ \pageblockwidth 
 					+ \spinefold,
 				\bleed 
-					+ \coverflap }%
+					+ \photobook at coverflap@active }%
 			{ \spinewidth }%
 			{ \pageblockheight + 2\coverboardgrow }%
 }{%
@@ -3854,15 +3891,15 @@
 \newenvironment{frontflap}{%
 	\begin{cell*}{
 				\bleed 
-					+ \jacketflapback 
-					+ 2\jacketwrap 
+					+ \photobook at jacketflapback@active
+					+ 2\photobook at jacketwrap@active
 					+ 2\coverboardgrow 
 					+ 2\pageblockwidth 
 					+ 2\spinefold 
 					+ \spinewidth,
 				\bleed 
-					+ \coverflap }% 
-			{ \jacketflapfront }%
+					+ \photobook at coverflap@active }%
+			{ \photobook at jacketflapfront@active }%
 			{ \pageblockheight + 2\coverboardgrow }%
 }{%
 	\end{cell*}}
@@ -3871,8 +3908,8 @@
 	\begin{cell*}{
 				\bleed,
 				\bleed 
-					+ \coverflap }%
-			{ \jacketflapback }%
+					+ \photobook at coverflap@active }%
+			{ \photobook at jacketflapback@active }%
 			{ \pageblockheight + 2\coverboardgrow }%
 }{%
 	\end{cell*}}



More information about the tex-live-commits mailing list.