summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2023-03-11 21:12:22 +0000
committerKarl Berry <karl@freefriends.org>2023-03-11 21:12:22 +0000
commitf29ec27dab00a84d881e018cf497a0bf8ae2e588 (patch)
treee01e385074c1790dd7307c5ef018bc395ec563a9
parent400580f99b67f55b909ff92bfb4d02fb5524ed6d (diff)
photobook (11mar23)
git-svn-id: svn://tug.org/texlive/trunk@66551 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r--Master/texmf-dist/doc/latex/photobook/photobook.pdfbin140491 -> 140737 bytes
-rw-r--r--Master/texmf-dist/doc/latex/photobook/scripts/README.md423
-rwxr-xr-xMaster/texmf-dist/doc/latex/photobook/scripts/cls2tex.sh15
-rw-r--r--Master/texmf-dist/doc/latex/photobook/scripts/make-images.sh450
-rw-r--r--Master/texmf-dist/doc/latex/photobook/scripts/make-spreads.sh756
-rw-r--r--Master/texmf-dist/tex/latex/photobook/photobook.cls107
6 files changed, 1259 insertions, 492 deletions
diff --git a/Master/texmf-dist/doc/latex/photobook/photobook.pdf b/Master/texmf-dist/doc/latex/photobook/photobook.pdf
index c10cb7eba2f..64778bbbf3a 100644
--- a/Master/texmf-dist/doc/latex/photobook/photobook.pdf
+++ b/Master/texmf-dist/doc/latex/photobook/photobook.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/photobook/scripts/README.md b/Master/texmf-dist/doc/latex/photobook/scripts/README.md
new file mode 100644
index 00000000000..5970cfbb725
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/photobook/scripts/README.md
@@ -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.
+```
+
+
diff --git a/Master/texmf-dist/doc/latex/photobook/scripts/cls2tex.sh b/Master/texmf-dist/doc/latex/photobook/scripts/cls2tex.sh
index 8ec15ebf452..d7e6c1013ea 100755
--- a/Master/texmf-dist/doc/latex/photobook/scripts/cls2tex.sh
+++ b/Master/texmf-dist/doc/latex/photobook/scripts/cls2tex.sh
@@ -31,7 +31,7 @@ printhelp(){
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 @@ if [ -z $STRIP_DOC ] ; then
> "$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 @@ fi
#----------------------------------------------------------------------
-# vim:set ts=4 sw=4 nowrap :
+# vim:set ts=4 sw=4 nowrap :
diff --git a/Master/texmf-dist/doc/latex/photobook/scripts/make-images.sh b/Master/texmf-dist/doc/latex/photobook/scripts/make-images.sh
deleted file mode 100644
index bfec27d9782..00000000000
--- a/Master/texmf-dist/doc/latex/photobook/scripts/make-images.sh
+++ /dev/null
@@ -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 :
diff --git a/Master/texmf-dist/doc/latex/photobook/scripts/make-spreads.sh b/Master/texmf-dist/doc/latex/photobook/scripts/make-spreads.sh
new file mode 100644
index 00000000000..57be2ff448d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/photobook/scripts/make-spreads.sh
@@ -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 :
diff --git a/Master/texmf-dist/tex/latex/photobook/photobook.cls b/Master/texmf-dist/tex/latex/photobook/photobook.cls
index c5e4f8d925e..8f9da6cf24d 100644
--- a/Master/texmf-dist/tex/latex/photobook/photobook.cls
+++ b/Master/texmf-dist/tex/latex/photobook/photobook.cls
@@ -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,14 +67,17 @@
% - \CopyrightNotice
% - ...
% - info
+% XXX DOC add notes about external libs section:
+% - textpos
+% cell/cell* depend on absolute mode being set globally
%
%
%----------------------------------------------------------------------
%%% NOTE: \def\<module-name>@[A-Z]+ macros will be visible to both the
%%% code and the generated docs...
-\edef\photobook@FILEVERSION{v0.1.9}
-\edef\photobook@FILEDATE{2023-03-01}
+\edef\photobook@FILEVERSION{v0.1.10}
+\edef\photobook@FILEDATE{2023-03-11}
%% \documentclass{ltxdoc}
@@ -705,6 +710,8 @@
\newlength\coverflap
\setlength\coverflap{\photobook@coverflap}
+\newlength\photobook@coverflap@active
+
%% \DescribeMacro{\jacketwrap=<len>}
%% \DescribeMacro{\jacketflap=<len>}
%% \DescribeMacro{\jacketflapfront=<len>}
@@ -721,6 +728,11 @@
\newlength\jacketflapback
\setlength\jacketflapback{\photobook@jacketflapback}
+\newlength\photobook@jacketwrap@active
+\newlength\photobook@jacketflap@active
+\newlength\photobook@jacketflapfront@active
+\newlength\photobook@jacketflapback@active
+
%% \DescribeMacro{\blockwidth=<len>}
%% \DescribeMacro{\blockheight=<len>}
%
@@ -987,17 +999,28 @@
\def\pdfpagelayout{SinglePage}\fi
\else
\def\pdfpagelayout{\photobook@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@coverflap@active{\coverflap}
+ \else
+ \setlength\photobook@coverflap@active{0pt}\fi
+ \ifjacketlayout
+ \setlength\photobook@jacketwrap@active{\jacketwrap}
+ \setlength\photobook@jacketflap@active{\jacketflap}
+ % flaps...
+ \ifdim\jacketflapfront=0pt
+ \setlength\photobook@jacketflapfront@active{\photobook@jacketflap@active}
+ \else
+ \setlength\photobook@jacketflapfront@active{\jacketflapfront}\fi
+ \ifdim\jacketflapback=0pt
+ \setlength\photobook@jacketflapback@active{\photobook@jacketflap@active}
+ \else
+ \setlength\photobook@jacketflapback@active{\jacketflapback}\fi
+ \else
+ \setlength\photobook@jacketwrap@active{0pt}
+ \setlength\photobook@jacketflap@active{0pt}
+ \setlength\photobook@jacketflapfront@active{0pt}
+ \setlength\photobook@jacketflapback@active{0pt}\fi
% block size...
\ifdim\blockwidth=0pt
% layout: block...
@@ -1041,7 +1064,7 @@
\pagestyle{empty}%
\setsepchar{,}%
\readlist*\pagefoldpanels{%
- \the\jacketflapback,
+ \the\photobook@jacketflapback@active,
\the\jacketwrap,
\the\dimexpr
\coverboardgrow
@@ -1053,7 +1076,7 @@
\coverboardgrow
+ \pageblockwidth \relax,
\the\jacketwrap,
- \the\jacketflapfront}%
+ \the\photobook@jacketflapfront@active}%
\photobook@setpagefold{out}
\setlength\blockwidth{
\dimexpr
@@ -1062,8 +1085,8 @@
+ \spinewidth
+ 2\spinefold
+ 2\jacketwrap
- + \jacketflapfront
- + \jacketflapback \relax}\fi
+ + \photobook@jacketflapfront@active
+ + \photobook@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@jacketflapback@active
+ + \photobook@coverflap@active
+ + \photobook@jacketwrap@active
+ \coverboardgrow
+ \pageblockwidth
+ 2\spinefold
+ \spinewidth,
\bleed
- + \coverflap }%
+ + \photobook@coverflap@active }%
{ \pageblockwidth + \coverboardgrow }%
{ \pageblockheight + 2\coverboardgrow }%
}{%
@@ -3810,11 +3847,11 @@
\newenvironment{backcover}{%
\begin{cell*}{
\bleed
- + \jacketflapback
- + \coverflap
- + \jacketwrap,
+ + \photobook@jacketflapback@active
+ + \photobook@coverflap@active
+ + \photobook@jacketwrap@active,
\bleed
- + \coverflap }%
+ + \photobook@coverflap@active }%
{ \pageblockwidth + \coverboardgrow }%
{ \pageblockheight + 2\coverboardgrow }%
}{%
@@ -3826,14 +3863,14 @@
\newenvironment{spine}{%
\begin{cell*}{
\bleed
- + \jacketflapback
- + \coverflap
- + \jacketwrap
+ + \photobook@jacketflapback@active
+ + \photobook@coverflap@active
+ + \photobook@jacketwrap@active
+ \coverboardgrow
+ \pageblockwidth
+ \spinefold,
\bleed
- + \coverflap }%
+ + \photobook@coverflap@active }%
{ \spinewidth }%
{ \pageblockheight + 2\coverboardgrow }%
}{%
@@ -3854,15 +3891,15 @@
\newenvironment{frontflap}{%
\begin{cell*}{
\bleed
- + \jacketflapback
- + 2\jacketwrap
+ + \photobook@jacketflapback@active
+ + 2\photobook@jacketwrap@active
+ 2\coverboardgrow
+ 2\pageblockwidth
+ 2\spinefold
+ \spinewidth,
\bleed
- + \coverflap }%
- { \jacketflapfront }%
+ + \photobook@coverflap@active }%
+ { \photobook@jacketflapfront@active }%
{ \pageblockheight + 2\coverboardgrow }%
}{%
\end{cell*}}
@@ -3871,8 +3908,8 @@
\begin{cell*}{
\bleed,
\bleed
- + \coverflap }%
- { \jacketflapback }%
+ + \photobook@coverflap@active }%
+ { \photobook@jacketflapback@active }%
{ \pageblockheight + 2\coverboardgrow }%
}{%
\end{cell*}}