%---------------------------------------------------------------------- % % % This does the following: % - sets up the document/pdf for viewing as a book % - adds support for page bleeds % - adds basic templates for image pages % % % This file contains both the code and the reference, but in a slightly % more readable format than the traditional LaTeX .dtx format. In general % there are two main sections: % - code % - reference % lines starting with "%%" or "%X" where X is a section id % Sections are parts of the reference that are logically ordered differently % than the code, e.g. main user tools should have priority in the reference % while meta code (identified by "%M") can be described later, while in code % we strictly need to define macros before they are used thus meta-macros % and other building blocks and components come before the user tools. % % Docs are build by the Makefile, so reference it for more info. % % $ make doc % % % NOTE: in a stripped code install this file may contain only code and % code comments, in this case, to see the docs refer to either the % source or the actual documentation/pdf. % NOTE: the stripped code file is auto-generated, it is not recommended % to edit it directly, edit the source instead. % % % XXX Q: do we add the pdf to the repo and if so, should it be % compressed (diff-able) or uncompressed (blob)?? % XXX revise \clearcaption / \captionclearpage... % XXX unify API -- see CellContent env... % XXX make this loadable both as a class and as a package... % \@ifclassloaded{photobook}{}{} % XXX revise command naming -- should be obvious from name what is what: % - meta commands -- ??? (currently same as templates) % - general macros -- \usecell{..} % - templates -- \ImagePage{..} % XXX see where we need to \ignorespaces... % XXX might be a good idea to add a spine calculator... % XXX add list of dependencies to docs... % XXX manual / book: % - basic usage % - setup % - templates (copyright, front matter, back matter, acknowledgements, ...) % - using templates % - pre-print % - customizing % - extending % % %---------------------------------------------------------------------- %%% NOTE: \def\@[A-Z]+ macros will be visible to both the %%% code and the generated docs... \edef\photobook@FILEVERSION{v0.1} \edef\photobook@FILEDATE{2021-07-28} %% \documentclass{ltxdoc} %% %%% \usepackage{iftex} %%% \ifluatex %%% \edef\pdfcompresslevel{\pdfvariable compresslevel} %%% \edef\pdfobjcompresslevel{\pdfvariable objcompresslevel} %%% \fi %%% \pdfcompresslevel 0 %%% \pdfobjcompresslevel 0 %% %% \usepackage[a4paper,margin=25mm,left=55mm,nohead]{geometry} %% %% % NOTE: this needs to load before hyperref or bookmarks will break... %% % NOTE: loading hyperref here will break it loading later in one of %% % the packages... %% \usepackage{titlesec} %% %% \usepackage[numbered]{hypdoc} %% \usepackage{doctools} %% \usepackage{needspace} %% %% \usepackage[toc]{multitoc} %% \renewcommand*{\multicolumntoc}{2} %% \setlength{\columnseprule}{0.5pt} %% %% \usepackage{imakeidx} %% \makeindex[ %% columns=1, %% title=Alphabetical Index, %% intoc, %% options= -s photobook.ist ] %% %%% \newcommand\DescribeGlobal[1]{% %%% \DescribeMacro{#1}} %% %% \newcommand\LEGACY[1][]{\fbox{LEGACY #1}} %% \newcommand\EXPERIMENTAL[1][]{\fbox{EXPERIMENTAL #1}} %% %%% sections to new pages... %% \newcommand\sectionbreak{\Needspace{5\baselineskip}} %% %% % remove section numbering... %% \setcounter{secnumdepth}{0} %% %% % paragraph configuration... %% \setlength\parindent{0pt} %% \setlength\parskip{0.5em} %% %% \newcommand\blankfootnote[1]{% %% \begingroup %% \renewcommand\thefootnote{}% %% \footnote{#1}% %% \addtocounter{footnote}{-1}% %% \endgroup} %% %% %% \begin{document} %% %% \title{\textsf{photobook} --- Document class for building photo-books %% \thanks{This file describes version \FILEVERSION, %% last revised \FILEDATE.}} %% %% \author{Alex A. Naanou\thanks{E-mail: alex.nanou@gmail.com}} %% %% \date{Released \FILEDATE} %% %% %% \maketitle %% %% \begin{abstract} %% The |photobook| \LaTeX\space document class extends the |book| class %% defining a set of parameters, meta-macros, macros and environments %% with reasonable defaults to help typeset, build and print books mainly %% based on visual/image content. %% \end{abstract} %% %% \tableofcontents %% % %%%% Introduction % %% \LaTeX\ is great with textual and text-primary content with figures %% peppered in, as long as pictures/figures flow within, with or as part %% of text, vanilla \LaTeX\ is fantastic. %% %% One can relatively easily stretch the flow concept to more complex %% layouts introducing {\it even} and {\it odd} pages (the |book| class is %% one example) and flow rules based on them, but the next step, {\it bleeds}, %% combining page pairs into {\it spreads} as is often needed when designing %% image-oriented books is lacking. Full-bleed images/pages can be implemented %% manually, some more effort is needed to split something horizontally %% into a page spread, but doing so for whole book's worth of content is %% not practical -- automating and experimenting with this process is %% how |photobook| began. %% %% |photobook| extends the |book| class adding page layout types, bleeds %% and other global geometry configuration, introduces the {\it page} and %% {\it spread} as first-class elements into the document flow. These concepts %% are generalized as |cell|s. A |cell| is similar to a figure, it can %% be placed within the document flow, but unlike a figure a |cell| can %% be aligned relative to a page, it can fill a page, a cell can even be %% horizontally split to fill several pages (how spreads are implemented). %% %% On top of the |cell|, {\it page}, and {\it spread} concepts, |photobook| %% also builds a set of configurable high level macros and templates for %% common use cases like full bleed image spreads, foldouts, ... etc. % % %%%% Usage % %% >> \documentclass[]{photobook} %% % %---------------------------------------------------------------------- \NeedsTeXFormat{LaTeX2e} \ProvidesClass{photobook} [\photobook@FILEDATE \space \photobook@FILEVERSION Photo book document class] % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%%% Options %% \edef\photobook@options{\@classoptionslist} \RequirePackage{kvoptions} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - % Helpers... \newcommand\@DeclareLiteralOptionTo[2]{% \DeclareVoidOption{#2}{% \expandafter\edef\csname photobook@#1\endcsname{#2}}} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%%%% Page geometry % %% \DescribeMacro{blockwidth=} %% \DescribeMacro{blockheight=} %% \DescribeMacro{bindingoffset=} %% \DescribeMacro{bleed=} % %% This is similar to what |geometry| does, but adds bleed support. %% %% \begin{minipage}{\textwidth} %% \begin{verbatim} %% %% <---> bleed <---> bleed %% %% + - - - - - - - - - - - - - - - - - - - - - + - + ^ %% . . . | bleed %% . +---------------------------------------+----- v . . --- %% . | ^ . = . %% . | . . . . . . | . . = . ^ %% . |<-- blockwidth ----------------------->= . | %% . | . | . . = . | %% . | | . = . textheight %% . | . Page | . . = . | %% . | blockheight . = . | %% . | . | . . = . | %% . | | <---> bindingoffset | %% . | . . . . . . | . . = . v %% . | v . = . %% . +---------------------------------------+----- ^ . . --- %% . . . . | bleed %% + - - - - - - - - - - - - - - - - - - - - - + - + v %% . . %% | <-- textwidth --------------> . | %% ^ binding line %% %% \end{verbatim} %% \end{minipage} %% % NOTE: if blockwidth/blockheight are set they will force recalculations % and overriding of the paperwidth/paperheight if they were changed % by the user code anywhere between \documentclass[..]{photobook} % and \begin{document}... \DeclareStringOption{blockwidth} \DeclareStringOption{blockheight} \DeclareStringOption[0pt]{bindingoffset}[10mm] \DeclareStringOption[5mm]{bleed}[5mm] %% \DescribeMacro{flatfold=} % %% Sets the clearance set aside for a flat fold, used for foldouts %% (see: \nameref{subsec:Foldout page cells} section). %% \DeclareStringOption[0pt]{flatfold}[0.2mm] %% \DescribeMacro{pagefold=} % %% Sets the default fold type. %% %% Can be |in| or |out|. %% % XXX check values... \DeclareStringOption{pagefold} %% \DescribeMacro{foldout=} % %% Sets the default fold specification (i.e. sets |\defaultfoldout|). %% %% For more information see: \nameref{subsec:Foldout page cells} section. %% \DeclareStringOption[2]{foldout}[2] %%%%% layout % %% \DescribeMacro{layoutmode=} %% \DescribeMacro{block} %% \DescribeMacro{endpaper} %% \DescribeMacro{cover} %% \DescribeMacro{jacket} % %% Sat page layout mode. % %% >> layoutmode=