updated docs...

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

examples/cliptocell-test.tex

@@ -75,6 +75,16 @@
 \end{page}%
 
 \begin{page}%
+	\fbox{%
+		\begin{inlinecell*}{\cellsize}{\cellsize}%
+			% XXX this is offset by 1mm for some reason...
+			\imagecell[fit]{}{DSC00403-2}%
+		\end{inlinecell*}}%
+	\hspace{1cm}%
+	\fbox{%
+		\begin{inlinecell*}{\cellsize}{\cellsize}%
+			\imagecell[fit, clearance=-1mm -2mm -3mm -4mm]{}{DSC00403-2}%
+		\end{inlinecell*}}%
 \end{page}%
 
 

examples/cover.tex

@@ -50,6 +50,10 @@
 			\imagecell[fill, clearance=-\coverflap]{}{DSC00403-2}
 		\end{cliptocell}
 	\end{backcover}
+
+	\textblockrulecolour{white}
+	\textcolor{white}
+	\GenerateTemplate
 \end{page}
 
 \end{document}

examples/endpaper.tex

@@ -16,119 +16,48 @@
 
 \begin{document} % - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-\begin{page}
-	cliptocellclearances=\cliptocellclearances
-
-	\cliptocellbleeds{5pt}
-
-	cliptocellclearances=\cliptocellclearances
-
-	\cliptocellbleeds{1pt 2pt}
-
-	cliptocellclearances=\cliptocellclearances
-
-	\cliptocellbleeds{1pt 2pt 3pt 4pt}
-
-	cliptocellclearances=\cliptocellclearances
-\end{page}
-
-
-% XXX ignores layoutmode=endpaper....
+% the simplest way to fill...
 \ImagePageFill{}{DSC00403-2}
 
 
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-% XXX ignores layoutmode=endpaper....
+% manual...
+% NOTE: to fill the page the image cell needs to be placed relative to
+% 		the page (papercell / pagecell) and not the text (page env)
 \begin{page}
-\begin{pagecell}
-	\imagecell[fill]{}{DSC00403-2}
-\end{pagecell}
-\end{page}
-
-
-
-% XXX for some reason this is not centered correctly but scaling seems
-%		correct...
-\begin{page}
-	\imagecell[fill]{}{DSC00403-2}
+\begin{papercell}
+	\imagecell[fill, clearance=-\bleed]{}{DSC00403-2}
+\end{papercell}
 \end{page}
 
 
 
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-
+% control #1 -- works fine...
 \begin{page}
 \begin{leftside}
 	\imagecell[fit]{}{DSC00403-2}
 \end{leftside}
-\begin{rightside*}
-	\imagecell[fit, clearance=-\bleed]{}{DSC00403-2}
-\end{rightside*}
-\end{page}
-
-
-
-\begin{page}
-\begin{leftside}
-	\begin{cliptocell}
-		\imagecell[fit]{}{DSC00403-2}
-	\end{cliptocell}
-\end{leftside}
 \begin{rightside}
-	\begin{cliptocell}
 	\imagecell[fit]{}{DSC00403-2}
-	\end{cliptocell}
 \end{rightside}
 \end{page}
 
 
-
 \begin{page}
 \begin{leftside*}
-	\begin{cliptocell}
-		% XXX this breaks things....
-		%\imagecell[fit, clearance={-\bleed} {-\bleed} 0mm {-\bleed}]{}{DSC00403-2}
-		\imagecell[fit, clearance=-\bleed]{}{DSC00403-2}
-	\end{cliptocell}
+	\imagecell[fill, right, clearance=\cliptocellclearances]{}{DSC00403-2}
 \end{leftside*}
 \begin{rightside*}
