From f29ec27dab00a84d881e018cf497a0bf8ae2e588 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 11 Mar 2023 21:12:22 +0000 Subject: photobook (11mar23) git-svn-id: svn://tug.org/texlive/trunk@66551 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/doc/latex/photobook/photobook.pdf | Bin 140491 -> 140737 bytes .../doc/latex/photobook/scripts/README.md | 423 ++++++++++++ .../doc/latex/photobook/scripts/cls2tex.sh | 15 +- .../doc/latex/photobook/scripts/make-images.sh | 450 ------------ .../doc/latex/photobook/scripts/make-spreads.sh | 756 +++++++++++++++++++++ .../texmf-dist/tex/latex/photobook/photobook.cls | 107 ++- 6 files changed, 1259 insertions(+), 492 deletions(-) create mode 100644 Master/texmf-dist/doc/latex/photobook/scripts/README.md delete mode 100644 Master/texmf-dist/doc/latex/photobook/scripts/make-images.sh create mode 100644 Master/texmf-dist/doc/latex/photobook/scripts/make-spreads.sh diff --git a/Master/texmf-dist/doc/latex/photobook/photobook.pdf b/Master/texmf-dist/doc/latex/photobook/photobook.pdf index c10cb7eba2f..64778bbbf3a 100644 Binary files a/Master/texmf-dist/doc/latex/photobook/photobook.pdf and b/Master/texmf-dist/doc/latex/photobook/photobook.pdf 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 +=============== + + + +- [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) + + + + +--- + +`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. +└── ... +``` + + + +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 + + + +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. + + + + +#### Manual template selection + +A template can be selected manually by providing a file in the form: + +```bnf +.tpl +``` + +The content of this file is ignored and `templates/.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}` + Filled with image path. +- `${CAPTION}` / `${CAPTION}` + Filled with caption file content +- `${TEXT}` / `${TEXT}` + 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/ +├── .txt +└── ... +``` + +The captions folder name/location is controlled by the `$CAPTION_DIR` +environment variable. + + +Inline captions are also supported: +```bnf +pages/ +├── / +│   ├── ... +│   ├── 00-. +│   ├── 00-.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. + + + +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\@[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. -# .tpl -# indicates the spread template to use. -# if given the rest of the .tex files in -# directory are ignored. -# resolves to: -# templates/.tex -# fields: -# ${IMAGE0} -# ${CAPTION0} -# ${IMAGE1} -# ${CAPTION1} -# imagepage.tex -# image page template. -# fields: -# ${IMAGE} -# ${CAPTION} -# textpage.tex -# text page template. -# fields: -# ${TEXT} -# -imagepage.tpl -# -textpage.tpl -# indicates the image/text page template to use. -# ignored if explicit templates are given. -# image fields: -# ${IMAGE} -# ${CAPTION} -# text fields: -# ${TEXT} -# 00-.png -# image. -# if $IMAGE_HIRES_DIR is set then this will -# resolve to: -# $IMAGE_HIRES_DIR/ -# XXX hi-res substitution currently disabled. -# 01-.txt -# text. -# ... -# ... -# -# -# -# Env variables: -# IMAGE_HIRES_DIR= -# 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: -# -left.tpl -# -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 .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/ +# .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. +# .tpl +# indicates the spread template to use. +# if given the rest of the .tex files in +# directory are ignored. +# resolves to: +# templates/.tex +# fields: +# ${IMAGE0} +# ${CAPTION0} +# ${TEXT0} +# ... +# imagepage.tex +# image page template. +# fields: +# ${IMAGE} +# ${CAPTION} +# ${TEXT0} +# ... +# textpage.tex +# text page template. +# fields: +# ${TEXT} +# ... +# -imagepage.tpl +# -textpage.tpl +# indicates the image/text page template to use. +# ignored if explicit templates are given. +# fields: +# ${IMAGE} +# ${CAPTION} +# ${TEXT} +# ... +# 00-.png +# image. +# if $IMAGE_HIRES_DIR is set then this will +# resolve to: +# $IMAGE_HIRES_DIR/ +# supported formats: +# .jpeg, .png, .pdf, .svg, .eps +# (see $IMAGE_FORMATS) +# 00-.txt +# local image caption text. +# NOTE: this must be named the same as the image. +# 01-.txt +# text. +# ... +# ... +# +# +# Env variables: +# ANOTATE_IMAGE_PATHS= +# TEXT_FORMATS=|.. +# IMAGE_FORMATS=|.. +# SPREADS_DIR= +# IMAGE_HIRES_DIR= +# sets the path to which the hi-res images are resolved. +# CAPTION_DIR= +# TEMPLATE_DIR= +# EMPTY_PAGE= +# TEXT_PAGE= +# IMAGE_PAGE= +# IMAGE_SPREAD= +# +# +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# +# 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 .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\@[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=} %% \DescribeMacro{\jacketflap=} %% \DescribeMacro{\jacketflapfront=} @@ -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=} %% \DescribeMacro{\blockheight=} % @@ -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*}{, }{}{} ... \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*}(, ){}{} %\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*}} -- cgit v1.2.3