basic-book-builder/build/latex/basic-book-builder.tex

598 lines
18 KiB
TeX

% Options for packages loaded elsewhere
\PassOptionsToPackage{unicode}{hyperref}
\PassOptionsToPackage{hyphens}{url}
\PassOptionsToPackage{dvipsnames,svgnames,x11names}{xcolor}
\documentclass[
12pt,
openany]{book}
\usepackage{xcolor}
\usepackage[margin=1in]{geometry}
\usepackage{amsmath,amssymb}
\setcounter{secnumdepth}{5}
\usepackage{iftex}
\ifPDFTeX
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{textcomp} % provide euro and other symbols
\else % if luatex or xetex
\usepackage{unicode-math} % this also loads fontspec
\defaultfontfeatures{Scale=MatchLowercase}
\defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
\fi
\usepackage{lmodern}
\ifPDFTeX\else
% xetex/luatex font selection
\setmainfont[]{Noto Serif}
\setsansfont[]{Noto Sans}
\setmonofont[]{Noto Sans Mono}
\fi
% Use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
\IfFileExists{microtype.sty}{% use microtype if available
\usepackage[]{microtype}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\makeatletter
\@ifundefined{KOMAClassName}{% if non-KOMA class
\IfFileExists{parskip.sty}{%
\usepackage{parskip}
}{% else
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}}
}{% if KOMA class
\KOMAoptions{parskip=half}}
\makeatother
\usepackage{longtable,booktabs,array}
\newcounter{none} % for unnumbered tables
\usepackage{calc} % for calculating minipage widths
% Correct order of tables after \paragraph or \subparagraph
\usepackage{etoolbox}
\makeatletter
\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{}
\makeatother
% Allow footnotes in longtable head/foot
\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}}
\makesavenoteenv{longtable}
\usepackage{graphicx}
\makeatletter
\newsavebox\pandoc@box
\newcommand*\pandocbounded[1]{% scales image to fit in text height/width
\sbox\pandoc@box{#1}%
\Gscale@div\@tempa{\textheight}{\dimexpr\ht\pandoc@box+\dp\pandoc@box\relax}%
\Gscale@div\@tempb{\linewidth}{\wd\pandoc@box}%
\ifdim\@tempb\p@<\@tempa\p@\let\@tempa\@tempb\fi% select the smaller of both
\ifdim\@tempa\p@<\p@\scalebox{\@tempa}{\usebox\pandoc@box}%
\else\usebox{\pandoc@box}%
\fi%
}
% Set default figure placement to htbp
\def\fps@figure{htbp}
\makeatother
% definitions for citeproc citations
\NewDocumentCommand\citeproctext{}{}
\NewDocumentCommand\citeproc{mm}{%
\begingroup\def\citeproctext{#2}\cite{#1}\endgroup}
\makeatletter
% allow citations to break across lines
\let\@cite@ofmt\@firstofone
% avoid brackets around text for \cite:
\def\@biblabel#1{}
\def\@cite#1#2{{#1\if@tempswa , #2\fi}}
\makeatother
\newlength{\cslhangindent}
\setlength{\cslhangindent}{1.5em}
\newlength{\csllabelwidth}
\setlength{\csllabelwidth}{3em}
\newenvironment{CSLReferences}[2] % #1 hanging-indent, #2 entry-spacing
{\begin{list}{}{%
\setlength{\itemindent}{0pt}
\setlength{\leftmargin}{0pt}
\setlength{\parsep}{0pt}
% turn on hanging indent if param 1 is 1
\ifodd #1
\setlength{\leftmargin}{\cslhangindent}
\setlength{\itemindent}{-1\cslhangindent}
\fi
% set entry spacing
\setlength{\itemsep}{#2\baselineskip}}}
{\end{list}}
\usepackage{calc}
\newcommand{\CSLBlock}[1]{\hfill\break\parbox[t]{\linewidth}{\strut\ignorespaces#1\strut}}
\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{\strut#1\strut}}
\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{\strut#1\strut}}
\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1}
\setlength{\emergencystretch}{3em} % prevent overfull lines
\providecommand{\tightlist}{%
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\usepackage{etoolbox}
\usepackage[most]{tcolorbox}
\usepackage{graphicx}
\usepackage{xparse}
\tcbuselibrary{breakable}
% --- Disable floating figures globally ---
\usepackage{float}
\let\origfigure\figure
\let\endorigfigure\endfigure
\renewenvironment{figure}[1][H]{\origfigure[H]}{\endorigfigure}
% --- Colors ---
\usepackage{xcolor}
\definecolor{speculativeback}{RGB}{247,232,255} % #f7e8ff
\definecolor{speculativeframe}{RGB}{139,43,226} % #8b2be2
\definecolor{lightgrayback}{RGB}{245,245,245}
\definecolor{lightgrayframe}{RGB}{180,180,180}
% --- Left-align all Pandoc tables ---
\usepackage{longtable}
\usepackage{etoolbox}
\makeatletter
\patchcmd\longtable{\par}{\par\raggedright}{}{}
\setlength{\LTleft}{0pt}
\setlength{\LTright}{0pt}
\makeatother
% Enable index generation
\usepackage{makeidx}
\makeindex
% Helper to show a blank title if empty
\newcommand{\blanktitle}{\mbox{}}
% =========================================================
% Concept Boxes
% =========================================================
\newtcolorbox{infobox}[1][Information]{%
title=\ifstrempty{#1}{\blanktitle}{#1},
colback=blue!3!white,
colframe=blue!50!black,
colbacktitle=blue!10!white,
fonttitle=\bfseries,
coltitle=black,
enhanced, sharp corners, breakable,
after=\par\vspace{6pt}
}
\newtcolorbox{proposedbox}[1][Proposed Concept]{%
title=\ifstrempty{#1}{\blanktitle}{#1},
colback=blue!5!white,
colframe=blue!75!black,
colbacktitle=blue!15!white,
fonttitle=\bfseries,
coltitle=black,
enhanced, sharp corners, breakable,
after=\par\vspace{6pt}
}
\newtcolorbox{establishedbox}[1][Established Concept]{%
title=\ifstrempty{#1}{\blanktitle}{#1},
colback=green!5!white,
colframe=green!75!black,
colbacktitle=green!15!white,
fonttitle=\bfseries,
coltitle=black,
enhanced, sharp corners, breakable,
after=\par\vspace{6pt}
}
\newtcolorbox{speculativebox}[1][Speculative Concept]{%
title=\ifstrempty{#1}{\blanktitle}{#1},
colback=speculativeback,
colframe=speculativeframe,
colbacktitle=speculativeback!80!white, % lighter variant for title bar
fonttitle=\bfseries,
coltitle=black,
enhanced, sharp corners, breakable,
after=\par\vspace{6pt}
}
\newtcolorbox{cautionbox}[1][Caution]{%
title=\ifstrempty{#1}{\blanktitle}{#1},
colback=orange!5!white,
colframe=orange!75!black,
colbacktitle=orange!15!white,
fonttitle=\bfseries,
coltitle=black,
enhanced, sharp corners, breakable,
after=\par\vspace{6pt}
}
\newtcolorbox{warningbox}[1][Warning]{%
title=\ifstrempty{#1}{\blanktitle}{#1},
colback=orange!5!white,
colframe=orange!75!black,
colbacktitle=orange!15!white,
fonttitle=\bfseries,
coltitle=black,
enhanced, sharp corners, breakable,
after=\par\vspace{6pt}
}
\newtcolorbox{dangerbox}[1][Danger]{%
title=\ifstrempty{#1}{\blanktitle}{#1},
colback=red!5!white,
colframe=red!75!black,
colbacktitle=red!15!white,
fonttitle=\bfseries,
coltitle=black,
enhanced, sharp corners, breakable,
after=\par\vspace{6pt}
}
% =========================================================
% Code / CLI Boxes
% =========================================================
\newtcolorbox{codebox}[1][Code]{%
title=\ifstrempty{#1}{\blanktitle}{#1},
colback=lightgrayback,
colframe=lightgrayframe,
colbacktitle=lightgrayback!90!white,
fonttitle=\bfseries,
coltitle=black,
enhanced, sharp corners, breakable,
after=\par\vspace{6pt}
}
\newtcolorbox{clibox}[1][Command Line]{%
title=\ifstrempty{#1}{\blanktitle}{#1},
colback=lightgrayback,
colframe=lightgrayframe,
colbacktitle=lightgrayback!90!white,
fonttitle=\bfseries,
coltitle=black,
enhanced, sharp corners, breakable,
after=\par\vspace{6pt}
}
\usepackage{xurl}
\usepackage{fancyhdr}
\setlength{\headheight}{15pt}
% --- Chapter-opening pages (plain style) ---
\fancypagestyle{plain}{%
\fancyhf{}%
\fancyhead[C]{\leftmark} % Chapter title
\cfoot{Basic Book Builder: A Pandoc template for building books, documents and articles} % Book title
\rfoot{\thepage} % Page number
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0pt}
}
% --- Normal running pages ---
\pagestyle{fancy}
\fancyhf{}
% Header
\fancyhead[C]{\leftmark} % Chapter title (centered)
% Footer
\cfoot{Basic Book Builder: A Pandoc template for building books, documents and articles} % Book title
\rfoot{\thepage} % Page number
% Line rules
\renewcommand{\headrulewidth}{0pt} % rule under header
\renewcommand{\footrulewidth}{0pt} % no rule above footer
\usepackage{bookmark}
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
\urlstyle{same}
\hypersetup{
colorlinks=true,
linkcolor={blue},
filecolor={Maroon},
citecolor={Blue},
urlcolor={Blue},
pdfcreator={LaTeX via pandoc}}
\author{}
\date{}
\begin{document}
\frontmatter
% -------------------------
% 1. Title Page
% -------------------------
\begin{titlepage}
\centering
\vspace*{2cm}
{\Huge\bfseries Basic Book Builder \par}
\vspace{0.4cm}
{\Large A Pandoc template for building books, documents and articles \par}
\vspace{1.2cm}
\includegraphics[width=0.5\textwidth]{lib/img/UAF-ACEP.png}
\vfill
\end{titlepage}
% -------------------------
% 2. COPYRIGHT / META PAGE
% -------------------------
\newpage
\thispagestyle{empty}
{\Large\bfseries Basic Book Builder \par}
\vspace{0.2cm}
{\normalsize\textit{A Pandoc template for building books, documents and articles}\par}
\vspace{0.4cm}
\renewcommand{\arraystretch}{1.3} % row spacing
\setlength{\tabcolsep}{8pt} % column padding
\begin{tabular}{@{}p{0.28\textwidth}p{0.65\textwidth}@{}}
\textbf{Author:} & John Haverlack \\
\textbf{Version:} & 1.1.0 \\
\textbf{Date:} & 2026-02-04 \\
\textbf{Affiliation:} & Alaska Center for Energy and Power \\
\textbf{Institution:} & University of Alaska Fairbanks \\
\textbf{ISBN:} & UNSPECIFIED \\
\textbf{DOI:} & UNSPECIFIED \\
\textbf{Maturity:} & BETA \\
\end{tabular}
\vspace{0.5cm}
\textbf{Copyright} © 2026 Alaska Center for Energy and Power
\vspace{0.5cm}
% ----- Licensing Section -----
\section*{Licensing}
\subsection*{Open Source Edition (PDF and HTML)}
Licensed under the Creative Commons Attribution-NoDerivatives 4.0 International License.
\begin{itemize}
\item License: \href{https://creativecommons.org/licenses/by-nd/4.0/}{CC BY-ND 4.0}
\end{itemize}
% \subsection*{Commercial Edition (ebook and print)}
% All Rights Reserved. No part of the EPUB or printed editions may be reproduced or redistributed without permission.
\vspace*{\fill}
% -------------------------
% 3. Cover Illustration Page
% -------------------------
% ----- Title Page Image Note -----
\newpage
\thispagestyle{empty}
% \vspace*{1.5cm}
% {\Large\bfseries Cover Illustration\par}
% \begin{center}
% \includegraphics[width=0.33\textwidth]{lib/img/UAF-ACEP.png}
% \vspace{0.6cm}
% \vspace{0.8cm}
% {\small
% \textit{“Cover illustration by****”}
% \end{center}
% -------------------------
% Reset numbering
% -------------------------
\clearpage
\pagenumbering{roman}
% -------------------------
% Insert dedication
% -------------------------
% \begin{titlepage}
% \centering
% \vspace*{\fill}
% \textit{This book is dedicated to ****.}
% \vspace*{\fill}
% \end{titlepage}
% (Pandoc will insert the TOC next, using roman numerals)
\renewcommand*\contentsname{Contents}
{
\setcounter{tocdepth}{3}
\tableofcontents
}
\mainmatter
\chapter{Introduction}\label{introduction}
This is a basic book (or article / document) builder template based on a
Pandoc(\citeproc{ref-PandocIndex}{\emph{Pandoc - Index},
n.d.})\index{Pandoc} build process in conjunction with a number of other
tools to generate PDF, HTML, LaTex, Markdown, ODT, DOCX, and Epub book
output formats from a single set Markdown source content , which can
optionally be edited as an Obsidian vault.
This \textbf{basic book
builder}(\citeproc{ref-JehaverlackBasicbookbuilderPandoca}{\emph{Jehaverlack/Basic-Book-Builder},
n.d.}) template has been curated by John
Haverlack.(\citeproc{ref-JohnHaverlackACEP}{\emph{John {Haverlack}
\textbar{} {ACEP}}, n.d.})
\chapter{Getting Started}\label{getting-started}
\section{Cloning the Basic Book
Builder}\label{cloning-the-basic-book-builder}
\begin{clibox}[Cloning the repository]
\begin{verbatim}
git clone https://github.com/jehaverlack/basic-book-builder.git
\end{verbatim}
\end{clibox}
\begin{clibox}[Navigate to the repo directory]
\begin{verbatim}
cd basic-book-builder
\end{verbatim}
\end{clibox}
\begin{codebox}[Code Example]
\begin{verbatim}
if then else
\end{verbatim}
\end{codebox}
\section{Setting Up Build
Environment}\label{setting-up-build-environment}
\begin{cautionbox}[Debian Based Linux]
This script only support Debian based linux system (Debian, Ubunutu,
Zorin, etc) This script has not been widely tested across platforms
\end{cautionbox}
\begin{clibox}[Setup Build Environment]
\begin{verbatim}
./scripts/setup-linux-deb.sh
\end{verbatim}
\end{clibox}
For more information on setting up the build environment for your system
see Appendix A.
\backmatter
\chapter*{Glossary}\label{glossary}
\addcontentsline{toc}{chapter}{Glossary}
{\def\LTcaptype{none} % do not increment counter
\begin{longtable}[]{@{}
>{\raggedright\arraybackslash}p{(\linewidth - 2\tabcolsep) * \real{0.1734}}
>{\raggedright\arraybackslash}p{(\linewidth - 2\tabcolsep) * \real{0.8266}}@{}}
\toprule\noalign{}
\begin{minipage}[b]{\linewidth}\raggedright
Term
\end{minipage} & \begin{minipage}[b]{\linewidth}\raggedright
Description
\end{minipage} \\
\midrule\noalign{}
\endhead
\bottomrule\noalign{}
\endlastfoot
\textbf{AST (Abstract Syntax Tree)} & Pandoc's internal structured
representation of a document. Lua filters operate on the AST before
rendering to a target format. \\
\textbf{Bibliography} & A \texttt{.bib} file (e.g., Zotero export) used
by Pandoc with \texttt{citeproc} to generate formatted citations and
reference lists. \\
\textbf{Callout} & A styled block (e.g., \texttt{{[}!warning{]}})
transformed by Lua filters into format-specific output such as LaTeX
environments or HTML \texttt{\textless{}div\textgreater{}} elements. \\
\textbf{Defaults File (YAML)} & A Pandoc configuration file defining
output format, filters, metadata, and rendering options (e.g.,
\texttt{pdf.yaml}, \texttt{html.yaml}). \\
\textbf{DOCX} & Microsoft Word document format generated by Pandoc;
styling is controlled via a \texttt{reference.docx} file. \\
\textbf{Filter (Lua)} & A script that modifies Pandoc's AST before
rendering. Used in this workflow for callouts and other structural
transformations. \\
\textbf{Frontmatter} & Format-specific content inserted before the main
body (e.g., \texttt{frontmatter.tex}, \texttt{frontmatter.html},
\texttt{frontmatter-docx.md}). \\
\textbf{HTML} & Web output format generated by Pandoc, typically styled
via CSS and supporting interactive features. \\
\textbf{LaTeX} & Typesetting system used for high-quality PDF generation
via XeLaTeX in this workflow. \\
\textbf{Lua Filter} & A lightweight scripting extension used by Pandoc
to customize document transformations programmatically. \\
\textbf{Makefile} & Automation script orchestrating the build pipeline
for PDF, HTML, DOCX, ODT, and Markdown outputs. \\
\textbf{Markdown} & Plain-text markup language serving as the source
format for all outputs in the workflow. \\
\textbf{Metadata} & Key--value pairs (e.g., \texttt{metadata.yaml})
defining title, author, license, version, and other document
variables. \\
\textbf{ODT} & OpenDocument Text format used by LibreOffice; similar to
DOCX but open-standard. \\
\textbf{Pandoc} & Universal document converter used to transform
Markdown into PDF, HTML, DOCX, ODT, EPUB, and more. \\
\textbf{PDF} & Portable Document Format output produced via Pandoc +
XeLaTeX. \\
\textbf{Reference Document} & A DOCX or ODT file defining styles (fonts,
headings, spacing) used when generating Word/LibreOffice outputs. \\
\textbf{Resource Path} & Directories Pandoc searches for images,
diagrams, and other assets during rendering. \\
\textbf{Template} & A format-specific layout file (e.g., LaTeX template)
used to control document structure beyond styling. \\
\textbf{TOC (Table of Contents)} & Automatically generated navigation
structure controlled by \texttt{toc} and \texttt{toc-depth} options. \\
\textbf{XeLaTeX} & LaTeX engine used to generate PDFs with modern font
support (via \texttt{fontspec}). \\
\textbf{Zotero} & Reference manager used to generate \texttt{.bib} files
for citation processing with Pandoc. \\
\end{longtable}
}
\clearpage
\thispagestyle{plain}
\markboth{Index}{Index}
\let\oldclearpage\clearpage
\let\oldcleardoublepage\cleardoublepage
\renewcommand{\clearpage}{}
\renewcommand{\cleardoublepage}{}
\chapter*{Index}
\addcontentsline{toc}{chapter}{Index}
\printindex
\renewcommand{\clearpage}{\oldclearpage}
\renewcommand{\cleardoublepage}{\oldcleardoublepage}
\clearpage
\thispagestyle{plain}
\markboth{Bibliography}{Bibliography}
\chapter*{Bibliography}\label{bibliography}
\addcontentsline{toc}{chapter}{Bibliography}
\protect\phantomsection\label{refs}
\begin{CSLReferences}{1}{1}
\bibitem[\citeproctext]{ref-JehaverlackBasicbookbuilderPandoca}
\emph{Jehaverlack/Basic-Book-Builder: {A Pandoc} Workflow for Building
{PDF}, {HTML}, {EPUB}, and {LaTeX} Book Format.} n.d.
Https://github.com/jehaverlack/basic-book-builder.
\bibitem[\citeproctext]{ref-JohnHaverlackACEP}
\emph{John {Haverlack} \textbar{} {ACEP}}. n.d.
Https://www.uaf.edu/acep/about/our-team/john-haverlack.php.
\bibitem[\citeproctext]{ref-PandocIndex}
\emph{Pandoc - Index}. n.d. Https://pandoc.org/.
\bibitem[\citeproctext]{ref-JehaverlackBasicbookbuilderPandoca}
\emph{Jehaverlack/Basic-Book-Builder: {A Pandoc} Workflow for Building
{PDF}, {HTML}, {EPUB}, and {LaTeX} Book Format.} n.d.
Https://github.com/jehaverlack/basic-book-builder.
\bibitem[\citeproctext]{ref-JohnHaverlackACEP}
\emph{John {Haverlack} \textbar{} {ACEP}}. n.d.
Https://www.uaf.edu/acep/about/our-team/john-haverlack.php.
\bibitem[\citeproctext]{ref-PandocIndex}
\emph{Pandoc - Index}. n.d. Https://pandoc.org/.
\end{CSLReferences}
\backmatter
\end{document}