-	\begin{cliptocell}
-		% XXX for some reason this is undefined here...
-		%\cliptocellclearances
-		% XXX \cliptocellclearances does not work yet... 
-		%\imagecell[fit, clearance=\cliptocellclearances]{}{DSC00403-2}
-		% XXX this does not seem to be forking correctly...
-		%		...looks like we are not accounting for clearance in offset...
-		\imagecell[fit, clearance={0pt} {-\bleed} {-\bleed} {-\bleed}]{}{DSC00403-2}
-	\end{cliptocell}
+	\imagecell[fill, left, clearance=\cliptocellclearances]{}{DSC00403-2}
 \end{rightside*}
 \end{page}
 
 
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-\begin{page}
-\begin{leftside}
-	\begin{cliptocell}
-		\imagecell[fill]{}{DSC00403-2}
-	\end{cliptocell}
-\end{leftside}
-\begin{rightside*}
-	\begin{cliptocell}
-		% XXX \cliptocellclearances does not work yet... 
-		%\imagecell[fill, clearance=\cliptocellclearances]{}{DSC00403-2}
-		% XXX this does not seem to be forking correctly...
-		%		...looks like we are not accounting for clearance in offset...
-		\imagecell[fill, clearance={0pt} {-\bleed} {-\bleed} {-\bleed}]{}{DSC00403-2}
-	\end{cliptocell}
-\end{rightside*}
-\end{page}
-
-
-
-
-
-\GenerateTemplate
 \GenerateTemplate
 
 

photobook.cls

@@ -93,7 +93,7 @@
 
 %%% NOTE: \def\<module-name>@[A-Z]+ macros will be visible to both the 
 %%%		code and the generated docs...
-\edef\photobook@FILEVERSION{v0.1.26}
+\edef\photobook@FILEVERSION{v0.1.28}
 \edef\photobook@FILEDATE{2023-08-24}
 
 
@@ -965,8 +965,8 @@
 %%% \DescribeMacro{\clearancetop=<len>}
 %%% \DescribeMacro{\clearanceright=<len>}
 %%% \DescribeMacro{\clearancebottom=<len>}
