%% This is file `stocksize-doc.text',
%%
%% Copyright (C) 2024–25 by João M. Lourenço <joao.lourenco@fct.unl.pt>
%%
%% This file may be distributed and/or modified under the conditions of
%% the LaTeX Project Public License, either version 1.3c of this license
%% or (at your option) any later version. The latest version of this
%% license is in:
%%
%%    http://www.latex-project.org/lppl.txt
%%
%% and version 1.3c or later is part of all distributions of LaTeX
%% version 2006/05/20 or later.
%%
\documentclass[12pt,a4paper,article]{article}

\usepackage[margin=1in]{geometry}
\usepackage{kantlipsum}
\usepackage{booktabs}
\usepackage{xcolor}
\usepackage{minted}
\usepackage[colorlinks=true,allcolors=blue]{hyperref}
\usepackage{stocksize}

\DeclareRobustCommand{\cs}[1]{\texttt{\char`\\#1}}
\DeclareRobustCommand{\marg}[1]{\texttt{\{#1\}}}

\newcommand{\ssname}{\textsf{\filename}}
\newcommand{\blue}[1]{\textcolor{blue!80!black}{#1}}

\newcommand{\printpagesize}[1][]{%
  \par\ifx&#1&\else
    The dimensions given for this page were: \blue{#1}.
  \fi
  
  \par\bigskip\noindent This page's dimensions (in pt) are:\medskip
  
  \begin{tabular}{lll}
    \toprule
                    & \multicolumn{1}{c}{\textbf{height}}   & \multicolumn{1}{c}{\textbf{width}}    \\
    \midrule
    \textbf{paper}  & \blue{\the\paperheight}  & \blue{\the\paperwidth}   \\
    \textbf{stock}  & \blue{\the\stockheight}  & \blue{\the\stockwidth}   \\    
    \textbf{text}  & \blue{\the\textheight}    & \blue{\the\textwidth}    \\    
    \bottomrule
  \end{tabular}\par\bigskip
}


\begin{document} 
  
  \title{The \ssname\ package}
  \author{João M. Lourenço\\\url{https://github.com/joaomlourenco/stocksize}}
  \date{\filedate\ (v\fileversion)}
  
  \maketitle
  
  \begin{abstract}
The \ssname\ package provides commands to query, modify, and restore the physical stock (paper) size within a \LaTeX{} document. 
It supports nested page size changes, automatic margin preservation, and integrates seamlessly with the \textsf{geometry} package. 
This package is ideal for workflows requiring adaptive page formats, multi-format printing, or dynamic layouts.
  \end{abstract}

\tableofcontents

\section{Introduction}

  The package 
    \href{https://github.com/davidcarlisle/geometry}{geometry} 
is excellent for customising the page layout. However, using the \cs{newgeometry} command (from the \textsf{geometry} package) to change the page size in the middle of the document only affects the typing area and does not impact the real paper (stock) size. This package circumvents this situation by resizing the paper (stock) size to the new page layout.

\subsection*{Terminology}

\begin{itemize}
  \item \textbf{Stock size} --- the physical sheet size (e.g., A4, Letter).
  \item \textbf{Paper size} --- the logical page defined in the \LaTeX{} document.
\end{itemize}

\section{User Interface}
  
\subsection{Loading the package}
  
To use the package, load it in the preamble:

\begin{minted}{python}
\usepackage{stocksize}
\end{minted}

The package automatically loads \textsf{geometry} (if not already loaded) and works with pdf\LaTeX, Xe\LaTeX, and Lua\LaTeX.

\subsection{Features}

\begin{description}
  \item [Dynamic page sizing]: Change paper dimensions mid-document. %✨
  \item [Nested sizes]: Stack multiple page sizes with automatic LIFO restoration. %🪆
  \item [Margin preservation]: Optionally keep and restore existing margins when resizing. %🧮
  \item [Compatible]: Minimal dependencies and easy integration. %⚙️
  \item [Debugging support]: Provides macros for easy querying of paper width and height. %🔍
  \item [Simple API]: Minimal commands to master. %🧰
  \item [Geometry integration]: Works with standard LaTeX classes and geometry setups. %🧩
  \item [Multi-engine support]: Works with pdfLaTeX, XeLaTeX, and LuaLaTeX. %🧠
  \item [Documented]: Companion documentation (`stocksize-doc.tex`) included. %🧾
\end{description}
  
\subsection{Starting a new page with a different page/stock size}
  
To start a new page with a different page/stock size use the \cs{newstocksize} and \cs{restorestocksize} commands.
  
  \begin{description}
    \item[] \cs{newstocksize}\marg{options} — This command starts a new stock (and paper) size.  The \verb!options! may include:
    \begin{description}
      \item[] \texttt{keepmargins} — The current (left, right, top, and bottom) margins will be preserved in the new page layout;
      \item[] \emph{other options} — The \emph{other options} are passed straight to the \verb!\newgeometry! command form the \verb!geometry! package.
    \end{description}
    \item[] \cs{restorestocksize} — This command ends the current stock size and restores the previous one (in a LIFO fashion).
  \end{description}
      
\subsection{Nesting different page/stock sizes}
  
  Multiple paper/stock sizes can be nested.  With each \cs{restorestocksize} command, the previous size is resumed.
  
  \begin{minted}{latex}
  This page has the default size  (e.g., a4paper).

    \newstocksize{layoutsize={15cm,10cm},margin=1.5cm}
    This page size is 15cm wide x 10cm high, with margins of 1.5cm.
    
      \newstocksize{layoutsize={20cm,20cm},margin=4.0cm}
      This page size is 20cm wide x 20cm high, with margins of 4.0cm.

    \restorestocksize
    Resuming the page size is 15cm wide x 10cm high, with margins of 1.5cm.
    
  \restorestocksize
  Resuming the default paper size and margins (e.g., a4paper)!

  \end{minted}
  

 \section{Notes and Limitations}

 \begin{itemize}
   \item Some drivers (e.g., \texttt{dvips}) may ignore stock size changes mid-document.
   \item Extremely deep nesting could hit TeX register limits.
   \item Packages that cache paper dimensions might not immediately reflect size changes.
 \end{itemize}
 
 \section{License}

 This work may be distributed and/or modified under the conditions of the 
 \LaTeX{} Project Public License, version 1.3c or later.  
 The latest version is available at \url{https://www.latex-project.org/lppl/}.

 \section{Version History}

 \begin{description}
   \item[v1.0.4 — November 2025] Improved documentation.
   \item[v1.0.3 — November 2024] Minor fix in the documentation.
   \item[v1.0.2 — November 2024] A new option (\cs{keepmargins}) to keep the current left/right/top/
   bottom margins in the new paper/stock size. Updated documentation.
   \item[v1.0.1 — November 2024] Initial version.
 \end{description}

 
  
\section{A Real Example of Different Page Sizes}

  % inital (21.0cm x 29.7cm)
  \printpagesize
  \kant[1-4]
  
  % new (15cm x 10cm)
  \newstocksize{layoutsize={15cm,10cm},margin=1.5cm}
  \printpagesize[15cm, 10cm, margin=1.5cm]
  \kant[1-2]
  
  % new (20cm x 20cm)
  \newstocksize{layoutsize={20cm,20cm},margin=4.0cm}
  \printpagesize[20cm, 20cm, margin=4cm]
  \kant[1-3]
  \restorestocksize
  
  % resume (15cm x 10cm)
  \printpagesize[15cm, 10cm, margin=1.5cm]
  \kant[1-2]
  \restorestocksize

  % resume (21.0cm x 29.7cm)
  \printpagesize
  \kant[1-5]

    
\end{document}