%% This is file `stocksize-doc.text',
%%
%% Copyright (C) 2024 by João 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[colorlinks=true,allcolors=blue]{hyperref}
\usepackage{stocksize}

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


\begin{document} 
  
  \title{The \textsf{\filename} package}
  \author{João M. Lourenço\\\url{https://github.com/joaomlourenco/stocksize}}
  \date{\filedate\ (v\fileversion)}
  
  \maketitle
  
  \begin{abstract}
    This package provides a flexible and easy interface to change the paper (stock) dimensions in LaTeX documents.
    Multiple user defined stock sizes are allowed in the same document, and stock sizes can be nested (in a LIFO order).
  \end{abstract}

\section{Introduction}

  The package 
    \href{https://github.com/davidcarlisle/geometry}{geometry} 
is excellent for customising the page layout. However, using the \verb!\newgeometry! command 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.

\section{User Interface}
  
\subsection{Loading the package}
  
  Simply load the package with (with no options):
  
  \begin{verbatim}
    \usepackage{stocksize}
  \end{verbatim}
  
\subsection{Starting a new page with a different page/stock size}
  
To start a new page with a different page/stock size use the \verb!\newstocksize! and \verb!\restorestocksize! commands.
  
  \begin{description}
    \item[] \verb!\newstocksize{options}! — This command starts a new stock (and paper) size.  The \verb!options! may include:
    \begin{description}
      \item[] \verb!keepmargins! — The current (left, right, top, and bottom) margins will be preserved in the new page layout;
      \item[] \verb!other_options! — The \verb!other_options! are passed straight to the \verb!\newgeometry! command form the \verb!geometry! package.
    \end{description}
    \item[] \verb!\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 \verb!\restorestocksize! command, the previous size is resumed.
  
  \begin{verbatim}
  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{verbatim}
  
  
\section{Example of multiple stock size pages}

  % 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=1cm]
  \kant[1-2]
  
  % new (20cm x 20cm)
  \newstocksize{layoutsize={20cm,20cm},margin=4.0cm}
  \printpagesize[20cm, 20cm, margin=1cm]
  \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}