make-images.sh readme mostly done...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

scripts/README.md

@@ -2,10 +2,23 @@
 Support scripts
 ===============
 
-Scripts:
+<!-- TOC depthfrom:2 -->
-- [`make-images.sh`](#make-imagessh)
-- [`cls2tex.sh`](#cls2texsh)
 
+- [make-images.sh](#make-imagessh)
+	- [The process](#the-process)
+		- [Automatic template inference](#automatic-template-inference)
+		- [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-images.sh`
 ----------------
@@ -36,7 +49,7 @@ book/
 │   ├── image-image.tex
 │   ├── fullbleed.tex
 │   └── ...
-├── pages/  . . . . . . . . . . . . . . Main block layout.
+├── spreads/  . . . . . . . . . . . . . . Main block layout.
 │   ├── 00/ . . . . . . . . . . . . . . A basic spread.
 │   │   ├── tweaks.tex                  The spread template is built
 │   │   └── 0-DSC02432.jpg              automatically with tweaks.tex
@@ -89,32 +102,32 @@ $ make-images.sh --help
 
 ### The process
 
-XXX spreads vs. pages
+<!-- 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-images.sh` build them rather than trying to layout each
 spread individually.
 
-Here there are several ways to arrive at a book layout starting from the
+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 book layout it is good to at least have a basic
+When starting work on a layout it is good to at least have a basic
-understanding of it's:
+understanding of the book's:
-- book structure and how it may change,
+- structure and how it may change,
 - core templates,
 - exceptions from the above.
 
-In most cases all of the above will change, and the main goal of this
+In most cases all of the above will change in one way or another during
-stage is to make this change as simple as possible, the less effort is
+the project's lifespan, and the main goal of this stage is to make this 
-needed to prove the need for change the simpler and more effortless this
+change as simple as possible -- it's all about providing the freedom to 
-change will be -- it's all about providing the freedom to make changes
+make changes instead of growing work invested and thus making change 
-instead of locking oneself into the work/time already invested.
+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 
+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 
@@ -130,50 +143,137 @@ 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.
 
-There are two ways to approach this:
+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 template, usually an
+  These are typical pages that makeup a spread, usually an
-  image page (`imagepage.tex`) and a text page (`textpage.tex`),
+  image page (`imagepage.tex`), a text page (`textpage.tex`), and an
-  `make-images.sh` can combine them to build spreads automatically.
+  optional empty page (`emptypage.tex`), `make-images.sh` can combine 
-- Spread templates
+  them to build spreads automatically.
+- Spread templates  
   These typeset a spread and can be either automatically inferred from
   the structure or manually selected.
 
-Note that `photobook` provides a set of ready high level templates
-specifically designed for this approach.
-
 
 #### Automatic template inference
 
+If no explicit template is defined (see next section) `make-images.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-images.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-images.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
 
-#### Individual spread layouts 
+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
 
-```bnf
+A template is a LaTeX file with zero or more special fields defined.
-templates/
+
-├── <template-name>.tex
+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}}
-
-### Layout
-
-```bnf
-pages/
-├── <spread>/
-│   ├── tweaks.tex
-│   ├── layout.tex
-│   ├── <template-name>.tpl
-│   ├── 00-<image-name>.<ext>
-│   ├── 01-<text>.txt
-│   └── ...
-└── ...
 ```
 
 
@@ -206,10 +306,59 @@ An inline caption must have the same filename as the corresponding image
 but with a .txt extension.
 
 
-### Environment variables
+### Environment variables and configuration
-
+
+All the configuration options can be given in a configuration file as
+well as environment variables.
+
+Environment variables take precedence over the configuration file.
+
+The default `make-images.cfg` would look something like:
+```shell
+# if non-empty make-images.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
+        [1]=imagebleedleft
+        [2]=image-image
+)
+```
 
 
+---
 
 `cls2tex.sh`
 ------------

scripts/make-images.sh

@@ -31,7 +31,7 @@ shopt -s nullglob extglob
 #			simplify the work with writers.
 #			For this reason this takes priority over local captions (XXX revise).
 #		...
-#	$IMAGE_DIR/
+#	$SPREADS_DIR/
 #		$spread/
 #			tweaks.tex
 #				template tweaks.
@@ -113,7 +113,7 @@ shopt -s nullglob extglob
 #	ANOTATE_IMAGE_PATHS=
 #	TEXT_FORMATS=<ext>|..
 #	IMAGE_FORMATS=<ext>|..
-#	IMAGE_DIR=<path>
+#	SPREADS_DIR=<path>
 #	IMAGE_HIRES_DIR=<path>
 #		sets the path to which the hi-res images are resolved.
 #	CAPTION_DIR=<path>
@@ -151,7 +151,7 @@ ANOTATE_IMAGE_PATHS=${ANOTATE_IMAGE_PATHS:=}
 TEXT_FORMATS=${TEXT_FORMATS:=txt}
 IMAGE_FORMATS=${IMAGE_FORMATS:=jpeg|jpg|png|pdf|svg|eps}
 
-IMAGE_DIR=${IMAGE_DIR:=pages/}
+SPREADS_DIR=${SPREADS_DIR:=spreads/}
 IMAGE_HIRES_DIR=${IMAGE_HIRES_DIR:=}
 CAPTION_DIR=${CAPTION_DIR:=captions/}
 TEMPLATE_DIR=${TEMPLATE_DIR:=templates/}
@@ -203,7 +203,7 @@ printhelp(){
 	echo "              - path to search for captions (default: $CAPTION_DIR)."
 	echo
 	echo "Parameters:"
-	echo "  PATH        - path to root pages directory (default: $IMAGE_DIR)"
+	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"
@@ -290,9 +290,9 @@ done
 
 
 if [ -z $1 ] ; then
-	IMAGE_DIR=pages/
+	SPREADS_DIR=pages/
 else
-	IMAGE_DIR=$1/
+	SPREADS_DIR=$1/
 fi
 
 
@@ -692,18 +692,18 @@ 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 (preview): \"$SPREADS_DIR\""
 echo "% Image source (hi-res): \"$IMAGE_HIRES_DIR\""
 echo %
 echo %----------------------------------------------------------------------
 echo %
 
-l=$(ls "$IMAGE_DIR/" | wc -l)
+l=$(ls "$SPREADS_DIR/" | wc -l)
 c=0
 d=0
-SPREADS=("$(ls "${IMAGE_DIR}" | sort -n)")
+SPREADS=("$(ls "${SPREADS_DIR}" | sort -n)")
 for spread in ${SPREADS[@]} ; do
-	spread="${IMAGE_DIR}/${spread}"
+	spread="${SPREADS_DIR}/${spread}"
 
 	# skip non-spreads...
 	if ! [ -d "$spread" ] ; then
@@ -725,7 +725,7 @@ for spread in ${SPREADS[@]} ; do
 		fi
 
 	# if we are building only a specific spread...
-	##if ! [ -z $SPREAD ] && [[ "$spread" != "$IMAGE_DIR/$SPREAD" ]]; then
+	##if ! [ -z $SPREAD ] && [[ "$spread" != "$SPREADS_DIR/$SPREAD" ]]; then
 	##	continue
 	##fi