-% XXX LEGACY CLEARANCE
-%%% \DescribeMacro{\clearance=<len>}
+% XXX revise...
+%%% \DescribeMacro{\clearances=<len's>}
 %
 %% Cell geometry. 
 %%
@@ -987,7 +987,6 @@
 \setlength\celloffsetleft{0pt}
 \newlength\celloffsettop
 \setlength\celloffsettop{0pt}
-% XXX EXPERIMENTAL CLEARANCE
 \newlength\clearanceleft
 \setlength\clearanceleft{0pt}
 \newlength\clearancetop
@@ -997,9 +996,6 @@
 \newlength\clearancebottom
 \setlength\clearancebottom{0pt}
 \def\clearances{0pt}
-% XXX LEGACY CLEARANCE
-%\newlength\clearance
-%\setlength\clearance{0pt}
 
 
 %% \DescribeMacro{\clearfoldoutgutter=<len>}
@@ -1491,6 +1487,9 @@
 %%
 %% Note that this may span more than one page if there is enough stuff 
 %% packed in.
+%% Also note that items within the page environment are placed in the 
+%% same way as in any normal page, for absolute placement use either
+%% specific cells/environments like |papercell| or more generic |call|.
 %%
 \newenvironment{page}{%
 	% XXX do we need \null here???
@@ -1617,8 +1616,6 @@
 %%% \DescribeMacro{\clearancetop=<len>}
 %%% \DescribeMacro{\clearanceright=<len>}
 %%% \DescribeMacro{\clearancebottom=<len>}
-% XXX LEGACY CLEARANCE
-%%% \DescribeMacro{\clearance=<len>}
 %%
 %% A cell defines a set of contextual lengths:
 %%
@@ -1750,13 +1747,10 @@
 		\setlength\cellheight{\photobook@protect@h}%
 		\setlength\celloffsettop{0pt}%
 		\setlength\celloffsetleft{0pt}%
-		% XXX EXPERIMENTAL CLEARANCE
 		\setlength\clearanceleft{0pt}%
 		\setlength\clearancetop{0pt}%
 		\setlength\clearanceright{0pt}%
 		\setlength\clearancebottom{0pt}%
-		% XXX LEGACY CLEARANCE
-		%\setlength\clearance{0pt}%
 		%
 		\begin{MinipageCellContent}[\photobook@minipagecell@parentvalign]{minipagecell}%
 }{%
@@ -2013,7 +2007,7 @@
 
 
 %% \DescribeEnv{cliptocell}
-%% \DescribeEnv{cliptocellbleeds}
+%% \DescribeEnv{setcliptocellbleeds}
 %
 %% Clip content to parent cell.
 %%
@@ -2046,24 +2040,27 @@
 \setlength\photobook@cliptocell@right{0mm}%
 \newlength\photobook@cliptocell@bottom
 \setlength\photobook@cliptocell@bottom{0mm}%
+
+\def\cliptocellbleeds{{0mm} {0mm} {0mm} {0mm}}%
 \def\cliptocellclearances{{0mm} {0mm} {0mm} {0mm}}%
 
 %% Set the default bleeds for |cliptocell| environments
 %%
-%%	>> \cliptocellbleeds{<size>}
-%%	>> \cliptocellbleeds{<horizontal> <vertical>}
-%%	>> \cliptocellbleeds{<left> <bottom> <right> <top>}
+%%	>> \setcliptocellbleeds{<size>}
+%%	>> \setcliptocellbleeds{<horizontal> <vertical>}
+%%	>> \setcliptocellbleeds{<left> <bottom> <right> <top>}
 %%
 %% This will only affect |cliptocell| environments on the same level, 
 %% without affecting the nested |cliptocell|s.
 %%
+%%% \DescribeEnv{cliptocellbleeds=<left> <bottom> <right> <top>}
 %%% \DescribeEnv{cliptocellclearances=<left> <bottom> <right> <top>}
 %%%
-%%% Set by |\cliptocellbleeds{..}| and contains clearances (negative 
-%%% clipping bleeds) usable by imagecell.
+%%% Set by |\setcliptocellbleeds{..}| and contain bleeds and clearances (negative 
+%%% clipping bleeds) respectively, usable by imagecell and others.
 %%%
 %%% XXX still testing....
-\newcommand\cliptocellbleeds[1]{
+\newcommand\setcliptocellbleeds[1]{
 	\setsepchar{ }%
 	\readlist*\photobook@cliptocell@bleeds{#1}%
 	\setsepchar{,}%
@@ -2100,16 +2097,20 @@
 	% NOTE: trailing spaces here are significant...
 	% XXX should we use \the here?
 	%		...it makes things printable...
+	\def\cliptocellbleeds{%
+		{\the\photobook@cliptocell@left} %
+		{\the\photobook@cliptocell@bottom} %
+		{\the\photobook@cliptocell@right} %
+		{\the\photobook@cliptocell@top}}%
 	\def\cliptocellclearances{%
 		{-\the\photobook@cliptocell@left} %
 		{-\the\photobook@cliptocell@bottom} %
 		{-\the\photobook@cliptocell@right} %
 		{-\the\photobook@cliptocell@top}}}
 
-% XXX use \cliptocellclearances as default...
 \newenvironment{cliptocell}[1][0mm]{%
 	\begingroup%
-		\cliptocellbleeds{#1}
+		\setcliptocellbleeds{#1}
 		% NOTE: the spaces at the end of each line here are significant!!
 		\begin{trimbox}{{\photobook@cliptocell@left} %
 				{\photobook@cliptocell@bottom} %
@@ -2120,7 +2121,7 @@
 				{\cellwidth + \photobook@cliptocell@right} %
 				{\height + \photobook@cliptocell@top}}%
 		% set defaults for nested cells...
-		\cliptocellbleeds{0mm}%
+		\setcliptocellbleeds{0mm}%
 		\begin{minipage}[t][\cellheight][t]{\cellwidth}% 
 			\ignorespaces%
 	}{%
@@ -2218,7 +2219,9 @@
 %% Image |clearance|. This sets the amount of clearance around an image 
 %% (default: |0pt|).
 %%
-%%	>> \imagecell[clearance=-4mm]{}{<image>}
+%%	>> \imagecell[clearance=<size>]{}{<image>}
+%%	>> \imagecell[clearance=<horizontal> <vertical>]{}{<image>}
+%%	>> \imagecell[clearance=<left> <bottom> <top> <right>]{}{<image>}
 %%
 %% \begin{minipage}{\textwidth}
 %% \begin{verbatim}
@@ -2331,9 +2334,6 @@
 \setlength\photobook@imagecell@clearance@right{0pt}
 \newlength\photobook@imagecell@clearance@bottom
 \setlength\photobook@imagecell@clearance@bottom{0pt}
-% XXX LEGACY
-\newlength\photobook@imagecell@clearance
-\setlength\photobook@imagecell@clearance{0pt}
 
 % NOTE: these feel like a hack...
 \newlength\photobook@imagecell@imgratio
@@ -2348,13 +2348,11 @@
 \define@boolkey{imagecell@args}{center}[true]{%
 	\def\photobook@imagecell@top{\dimexpr 
 		+0.5\cellheight 
-		% XXX EXPERIMENTAL CLEARANCE -- test...
 		+0.5\photobook@imagecell@clearance@top
 		-0.5\photobook@imagecell@clearance@bottom
 		-0.5\ht\photobook@imagebox \relax}%
 	\def\photobook@imagecell@left{\dimexpr 
 		+0.5\cellwidth 
-		% XXX EXPERIMENTAL CLEARANCE -- test...
 		+0.5\photobook@imagecell@clearance@left
 		-0.5\photobook@imagecell@clearance@right
 		-0.5\wd\photobook@imagebox \relax}}%
@@ -2363,7 +2361,6 @@
 \newcommand\photobook@imagecell@LEFT{%
 	\def\photobook@imagecell@left{\dimexpr%
 		+\photobook@imagecell@clearance@left \relax}%
-		%+\photobook@imagecell@clearance \relax}%
 	\def\photobook@imagecell@captionleft{
 		% XXX not sure why this branch is needed...
 		\ifKV@imagecell@args@fit
@@ -2403,7 +2400,6 @@
 \define@boolkey{imagecell@args}{top}[true]{%
 	\def\photobook@imagecell@top{%
 		\photobook@imagecell@clearance@top}%
-		%\photobook@imagecell@clearance}%
 	\def\photobook@imagecell@captiontop{%
 		-\dimexpr 
 			+\cellheight 
@@ -2419,7 +2415,6 @@
 		\dimexpr
 			\photobook@imagecell@top 
 			+\photobook@imagecell@clearance@bottom \relax}}%
-			%+\photobook@imagecell@clearance \relax}}%
 % clearance=<len>...
 % clearance=<horizontal> <vertical>...
 % clearance=<left> <bottom> <right> <top>...
@@ -2427,7 +2422,7 @@
 	% XXX EXPERIMENTAL
 	% XXX this is essentially the same as \photobook@cliptocell@bleeds -- unite...
 	\def\photobook@imagecell@clearances{#1}%
-	\setsepchar{ }
+	\setsepchar{ }%
 	\readlist*\photobook@imagecell@clearencelist{#1}%
 	\setsepchar{,}%
 	%% args: size
@@ -2459,9 +2454,7 @@
 		\setlength\photobook@imagecell@clearance@right{%
 			\photobook@imagecell@clearencelist[3]}%
 		\setlength\photobook@imagecell@clearance@top{%
-			\photobook@imagecell@clearencelist[4]}\fi%
-	% XXX LEGACY...
-	\setlength\photobook@imagecell@clearance{#1}}%
+			\photobook@imagecell@clearencelist[4]}\fi}%
 
 % offsettop=<len> / offsetleft=<len>...
 % XXX DOC!!!
@@ -2511,12 +2504,10 @@
 						\cellwidth 
 						- \photobook@imagecell@clearance@left 
 						- \photobook@imagecell@clearance@right \relax,
-						%- ((\photobook@imagecell@clearance) * 2) \relax,
 					height=\photobook@imagecell@scale\dimexpr 
 						\cellheight 
 						- \photobook@imagecell@clearance@top 
 						- \photobook@imagecell@clearance@bottom \relax]{#3}}%
-						%- ((\photobook@imagecell@clearance) * 2) \relax]{#3}}%
 		% fill...
 		\else\ifKV@imagecell@args@fill%
 			% preload image to get its proportions...
@@ -2537,7 +2528,6 @@
 							+ \cellwidth
 							- \photobook@imagecell@clearance@left
 							- \photobook@imagecell@clearance@right \relax]{#3}}%
-							%- ((\photobook@imagecell@clearance) * 2) \relax]{#3}}%
 			\else%
 				\sbox{\photobook@imagebox}{%
 					\includegraphics[%
@@ -2546,7 +2536,6 @@
 							+ \cellheight 
 							- \photobook@imagecell@clearance@top
 							- \photobook@imagecell@clearance@bottom \relax]{#3}}%
-							%- ((\photobook@imagecell@clearance) * 2) \relax]{#3}}%
 		\fi\fi\fi%
 		%
 		\setlength\celloffsetleft{%
@@ -2589,14 +2578,11 @@
 			\maxdim{\celloffsetleft}{0pt}}%
 		\setlength\celloffsettop{%
 			\maxdim{\celloffsettop}{0pt}}%
-		% XXX EXPERIMENTAL CLEARANCE
 		\setlength\clearanceleft{\photobook@imagecell@clearance@left}
 		\setlength\clearancetop{\photobook@imagecell@clearance@top}
 		\setlength\clearanceright{\photobook@imagecell@clearance@right}
 		\setlength\clearancebottom{\photobook@imagecell@clearance@bottom}
 		\def\clearances{\photobook@imagecell@clearences}
-		% XXX LEGACY CLEARANCE
-		%\setlength\clearance{\photobook@imagecell@clearance}%
 		% clear parent...
 		% XXX might be a good idea to put this into a special reusable cell...
 		\ifphotobook@imagecell@captionclearparent%
@@ -3055,10 +3041,12 @@
 						- \photobook@captionblockcell@spacing
 						- \cellwidth 
 						- \clearcaption 
+						% XXX EXPERIMENTAL CLEARANCE
 						% XXX this is only present in images...
-						% XXX change this to use \clearanceleft / \clearanceright / ...
+						- \clearanceleft
+						%- \clearanceright
 						% XXX LEGACY CLEARANCE
-						- \clearance 
+						%- \clearance 
 					\relax%
 				\else%
 					\photobook@captionblockcell@width\fi}%
@@ -4079,8 +4067,10 @@
 % XXX EXPERIMENTAL
 \newenvironment{leftside*}{%
 	\begin{leftside}%
-		\cliptocellbleeds{{\bleed} {\bleed} 0mm {\bleed}}%
+	\begin{cliptocell}[{\bleed} {\bleed} 0mm {\bleed}]%
+	\setcliptocellbleeds{{\bleed} {\bleed} 0mm {\bleed}}%
 }{%
+	\end{cliptocell}
 	\end{leftside}}
 
 \newenvironment{rightside}{%
@@ -4092,8 +4082,10 @@
 % XXX EXPERIMENTAL
 \newenvironment{rightside*}{%
 	\begin{rightside}%
-		\cliptocellbleeds{0mm {\bleed} {\bleed} {\bleed}}%
+	\begin{cliptocell}[0mm {\bleed} {\bleed} {\bleed}]%
+	\setcliptocellbleeds{0mm {\bleed} {\bleed} {\bleed}}%
 }{%
+	\end{cliptocell}
 	\end{rightside}}
 
 
@@ -4872,7 +4864,8 @@
 			%\clearpage%
 			\begin{page}%
 			% NOTE: this does not account for \bindingoffset...
-			\begin{pagecell}%
+			% XXX should this be a page or a paper cell???
+			\begin{papercell}%
 				\imagecell[%
 					center, 
 					clearance=-\bleed, 
@@ -4881,7 +4874,7 @@
 					offsetleft=\imageoffsetleft,
 					captionclearparent=\captionclearpage,
 					#1]{#2}{#3}%
-			\end{pagecell}%
+			\end{papercell}%
 			\end{page}%
 		% special case: centered vertical image -> account for \bindingoffset...
 		\else%
@@ -5462,6 +5455,10 @@
 %%
 %% This is a no-op for |layoutmode=block|.
 %%
+%% To change text color set |\textcolor{<color>}| the usual way and for
+%% line and fill colors use |\textblockrulecolour{<color>}| and 
+%% |\textblockcolour{<colour>}| respecitvely.
+%%
 % XXX should digits/rounding be configurable???
 \newcommand\photobook@TemplateCell[2][mm]{
 	\begin{center}