summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/textpos
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-05-04 22:47:13 +0000
committerKarl Berry <karl@freefriends.org>2019-05-04 22:47:13 +0000
commitb29d97e34cfe9a6d8ecf55de223c21ae703bda8a (patch)
tree498144d9a2082c1e12cbf4c3fb28d00a58754221 /Master/texmf-dist/source/latex/textpos
parentc454261d3133ff69d91828cf2411f1d830c7b249 (diff)
textpos (16apr19)
git-svn-id: svn://tug.org/texlive/trunk@50988 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/textpos')
-rw-r--r--Master/texmf-dist/source/latex/textpos/textpos.drv10
-rw-r--r--Master/texmf-dist/source/latex/textpos/textpos.dtx288
2 files changed, 200 insertions, 98 deletions
diff --git a/Master/texmf-dist/source/latex/textpos/textpos.drv b/Master/texmf-dist/source/latex/textpos/textpos.drv
index d4e867177ba..c77cc9eb131 100644
--- a/Master/texmf-dist/source/latex/textpos/textpos.drv
+++ b/Master/texmf-dist/source/latex/textpos/textpos.drv
@@ -7,7 +7,7 @@
%% textpos.dtx (with options: `driver')
%% Textpos: absolute positioning of text on the page
%%%% File: textpos.dtx
-%%%% Copyright 1999, 2001-03, 2005-7, 2009-12, 2014-16., Norman Gray
+%%%% Copyright 1999-2019, Norman Gray
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
@@ -22,20 +22,20 @@
%% The Current Maintainer of this work is Norman Gray <http://nxg.me.uk>
%%
%% This work consists of the files textpos.dtx and textpos.ins,
-%% and the derived file textpos.cls.
+%% and the derived file textpos.sty.
%%
%% Author: Norman Gray, norman@astro.gla.ac.uk.
%% Department of Physics and Astronomy, University of Glasgow, UK
%%
%% See the file LICENCE for a copy of the LPPL.
%%
-%% Mercurial ident: 8aa202e2b283, 2016-06-07 23:52 +0100
+%% Mercurial ident: 09ee0efc21ac (1.9.1+0), 2019-04-15 22:14 +0100
%%
\documentclass{ltxdoc}
\title{Textpos: absolute positioning of text on the page}
\author{Norman Gray\\(\texttt{http://nxg.me.uk})}
-\date{Version 1.8, 2016 June 7\footnote{Mercurial ident: 8aa202e2b283, 2016-06-07 23:52 +0100.
-This software is copyright, 1999, 2001-03, 2005-7, 2009-12, 2014-16. Norman Gray.
+\date{Version 1.9.1, 2019 April 15\footnote{Mercurial ident: 09ee0efc21ac (1.9.1+0), 2019-04-15 22:14 +0100.
+This software is copyright, 1999-2019 Norman Gray.
It is released under the terms of the LaTeX Project Public License,
either version 1.3 of this licence or (at your option) any later version.
The latest version of this license is at \texttt{http://www.latex-project.org/lppl.txt}.}}
diff --git a/Master/texmf-dist/source/latex/textpos/textpos.dtx b/Master/texmf-dist/source/latex/textpos/textpos.dtx
index 1d52892300e..7be07003894 100644
--- a/Master/texmf-dist/source/latex/textpos/textpos.dtx
+++ b/Master/texmf-dist/source/latex/textpos/textpos.dtx
@@ -3,7 +3,7 @@
% anywhere on the LaTeX page. It's useful for posters.
%
%%%% File: textpos.dtx
-%%%% Copyright 1999, 2001-03, 2005-7, 2009-12, 2014-16., Norman Gray
+%%%% Copyright 1999-2019, Norman Gray
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
@@ -18,25 +18,25 @@
%% The Current Maintainer of this work is Norman Gray <http://nxg.me.uk>
%%
%% This work consists of the files textpos.dtx and textpos.ins,
-%% and the derived file textpos.cls.
+%% and the derived file textpos.sty.
%%
%% Author: Norman Gray, norman@astro.gla.ac.uk.
%% Department of Physics and Astronomy, University of Glasgow, UK
%%
%% See the file LICENCE for a copy of the LPPL.
%%
-%% Mercurial ident: 8aa202e2b283, 2016-06-07 23:52 +0100
+%% Mercurial ident: 09ee0efc21ac (1.9.1+0), 2019-04-15 22:14 +0100
%%
%<+package>\NeedsTeXFormat{LaTeX2e}
-%<+package>\ProvidesPackage{textpos}[2016/06/07 v1.8]
-%<+package>\typeout{Package: textpos 2016/06/07 1.8, absolute positioning of text on the page}
+%<+package>\ProvidesPackage{textpos}[2019/04/15 v1.9.1]
+%<+package>\typeout{Package: textpos 2019/04/15 1.9.1, absolute positioning of text on the page}
%
%<*driver>
\documentclass{ltxdoc}
\title{Textpos: absolute positioning of text on the page}
\author{Norman Gray\\(\texttt{http://nxg.me.uk})}
-\date{Version 1.8, 2016 June 7\footnote{Mercurial ident: 8aa202e2b283, 2016-06-07 23:52 +0100.
-This software is copyright, 1999, 2001-03, 2005-7, 2009-12, 2014-16. Norman Gray.
+\date{Version 1.9.1, 2019 April 15\footnote{Mercurial ident: 09ee0efc21ac (1.9.1+0), 2019-04-15 22:14 +0100.
+This software is copyright, 1999-2019 Norman Gray.
It is released under the terms of the LaTeX Project Public License,
either version 1.3 of this licence or (at your option) any later version.
The latest version of this license is at \texttt{http://www.latex-project.org/lppl.txt}.}}
@@ -117,9 +117,9 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% This package requires the services of Martin Schr\"oder's package
% \texttt{everyshi}. If this is not already part of your \TeX{}
% installation, you will need to download this package from CTAN. See
-% \url{http://www.tex.ac.uk/tex-archive/macros/latex/contrib/supported/ms/}
-% or one of the other CTAN hosts.
+% \url{https://www.ctan.org/pkg/everyshi}.
%
+% The canonical CTAN URL for Textpos is \url{https://ctan.org/pkg/textpos}.
% Textpos has a home page at \url{http://purl.org/nxg/dist/textpos}.
% The source is held at bitbucket: \url{https://bitbucket.org/nxg/textpos},
% and there is an issues list there, for bug reports. Code
@@ -202,11 +202,15 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% Here \meta{hpos} and \meta{vpos} are dimensions such as `10mm',
% relative to the top-left corner of the paper. You may use this
% command only if the package was invoked with the \Lopt{absolute}
-% option. See also section~\ref{packopts} for how to alternate
-% between modes, and section~\ref{absolute-newpage} for notes on the
-% interaction with the |\newpage| command.
+% option.
%
-% The textblocks are placed on the page in the order in which they
+% See also section~\ref{packopts} for how to alternate
+% between modes, see section~\ref{absolute-newpage} for notes on the
+% interaction with the |\newpage| command, and see
+% section~\ref{s:absrelmode} for some subtleties about choosing which
+% mode to use.
+%
+% The textblocks are placed on the page\marginpar{layers} in the order in which they
% appear in the file. This means that later textblocks will be placed
% on top of earlier ones, which may matter if one or other contains,
% for example, a block of opaque colour (I believe this to be true in
@@ -238,11 +242,8 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% can be useful when you are previewing a document.
% \item[\Lopt{absolute}]If this is present, then the positions on the
% \Lenv{textblock} environment are taken to be absolute positions on
-% the page. See above for more detail, and see
-% section~\ref{absolute-newpage} for the interaction with the
-% |\newpage| command. There is also a \Lopt{relative} option, but
-% since relative mode is, and will remain, the default, the
-% \Lopt{relative} option is redundant, and is here only for symmetry.
+% the page. There is also a \Lopt{relative} option, which is the default.
+% See above for more detail.
% \item[\Lopt{overlay}]When using the absolute-position mode, the
% textblocks are placed under any other text on the page. This is
% normally what you want, but if you have page contents, and they have
@@ -384,9 +385,20 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
%
% Note: This behaviour was somewhat underspecified in versions of
% textpos before v1.8, and in consequence inconsistently implemented.
-% The rationalisation here \emph{may} change documents which relied on
+% The rationalisation in this version \emph{may} change documents which relied on
% the previous behaviour.
%
+% \begin{macro}{\TPReferencePosition}
+% As noted, the default reference position is |[0,0]|. This can be overridden
+% using the |\TPReferencePosition| command, which takes as argument
+% the reference position argument to be used for subsequent boxes.
+% Thus |\TPReferencePosition{0.5,0.5}| (note no square brackets) would
+% cause subsequent boxes to be centred on their
+% location\footnote{Thanks to an anonymous textpos user for the suggestion
+% here, which was added in v1.9
+% -- I was surprised that this functionality hadn't been present for years.}.
+% \end{macro}
+%
% \subsubsection{Specifying textblocks with absolute sizes}
% \label{s:textblock-absolute}
%
@@ -461,6 +473,14 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% frames and wish to make them a feature of your poster's design, you
% may adjust the size using |\setlength| or |\addtolength|. The
% default is 0.4pt. See also the |\textblockrulecolour| command.
+% Note that the \Lopt{showboxes} option is mostly conceived of as an
+% aid to layout, and so the options for customising these rules are
+% rather limited. If you wish more extensively customised boxes, then
+% you would probably be best using a package which provides specific
+% support for that, going beyond what could be usefully added to
+% textpos.\footnote{A StackOverflow discussion at
+% \url{https://tex.stackexchange.com/questions/34088/} suggests
+% packages TikZ, mdframed or tcolorbox.}
% \item[\texttt{\bslash textblocklabel}]
% \DescribeMacro{\textblocklabel}
% This may be used within any \Lenv{textblock}
@@ -574,8 +594,8 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \newpage}
% \end{verbatim}
% This inserts a complete page, with some graphic on it, immediately
-% after the end of the current page (thanks to Matthias Gloede for
-% this technique).
+% after the end of the current page\footnote{Thanks to Matthias Gloede for
+% this technique.}.
%
% \section{Notes}
% \subsection{Suggestions: Producing large-format posters}
@@ -616,53 +636,86 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% This happens for the same reason that, also quite surprisingly, two
% |\newline| commands in a row do not produce a blank page.
%
-% \subsection{Interactions}
-% \label{s:interactions}
-%
-% Textpos does not appear to get on terribly well with
-% Prosper\marginpar{textpos \& prosper} (a
-% problem reported by Erik Van Eynde). This is because
-% Textpos in absolute mode places its text onto the page at the last
-% moment before the page is shipped out, which will be \emph{after}
+% \subsection{Absolute or relative mode?}
+% \label{s:absrelmode}
+%
+% The \Lopt{absolute} mode appears to be the obvious mode to choose:
+% the positions it specifies are independent of margins, spacing and
+% other offsets, and so easier to think with. Because of the way
+% \Lopt{absolute} mode is implemented, however, it has some
+% interactions which may make \Lopt{relative} mode better in some
+% cases.
+%
+% \Lopt{absolute} mode works by inserting a \TeX\ box into a page at
+% almost the last moment before the page is finalised for output (at
+% |\shipout| time, if you're a \TeX\ afficionado). This is normally
+% robust, and in many ways it is an attractively simple solution, but
+% it may interact badly with other packages which
+% manipulate this `shipout' box, or packages which juggle or inspect
+% boxes at or just before this late stage. In particular, the Prosper
+% package manipulates the page just before this stage,
+% the Color package inserts material using |\shipout|.
+%
+% Similarly the TikZ package\marginpar{textpos \& TikZ}
+% (or at least its `externalize' support) examines the page at
+% a time which means it fails to spot the absolute-mode textpos
+% material. In the TikZ case, you can try using the
+% option |\TPoptions{discardcontent=true}| which,
+% in Textpos absolute mode, discards the contents of all
+% |{textblock}| boxes, in a way which should make it compatible with
+% TikZ. This option is \emph{experimental} in Textpos v1.9, and may
+% change or disappear in future versions -- the author would be
+% particular interested to get feedback regarding this
+% option.\footnote{My understanding of the problem here is derived from an excellent Stackoverflow answer
+% by `JLDiaz' \url{http://tex.stackexchange.com/a/66853}, a Textpos
+% bugreport by Michael H\"upkes, and a discussion on the PGF bugparade
+% \url{https://github.com/pgf-tikz/pgf/issues/393}.}
+%
+% These are discussed in a little more detail below, but in each of
+% these cases, using textpos in \Lopt{relative} mode will evade the
+% problem. This solution will work in the cases where the
+% \Lenv{textblock} environment is at a more-or-less predictable
+% location on the page.
+%
+% Textpos and Prosper\marginpar{textpos \& prosper} squabble because
+% Textpos in absolute mode places its text onto the page \emph{after}
% Prosper has rotated the page from portrait to landscape format, so
% that the \Lenv{textblock} contents end up at the correct position on
-% the portrait page, but the wrong position on the landscape page.
-% This unfortunately means that Textpos in absolute mode is
-% incompatible with Prosper. But all is not lost: since Prosper
-% slides start at a consistent point, you can fairly happily use Textpos in
+% the portrait page, but the wrong position on the landscape
+% page\footnote{Thanks to Erik Van Eynde for the initial discussion of this.}.
+% Since Prosper slides start at a consistent point, however, you can fairly happily use Textpos in
% relative mode as long as the \Lenv{textblock} environment is the
% first thing on the slide.
-% \marginpar{\dots \& beamer}
-% For a similar reason, you should use the \Lopt{overlay,absolute}
-% options with Beamer.\footnote{This is also because the Beamer
-% background frame overlays the textpos material, unless the
-% \Lopt{overlay} option is used to tell textpos to delay it.
-% Thanks to Marius Arenz for useful comments here.}
-%
-% In general, however, \emph{anything} doing things at |\shipout| time
-% (which includes Textpos in absolute mode)
-% is going to be in a slightly precarious position
-% with respect to anything else which plays games here.
-%
-% There's also an unfortunate interaction with the \texttt{color}
-% package\marginpar{textpos \& color}. Textpos in absolute mode, and
-% the \texttt{pdftex} graphics driver, both squabble over who gets to
-% redefine the |\shipout| command: using the |\pagecolor| command with
-% \texttt{pdflatex} causes textpos absolute mode to behave
+%
+% There's a similar unfortunate interaction with the \texttt{color}
+% package\marginpar{textpos \& color}. That package's |\pagecolor|
+% command, when used with
+% \texttt{pdflatex}, causes textpos absolute mode to behave
% strangely\footnote{See the \texttt{comp.text.tex} thread `Colour in
% a0 poster' starting 2007 April 3}. A fix may appear here in time, but
% for the present, there are three workarounds. The first is to place
% the |\pagecolor{...}| command before |\begin{document}|, which
% causes the redefinitions of |\shipout| to happen in a working
% order. If this is impossible for some reason, then (as with the
-% Prosper workaround above) you can use textpos not in absolute
+% Prosper workaround above) you can use textpos in relative
% mode: if the textblocks are the first printable material on the
% page, then they're anchored at a fixed position, and you should be
% able to use textblocks and |\pagecolor| with \texttt{pdflatex}
% much as normal. The final possibility is to use \texttt{latex},
% \texttt{dvips} and \texttt{ps2pdf} to produce PDF, since the
-% dvips driver happens not to have this problem (thanks to Joris Vankerschaver
-% for the initial report, and to Heiko Oberdiek for one of the workarounds).
+% dvips driver happens not to have this problem\footnote{Thanks to Joris Vankerschaver
+% for the initial report, and to Heiko Oberdiek for one of the
+% workarounds}.
+%
+% \subsection{Other interactions}
+% \label{s:interactions}
+%
+% The Beamer package's\marginpar{textpos \& beamer}
+% background frame overlays the textpos material, unless the
+% \Lopt{overlay} option is used to tell textpos to delay it.
+% Therefore, you should use the \Lopt{overlay,absolute}
+% options with Beamer.\footnote{Thanks to Marius Arenz for
+% the explanation here.}
%
% Gabriel Zachmann suggested having Textpos put a grid on the
% page\marginpar{page grid}, so
@@ -704,16 +757,38 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \section{History}
% \iffalse @RELEASENOTES@ \fi
% \begin{description}
-% \item[\textbf{1.8, 2016 June 5}]\relax
+% \item[\textbf{1.9.1, 2019 April 15}]\relax
+%
+% \begin{itemize}
+% \item Added the |\TPReferencePosition| command, to change the
+% default reference position away from |[0,0]|.
+% \item Added the \emph{experimental}
+% |\TPoptions{discardcontent=true}| option, to improve
+% compatibility with TikZ
+% (see issue 6 in the repository\footnote{\url{https://bitbucket.org/nxg/textpos/issues/6/}}).
+% Note: \emph{This option may change or disappear in future versions}, and the author would be
+% particular interested to get feedback regarding it.
+% \item Documentation: added discussion of the implementation difference
+% between relative and absolute mode, and when one is preferable to the other.
+% \item Documentation: note that the showboxes option is intended only as
+% a basic aid to layout.
+% \item (Version 1.9 was partially released, but it contained an
+% attribution error which could be most easily fixed by a minor version bump).
+% \end{itemize}
+%
+%
+% \item[1.8, 2016 June 5]\relax
% \begin{itemize}
-% \item Added the |{\TPoptions| command, to switch modes on and
+% \item Added the |\TPoptions| command, to switch modes on and
% off within the document. Various documentation tweaks.
-% \item The behaviour of |{\TPMargin| and
-% |{\TPMargin*| were somewhat underspecified in versions of
+% \item The behaviour of |\TPMargin| and
+% |\TPMargin*| were somewhat underspecified in versions of
% Textpos before v1.8, and in consequence inconsistently implemented.
% This has now been rationalised, but the change \emph{may} change
% documents which relied on the previous behaviour.
% Thanks to Richard Schreiber for the detailed bug report.
+% \item In this release, I switched to more conventional dotted-integer, n.m.r,
+% version numbers, from the LaTeX-style model with intermediate releases denoted by letters.
% \end{itemize}
%
% \item[1.7j, 2014 January 3]\relax
@@ -730,7 +805,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
%
% \item[1.7g, 2010 September 30]\relax
% Bugfix: change the way we handle the {color} package not being
-% loaded – replacement |{\color| command is now robust.
+% loaded – replacement |\color| command is now robust.
% Thanks to Joseph Wright for the bugreport.
% Also adjusted documentation of reference points.
%
@@ -758,22 +833,22 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% latter provided code which I've incorporated in this fix.
%
% \item[1.7b, 2007 March 21]\relax
-% Robert Whittaker reported a problem with |{\TPmargin|,
+% Robert Whittaker reported a problem with |\TPmargin|,
% which meant that lists and quotations (and other things which
-% manipulated |{\leftskip| and |{\rightskip|) were
-% not decreasing in size when you set |{\TPmargin| non-zero.
+% manipulated |\leftskip| and |\rightskip|) were
+% not decreasing in size when you set |\TPmargin| non-zero.
% Fixed.
%
% \item[1.7a, 2006 September 2]\relax
% Version 1.7 created an inadvertant dependency on the
-% |{{color}| package. Now, if you do not load that package,
-% |{\textblockrulecolour| will have no effect, rather than
+% |{color}| package. Now, if you do not load that package,
+% |\textblockrulecolour| will have no effect, rather than
% failing. Textpos will give you a warning in this case, reminding you
-% to load the |{{color}| package.
+% to load the |{color}| package.
%
% \item[\textbf{1.7, 2006 August 24}]\relax
-% Added the |{\textblockrulecolour| and
-% |{\TPshowboxes{true,false}| commands, to further control the
+% Added the |\textblockrulecolour| and
+% |\TPshowboxes{true,false}| commands, to further control the
% display of the rules around the text blocks.
%
% \item[1.6b, 2006 August 10]\relax
@@ -784,12 +859,12 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% when there is no previous environment to override.
%
% \item[\textbf{1.6, 2005 August 30}]\relax
-% Made |{{calc}|-style dimensions to the
-% |{{textblock*}| argument work again (so \emph{that's} what
-% regression tests are for...). Override the |{figure| and
-% |{table| environments within |{textblock|
+% Made |{calc}|-style dimensions to the
+% |{textblock*}| argument work again (so \emph{that's} what
+% regression tests are for...). Override the |figure| and
+% |table| environments within |textblock|
% environments, to avoid their surprising and undesirable interaction
-% with |{textblock|.
+% with |textblock|.
%
% \item[1.5b, 2005 June 13]\relax
% The 1.5 release broke the textblock environment's optional
@@ -798,16 +873,16 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
%
% \item[1.5a, 2005 March 26]\relax
% Documentation fixes: added a section on the
-% interaction between absolute mode and LaTeX's |{\newpage|
+% interaction between absolute mode and LaTeX's |\newpage|
% command.
%
% \item[\textbf{1.5, 2005 March 23}]\relax
-% Implement |{\TPMargin| command, which causes a margin
+% Implement |\TPMargin| command, which causes a margin
% to appear round the blocks of text within textblock
% environments. This makes it easy to use blocks of colour which
% are larger than the block of text by a decent margin, or to put a
% border round textblocks by setting a suitably-sized margin and using
-% the |{showboxes| package option.
+% the |showboxes| package option.
%
% \item[\textbf{1.4, 2003 September 7}]\relax
% Changes in the handling of vertical spacing; inconsistent in some
@@ -817,7 +892,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% remain available for some time in case these fixes break things.
%
% \item[1.3a, 2003 June 24]\relax
-% Added the |{\textblockcolour| command, to set
+% Added the |\textblockcolour| command, to set
% the background colour of text blocks
%
% \item[\textbf{1.3, 2003 June 24}]\relax
@@ -831,15 +906,15 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \item[1.2a, 2002 April 28]\relax
% Version 1.2 had an error, which caused a confusing error
% if you gave any fractional part in the arguments to the
-% |{{textblock}| environment. This was fixed in version 1.2a,
-% which adds a |{{textblock*}| environment (fully compatible
-% with |{calc|), and does not attempt to support calc-style
+% |{textblock}| environment. This was fixed in version 1.2a,
+% which adds a |{textblock*}| environment (fully compatible
+% with |calc|), and does not attempt to support calc-style
% expressions in the parameters to the unstarred
-% |{{textblock}| environment.
+% |{textblock}| environment.
%
% \item[\textbf{1.2, 2002 April 21}]\relax
-% Rolf Niepraschk |{niepraschk@ptb.de| provided code to
-% make textpos compatible with the |{calc| package
+% Rolf Niepraschk |niepraschk@ptb.de| provided code to
+% make textpos compatible with the |calc| package
%
% \item[Version 1.1]\relax
% Released in 1999
@@ -880,7 +955,10 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% provided problem reports about the interactions between Textpos and
% other packages, and provided suggestions for workarounds and fixes.
%
-% Thanks also for general bugreports and other suggestions to
+% The text includes footnoted thanks to various people who have made
+% (sometimes very detailed) suggestions for functionality.
+%
+% Thanks are additionally due, for general bugreports and other suggestions, to
% Jozef Bednarcik,
% Richard G Daniel,
% Wolfgang Fleischer,
@@ -994,6 +1072,13 @@ located at that point, rather than the top-left corner.
\DeclareOption{verbose}{\TP@chattertrue}
% \end{macrocode}
%
+% Define a switch to suppress holdbox processing (see |\TP@holdbox| below).
+% \begin{macrocode}
+\newif\ifTP@displayholdbox
+ \TP@displayholdboxtrue
+\DeclareOption{discardcontent}{\TP@displayholdboxfalse}
+% \end{macrocode}
+%
% That's it. Now process the options and get on with it.
% \begin{macrocode}
\ProcessOptions
@@ -1012,12 +1097,15 @@ located at that point, rather than the top-left corner.
%
% \subsection{Changing options within the text}
%
+% Define a |\TPoptions| macro which supports constructions like |\TPoptions{verbose=true}|.
% \begin{macrocode}
\define@key{tp}{absolute}{\csname TP@abspos#1\endcsname}
\define@key{tp}{overlay}{\csname TP@overlay#1\endcsname}
\define@key{tp}{verbose}{\csname TP@chatter#1\endcsname}
\define@key{tp}{showboxes}{\csname TPshowboxes#1\endcsname}
\define@key{tp}{showtext}{\csname TP@showtext#1\endcsname}
+\define@key{tp}{discardcontent}{\csname @tempswa#1\endcsname
+ \if@tempswa\TP@displayholdboxfalse\else\TP@displayholdboxtrue\fi}
\def\TPoptions{\setkeys{tp}}
% \end{macrocode}
%
@@ -1066,6 +1154,12 @@ located at that point, rather than the top-left corner.
% shipped out (these additions contributed by Olaf Maibaum).
% \changes{v1.1}{1999/02/22}{Introduce holdbox, and absolute/relative modes}
%
+% Define the holdbox only in the `absolute positioning' mode.
+% \begin{macrocode}
+\ifTP@abspos
+ \newbox\TP@holdbox % starts off void
+% \end{macrocode}
+%
% \TeX\ does not call the output routine if there is nothing on the
% page. To deal with this situation, add code to the end-document
% hook to add a zero-size hbox on the page if |\TP@holdbox| is
@@ -1075,10 +1169,8 @@ located at that point, rather than the top-left corner.
% this problem, but introduces others by interfering with vertical spacing.
% (thanks to Bjoern Pedersen for diagnosing this in an old version
% of textpos).
-% \begin{macrocode}
-\ifTP@abspos
- \newbox\TP@holdbox % starts off void
- \AtEndDocument{\ifvoid\TP@holdbox \else \hbox{}\fi}
+% \begin{macrocode}
+ \AtEndDocument{\ifTP@displayholdbox\ifvoid\TP@holdbox \else \hbox{}\fi\fi}
\fi
% \end{macrocode}
% All the dimensions (except the optional argument of the textblock
@@ -1301,6 +1393,12 @@ located at that point, rather than the top-left corner.
}
% \end{macrocode}
%
+% Default the reference position, and support the command to override it.
+% \begin{macrocode}
+\def\TP@referenceposition{0,0}
+\def\TPReferencePosition#1{\def\TP@referenceposition{#1}}
+% \end{macrocode}
+%
% \begin{macro}{\textblock}
% Now define the start of the textblock environment. Read the first
% argument, and save it for the moment as |\@tempdima|. If we are
@@ -1325,7 +1423,7 @@ located at that point, rather than the top-left corner.
\par % force us back into vertical mode
\fi
\fi
- \@ifnextchar[{\TP@textblock}{\TP@textblock[0,0]}%] bracematch
+ \@ifnextchar[{\TP@textblock}{\expandafter\TP@textblock\expandafter[\TP@referenceposition]}%] bracematch
}
% \end{macrocode}
% \end{macro}
@@ -1346,7 +1444,7 @@ located at that point, rather than the top-left corner.
Alignment may work out wrongly.}%
\par % force us back into vertical mode
\fi
- \@ifnextchar[{\TP@textblock}{\TP@textblock[0,0]}%] bracematch
+ \@ifnextchar[{\TP@textblock}{\expandafter\TP@textblock\expandafter[\TP@referenceposition]}%] bracematch
}
\expandafter\let\csname textblock*\endcsname\TP@textblockstar
% \end{macrocode}
@@ -1625,6 +1723,9 @@ located at that point, rather than the top-left corner.
\vss
}% end of box0
% \end{macrocode}
+%
+% \subsection{Sending the boxes to the output}
+%
% Now switch behaviour depending on whether or not we're in the
% absolute-position mode. If we are, then add the newly-constructed
% box 0 to (the end of) the holdbox. The order matters in some
@@ -1670,23 +1771,24 @@ located at that point, rather than the top-left corner.
% or~253), but if it is an hbox, because some package has misbehaved,
% then we ought to try not to simply collapse. Work round this by
% testing explicitly whether box~255 is a vbox or not.
+% If |\ifTP@displayholdbox| is false, then both of these should be no-ops.
% \changes{v1.2b}{2002/07/01}{Defend against box 255 not being a vbox}
% \begin{macrocode}
\ifTP@abspos
\ifTP@overlay
- \EveryShipout{%
+ \EveryShipout{\ifTP@displayholdbox
\global\setbox\@cclv\vbox{%
\vbox to 0pt{\ifvbox\@cclv \unvbox\@cclv \else \box\@cclv \fi \vss}%
\unvbox\TP@holdbox % TP@holdbox is now void
- }
- }%
+ }%
+ \fi}%
\else
- \EveryShipout{%
+ \EveryShipout{\ifTP@displayholdbox
\global\setbox\@cclv\vbox{%
\unvbox\TP@holdbox
\ifvbox\@cclv \unvbox\@cclv \else \box\@cclv \fi
}%
- }%
+ \fi}%
\fi
\textblockorigin{0pt}{0pt}%
\fi