summaryrefslogtreecommitdiff
path: root/support/wheretotrim/wheretotrim.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/wheretotrim/wheretotrim.dtx
Initial commit
Diffstat (limited to 'support/wheretotrim/wheretotrim.dtx')
-rw-r--r--support/wheretotrim/wheretotrim.dtx725
1 files changed, 725 insertions, 0 deletions
diff --git a/support/wheretotrim/wheretotrim.dtx b/support/wheretotrim/wheretotrim.dtx
new file mode 100644
index 0000000000..de8c5c1df1
--- /dev/null
+++ b/support/wheretotrim/wheretotrim.dtx
@@ -0,0 +1,725 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2013 by Scott Pakin <scott+wtt@pakin.org>
+% -------------------------------------------------------
+%
+% 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 2008/05/04 or later.
+%
+% \fi
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{wheretotrim.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{wheretotrim}
+%<*package>
+ [2013/05/15 v1.0 Helper package for the wheretotrim script]
+%</package>
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{tabularx}
+\usepackage{type1cm}
+\usepackage{pifont}
+\usepackage{needspace}
+\usepackage[bookmarksopen]{hyperref}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{wheretotrim.dtx}
+% \PrintChanges
+ \makeatletter
+ \let\orig@index@prologue=\index@prologue
+ \def\index@prologue{%
+ \phantomsection\addcontentsline{toc}{section}{Index}
+ \orig@index@prologue
+ }%
+ \makeatother
+ \Needspace{12\baselineskip}
+ \begingroup
+ \catcode`\_=12
+ \PrintIndex
+ \endgroup
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{180}
+%
+% \CharacterTable
+% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+%
+%
+% \changes{v1.0}{2013/05/15}{Initial version}
+%
+% \GetFileInfo{wheretotrim.dtx}
+%
+% \DoNotIndex{\",\$,\%,\(,\),!,\D,\d,\n}
+% \DoNotIndex{\addtocounter,\def,\edef,\fi,\gdef,\ifnum,\let}
+% \DoNotIndex{\newcommand,\newcounter,\noexpand,\noindent,\par,\relax}
+% \DoNotIndex{\setcounter,\space,\the,\value,\xdef}
+% \newcommand{\see}[1]{\textit{see} #1}
+% \index{command-line options|see{program options}}
+%
+% ^^A Define a few logical styles to help typeset the documentation.
+% \DeclareRobustCommand{\pkgname}[1]{^^A
+% \mbox{\textsf{#1}}^^A
+% \SortIndex{packages}{packages>\textsf{#1}}^^A
+% \SortIndex{#1}{\textsf{#1} (package)}}
+% \DeclareRobustCommand{\optname}[1]{^^A
+% \mbox{\texttt{#1}}^^A
+% \SortIndex{package options}{package options>\texttt{#1}}^^A
+% \SortIndex{#1}{\texttt{#1} (package option)}}
+% \DeclareRobustCommand{\progname}[1]{^^A
+% \mbox{\texttt{#1}}^^A
+% \SortIndex{programs}{programs>\texttt{#1}}^^A
+% \SortIndex{#1}{\texttt{#1} (program)}}
+% \DeclareRobustCommand{\longopt}[1]{^^A
+% \mbox{\textbf{-{}-#1}}^^A
+% \SortIndex{program options}{program options>\texttt{-{}-#1}}^^A
+% \SortIndex{#1}{\texttt{-{}-#1} (program option)}}
+%
+% ^^A Specify this document's metadata.
+% \title{The \textsf{wheretotrim} package\thanks{This document
+% corresponds to \textsf{wheretotrim}~\fileversion, dated \filedate.}}
+% \author{Scott Pakin \\ \texttt{scott+wtt@pakin.org}}
+% \hypersetup{^^A
+% pdfauthor={Scott Pakin},
+% pdftitle={The wheretotrim package},
+% pdfsubject={Determine where to cut text to most easily reduce page count}
+% }
+%
+% \maketitle
+% \sloppy
+%
+% \section{Introduction}
+% \label{sec:introduction}
+%
+% \progname{wheretotrim} is a tool to help \LaTeX\ users reduce their
+% document's page count. It is intended to be used with documents that
+% exceed a publisher's specified page-length limitation by a small
+% amount (much less than a full column or page). \progname{wheretotrim}
+% is therefore similar to the \pkgname{savetrees} package in that both
+% seek to reduce page count. The two differ in that \pkgname{savetrees}
+% saves space by altering document formatting while
+% \progname{wheretotrim} suggests where text can be removed to reduce
+% page count without altering any formatting. \progname{wheretotrim}
+% and \pkgname{savetrees} are compatible with each other, though:
+% \progname{wheretotrim} can safely be run on a document that includes a
+% |\usepackage{savetrees}|.
+%
+% \progname{wheretotrim} operates by building the document repeatedly,
+% successively expanding each column on each page by one line height to
+% mimic reducing the amount of text in that column by an equivalent
+% amount. If doing so does not reduce the page count,
+% \progname{wheretotrim} repeats the process with two line heights'
+% expansion of each column, then three, and so forth until it expands
+% each column in turn by the full height of the column. The following
+% is some sample output for a single-column document when
+% \progname{wheretotrim} is run with the \longopt{allpages} option
+% (cf.~Section~\ref{sec:cmdline}):
+% \begin{verbatim}
+% To reduce the page count from 11 to 10, do any of the following:
+%
+% * Reduce page 2 by 8 lines.
+% * Reduce page 5 by 7 lines.
+% * Reduce page 6 by 7 lines.
+% * Reduce page 7 by 7 lines.
+% * Reduce page 8 by 7 lines.
+% * Reduce page 9 by 7 lines.
+% * Reduce page 10 by 5 lines.
+% * Reduce page 11 by 5 lines.
+%
+% Note: 5 lines = 1.0" = 2.5 cm = 11.1% of the page height
+% \end{verbatim}
+%
+% \noindent
+% That is, reducing either page~10 or page~11 by five lines is the most
+% expedient way to reduce the document's page count. Seven lines would
+% need to be cut from page~5, 6, 7, or~8 to achieve the same effect, and
+% eight lines would need to be cut from page~2. In contrast, no amount
+% of text trimming on pages~1, 3, or~4 will reduce the page count.
+%
+% \section{Usage}
+% \label{sec:usage}
+%
+% Sections~\ref{sec:cmdline}--\ref{sec:restrictions} explain how to use
+% \progname{wheretotrim}.
+%
+% \subsection{Command-line options}
+% \label{sec:cmdline}
+%
+% Run \progname{wheretotrim} as follows:
+%
+% \DeleteShortVerb{\|}
+% \begin{quote}
+% \raggedright
+% \progname{wheretotrim}
+% [\longopt{allpages}]
+% [\longopt{verbose} \textbar\ \longopt{quiet}]
+% [\longopt{debug}=\meta{page},\meta{column},\meta{lines}]
+% \meta{latex command}
+% \end{quote}
+% \noindent
+% or
+% \begin{quote}
+% \raggedright
+% \progname{wheretotrim} [\longopt{verbose}] \longopt{help} \textbar\ \longopt{version}
+% \end{quote}
+% \MakeShortVerb{\|}
+%
+% \progname{wheretotrim} accepts the following command-line options:
+%
+% \begin{description}
+% \item[-a, \longopt{allpages}] Perform enough extra runs of
+% \progname{latex} to report the amount of space that must be
+% trimmed from \emph{each} column or page to reduce page count, not
+% just the columns or pages to which the page count is the most
+% sensitive.
+%
+% \item[-v, \longopt{verbose}] Display the output of each run of
+% \progname{latex}. This is useful for troubleshooting and to help
+% monitor the progress of long \progname{latex} runs.
+%
+% \item[-q, \longopt{quiet}] Suppress progress updates and output only the
+% final report.
+%
+% \item[-d \meta{page},\meta{column},\meta{lines},
+% \longopt{debug}=\meta{page},\meta{column},\meta{lines}] Debug
+% \progname{wheretotrim}'s execution by expanding page \meta{page},
+% column \meta{column} by \meta{lines} line heights and leaving the
+% \progname{latex} output in that state.
+%
+% \item[-h, \longopt{help}] Summarize usage information and exit.
+% These may be used with \longopt{verbose} to display more extended
+% documentation.
+%
+% \item[-V, \longopt{version}] Display \progname{wheretotrim}'s version
+% number and exit.
+% \end{description}
+%
+% In addition to the preceding options, \progname{wheretotrim} requires
+% a \meta{latex command} argument that specifies how to build the
+% document.
+%
+% \subsection{Examples}
+% \label{sec:examples}
+%
+% For the most basic usage, simply provide a \progname{latex} command to
+% run:
+%
+% \begin{verbatim}
+% wheretotrim latex myfile.tex
+% \end{verbatim}
+%
+% \noindent
+% or, for example,
+%
+% \begin{verbatim}
+% wheretotrim pdflatex myfile.tex
+% \end{verbatim}
+%
+% \progname{wheretotrim} executes the specified command a large number
+% of times and finally terminates with a report resembling the
+% following:
+%
+% \begin{verbatim}
+% To reduce the page count from 10 to 9, do any of the following:
+%
+% * Reduce page 9, column 1 by 12 lines.
+% * Reduce page 9, column 2 by 12 lines.
+% * Reduce page 10, column 1 by 12 lines.
+%
+% Note: 12 lines = 2.4" = 6.1 cm = 26.8% of the column height
+% \end{verbatim}
+%
+% To ask \progname{wheretotrim} to report how much space needs to be
+% trimmed on each column and page to reduce the total page count,
+% specify the \longopt{allpages} option:
+%
+% \begin{verbatim}
+% wheretotrim --allpages latex myfile.tex
+% \end{verbatim}
+%
+% The output now looks like the following:
+%
+% \begin{verbatim}
+% To reduce the page count from 10 to 9, do any of the following:
+%
+% * Reduce page 1, column 1 by 13 lines.
+% * Reduce page 1, column 2 by 13 lines.
+% * Reduce page 2, column 1 by 13 lines.
+% * Reduce page 2, column 2 by 13 lines.
+% * Reduce page 4, column 1 by 13 lines.
+% * Reduce page 4, column 2 by 13 lines.
+% * Reduce page 5, column 1 by 13 lines.
+% * Reduce page 5, column 2 by 13 lines.
+% * Reduce page 6, column 1 by 13 lines.
+% * Reduce page 6, column 2 by 13 lines.
+% * Reduce page 7, column 1 by 13 lines.
+% * Reduce page 7, column 2 by 13 lines.
+% * Reduce page 8, column 1 by 13 lines.
+% * Reduce page 8, column 2 by 13 lines.
+% * Reduce page 9, column 1 by 12 lines.
+% * Reduce page 9, column 2 by 12 lines.
+% * Reduce page 10, column 1 by 12 lines.
+%
+% Note: 12 lines = 2.4" = 6.1 cm = 26.8% of the column height
+% \end{verbatim}
+%
+% If you're curious how the document managed to shrink substantially as
+% the result of a relatively minor text reduction, you can typeset the
+% document with a particular page and column enlarged by a given amount:
+%
+% \begin{verbatim}
+% wheretotrim --debug=9,1,12 latex myfile.tex
+% \end{verbatim}
+%
+% \subsection{Caveats}
+% \label{sec:caveats}
+%
+% \progname{wheretotrim} hooks into \LaTeX's output routines, which are
+% notoriously arcane and somewhat fragile. As a result, it is quite
+% likely that \progname{wheretotrim} will fail to analyze a large set of
+% documents. Use the \longopt{verbose} flag to help identify any
+% problems that \progname{latex} encounters.
+%
+% In many cases, \progname{wheretotrim} will recover by simply ignoring
+% a few possible page and column expansions. For example, certain
+% expansions may result in a
+% \href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=fllost}{\texttt{Float(s)
+% lost}} message. In other cases, \progname{wheretotrim} will fail
+% to analyze any modification to the document. For example, it may
+% receive an \texttt{Infinite glue shrinkage found in box being split}
+% error from every page and column variation it tries. In this
+% particular case, see the discussion at
+% \url{http://www.michaelshell.org/tex/ieeetran/}.
+%
+% When \progname{wheretotrim} is used with a \progname{latex} auto-build
+% script you may need to take measures to force the script to rebuild
+% the document even if it appears that no files have changed. For
+% example, \progname{latexmk} should be given the |-CF| option to force
+% rebuilding:
+%
+% \begin{verbatim}
+% wheretotrim latexmk -CF myfile.tex
+% \end{verbatim}
+%
+% \subsection{Restrictions}
+% \label{sec:restrictions}
+%
+% \progname{wheretotrim} is implemented as a Perl script with an
+% auxiliary \LaTeXe\ package. It has been tested only on Linux, but I
+% suspect that it should also work on OS~X. I doubt it will work
+% under Windows, though, due to the way the script uses a
+% \progname{bash}-specific technique for redirecting the standard error
+% device into the standard output device.
+%
+%
+% \StopEventually{}
+%
+% \iffalse
+%<*package>
+% \fi
+%
+% \section{Package implementation}
+%
+% This section presents the commented \LaTeX\ source code for the
+% \pkgname{wheretotrim} package. Read this section if you want to learn
+% how the package is implemented. Note that the package is not intended
+% to be used explicitly (i.e.,~via |\usepackage|) but rather implicitly
+% by the \progname{wheretotrim} Perl script.
+%
+% \subsection{Theory of operation}
+%
+% The \pkgname{wheretotrim} package mimics the effect of reducing a
+% given page and column of a document by a given number of line heights.
+% For simplicity, it does so by enlarging the specified column (so
+% as to fit additional lines of text) rather than by reducing the
+% amount of text in that column.
+%
+% Users are not expected to load the \pkgname{wheretotrim} package
+% explicitly. Instead, whenever the \progname{wheretotrim} script needs
+% to observe the effect of enlarging a given column, it creates a
+% temporary |.tex| file using the following template:
+%
+% \begingroup
+% \ttfamily
+% \begin{tabbing}
+% ~~~~\=|\RequirePackage[|\=\kill
+% \>|\RequirePackage[|\> column={\normalfont\meta{absolute column}}], \\
+% \> \> expansion={\normalfont\meta{lines}}, \\
+% \> \> extracols={\normalfont\meta{padding columns}}]|{wheretotrim}| \\
+% \> |\PassOptionsToPackage{draft}{hyperref}| \\
+% \> |\input{|{\normalfont\meta{filename}}|}| \\
+% \end{tabbing}
+% \endgroup
+%
+% \noindent
+% where \meta{absolute column} is the absolute column number to expand
+% (with the first column on the first page being numbered~ 1);
+% \meta{lines} is the number of line heights (multiples of
+% |\baselineskip|) by which to enlarge that column; \meta{padding
+% columns} is the number of extra full columns to append to the
+% document (cf.~Section~\ref{sec:page-spillover}); and \meta{filename}
+% is the name of the user's top-level \LaTeX\ file.
+%
+% The \pkgname{wheretotrim} package works by modifying various \TeX- and
+% \LaTeX-internal commands. At every |\shipout|, \pkgname{wheretotrim}
+% increases the absolute page counter. Whenever \LaTeX\ constructs a
+% column using |\@makecol|, \pkgname{wheretotrim} logs the current
+% absolute page and column numbers and invokes \LaTeX's
+% |\enlargethispage| macro when on the target page and column number.
+% Because |\@makecol| is not called for every column,
+% \pkgname{wheretotrim} additionally modifies |\clearpage| and
+% |\maketitle| also to conditionally enlarge the current column.
+%
+% At the end of the document, \pkgname{wheretotrim} outputs
+% |\baselineskip| and |\textheight|, as these are needed by the
+% \progname{wheretotrim} script.
+%
+% \subsection{Package options}
+% \label{sec:pkg-opts}
+%
+% The \pkgname{wheretotrim} package accepts three package
+% options---\optname{column}, \optname{expansion}, and
+% \optname{extracols}---which are described
+% below in the context of, respectively, |\wtt@target@column|,
+% |\wtt@column@expand|, and |\wtt@extra@full@columns|.
+%
+% \begin{macro}{\wtt@target@column}
+% |\wtt@target@column| is set by the \optname{column} option and
+% defaults to nonexistent column~0. It specifies the absolute column
+% number to expand.
+% \begin{macrocode}
+\newcommand{\wtt@target@column}{0}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\wtt@column@expand}
+% The |\wtt@column@expand| length---implemented as an ordinary
+% macro---is set by the \optname{expansion} option and defaults to
+% 0\,pt. It specifies the number of lines by which to expand that
+% column (i.e.,~the multiple of |\baselineskip|).
+% \begin{macrocode}
+\newcommand{\wtt@column@expand}{0pt}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\wtt@extra@full@columns}
+% |\wtt@extra@full@columns| is set by the \optname{extracols} option and
+% specifies the number of additional, dummy, full columns to append to
+% the end of the document to force spillover onto an additional page.
+% \begin{macrocode}
+\newcommand{\wtt@extra@full@columns}{0}
+% \end{macrocode}
+% \end{macro}
+%
+% We use the \pkgname{keyval} package to help with option processing as
+% it's widely available and \pkgname{wheretotrim}'s option-processing
+% needs are fairly simple.
+% \begin{macrocode}
+\RequirePackage{keyval}
+% \end{macrocode}
+% \begin{macrocode}
+\define@key{wtt}{column}{\gdef\wtt@target@column{#1}}
+\define@key{wtt}{expansion}{%
+ \xdef\wtt@column@expand{#1\noexpand\baselineskip}%
+}
+\define@key{wtt}{extracols}{\gdef\wtt@extra@full@columns{#1}}
+% \end{macrocode}
+%
+% \begin{macro}{\next}
+% Process our options. We need to expand |\CurrentOption| before
+% passing it to \pkgname{keyval}'s |\setkeys| macro, however.
+% \begin{macrocode}
+\DeclareOption*{%
+ \edef\next{\noexpand\setkeys{wtt}{\CurrentOption}}%
+ \next
+}
+\ProcessOptions\relax
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Column enlargement}
+% \label{sec:col-enlarge}
+%
+% \begin{macro}{\c@wtt@true@page}
+% The \pkgname{wheretotrim} package needs to keep track of the current
+% page number. The |page| counter is unsuitable for this task because
+% it is really a page \emph{name}. That is, (1)~it is not necessarily
+% numeric (e.g.,~it may be a roman numeral while in the document's front
+% matter), and (2)~it is not necessarily unique (e.g.,~|page| may be~|1|
+% on the title page, abstract, and first page of text). To address this
+% limitation we define a |wtt@true@page| counter and, with the help of
+% the \pkgname{everyshi} package, prepare for it to be incremented on
+% every \TeX\ page shipout.
+% \begin{macrocode}
+\newcounter{wtt@true@page}
+\setcounter{wtt@true@page}{1}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+\RequirePackage{everyshi}
+\EveryShipout{\addtocounter{wtt@true@page}{1}}
+% \end{macrocode}
+%
+% \begin{macro}{\c@wtt@column@num}
+% The \pkgname{wheretotrim} package also needs to keep track of the
+% current absolute column number. By ``absolute'' we mean a running
+% column number that does not reset to~1 on each page. We define a
+% |wtt@column@num| counter to hold the current column number, and,
+% below, we modify \LaTeXe's |\@makecol| macro to increment it. Note
+% that some pages may contain fewer pages than others due to, for
+% example, |\clearpage| calls that cause pages to ship out early.
+% \begin{macrocode}
+\newcounter{wtt@column@num}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\wtt@makecol}
+% Before redefining |\@makecol|, we store its old definition in
+% |\wtt@makecol|.
+% \begin{macrocode}
+\let\wtt@makecol=\@makecol
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@makecol}
+% |\@makecol| is \LaTeXe's primary mechanism for typesetting a column:
+%
+% \begin{center}
+% \small
+% \begin{tabularx}{\linewidth}{@{}rX@{}}
+% \hspace{1em}|\@makecol|:
+% & Makes the contents of |\box||255| plus the accumulated footnotes,
+% plus the floats in |\@toplist| and |\@botlist|, into a single
+% column of height |\@colht| (unless the page height has been
+% locally changed), which it puts into box |\@outputbox|. It puts
+% boxes in |\@midlist| back onto |\@freelist| and restores
+% |\maxdepth|.
+% \end{tabularx}
+% \end{center}
+%
+% Here, we augment |\@makecol| with code to report the current column
+% and page number---and for the user's convenience, page name
+% (|\thepage|). Our redefined |\@makecol| then increments the current
+% absolute column number and compares it against |\wtt@target@column|.
+% If equal, it uses \LaTeXe's |\enlargethispage| to increase the column
+% height. Finally, it invokes the original |\@makecol| (stored in
+% |\wtt@makecol| to typeset the column.
+% \begin{macrocode}
+\def\@makecol{%
+ \PackageInfo{wheretotrim}%
+ {Column \thewtt@column@num\space is on page
+ \thewtt@true@page\space (\thepage)}%
+ \addtocounter{wtt@column@num}{1}%
+ \ifnum\value{wtt@column@num}=\wtt@target@column
+ \enlargethispage{\wtt@column@expand}%
+ \fi
+ \wtt@makecol
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\wtt@clearpage}
+% Before redefining |\clearpage|, we store its old definition in
+% |\wtt@clearpage|.
+% \begin{macrocode}
+\let\wtt@clearpage=\clearpage
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\clearpage}
+% \LaTeXe's |\clearpage| macro frustrates the \pkgname{wheretotrim}
+% package's attempts to enlarge a given column. We therefore redefine
+% |\clearpage| first to perform its ordinary behavior (stored in
+% |\wtt@clearpage|, then to check the value of the preceding penalty
+% item. If the last penalty is -10001 then this is an opportune time to
+% insert an |\enlargethispage| (assuming the current column is equal to
+% |\wtt@target@column|). Because |\clearpage| may be called multiple
+% times in a row and may be followed by |\@makecol| we restore the
+% column counter to its prior value after comparing it to
+% |\wtt@target@column| so it is not multiply incremented.
+%
+% Note that |\cleardoublepage| internally calls |\clearpage| so it is
+% sufficient to redefine only |\clearpage|.
+% \begin{macrocode}
+\gdef\clearpage{%
+ \wtt@clearpage
+ \ifnum\lastpenalty=-10001\relax
+ \addtocounter{wtt@column@num}{1}%
+ \ifnum\value{wtt@column@num}=\wtt@target@column
+ \enlargethispage{\wtt@column@expand}%
+ \fi
+ \addtocounter{wtt@column@num}{-1}%
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+% Wait until after the |\begin{document}| to redefine |\maketitle| in
+% case |\maketitle| is modified before that point.
+% \begin{macrocode}
+\AtBeginDocument{%
+% \end{macrocode}
+% \begin{macro}{\wtt@maketitle}
+% Before redefining |\maketitle|, we store its old definition in
+% |\wtt@maketitle|.
+% \begin{macrocode}
+ \let\wtt@maketitle=\maketitle
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\maketitle}
+% |\maketitle| is problematic macro for the \pkgname{wheretotrim}
+% package because of the way it switches into two-column mode within a
+% one-column document (via \LaTeXe's |\twocolumn| macro). For lack of a
+% more general solution we redefine |\maketitle| to enlarge the column
+% only after typesetting the title and only when in two-column mode.
+% Otherwise, the |\enlargethispage| inserted by |\@makecol| already had
+% its intended effect.
+% \begin{macrocode}
+ \gdef\maketitle{%
+ \wtt@maketitle
+ \if@twocolumn
+ \ifnum\value{wtt@column@num}=\wtt@target@column
+ \enlargethispage{\wtt@column@expand}%
+ \fi
+ \fi
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Page spillover}
+% \label{sec:page-spillover}
+%
+% Normally, it would not be possible to reduce page count by enlarging
+% the last column by any amount. The trick we use here is to add to the
+% end of the document a full column or two to make the document spill
+% over onto an additional page, as illustrated by
+% Figure~\ref{fig:page-spillover}. Thus, enlarging the last column by
+% the height of the text it contains will enable a padding column to
+% shift into that column and reduce the page count.
+%
+% \begin{figure}[htbp]
+% \centering
+% \fbox{^^A
+% \begin{minipage}[t][3cm]{1cm}
+% \fontsize{2}{2}\selectfont\raggedright
+% \vspace{4pt}
+% Quisque fringilla, felis eu ultricies commodo, tortor justo lobortis
+% est, sit amet molestie ligula lorem at urna. Duis sit amet ligula
+% odio, sed varius massa. Duis lacinia odio elit. Nam adipiscing orci
+% eu lectus tincidunt porta rhoncus in nisl. Mauris tincidunt mollis
+% malesuada.
+% \end{minipage}
+% \begin{minipage}[t][3cm]{1cm}
+% \mbox{}
+% \end{minipage}
+% }
+% \begin{minipage}[t][3cm]{1cm}
+% \vspace{1cm}
+% \fontsize{36}{36}\ding{220}
+% \end{minipage}
+% ~^^A
+% \fbox{^^A
+% \begin{minipage}[t][3cm]{1cm}
+% \fontsize{2}{2}\selectfont\raggedright
+% \vspace{4pt}
+% Quisque fringilla, felis eu ultricies commodo, tortor justo lobortis
+% est, sit amet molestie ligula lorem at urna. Duis sit amet ligula
+% odio, sed varius massa. Duis lacinia odio elit. Nam adipiscing orci
+% eu lectus tincidunt porta rhoncus in nisl. Mauris tincidunt mollis
+% malesuada.
+% \end{minipage}
+% \begin{minipage}[t][3cm]{1cm}
+% \rule[-2.9cm]{1cm}{2.8cm}
+% \end{minipage}
+% }
+% \fbox{^^A
+% \begin{minipage}[t][3cm]{1cm}
+% \rule[-2.9cm]{1cm}{2.8cm}
+% \end{minipage}
+% \begin{minipage}[t][3cm]{1cm}
+% \mbox{}
+% \end{minipage}
+% }
+% \caption{Padding a document with extra columns to induce page spillover}
+% \label{fig:page-spillover}
+% \end{figure}
+%
+% \begin{macrocode}
+\AtEndDocument{%
+% \end{macrocode}
+% Add zero, one, or two columns of padding (a |\parbox| of width
+% |\linewidth| and height |\textheight|) based on the value of
+% |\wtt@extra@full@columns| (set by the \optname{extracols} package
+% option).
+% \begin{macrocode}
+ \ifnum\wtt@extra@full@columns>0\relax
+ \noindent\parbox[t][\textheight]{\linewidth}{%
+ \rule{\linewidth}{\baselineskip}}\par
+ \ifnum\wtt@extra@full@columns>1\relax
+ \noindent\parbox[t][\textheight]{\linewidth}{%
+ \rule{\linewidth}{\baselineskip}}\par
+ \fi
+ \fi
+% \end{macrocode}
+% Also at the end of the document, output the value of |\baselineskip|
+% and the value of |\textheight|, as these are read by the
+% \progname{wheretotrim} script.
+% \begin{macrocode}
+ \PackageInfo{wheretotrim}%
+ {Baseline skip: \the\baselineskip}%
+ \PackageInfo{wheretotrim}%
+ {Text height: \the\textheight}%
+}
+% \end{macrocode}
+%
+% \iffalse
+%</package>
+% \fi
+%
+% \section{Script implementation}
+%
+% This section presents the commented \LaTeX\ source code for the
+% \progname{wheretotrim} Perl script. Read this section if you want
+% to learn how the script is implemented.
+%
+% \iffalse
+%<*script>
+% \fi
+%
+% \DocInput{wheretotrim-pl.dtx}
+%
+% \iffalse
+%</script>
+% \fi
+%
+% \Finale
+\endinput