% !TeX program = lualatex
% This filename = jiffy-doc.tex
\documentclass[11pt]{article}

\usepackage[margin=1in]{geometry}
\usepackage{booktabs}
\usepackage{amsmath}
\usepackage{array}
\usepackage{enumitem}
\usepackage[hidelinks]{hyperref}

\setlength{\parindent}{0pt}
\setlength{\parskip}{0.65em}
\setlist[itemize]{topsep=0.25em,itemsep=0.2em}
\urlstyle{same}

\newcommand{\pkg}[1]{\textsf{#1}}
\newcommand{\opt}[1]{\texttt{#1}}
\newcommand{\cs}[1]{\texttt{\textbackslash#1}}
\newcommand{\mcs}[1]{\mbox{\cs{#1}}}

\title{%
\pkg{jiffy}\\[0.4em]
\large A TikZ-Based Page-Layout Diagnostic Tool for \LaTeX
}

\author{%
Scot Parker\\[0.6em]
\small With contributions from Gemini Pro and ChatGPT
}

\date{Version 0.3 --- 2026/09/13}

\begin{document}
\maketitle

\begin{abstract}
\pkg{jiffy} produces a graphical diagnostic of a \LaTeX\ document's page
geometry.  It displays the physical sheet, text block, header, footer
baseline, margin-note column, TeX's one-inch reference lines, and the
principal horizontal and vertical layout dimensions.  In two-sided
mode, \pkg{jiffy} produces companion verso and recto diagrams followed
by a consolidated data sheet containing measured values, diagnostics,
and document/typography information.
\end{abstract}

\tableofcontents
\clearpage

\section{Purpose}

The traditional \pkg{layout} package is useful for inspecting \LaTeX\ page
parameters, but the numerical parameters do not always make the physical
page immediately obvious.  \pkg{jiffy} provides a TikZ-based map of the
same general subject: the relationship between the physical page and the
layout dimensions that place the text, header, footer, and margin-note
areas.

The package is intended primarily as a diagnostic and teaching tool.  It
is especially useful while designing book and report layouts, where the
verso and recto pages may use different side-margin settings.

\section{Installation}

After installation from CTAN, load the package in the normal way:

\begin{verbatim}
\usepackage{jiffy}
\end{verbatim}

For local testing, place \texttt{jiffy.sty} in the same directory as the
document being compiled.  The package requires the standard packages
\pkg{tikz}, \pkg{xcolor}, \pkg{nextpage}, \pkg{iftex}, \pkg{pgfopts}, and
\pkg{pdflscape}.  The TikZ libraries \texttt{calc} and
\texttt{arrows.meta} are used internally.

\section{Basic use}

Load \pkg{jiffy} in the preamble and place \cs{jiffy} where the
diagnostic pages are to be generated:

\begin{verbatim}
\documentclass[11pt,twoside]{book}

\usepackage[
  pt_precision=1,
  fullpage=false,
  display-language=english-us
]{jiffy}

\begin{document}

\jiffy

\end{document}
\end{verbatim}

The public command is:

\begin{description}
\item[\cs{jiffy}]
Generates the diagnostic pages appropriate to the document's sidedness.
In a two-sided document, the package first advances to an even page and
then generates a verso geometry diagram, a recto geometry diagram, and
a data sheet.  In a one-sided document, it generates one geometry
diagram using \LaTeX's odd-page layout settings, followed by the data
sheet.
\end{description}

Consequently, \cs{jiffy} is most naturally used at a point where a
short diagnostic insert is acceptable.  The pages produced by the
command use an empty page style.

\section{Package options}

\subsection{Numerical precision}

\begin{description}
\item[\opt{pt\_precision=<integer>}]
Sets the number of decimal places printed for values in points.  The
default is \texttt{1}.
\end{description}

The millimeter and inch precision values are derived automatically:

\begin{center}
\begin{tabular}{lc}
\toprule
Unit & Decimal places \\
\midrule
pt & \opt{pt\_precision} \\
mm & \opt{pt\_precision + 1} \\
in & \opt{pt\_precision + 2} \\
\bottomrule
\end{tabular}
\end{center}

For example,

\begin{verbatim}
\usepackage[pt_precision=1]{jiffy}
\end{verbatim}

prints point values to one decimal place, millimeter values to two
decimal places, and inch values to three decimal places.

\subsection{Display language}

\begin{description}
\item[\opt{display-language=<language>}]
Selects the language used by \pkg{jiffy} for diagram labels, table
headings, and diagnostic messages.  The default is
\texttt{english-us}.
\end{description}

The currently defined values are:

\begin{center}
\begin{tabular}{ll}
\toprule
Option value & Language \\
\midrule
\texttt{english-us} & English (US) \\
\texttt{vietnamese} & Vietnamese \\
\texttt{spanish} & Spanish \\
\texttt{german} & German \\
\texttt{french} & French \\
\texttt{dutch} & Dutch \\
\bottomrule
\end{tabular}
\end{center}

If an unsupported display language is requested, \pkg{jiffy} issues a
package warning and falls back to \texttt{english-us}.

\subsection{Full-page rendering}

\begin{description}
\item[\opt{fullpage=false}]
Uses the miniature diagnostic renderer.  This is the default.

\item[\opt{fullpage=true}]
Uses a true 1:1 overlay anchored to the physical PDF page.
\end{description}

The synonyms \texttt{yes} and \texttt{no} are accepted.  A bare
\texttt{fullpage} option is equivalent to \texttt{fullpage=true}:

\begin{verbatim}
\usepackage[fullpage]{jiffy}
\usepackage[fullpage=true]{jiffy}
\usepackage[fullpage=yes]{jiffy}
\end{verbatim}

In full-page mode, dimensions that would otherwise lie outside the
physical sheet are moved inside the page.  Renderer choice does not
change the number or order of diagnostic pages.

\section{Diagnostic pages}

\subsection{Two-sided documents}

For a two-sided document, \cs{jiffy} creates the following sequence:

\begin{enumerate}
\item an even-page \textbf{verso} geometry diagram;
\item an odd-page \textbf{recto} geometry diagram;
\item an even-page \textbf{data sheet}.
\end{enumerate}

The command uses \pkg{nextpage}'s even-page clearing mechanism so that
the first geometry page has the intended verso parity.

\subsection{One-sided documents}

For a one-sided document, there is no distinct verso geometry: \LaTeX\
uses its odd-page layout settings for every page.  Therefore, \cs{jiffy}
creates only:

\begin{enumerate}
\item one \textbf{geometry diagram};
\item one \textbf{data sheet}.
\end{enumerate}

No even-page clearing is performed in one-sided mode, because page
parity has no layout significance there.

\subsection{Margin-note side}

The diagram follows the active margin-note side.  In two-sided layouts,
the margin-note column can switch with page parity; the result is also
reversed when \cs{reversemarginpar} is in effect.

\section{Geometry shown by the diagram}

\subsection{TeX's one-inch reference lines}

\pkg{jiffy} explicitly draws the historical TeX reference lines.  Their
physical positions are

\[
  x_{\mathrm{ref}} = 1\,\mathrm{in} + \mcs{hoffset},
  \qquad
  y_{\mathrm{ref}} = 1\,\mathrm{in} + \mcs{voffset}.
\]

The physical left edge of the text block is therefore

\[
  x_{\mathrm{text}} = x_{\mathrm{ref}} +
  \begin{cases}
    \mcs{evensidemargin}, & \mbox{verso},\\
    \mcs{oddsidemargin}, & \mbox{recto}.
  \end{cases}
\]

The physical top edge of the text block is

\[
  y_{\mathrm{text}} = y_{\mathrm{ref}} + \mcs{topmargin}
  + \mcs{headheight} + \mcs{headsep}.
\]

When \cs{hoffset} or \cs{voffset} is nonzero, \pkg{jiffy} marks
the corresponding reference line with a dot and includes the nonzero
offset in the parameter table.

\subsection{Reference numbers}

The numbered circles on the geometry diagrams correspond to the
following quantities.

\begin{center}
\small
\begin{tabular}{>{\bfseries}c l l}
\toprule
Ref. & Quantity & Meaning \\
\midrule
1W & \cs{paperwidth} & physical paper width \\
1H & \cs{paperheight} & physical paper height \\
2W & \cs{textwidth} & text-block width \\
2H & \cs{textheight} & text-block height \\
3W & \cs{evensidemargin} & verso/even TeX side-margin parameter \\
4W & \cs{oddsidemargin} & recto/odd TeX side-margin parameter \\
3H & physical top margin & top of paper to top of text block \\
4H & physical bottom margin & bottom of text block to bottom of paper \\
5W & \cs{marginparwidth} & margin-note column width \\
6W & \cs{marginparsep} & text-to-margin-note separation \\
5H & \cs{headheight} & header height \\
6H & \cs{headsep} & header-to-text separation \\
7H & \cs{footskip} & text-bottom to footer-baseline distance \\
\bottomrule
\end{tabular}
\end{center}

The data sheet also reports the actual physical left and right margins
for both verso and recto pages.  These physical margins are derived
values; they should not be confused with the TeX parameters
\cs{evensidemargin} and \cs{oddsidemargin}.

\section{The data sheet}

The final diagnostic page is the data sheet.  It consolidates information
that would otherwise obscure the geometry diagram or diagrams.  It
contains three groups.

\subsection{Diagnostics}

\pkg{jiffy} checks whether the following items extend beyond the physical
page:

\begin{itemize}
\item the text block;
\item the header;
\item the margin-note column;
\item the footer baseline;
\item TeX's horizontal and vertical one-inch reference lines.
\end{itemize}

If no off-page condition is found, the data sheet reports that no
off-page conditions were detected.  If a condition is found, the
intended diagnostic includes the amount of the overrun in points,
millimeters, and inches.

\subsection{Page parameters}

The parameter table reports the principal dimensions in three units:
points, millimeters, and inches.  Its \textbf{BVR} column identifies
whether a row applies to both pages (B), the verso page (V), or the recto
page (R).

\subsection{Document and typography}

The data sheet also records selected properties of the surrounding
document at the point where the layout is computed:

\begin{itemize}
\item TeX engine (pdfTeX, LuaTeX, or XeTeX);
\item active document language, when available;
\item one- or two-column mode;
\item current font size and baseline skip;
\item font encoding, family, series, and shape;
\item traditional TeX mathematics or \pkg{unicode-math};
\item current text-font name.
\end{itemize}

\section{Example}

The distribution includes \texttt{jiffy-example.tex}.  It defines a
two-sided page and exercises the package directly.  A
representative package invocation is:

\begin{verbatim}
\usepackage[
  pt_precision=1,
  fullpage,
  display-language=english-us
]{jiffy}
\end{verbatim}

To compare the miniature renderer with the 1:1 renderer, change
\texttt{fullpage} to \texttt{fullpage=false} and compile again.

\section{Compatibility and scope}

\pkg{jiffy} detects pdfTeX, LuaTeX, and XeTeX.  It reads the standard
\LaTeX\ page-layout lengths directly and is therefore useful with page
layouts established by the document class or by layout packages such as
\pkg{geometry}, provided those lengths have their final values when
\cs{jiffy} is executed.

The package is diagnostic: it reports and visualizes the current layout;
it does not itself redesign the page.

\section{Distribution files}

A compact CTAN distribution may contain:

\begin{center}
\begin{tabular}{ll}
\toprule
File & Purpose \\
\midrule
\texttt{jiffy.sty} & package implementation \\
\texttt{jiffy-doc.tex} & documentation source \\
\texttt{jiffy-doc.pdf} & compiled documentation \\
\texttt{jiffy-example.tex} & standalone example \\
\texttt{README.md} & package summary and installation information \\
\bottomrule
\end{tabular}
\end{center}

The release history is maintained in this manual, so a separate
\texttt{CHANGELOG.md} is optional rather than necessary.

\section{Support}

Repository and issue tracker:
\begin{center}
\url{https://github.com/squidmore/jiffy}
\end{center}

Supporting email:
\begin{center}
\href{mailto:jiffy.latex@gmail.com}{\texttt{jiffy.latex@gmail.com}}
\end{center}

\section{License}

\pkg{jiffy} is distributed under the \LaTeX\ Project Public License
(LPPL), version 1.3c.

\section{Change history}

\subsection*{Version 0.3 --- 2026/09/13}
\begin{itemize}
\item Rewrote the user documentation to describe the current package
      implementation and the output appropriate to one- and two-sided documents.
\item Documented the \texttt{pt\_precision},
      \texttt{display-language}, and \texttt{fullpage} options.
\item Changed the default point display precision from three decimal
      places to one; millimeters and inches consequently default to two
      and three decimal places, respectively.
\item Corrected the off-page diagnostic formatter so overrun values are
      reported reliably in points, millimeters, and inches.
\item Documented miniature and true 1:1 full-page rendering.
\item Changed one-sided output to one geometry diagram plus one data sheet;
      two-sided output remains verso, recto, and data sheet.
\item Documented the parameter data sheet, off-page diagnostics, and
      document/typography report.
\item Moved the maintained release history into the documentation;
      a separate \texttt{CHANGELOG.md} is no longer required.
\item Changed the dimensional notation assignments from H/V (Horizontal/Vertical) to W/H (Width/Height) to eliminate ambiguity and match standard \LaTeX\ terminology.
\item Removed the large page numbers from the bottom corners of the geometry diagrams.
\item Fixed a missing backslash bug in the \cs{if@twocolumn} check that previously caused compilation errors in one-column documents.
\end{itemize}

\subsection*{Development snapshot 0.2b --- 2026/08/30}
This was not submitted to CTAN.  A separate \texttt{CHANGELOG.md} was
created during development; its history is incorporated here for the
0.3 release.

\subsection*{Version 0.2a --- 2026/08/29}
\begin{itemize}
\item Created the supporting address \texttt{jiffy.latex@gmail.com}.
\item Created the GitHub account/repository used for \pkg{jiffy}.
\item CTAN package repository assigned to
      \texttt{/graphics/pgf/contrib/jiffy}.
\end{itemize}

\subsection*{Version 0.2 --- 2026/08/28}
Initial CTAN release.

\end{document}