Debian Codegraph @

texmf-dist/source/latex/textpos/textpos.dtx

raw
1 % \iffalse
2 % This is textpos.dtx, which allows you to place text (and graphics)
3 % anywhere on the LaTeX page. It's useful for posters.
4 %
5 %%%% File: textpos.dtx
6 %%%% Copyright 1999-2020, Norman Gray
7 %%
8 %% This work may be distributed and/or modified under the
9 %% conditions of the LaTeX Project Public License, either version 1.3
10 %% of this license or (at your option) any later version.
11 %% The latest version of this license is in
12 %% https://www.latex-project.org/lppl.txt
13 %% and version 1.3 or later is part of all distributions of LaTeX
14 %% version 2005/12/01 or later.
15 %%
16 %% This work has the LPPL maintenance status `maintained'.
17 %%
18 %% The Current Maintainer of this work is Norman Gray <https://nxg.me.uk>
19 %%
20 %% This work consists of the files textpos.dtx and textpos.ins,
21 %% and the derived file textpos.sty.
22 %%
23 %% Author: Norman Gray, [email protected]
24 %% Department of Physics and Astronomy, University of Glasgow, UK
25 %%
26 %% See the file LICENCE for a copy of the LPPL.
27 %%
28 %% Mercurial ident: 1.10.1 (@VCSINFO)
29 %%
30 %<+package>\NeedsTeXFormat{LaTeX2e}
31 %<+package>\ProvidesPackage{textpos}[2022/07/23 v1.10.1]
32 %
33 %<*driver>
34 \documentclass{ltxdoc}
35 \title{Textpos: absolute positioning of text on the page}
36 \author{Norman Gray\\(\texttt{https://nxg.me.uk})}
37 \date{Version 1.10.1, 2022 July 23\footnote{This software is copyright, 1999-2020 Norman Gray.
38 It is released under the terms of the LaTeX Project Public License,
39 either version 1.3 of this licence or (at your option) any later version.
40 The latest version of this license is at \texttt{https://www.latex-project.org/lppl.txt}.}}
41 \newcommand\Lopt[1]{\textsf {\small [#1]}}
42 \newcommand\file[1]{\texttt {#1}}
43 \newcommand\Lcount[1]{\textsl{\small#1}}
44 \newcommand\Lenv[1]{\texttt{\{#1\}}}
45 \newcommand\pstyle[1]{\textsf{#1}}
46 \makeatletter % make the ttfamily font less overbearingly large
47 \renewcommand\ttfamily{\not@math@alphabet\ttfamily\mathtt
48 \fontfamily\ttdefault
49 \fontsize{9}{\f@baselineskip}\selectfont}
50 \makeatother
51 \def\LaTeXiie{\LaTeX$2\epsilon$}
52 % Make command strings easier to write
53 \def\activemeta#1>{\meta{#1}}
54 {\catcode`\<=\active
55 \gdef\cmd{\begingroup
56 \catcode`\\=12 \catcode`\{=12 \catcode`\}=12
57 \catcode`\<=\active \let<\activemeta
58 \catcode`\|=12
59 \docmd}}
60 \def\docmd|#1|{\texttt{#1}\endgroup}
61 %% \url macro (url.sty does this better)
62 \def\setpathdots{\discretionary{.}{}{.}}
63 \def\setpathslash{\discretionary{/}{}{/}}
64 {\catcode`\.=\active
65 \catcode`\/=\active
66 \gdef\pathcats{%
67 \catcode`\%=12 \catcode`\~=12
68 \catcode`\.=\active \let.\setpathdots
69 \catcode`\/=\active \let/\setpathslash
70 \catcode`\#=12 \catcode`\_=12}%
71 }
72 \def\setpath#1{\ttfamily\small <\nobreak #1\nobreak>\endgroup}
73 \def\url{\begingroup\pathcats\setpath}
74 %\RecordChanges
75 %\OnlyDescription
76 \begin{document}
77 \maketitle
78 \tableofcontents
79 %% \bigskip
80 %% \hrule
81 %% \bigskip
82 \newpage
83 \DocInput{textpos.dtx}
84 \end{document}
85 %</driver>
86 %
87 % \fi
88 %
89 %
90 %
91 %
92 % \changes{v1.0a}{1998/04/29}{Robin Fairbairns pointed out and adjusted errors in the documentation}
93 % \changes{v1.0b}{1998/04/30}{Reorganised documentation -- properly this time}
94 % \changes{v1.1b}{1999/03/05}{Added note to the effect that everyshi can be found at CTAN}
95 % \changes{v1.1c}{1999/03/09}{Corrected checksum (again!)}
96 % \changes{v1.1d}{1999/06/06}{Clarified copyright and licence status}
97 % \changes{v1.3?}{2003/06/??}{Finally removed bloody useless checksum and character table}
98 %
99 %
100 % \noindent
101 % This package facilitates placing boxes at absolute positions on the
102 % \LaTeX\ page. There are several reasons why this might be useful, but
103 % the reason which originally motivated this package is to help produce a
104 % large-format conference poster. However the facility is also useful
105 % for filling in forms or other special purpose layout.
106 %
107 % This package provides a single environment, which contains the text
108 % (or graphics, or table, or whatever) which is to be placed on the
109 % page, and which specifies where it is to be placed.
110 %
111 % The package tries not to get in the way. That is, you should be
112 % able to use most of the apparatus of \LaTeX\ in your poster, such as
113 % section headings, citations, graphics inclusion, and so on. Please
114 % let me know if you experience problems in this respect.
115 %
116 % \emph{If it is running in \LaTeXiie} (as opposed to the newer \LaTeX3),
117 % this package requires the services of Martin Schr\"oder's package \pstyle{everyshi}.
118 % If this is not already part of your \TeX{}
119 % installation, you will need to download this package from CTAN. See
120 % \url{https://www.ctan.org/pkg/everyshi}.
121 %
122 % The canonical CTAN URL for Textpos is \url{https://ctan.org/pkg/textpos}.
123 % Textpos has a home page at \url{https://purl.org/nxg/dist/textpos}.
124 % The source is held at \url{https://heptapod.host/nxg/textpos}.
125 % \iffalse and there is an issues list there, for bug reports.\fi
126 % Code
127 % contributions or fixes are welcome, but note that I feel that
128 % Textpos is pretty mature now, and I'm reluctant to extend its
129 % functionality beyond its natural boundaries, so it would be wise to
130 % chat to me about any new features before spending a lot of time
131 % drafting them in code.
132 %
133 % An article describing Textpos appeared in TUGboat in 2002:
134 % Norman Gray, `Absolute Positioning with
135 % Textpos', TUGboat \textbf{23} (3/4), pp341--4, 2002, available at
136 % \url{https://www.tug.org/TUGboat/tb23-3-4/tb75gray.pdf}.
137 %
138 % \section{Description}
139 %
140 % Load the package as usual, with
141 % \begin{quote}
142 % \cmd|\usepackage<package-options>{textpos}|
143 % \end{quote}
144 % The \meta{package-options} are as described in section~\ref{packopts}.
145 %
146 % The environment is used as follows
147 % \DescribeEnv{textblock}
148 % \begin{quote}\begin{raggedright}
149 % \cmd|\begin{textblock}{<hsize>}(<hpos>,<vpos>)|\\
150 % text...\\
151 % |\end{textblock}|
152 % \end{raggedright}
153 % \end{quote}
154 % The \meta{hsize} and \meta{hpos} arguments are given in units of a
155 % module |\TPHorizModule|, and \meta{vpos} is given in units of a
156 % module |\TPVertModule|. You set these using
157 % the command
158 % \cmd|\setlength{\TPHorizModule}{<dimen>}|,
159 % and similarly for |\TPVertModule|.
160 % The arguments may be any dimension, and you may use the modules as
161 % units elsewhere in your document if you wish to, for example in
162 % \texttt{\bslash makebox[2\bslash TPHorizModule]\{gnus\}}. The text in the
163 % environment will be set in a
164 % box \meta{hsize} modules wide, and placed on the page with its
165 % upper left corner at the position (\textit{hpos,vpos}). As is
166 % natural in \TeX, the \meta{vpos} parameter indicates distance
167 % \emph{down} from the `anchor point' (see below).
168 %
169 % The \Lenv{textblock} parameters \meta{hsize},
170 % \meta{hpos} and \meta{vpos} are \emph{multiples or fractions of the horizontal
171 % and vertical modules}, as appropriate. If you want or need to give
172 % explicit sizes here, see the \Lenv{textblock*} environment below.
173 %
174 % Notice that the positioning arguments for the \Lenv{textblock}
175 % command -- the coordinates \cmd|...(<hpos>,<vpos>)| -- are in
176 % \emph{round} brackets,\marginpar{Round brackets!}
177 % not curly ones. This is in imitation of the \texttt{picture}
178 % environment, and whether or not this is sensible, it's not going to
179 % change now.
180 %
181 % This package works in two modes, relative and absolute.
182 % \marginpar{relative \& absolute mode}
183 % In the first one, the default, the block-positioning parameters in the
184 % \Lenv{textblock} envirionment are taken to be relative to an `anchor
185 % point' which is the current position on the page, that is, the place
186 % where (the bottom left of) a character would appear if it were typed
187 % at this point. This will be appropriate if you are
188 % laying out text within a \texttt{figure} environment or the like.
189 % In this mode, you will typically give several \Lenv{textblock}
190 % environments one after the other, so that they are all relative to
191 % the same point.
192 %
193 % If, however, your entire
194 % document is to be laid out piece by piece (which is the case in the
195 % canonical use of the package, to lay out a poster), then you might
196 % want to be more sure of where the origin is. In this case, you make
197 % the package work in its absolute mode, by invoking it with
198 % the \Lopt{absolute} option: |\usepackage[absolute]{textpos}|.
199 % In this mode, all the block-positioning parameters are given
200 % relative to a single origin on the page. By default, this `anchor point' is the
201 % top-left corner of the page, but you may change it with the
202 % command \cmd|\textblockorigin{<hpos>}{<vpos>}|.
203 % Here \meta{hpos} and \meta{vpos} are dimensions such as `10mm',
204 % relative to the top-left corner of the paper. You may use this
205 % command only if the package was invoked with the \Lopt{absolute}
206 % option.
207 %
208 % See also section~\ref{packopts} for how to alternate
209 % between modes, see section~\ref{absolute-newpage} for notes on the
210 % interaction with the |\newpage| command, and see
211 % section~\ref{s:absrelmode} for some subtleties about choosing which
212 % mode to use.
213 %
214 % The textblocks are placed on the page\marginpar{layers} in the order in which they
215 % appear in the file. This means that later textblocks will be placed
216 % on top of earlier ones, which may matter if one or other contains,
217 % for example, a block of opaque colour (I believe this to be true in
218 % practice for all output mechanisms, though I doubt it's guaranteed
219 % in principle). This order was unspecified before textpos 1.7e; it
220 % was changed, and specified, in that version.
221 %
222 % The \Lenv{textblock} environment will most often be used in
223 % vertical mode. It can also be called in horizontal (ie, paragraph)
224 % mode. In each case, it should be invisible, in the sense of having
225 % no effect on the spacing of the paragraph text.\footnote{Note:
226 % \emph{this is a change} in version
227 % 1.10. Before then the behaviour of the package in horizontal
228 % mode was deliberately somewhat underspecified (with an intended
229 % implication of `don't do this'), and the package, for want of anything
230 % more imaginative to do, simply threw in a paragraph break. As a
231 % result of user feedback, from version 1.10 it seemed reasonable to try
232 % a little harder to be invisible in the horizontal case.}
233 % If called in horizontal mode (in \TeX\ terms), the relative-mode
234 % `anchor point' is just below the box containing the current line (it
235 % uses |\vadjust|, if that helps).
236 % If you try to use the environment when in maths mode, the package
237 % objects.
238 %
239 % \subsection{Package options}
240 % \label{packopts}
241 %
242 % There are several package options:
243 % \begin{description}
244 % \item[\Lopt{showboxes}]When you are laying things out, it can be
245 % useful to have the boxes drawn in for you. This option draws a box
246 % fitting closely round the contents of each \Lenv{textblock} environment.
247 % Note that this option is
248 % intended to help locate boxes on the page when composing a document,
249 % and the boxes are not intended to be decorative. However the
250 % \Lenv{textblock} environment is compatible with (for example) the
251 % \pstyle{tcolorbox} package, in the sense that you can
252 % include a \Lenv{tcolorbox} environment within a \Lenv{textblock}
253 % environment, with the expected effect\footnote{See also \url{https://tex.stackexchange.com/questions/34088/}.}.
254 % \item[\Lopt{noshowtext}]This suppresses the display of the text in
255 % each block (so it's not really usable without the \Lopt{showboxes}
256 % option). The resulting box will be the correct size, but empty,
257 % unless the |\textblocklabel| command has been given. This
258 % can be useful when you are previewing a document.
259 % \item[\Lopt{absolute}]If this is present, then the positions on the
260 % \Lenv{textblock} environment are taken to be absolute positions on
261 % the page. There is also a \Lopt{relative} option, which is the default.
262 % See above for more detail.
263 % \item[\Lopt{overlay}]When using the absolute-position mode, the
264 % textblocks are placed under any other text on the page. This is
265 % normally what you want, but if you have page contents, and they have
266 % something
267 % which \emph{obscures} the textblocks (for example, a block of opaque
268 % colour), then the positioned textboxes disappear. In this case,
269 % specify the option \Lopt{overlay}, to request that the positioned
270 % blocks of text overlay any other page contents, rather
271 % than being overlaid.
272 % \item[\Lopt{verbose}, \Lopt{quiet}]The package writes a few messages
273 % to the output, describing its calculations. These are potentially
274 % irritating, so you can turn them off with the \Lopt{quiet} option or
275 % on with the \Lopt{verbose} option. The default is currently
276 % \Lopt{verbose}, but this might change in future.
277 % \item[\Lopt{discardcontent}] This discards box content in a way
278 % which might make the |{textblock}| content compatible with TikZ.
279 % This behaviour is still somewhat experimental (since v1.9), should
280 % probably be used only rarely, and is more fully discussed in Sect.~\ref{s:absrelmode}.
281 % \end{description}
282 %
283 % \subsection{Changing options on the fly}
284 % \label{s:changing-options}
285 %
286 % \begin{macro}{\TPoptions}
287 % Each of the options mentioned in the previous section can be changed
288 % within the body of the text\footnote{Available since v1.8},
289 % using the command |\TPoptions| with a comma-separated list of
290 % keywords
291 % \textit{$\langle$keyword$\rangle$}\texttt{=true} or
292 % \textit{$\langle$keyword$\rangle$}\texttt{=false}.
293 % The recognised keywords are `absolute', `verbose',
294 % `showboxes', `showtext', and `discardcontent'. Thus the command
295 % \begin{quote}
296 % |\TPoptions{absolute=false , showboxes = true }|
297 % \end{quote}
298 % will switch off \Lopt{absolute} mode, and switch on \Lopt{showboxes}
299 % mode. As this example illustrates, you can include whitespace in
300 % the specification; the arguments \emph{must} be either \texttt{true}
301 % or \texttt{false}, or else bad things will happen.
302 %
303 % You can switch between absolute and relative mode within a page. If
304 % a document is to use absolute mode \emph{anywhere} within it,
305 % however, it must be \emph{started} in absolute mode, with the
306 % \Lopt{absolute} option to the |\usepackage| command.
307 %
308 % Note that (at least in v1.10), the presence or absence of the \texttt{overlay}
309 % package option takes effect at the time the package is loaded, and
310 % it cannot be changed thereafter. It's not impossible that this would
311 % change in future, but I have no current plans to implement that.
312 %
313 % \end{macro}
314 %
315 % \subsection{Configuration commands, and variants}
316 %
317 % \subsubsection{Setting up a positioning grid}
318 %
319 % \DescribeMacro{\TPGrid}
320 % The dimensions |\TPHorizModule| and |\TPVertModule| implicitly
321 % create a positioning grid on the page. Rather than
322 % calculate and specify the two modules explicitly, you can set up the
323 % grid with a command
324 % \cmd|\TPGrid{<nhoriz>}{<nvert>}|, which sets
325 % |\TPHorizModule| to be \meta{paper
326 % width}/\meta{nhoriz}, and |\TPVertModule| to be
327 % \meta{paper height}/\meta{nvert}. This takes an optional pair of
328 % dimension arguments, which specify a coordinate, as follows.
329 % \begin{quote}\begin{raggedright}
330 % \cmd|\TPGrid[<x>,<y>]{<nhoriz>}{<nvert>}|
331 % \end{raggedright}\end{quote}
332 % If these are present, then the modules are set
333 % up to leave a border of the given size around the grid. That is,
334 % |\TPHorizModule| is set to be (\meta{paper
335 % width}${}-{}2$\meta{x})/\meta{nhoriz}, and similarly for
336 % |\TPVertModule|. Further, if the package was given
337 % the \Lopt{absolute} option, then the text origin is set to be
338 % (\meta{x},\meta{y}) through a call to |\textblockorigin|
339 % (see below). For example, the declaration
340 % \begin{quote}\begin{raggedright}
341 % \cmd|\TPGrid[40mm,20mm]{10}{5}|
342 % \end{raggedright}\end{quote}
343 % would choose \cmd|\TPHorizModule| and \cmd|\TPVertModule| so as to
344 % give a grid of 10~intervals across and 5~intervals down, after
345 % leaving 40mm of a border on the right and left sides, and a 20mm
346 % border top and bottom.
347 %
348 % \DescribeMacro{\TPShowGrid}
349 % Note that this sets up a notional layout grid for the page or, put
350 % another way, it sets the module units with respect to which the
351 % |(<hpos>,<vpos>)| coordinates are interpreted, but it
352 % does not actually draw a grid on the page. To display the grid, use
353 % the |\TPShowGrid{<nhoriz>}{<nvert>}| macro. This has a starred
354 % variant, which additionally shows the coordinates at each grid
355 % point. You should do this near the beginning of your file.
356 % For an alternative approach, see Sect.~\ref{s:interactions}.
357 %
358 % \subsubsection{Box margin}
359 %
360 % \DescribeMacro{\TPMargin}
361 % By default, the box that is positioned by the
362 % \Lenv{textblock} environment is a tight fit to the block of text
363 % (or other material) inside it. This looks rather odd when you also
364 % use the |\textblockcolour| macro described below, or specify a larger
365 % than default |\TPboxrulesize|, in order to get a noticeable border
366 % round a piece of text. In those cases, you will want to request a
367 % non-zero margin around your text. If you give the command
368 % \begin{quote}
369 % |\TPMargin{|\meta{size}|}|
370 % \end{quote}
371 % then the block of text inside the textblock will be decreased in
372 % width, enough to give the specified margin on each side. That is,
373 % the \meta{hsize} of the textblock, and thus the coloured block (or
374 % the edge of the displayed border), remains the same, but the text
375 % width inside it decreases. The parameter \meta{size} may be any
376 % non-negative dimension, and may as usual be in units of
377 % |\TPHorizModule| or |\TPVertModule|. The default behaviour is
378 % recovered by giving a \meta{size} of \texttt{0pt}.
379 %
380 % \DescribeMacro{\TPMargin*}
381 % There is a starred variant of this command,
382 % |\TPMargin*{|\meta{size}|}|, where the argument must again be
383 % non-negative. In this case, the text block inside the box is set
384 % with the \meta{hsize} specified in the \Lenv{textblock}
385 % environment, but the coloured block is increased in size, such that
386 % there is again a margin of the specified size around the text block.
387 %
388 % \subsubsection{Choosing the textblock reference point}
389 %
390 % You may give an optional argument to the \Lenv{textblock}
391 % environment, specifying which point in the box
392 % is to be placed at the specified point:
393 % \begin{quote}
394 % \begin{raggedright}
395 % \cmd|\begin{textblock}{<hsize>}[<ho>,<vo>](<hpos>,<vpos>)|\\
396 % text...\\
397 % |\end{textblock}|
398 % \end{raggedright}
399 % \end{quote}
400 % The coordinates \meta{ho} and \meta{vo} are fractions of the
401 % width and height of the text box, respectively, and state that the
402 % box is to be placed so that the reference
403 % point (\meta{ho},\meta{vo}) within the box is to be placed at the point
404 % (\meta{hpos},\meta{vpos}) on the page. The default specification is
405 % [0,0], indicating the top left of the box; the argument [0,1] (for
406 % example) would specify the bottom left, and [0.5,0.5] the middle.
407 %
408 % If the margin is non zero, then the position identified by
409 % [\meta{ho},\meta{vo}] is slightly subtle:
410 % \begin{itemize}
411 % \item if the margin was specified with |\TPMargin|, then these
412 % coordinates are relative to the box \emph{including} the margin;
413 % \item if the margin was specified with |\TPMargin*|, then the
414 % coordinates are relative to the contents of the \Lenv{textblock},
415 % \emph{excluding} the margin.
416 % \end{itemize}
417 % For example, in the default case where the positioning argument is
418 % [0,0], |\TPMargin| will cause the top-left of the surrounding box to
419 % be at position (\meta{hpos},\meta{vpos}) (and the text to be
420 % narrower), but |\TPMargin*| will cause the top left of the enclosed
421 % text to be at (\meta{hpos},\meta{vpos}) (and the enclosing box to be
422 % wider).
423 %
424 % Note: This behaviour was somewhat underspecified in versions of
425 % textpos before v1.8, and in consequence inconsistently implemented.
426 % The rationalisation in this version \emph{may} change documents which relied on
427 % the previous behaviour.
428 %
429 % \begin{macro}{\TPReferencePosition}
430 % As noted, the default reference position is |[0,0]|. This can be overridden
431 % using the |\TPReferencePosition| command, which takes as argument
432 % the reference position argument to be used for subsequent boxes.
433 % Thus |\TPReferencePosition{0.5,0.5}| (note no square brackets) would
434 % cause subsequent boxes to be centred on their
435 % location\footnote{Thanks to an anonymous textpos user for the suggestion
436 % here, which was added in v1.9
437 % -- I was surprised that this functionality hadn't been present for years.}.
438 % \end{macro}
439 %
440 % \subsubsection{Specifying textblocks with absolute sizes}
441 % \label{s:textblock-absolute}
442 %
443 % \DescribeEnv{textblock*}
444 % There is an alternative, starred, form of the \Lenv{textblock}
445 % environment. In the argument to the \Lenv{textblock*} environment, the
446 % block width, and the block position (but \emph{not} the
447 % specification of the block reference point) are given as absolute
448 % dimensions, rather than as numbers in units of the horizontal and
449 % vertical modules. Thus
450 % \begin{quote}
451 % \begin{raggedright}
452 % \cmd|\begin{textblock*}{<hsize>}[<ho>,<vo>](<hpos>,<vpos>)|\\
453 % text...\\
454 % \cmd|\end{textblock*}|
455 % \end{raggedright}
456 % \end{quote}
457 % produces a textblock of the given size, where this time \meta{hsize},
458 % \meta{hpos} and \meta{vpos} are absolute dimensions, but \meta{ho}
459 % and \meta{vo} are still pure-number offsets (that is, fractions of the
460 % width and height of the textblock), as above.
461 %
462 % Each \Lenv{textblock} environment takes up zero space on the page (which
463 % means, by the way, that it cannot detect that it's overprinting or
464 % being overprinted), so you can (and typically will) use several of
465 % the environments in a row to scatter text all over the page.
466 %
467 % The package is compatible with the \pstyle{calc} package, so that
468 % you may use calc-style expressions when specifying lengths. Thus
469 % \begin{quote}
470 % \begin{raggedright}
471 % |\usepackage{calc}|\\
472 % |\textblockorigin{56.9055pt-10mm}{0pt+1cm}|\\
473 % |\begin{textblock*}{10mm+14cm}(0.3cm*5,10\TPVertModule+5mm)|\\
474 % text\dots\\
475 % |\end{textblock*}|\\
476 % \end{raggedright}
477 % \end{quote}
478 % Note that you can only use calc-style expressions where you would
479 % specify a length with units, such as the width and location
480 % arguments of \Lenv{textblock*} or the arguments to |\textblockorigin|
481 % -- you can't use them when specifying a
482 % length in units of the horizontal and vertical modules, such as in
483 % the width and location arguments to the (unstarred) \Lenv{textblock}
484 % environment.
485 %
486 % With the unstarred \Lenv{textblock} environment, however, you will generally be able to
487 % use the |\fpeval| command of the `xfp' package.\footnote{https://ctan.org/pkg/xfp}
488 %
489 % \subsection{Package parameters}
490 % \begin{raggedright}
491 % \begin{description}
492 % \item[\texttt{\bslash TPHorizModule}]
493 % \DescribeMacro{\TPHorizModule}
494 % The length unit which is used for the horizontal positioning and
495 % size parameters of the \Lenv{textblock} environment. Set it using
496 % the command \cmd|\setlength{\TPHorizModule}{<dimen>}| (or indeed
497 % |\addtolength|).
498 % The default is one sixteenth of the paper width
499 % (ie, as if set up with |\TPGrid{16}{16}|).
500 % \item[\texttt{\bslash TPVertModule}]
501 % \DescribeMacro{\TPVertModule}
502 % The length unit which is used for the vertical positioning and
503 % size parameters of the \Lenv{textblock} environment. Set it using
504 % the command \cmd|\setlength{\TPVertModule}{<dimen>}| (or |\addtolength|).
505 % The default is one sixteenth of the paper height.
506 % \item[\texttt{\bslash TPshowboxestrue} and \texttt{\bslash TPshowboxesfalse}]
507 % You can control whether text blocks have the rule around them by
508 % using the |\TPshowboxestrue| and |\TPshowboxesfalse| commands. The
509 % \Lopt{showboxes} option simply sets the initial value of this switch.
510 % \item[\texttt{\bslash TPboxrulesize}]
511 % \DescribeMacro{\TPboxrulesize}
512 % When you use the \Lopt{showboxes} option,
513 % the lines drawn are of this width. If this too small to show up
514 % when you are previewing your document, or if you simply like bold
515 % frames and wish to make them a feature of your poster's design, you
516 % may adjust the size using |\setlength| or |\addtolength|. The
517 % default is 0.4pt. See also the |\textblockrulecolour| command.
518 % Note that the \Lopt{showboxes} option is mostly conceived of as an
519 % aid to layout, and so the options for customising these rules are
520 % rather limited. If you wish more extensively customised boxes, then
521 % you would probably be best using a package which provides specific
522 % support for that, going beyond what could be usefully added to
523 % textpos.\footnote{A StackOverflow discussion at
524 % \url{https://tex.stackexchange.com/questions/34088/} suggests
525 % packages TikZ, mdframed or tcolorbox.}
526 % \item[\texttt{\bslash textblocklabel}]
527 % \DescribeMacro{\textblocklabel}
528 % This may be used within any \Lenv{textblock}
529 % environment. It is ignored, unless the \Lopt{noshowtext} option has
530 % been specified, when it will be used to label the textblock it is
531 % inside. Use: |\textblocklabel{Identifying text}|.
532 % \item[\texttt{\bslash showtextsize}]
533 % \DescribeMacro{\showtextsize}
534 % When |\textblocklabel| is being
535 % shown, the text appears in size |\showtextsize|, which is
536 % defined by default to be |\normalsize|. If this is too
537 % small, you may adjust it using |\newcommand{\showtextsize}{\large}|, or
538 % whatever size you prefer.
539 % \item[\texttt{\bslash textblockorigin}]
540 % \DescribeMacro{\textblockorigin}
541 % Sets the position of the top-left of the
542 % printable area. See above.
543 % \end{description}
544 % \end{raggedright}
545 %
546 % \DescribeMacro{\textblockcolour}
547 % The text blocks can be coloured in. If you load the \pstyle{color}
548 % package, then the commands of that package, |\textcolor|,
549 % |\pagecolor| and the like, should work as usual. The
550 % \pstyle{textpos} package adds a new command,
551 % |\textblockcolour|. If you give the command
552 % \begin{quote}
553 % |\textblockcolour{|\meta{colour}|}|
554 % \end{quote}
555 % all text blocks following will have their background filled with the
556 % specified colour, which must be one of the standard colours or have
557 % been declared in a
558 % |\definecolor| declaration in the document preamble. This colour
559 % may be overridden for individual text blocks by giving this command
560 % within the \Lenv{textblock} environment. If you wish a block not to
561 % have any background colour, you can suppress it, again for one block
562 % at a time, with the command |\textblockcolour{}| inside the
563 % \Lenv{textblock} environment.
564 %
565 % \DescribeMacro{\textblockrulecolour}
566 % You can similarly change the colour of the borders around the text
567 % block. If you give the command
568 % \begin{quote}
569 % |\textblockrulecolour{|\meta{colour}|}|
570 % \end{quote}
571 % then following text blocks will have their border in the given
572 % colour, which must again be either one of the standard ones of
573 % declared in the document preamble.
574 %
575 % \DescribeMacro{\textblockcolor}
576 % For the benefit of those who observe Mr.\ Noah Webster's spelling
577 % reforms, |\textblockcolor| is defined as a synonym for
578 % |\textblockcolour|, but those who would condemn such anaemic half measures
579 % \DescribeMacro{\tekstblokkulur}
580 % can use |\tekstblokkulur| instead.
581 % \DescribeMacro{\textblockrulecolor}
582 % \DescribeMacro{\tekstblokroolkulur}
583 % There are also the corresponding spelling-reform variants of
584 % |\textblockrulecolour|.
585 %
586 % \subsection{Figure and table environments}
587 %
588 % \pstyle{Textpos} changes
589 % the behaviour of any \Lenv{figure} and \Lenv{table} environments
590 % \emph{within} instances of the \Lenv{textblock} environment, in such
591 % a way that the figure or table contents do not float away from the
592 % \Lenv{textblock} environment. For the same reason, |\marginpar| is
593 % forbidden within a textblock. It makes no change, however, outside
594 % the environment, where figures float as normal, and you are still
595 % able to use \pstyle{textblock} within figures, as described above.
596 % Within a \Lenv{textblock}, these environments do nothing
597 % beyond accepting the usual |\caption| command, which behaves
598 % correctly with respect to caption numbering and |\label| commands
599 % (it also respects |\@makecaption|, so you can tinker with that if
600 % you like that sort of thing). There's no real need to use either
601 % the \Lenv{figure} or \Lenv{table} environments within a textblock --
602 % you don't require them to allow |\includegraphics| or \Lenv{tabular}
603 % to work, for example -- but many people automatically use them to
604 % surround graphics or tables, and also expect to use these
605 % environments to number figures and tables within \Lenv{textblock}
606 % environments; they are therefore here on a principle of least
607 % surprise.
608 %
609 % The support here is admittedly simple, and it is known to fail in
610 % the case where there are \Lenv{figure} (or \Lenv{table})
611 % environments both inside and outside \Lenv{textblock}s on the same
612 % page (the LoF is ordered incorrectly in this case, due to the
613 % different times that the various environments write to the
614 % \texttt{.lof} file). I don't have immediate plans to fix this: the
615 % situation is surely sufficiently rare as not to justify the
616 % (potentially fragile) complication of the fix -- if you disagree,
617 % let me know.
618 %
619 % Since both \LaTeX's floats mechanism (that is, \Lenv{figure} and
620 % \Lenv{table}) and the \Lopt{absolute} mode are designed to move
621 % content around, we can't expect them to play together nicely. With
622 % \Lopt{absolute} mode on, the contents of a \Lenv{textblock} inside a
623 % floating \Lenv{figure} probably isn't going to end up where you
624 % expect it to. The only case I can think of where this would
625 % inconvenience you, is if you wanted some absolutely-positioned
626 % material to appear on the `next' page. You might at first try to use
627 % a |\begin{figure}[p]| -- that won't work, but the following will, if
628 % you first load the \pstyle{afterpage} package:
629 % \begin{verbatim}
630 % \afterpage{%
631 % \newpage%
632 % \begin{textblock*}{297mm}(0mm,0mm)%
633 % \includegraphics{picture.png}% a full-page picture?
634 % \end{textblock*}%
635 % \null%
636 % \newpage}
637 % \end{verbatim}
638 % This inserts a complete page, with some graphic on it, immediately
639 % after the end of the current page\footnote{Thanks to Matthias Gloede for
640 % this technique.}.
641 %
642 % \section{Notes}
643 % \subsection{Suggestions: Producing large-format posters}
644 %
645 % If you are producing a large-format poster, such as A0 size, you
646 % might want to use Gerlinde Kettl and Matthias Weiser's \cmd|a0poster|
647 % class, which painlessly deals with the miscellaneous hassles of
648 % printing to a large-format postscript printer.
649 %
650 % I have a collection of suggestions for producing such posters at
651 % \url{https://purl.org/nxg/note/posters}.
652 %
653 % The text on a large poster will typically use a very large font. It
654 % can be a hassle to create (or have dvips create) these fonts, and
655 % they take up a good deal of space on your disk. You might want to
656 % investigate the BlueSky/AMS fonts (available at CTAN), which are
657 % postscript versions of the Computer Modern fonts, and which can
658 % therefore be scaled arbitrarily.
659 %
660 % \subsection{Absolute mode and $\backslash$newpage}
661 % \label{absolute-newpage}
662 %
663 % You can sometimes get rather puzzling behaviour when you use
664 % |\newpage| in absolute mode.
665 %
666 % When using the \Lopt{absolute} option, you will often
667 % have all of the text on your page inside \Lenv{textblock}
668 % environments. In this case, \TeX\ does not believe that you have
669 % anything on the page at all, and so if you give a |\newpage| command
670 % to start a second sheet (perhaps you have a particularly generous
671 % poster space allocation at your conference, or you are filling out a
672 % form), \TeX\ thinks it is redundant, and ignores it, so that all
673 % your \Lenv{textblock} environments end up on just one page. To work
674 % round this, use |\null\newpage| instead: the |\null| (which produces
675 % a zero-width box) is enough to persuade
676 % \TeX\ to respect the page-break.
677 %
678 % This happens for the same reason that, also quite surprisingly, two
679 % |\newpage| commands in a row do not produce a blank page.
680 %
681 % \subsection{Absolute or relative mode?}
682 % \label{s:absrelmode}
683 %
684 % The \Lopt{absolute} mode appears to be the obvious mode to choose:
685 % the positions it specifies are independent of margins, spacing and
686 % other offsets, and so easier to think with. Because of the way
687 % \Lopt{absolute} mode is implemented, however, it has some
688 % interactions which may make \Lopt{relative} mode better in some
689 % cases.
690 %
691 % \Lopt{absolute} mode works by inserting a \TeX\ box into a page at
692 % almost the last moment before the page is finalised for output (at
693 % |\shipout| time, if you're a \TeX\ afficionado). This is normally
694 % robust, and in many ways it is an attractively simple solution, but
695 % it may interact badly with other packages which
696 % manipulate this `shipout' box, or packages which juggle or inspect
697 % boxes at or just before this late stage. In particular, the Prosper
698 % package manipulates the page just before this stage,
699 % the Color package inserts material using |\shipout|.
700 %
701 % Similarly the TikZ package\marginpar{textpos \& TikZ}
702 % (or at least its `externalize' support) examines the page at
703 % a time which means it fails to spot the absolute-mode textpos
704 % material. In the TikZ case, you can try using the
705 % option |\TPoptions{discardcontent=true}| which,
706 % in Textpos absolute mode, discards the contents of all
707 % |{textblock}| boxes, in a way which should make it compatible with
708 % TikZ. This option is \emph{experimental} in Textpos v1.9, and may
709 % change or disappear in future versions -- the author would be
710 % particular interested in feedback regarding this
711 % option.\footnote{My understanding of the problem here is derived from an excellent Stackoverflow answer
712 % by `JLDiaz' \url{https://tex.stackexchange.com/a/66853}, a Textpos
713 % bugreport by Michael H\"upkes, and a discussion on the PGF bugparade
714 % \url{https://github.com/pgf-tikz/pgf/issues/393}.}
715 %
716 % These are discussed in a little more detail below, but in each of
717 % these cases, using textpos in \Lopt{relative} mode will evade the
718 % problem. This solution will work in the cases where the
719 % \Lenv{textblock} environment is at a more-or-less predictable
720 % location on the page.
721 %
722 % Textpos and Prosper\marginpar{textpos \& prosper} squabble because
723 % Textpos in absolute mode places its text onto the page \emph{after}
724 % Prosper has rotated the page from portrait to landscape format, so
725 % that the \Lenv{textblock} contents end up at the correct position on
726 % the portrait page, but the wrong position on the landscape
727 % page\footnote{Thanks to Erik Van Eynde for the initial discussion of this.}.
728 % Since Prosper slides start at a consistent point, however, you can fairly happily use Textpos in
729 % relative mode as long as the \Lenv{textblock} environment is the
730 % first thing on the slide.
731 %
732 % There's a similar unfortunate interaction with the \texttt{color}
733 % package\marginpar{textpos \& color}. That package's |\pagecolor|
734 % command, when used with
735 % \texttt{pdflatex}, causes textpos absolute mode to behave
736 % strangely\footnote{See the \texttt{comp.text.tex} thread `Colour in
737 % a0 poster' starting 2007 April 3}. A fix may appear here in time, but
738 % for the present, there are three workarounds. The first is to place
739 % the |\pagecolor{...}| command before |\begin{document}|, which
740 % causes the redefinitions of |\shipout| to happen in a working
741 % order. If this is impossible for some reason, then (as with the
742 % Prosper workaround above) you can use textpos in relative
743 % mode: if the textblocks are the first printable material on the
744 % page, then they're anchored at a fixed position, and you should be
745 % able to use textblocks and |\pagecolor| with \texttt{pdflatex}
746 % much as normal. The final possibility is to use \texttt{latex},
747 % \texttt{dvips} and \texttt{ps2pdf} to produce PDF, since the
748 % dvips driver happens not to have this problem\footnote{Thanks to Joris Vankerschaver
749 % for the initial report, and to Heiko Oberdiek for one of the
750 % workarounds}.
751 %
752 % In older versions of the beamer package,\marginpar{textpos \&
753 % beamer} there were at least some cases where beamer's background
754 % frame would overlay textpos material. It appears this is no longer
755 % the case (at least with beamer 3.59), and the packages are fully
756 % compatible. But if you see a problem here you should use the
757 % \Lopt{overlay} option to tell textpos to delay its
758 % work.\footnote{Thanks to Marius Arenz for the explanation here, and
759 % to Matthias Braun for reporting that the problem has gone away.}
760 %
761 % \subsection{Other interactions}
762 % \label{s:interactions}
763 %
764 % Gabriel Zachmann suggested having Textpos put a grid on the
765 % page\marginpar{page grid}, so
766 % that it is easier to work out \Lenv{textblock} coordinates. I have
767 % (finally, in 1.10) followed this suggestion, in the |\TPShowGrid| macro, but
768 % another approach to doing this, which may have further useful
769 % flexibility, is to use Rolf Niepraschk's
770 % \texttt{eso-pic} package. There is a vivid example of using Textpos along with Rolf's
771 % \texttt{eso-pic} package and the \texttt{calc} package on the
772 % Textpos web pages, at
773 % \url{https://heptapod.host/nxg/textpos}, and an example of how to
774 % create a grid with TikZ at \url{https://tex.stackexchange.com/a/85088/96}.
775 %
776 % Finally, Robert Wenner reported a problem when using Textpos along
777 % with the \texttt{texdraw} package\marginpar{textpos \& texdraw}, with
778 % |\move(0,0)| apparently
779 % making a difference when it should be a no-op. I haven't worked out
780 % what's going on here, and further reports of this, ideally with a
781 % minimal example, would be most welcome.
782 %
783 % \subsection{Troubleshooting}
784 %
785 % \begin{description}
786 % \item[Switching to absolute mode with \texttt{$\backslash$TPoptions} doesn't work]
787 % In order for the \Lopt{absolute} mode to work anywhere, the document
788 % has to be \emph{started} in absolute mode (see Sect.~\ref{s:changing-options}).
789 % This is a hard-to-avoid limitation of the way that this mode is implemented.
790 %
791 % \item[Error: `Missing number, treated as zero']
792 % If you give absolute values (that is, values with units) to the
793 % \Lenv{textblock} environment, then you will be confronted with the
794 % rather opaque error `Missing number, treated as zero'. Remember
795 % that the \Lenv{textblock} environment requires relative sizes, and
796 % the \Lenv{textblock*} environment requires sizes with units; see
797 % Sect.~\ref{s:textblock-absolute}. You get a similar error message
798 % if you give relative sizes to the \Lenv{textblock*} environment.
799 %
800 % \end{description}
801 %
802 % \section{History}
803 % \iffalse @RELEASENOTES@ \fi
804 % \begin{description}
805 % \item[\textbf{Release 1.10.1, 2022 July 23}]\relax
806 %
807 % \begin{itemize}
808 % \item Mildly improve the handling of a missing |{color}| package.
809 % \item The |overlay| option isn't changeable in
810 % |\TPoptions|; attempting to do so now produces a
811 % warning.
812 % \item Various mild documentation improvements.
813 % \item The code repository has moved again, to
814 % heptapod\footnote{\url{https://heptapod.host/nxg/textpos}}.
815 % \end{itemize}
816 %
817 %
818 % \item[\textbf{1.10, 2020 September 26}]\relax
819 %
820 % \begin{itemize}
821 % \item Use the \emph{ltshipout} package to place boxes in absolute mode.
822 % Therefore the package should now be compatible with LaTeX3.
823 % Many thanks to Ulrike Fischer for guidance on the changes which were required here.
824 % \item The code has moved from bitbucket.org to
825 % code.nxg.name\footnote{\url{https://code.nxg.name/nxg/tex/textpos/}},
826 % since bitbucket have closed down support for Mercurial. The
827 % outstanding issues have been preserved, but have not (yet) been
828 % migrated to a new system, so may become inaccessible.
829 % \end{itemize}
830 %
831 %
832 % \item[1.10b1, 2020 January 26]\relax
833 %
834 % \begin{itemize}
835 % \item Add the |\TPShowGrid| macro.
836 % \item Become invisible in horizontal mode.
837 % \emph{Note: this is a change in behaviour:}
838 % Before this the behaviour of the package in horizontal
839 % mode was deliberately somewhat underspecified (with an intended
840 % implication of ‘don't do this’), and the package, for want of anything
841 % more imaginative to do, simply threw in a paragraph break, which
842 % produced ugly spacing in some circumstances. As a result of
843 % user
844 % feedback\footnote{\url{https://tex.stackexchange.com/questions/525453/}}, from version 1.10 it seemed reasonable to try a little
845 % harder to be invisible in the horizontal case
846 % (see issue 16\footnote{\url{https://bitbucket.org/nxg/textpos/issues/16/}}).
847 % \item Various documentation improvements.
848 % \end{itemize}
849 %
850 %
851 % \item[1.9.1, 2019 April 15]\relax
852 %
853 % \begin{itemize}
854 % \item Added the |\TPReferencePosition| command, to change the
855 % default reference position away from |[0,0]|.
856 % \item Added the \emph{experimental}
857 % |\TPoptions{discardcontent=true}| option, to improve
858 % compatibility with TikZ
859 % (see issue 6 in the repository\footnote{\url{https://bitbucket.org/nxg/textpos/issues/6/}}).
860 % Note: \emph{This option may change or disappear in future versions}, and the author would be
861 % particular interested to get feedback regarding it.
862 % \item Documentation: added discussion of the implementation difference
863 % between relative and absolute mode, and when one is preferable to the other.
864 % \item Documentation: note that the showboxes option is intended only as
865 % a basic aid to layout.
866 % \item (Version 1.9 was partially released, but it contained an
867 % attribution error which could be most easily fixed by a minor version bump).
868 % \end{itemize}
869 %
870 %
871 % \item[1.8, 2016 June 5]\relax
872 % \begin{itemize}
873 % \item Added the |\TPoptions| command, to switch modes on and
874 % off within the document. Various documentation tweaks.
875 % \item The behaviour of |\TPMargin| and
876 % |\TPMargin*| were somewhat underspecified in versions of
877 % Textpos before v1.8, and in consequence inconsistently implemented.
878 % This has now been rationalised, but the change \emph{may} change
879 % documents which relied on the previous behaviour.
880 % Thanks to Richard Schreiber for the detailed bug report.
881 % \item In this release, I switched to more conventional dotted-integer, n.m.r,
882 % version numbers, from the LaTeX-style model with intermediate releases denoted by letters.
883 % \end{itemize}
884 %
885 % \item[1.7j, 2014 January 3]\relax
886 % Re-released under the LPPL.
887 %
888 % \item[1.7i, 2012 November 10]\relax
889 % Bugfix: further change to the way the {color} package is loaded
890 % (fixes issue 2); now finally fixed?
891 %
892 % \item[1.7h, 2012 June 1]\relax
893 % Bugfix: further change to the way the {color} package is loaded.
894 % Some documentation tweaks.
895 % Pointers to bitbucket repository.
896 %
897 % \item[1.7g, 2010 September 30]\relax
898 % Bugfix: change the way we handle the {color} package not being
899 % loaded – replacement |\color| command is now robust.
900 % Thanks to Joseph Wright for the bugreport.
901 % Also adjusted documentation of reference points.
902 %
903 % \item[1.7f, 2009 May 28]\relax
904 % The change in behaviour introduced in v1.7e is now documented (it
905 % was unspecified before, and 1.7e didn't commit itself one way or the
906 % other).
907 %
908 % \item[1.7e, 2009 March 29]\relax
909 % Daniel Richard G noted that the order in which textblock contents
910 % was laid down on the page was counter-intuitive, since one would
911 % expect that later environments go 'on top of' earlier ones. This
912 % order was unspecified before this version, but I've changed this,
913 % satisfying a principle of least surprise (later ones now go 'on
914 % top').
915 %
916 % \item[1.7d, 2007 March 30]\relax
917 % Axel Sommerfeldt suggested a further alternative approach, even more
918 % lightweight, and I incorporated a version of that.
919 %
920 % \item[1.7c, 2007 March 29]\relax
921 % Giovanni Radilla reported a problem with captions, which meant that the
922 % captions weren't appearing properly in the list of figures. Dan
923 % Luecking and Axel Sommerfeldt analysed the problem precisely, and the
924 % latter provided code which I've incorporated in this fix.
925 %
926 % \item[1.7b, 2007 March 21]\relax
927 % Robert Whittaker reported a problem with |\TPmargin|,
928 % which meant that lists and quotations (and other things which
929 % manipulated |\leftskip| and |\rightskip|) were
930 % not decreasing in size when you set |\TPmargin| non-zero.
931 % Fixed.
932 %
933 % \item[1.7a, 2006 September 2]\relax
934 % Version 1.7 created an inadvertant dependency on the
935 % |{color}| package. Now, if you do not load that package,
936 % |\textblockrulecolour| will have no effect, rather than
937 % failing. Textpos will give you a warning in this case, reminding you
938 % to load the |{color}| package.
939 %
940 % \item[\textbf{1.7, 2006 August 24}]\relax
941 % Added the |\textblockrulecolour| and
942 % |\TPshowboxes{true,false}| commands, to further control the
943 % display of the rules around the text blocks.
944 %
945 % \item[1.6b, 2006 August 10]\relax
946 % Minor documentation fixes
947 %
948 % \item[1.6a, 2005 October 13]\relax
949 % The overriding of the figure and table environments now also works
950 % when there is no previous environment to override.
951 %
952 % \item[\textbf{1.6, 2005 August 30}]\relax
953 % Made |{calc}|-style dimensions to the
954 % |{textblock*}| argument work again (so \emph{that's} what
955 % regression tests are for...). Override the |figure| and
956 % |table| environments within |textblock|
957 % environments, to avoid their surprising and undesirable interaction
958 % with |textblock|.
959 %
960 % \item[1.5b, 2005 June 13]\relax
961 % The 1.5 release broke the textblock environment's optional
962 % argument, controlling the position of the reference point within the
963 % block. Fixed.
964 %
965 % \item[1.5a, 2005 March 26]\relax
966 % Documentation fixes: added a section on the
967 % interaction between absolute mode and LaTeX's |\newpage|
968 % command.
969 %
970 % \item[\textbf{1.5, 2005 March 23}]\relax
971 % Implement |\TPMargin| command, which causes a margin
972 % to appear round the blocks of text within textblock
973 % environments. This makes it easy to use blocks of colour which
974 % are larger than the block of text by a decent margin, or to put a
975 % border round textblocks by setting a suitably-sized margin and using
976 % the |showboxes| package option.
977 %
978 % \item[\textbf{1.4, 2003 September 7}]\relax
979 % Changes in the handling of vertical spacing; inconsistent in some
980 % circumstances before. Slight (consequent) change to the algorithm
981 % which ensures that material is output in absolute mode even when the
982 % page is otherwise empty. See README for details. Version 1.3a will
983 % remain available for some time in case these fixes break things.
984 %
985 % \item[1.3a, 2003 June 24]\relax
986 % Added the |\textblockcolour| command, to set
987 % the background colour of text blocks
988 %
989 % \item[\textbf{1.3, 2003 June 24}]\relax
990 % (there was a release 1.3, but it was broken, and immediately
991 % replaced by 1.3a)
992 %
993 % \item[1.2b, 2002 July 1]\relax
994 % Works around a bug present in at least one package,
995 % which leaves box255 holding an hbox at the wrong moment
996 %
997 % \item[1.2a, 2002 April 28]\relax
998 % Version 1.2 had an error, which caused a confusing error
999 % if you gave any fractional part in the arguments to the
1000 % |{textblock}| environment. This was fixed in version 1.2a,
1001 % which adds a |{textblock*}| environment (fully compatible
1002 % with |calc|), and does not attempt to support calc-style
1003 % expressions in the parameters to the unstarred
1004 % |{textblock}| environment.
1005 %
1006 % \item[\textbf{1.2, 2002 April 21}]\relax
1007 % Rolf Niepraschk |[email protected]| provided code to
1008 % make textpos compatible with the |calc| package
1009 %
1010 % \item[Version 1.1]\relax
1011 % Released in 1999
1012 %
1013 % \end{description}%
1014 % \section{Credits}
1015 %
1016 % Olaf Maibaum, \texttt{[email protected]},
1017 % made an elegant improvement to an earlier version of this package,
1018 % by producing the code which I've incorporated here as the `absolute
1019 % mode' (I'd had something like this before, but it was \emph{very}
1020 % kludgy).
1021 %
1022 % Bjoern Pedersen, \texttt{[email protected]},
1023 % made the excellent suggestion that the horizontal and vertical
1024 % modules should be independent, and provided code to implement this.
1025 %
1026 % Rolf Niepraschk, \texttt{[email protected]}, provided the code changes
1027 % which made textpos compatible with the \pstyle{calc} package.
1028 %
1029 % Wybo Dekker, \texttt{[email protected]}, reported a problem when
1030 % box~255 was (erroneously) not a vbox, and passed on a fix from Hans
1031 % Hagen.
1032 %
1033 % Jenny Maresh and Matthias Jerg independently suggested that it would
1034 % be useful to specify a margin around the block of text in a
1035 % \Lenv{textblock} environment. That resulted in the |\TPMargin|
1036 % command (after an unconscionably long gestation period). Rusen Lu
1037 % suggested that one should be able to specify the colours of the box
1038 % borders, and that it would be useful to turn the bordering feature
1039 % on and off within the file.
1040 %
1041 % Axel Sommerfeldt provided elegant code to fix incorrect
1042 % behaviour of |\caption| within the \Lenv{figure} environment.
1043 %
1044 % Section~\ref{s:interactions}, above, lists numerous people who have
1045 % provided problem reports about the interactions between Textpos and
1046 % other packages, and provided suggestions for workarounds and fixes.
1047 %
1048 % The text includes footnoted thanks to various people who have made
1049 % (sometimes very detailed) suggestions for functionality.
1050 %
1051 % Ulrike Fischer provided detailed guidance on the changes required to
1052 % make \pstyle{textpos} compatible with \LaTeX3.
1053 %
1054 % Thanks are additionally due, for general bugreports and other suggestions, to
1055 % Jozef Bednarcik,
1056 % Richard G Daniel,
1057 % Wolfgang Fleischer,
1058 % Greg Petriccione,
1059 % Giovanni Radilla,
1060 % Richard Schreiber,
1061 % Brian Stephanik,
1062 % Robert Whittaker,
1063 % Joseph Wright,
1064 % and Joachim Wuttke,
1065 %
1066 % If you've reported a bug or made a suggestion and I haven't credited
1067 % you here, please do accept my apologies, and please let me know.
1068 %
1069 % \section{Example}
1070 %
1071 % Here is a short example file.
1072 % \begin{macrocode}
1073 %<*example>
1074 \documentclass{article}
1075
1076 \usepackage[absolute]{textpos}
1077
1078 \setlength{\TPHorizModule}{30mm}
1079 \setlength{\TPVertModule}{\TPHorizModule}
1080 \textblockorigin{10mm}{10mm} % start everything near the top-left corner
1081 \setlength{\parindent}{0pt}
1082
1083 \begin{document}
1084
1085 \begin{textblock}{3}(0,0)
1086 This block is 3 modules wide, and is placed with its top left corner
1087 at the `origin' on the page. Note that the length of the block is not
1088 specified in the arguments -- the box will be as long as necessary to
1089 accomodate the text inside it. You need to examine the output of the
1090 text to adjust the positioning of the blocks on the page.
1091 \end{textblock}
1092
1093 \begin{textblock}{2}(2,1)
1094 \textblocklabel{block two}
1095 Here is another, slightly narrower, block, at position (2,1) on the page.
1096 \end{textblock}
1097
1098 \begin{textblock}{3}[0.5,0.5](2,3)
1099 This block is at position (2,3), but because the optional argument
1100 [0.5,0.5] has been given, it is the centre of the block which is
1101 located at that point, rather than the top-left corner.
1102 \end{textblock}
1103
1104 \end{document}
1105 %</example>
1106 % \end{macrocode}
1107 %
1108 % \StopEventually{}
1109
1110 % \section{Implementation}
1111 % \begin{macrocode}
1112 %<*package>
1113 % \end{macrocode}
1114 %
1115 %
1116 % \subsection{Options}
1117 %
1118 % Allow the user to switch on display of boxes round the text.
1119 % \begin{macrocode}
1120 \newif\ifTPshowboxes
1121 \TPshowboxesfalse
1122 \DeclareOption{showboxes}{\TPshowboxestrue}
1123 % \end{macrocode}
1124 % \dots and switch off printing of text.
1125 % \begin{macrocode}
1126 \newif\ifTP@showtext
1127 \TP@showtexttrue
1128 \DeclareOption{noshowtext}{\TP@showtextfalse}
1129 % \end{macrocode}
1130 %
1131 % The user may declare that the positions given to the |\textblock|
1132 % environment are to be absolute on the page, rather than relative to
1133 % the current position. Relative mode is, and will remain, the
1134 % default, so the \Lopt{relative} option is redundant, but is here for symmetry.
1135 % \begin{macrocode}
1136 \newif\ifTP@abspos
1137 \TP@absposfalse
1138 \DeclareOption{absolute}{\TP@abspostrue}
1139 \DeclareOption{relative}{\TP@absposfalse}
1140 % \end{macrocode}
1141 %
1142 % When using the absolute-position mode, the holdbox is placed into
1143 % box~255 in front of the previous contents of box~255. This is
1144 % normally what you want, but if the page contents have something
1145 % which \emph{obscures} the hold box (for example, a block of opaque
1146 % colour), then the positioned textboxes disappear. In this case,
1147 % allow the user to specify that the holdbox is to be placed
1148 % \emph{after} the contents of box~255, so that it overlays it rather
1149 % than being overlayed.
1150 % \changes{v1.1c}{1999/03/22}{Added overlay option}
1151 % \begin{macrocode}
1152 \newif\ifTP@overlay
1153 \TP@overlayfalse
1154 \DeclareOption{overlay}{\TP@overlaytrue}
1155 % \end{macrocode}
1156 %
1157 % The package can produce some messages reporting on its progress.
1158 % Allow these to be turned off and on explicitly. The default is
1159 % (currently) on.
1160 % \changes{v1.2}{2002/04/21}{Added verbose and quiet options}
1161 % \begin{macrocode}
1162 \newif\ifTP@chatter
1163 \TP@chattertrue
1164 \DeclareOption{quiet}{\TP@chatterfalse}
1165 \DeclareOption{verbose}{\TP@chattertrue}
1166 % \end{macrocode}
1167 %
1168 % Define a switch to suppress holdbox processing (see |\TP@holdbox| below).
1169 % \begin{macrocode}
1170 \newif\ifTP@displayholdbox
1171 \TP@displayholdboxtrue
1172 \DeclareOption{discardcontent}{\TP@displayholdboxfalse}
1173 % \end{macrocode}
1174 %
1175 % That's it. Now process the options and get on with it.
1176 % \begin{macrocode}
1177 \ProcessOptions
1178 % \end{macrocode}
1179 %
1180 % \subsection{\LaTeX3/\LaTeXiie\ compatibility}
1181 %
1182 % This code aims to be compatible with both \LaTeXiie\ and \LaTeX3. This
1183 % means that it must use the \pstyle{everyshi} package in the \LaTeXiie\
1184 % case, and must use the corresponding built-in \LaTeX3 mechanism otherwise.
1185 % For documentation on the latter, see the `ltshipout' package
1186 % documentation.\footnote{Thanks to Ulrike Fischer for detailed advice
1187 % on the steps to take here}
1188 %
1189 % There are a couple of places in where we must switch behaviour.
1190 % Conditionalise them with a single switch.
1191 % Note that we can't use the (apparently preferable)
1192 % |\IfFormatAtLeastTF| command to do this test: we want to continue to
1193 % work even when we're using a \LaTeX\ which is too old for this
1194 % command to be defined.
1195 % \begin{macrocode}
1196 \newif\ifTP@Liii
1197 \@ifl@t@r\fmtversion{2020/10/01}\TP@Liiitrue\TP@Liiifalse
1198 \PackageInfo{textpos}{choosing support for \ifTP@Liii LaTeX3\else LaTeX2e\fi}
1199 % \end{macrocode}
1200 %
1201 % \subsection{Required Packages}
1202 %
1203 % To manipulate |\box255| when using \LaTeXiie (and only in that case),
1204 % this package needs the package \pstyle{everyshi},
1205 % which provides the command |\EveryShipout|.
1206 % \begin{macrocode}
1207 \ifTP@Liii\else
1208 \ifTP@abspos
1209 \RequirePackage{everyshi}
1210 \fi
1211 \fi
1212 \RequirePackage{keyval}
1213 % \end{macrocode}
1214 %
1215 % \subsection{Changing options within the text}
1216 %
1217 % Define a |\TPoptions| macro which supports constructions like |\TPoptions{verbose=true}|.
1218 % \iffalse This was I think prompted by the SE question https://tex.stackexchange.com/questions/172902/
1219 % It was a comment to question
1220 % https://tex.stackexchange.com/questions/248504/ that made me realise
1221 % the overlay option wasn't changeable here.
1222 % \fi
1223 % \begin{macrocode}
1224 \define@key{tp}{absolute}{\csname TP@abspos#1\endcsname}
1225 \define@key{tp}{overlay}{\PackageWarning{textpos}{The overlay option
1226 to TPoptions is not implemented and has been ignored}}
1227 \define@key{tp}{verbose}{\csname TP@chatter#1\endcsname}
1228 \define@key{tp}{showboxes}{\csname TPshowboxes#1\endcsname}
1229 \define@key{tp}{showtext}{\csname TP@showtext#1\endcsname}
1230 \define@key{tp}{discardcontent}{%
1231 \csname @tempswa#1\endcsname
1232 \if@tempswa\TP@displayholdboxfalse\else\TP@displayholdboxtrue\fi}
1233 \def\TPoptions{\setkeys{tp}}
1234 % \end{macrocode}
1235 %
1236 % \subsection{Other initialisation}
1237 %
1238 % Handle floats. The following definition of |\TP@xfloat| will be
1239 % used to redefine |\@xfloat| within textblocks. It has the same
1240 % `interface' as |\@xfloat| -- and in particular, it sets |\@captype|,
1241 % so that |\caption| will still work -- except that it ignores any
1242 % placement specifiers, and doesn't put anything into the |\@currbox|.
1243 % Thus nothing will actually float from here, and thus float out of the
1244 % textblock.
1245 %
1246 % We have to open a box, and set |\@floatpenalty|, because
1247 % |\end@float| expects to close a box; and we don't want to redefine
1248 % |\end@float| because that would required us to redefine
1249 % |\end@dblfloat| as well. Redefine |\@xympar| to throw an error:
1250 % this means that |\marginpar| is forbidden inside textblocks. Hmm,
1251 % it also means that it's forbidden even within a minipage -- is that
1252 % a bad thing?
1253 % \changes{1.6a}{2005/10/13}{remove superfluous definitions of thefigure}
1254 % \changes{1.7c}{2007/03/29}{fix caption handling -- code from Axel Sommerfeldt}
1255 % \changes{1.7d}{2007/03/30}{further figure fixes, building on more Axel suggestions}
1256 % \begin{macrocode}
1257 \def\TP@xfloat#1[#2]{
1258 \par\def\@captype{#1}%
1259 \@floatpenalty\z@
1260 \color@vbox
1261 \normalcolor
1262 \vbox\bgroup
1263 }
1264 \def\TP@xympar{
1265 \PackageError{textpos}
1266 {You can't use \protect\marginpar\space within a textblock}
1267 {You're using textpos because you _don't_ want things to float around, yes?}}
1268 % \end{macrocode}
1269 %
1270 % \subsection{The box handling starts here}
1271 % The text we set will be put into the box |\TP@textbox|.
1272 % \begin{macrocode}
1273 \newbox\TP@textbox
1274 % \end{macrocode}
1275 % When the package is invoked in `absolute' mode, the contents of
1276 % |\TP@textbox| are not shipped out immediately, but instead put into the box
1277 % |\TP@holdbox|, which holds the boxes until the page as a whole is
1278 % shipped out.\footnote{These additions contributed by Olaf Maibaum}
1279 % \changes{v1.1}{1999/02/22}{Introduce holdbox, and absolute/relative modes}
1280 %
1281 % Add a flag which is used to recall the vertical/horizontal mode in
1282 % which the textblock is prepared.
1283 % \begin{macrocode}
1284 \newif\ifTP@vmode
1285 % \end{macrocode}
1286 %
1287 % Define the holdbox only in the `absolute positioning' mode.
1288 % \begin{macrocode}
1289 \ifTP@abspos
1290 \newbox\TP@holdbox % starts off void
1291 % \end{macrocode}
1292 %
1293 % \TeX\ does not call the output routine if there is nothing on the
1294 % page. To deal with this situation, add code to the end-document
1295 % hook to add a zero-size hbox on the page if |\TP@holdbox| is
1296 % non-empty; the page is no longer empty, so the output routine must
1297 % be called at some point. The alternative is to add such an hbox at
1298 % the end of every textblock, when in absolute mode. That solves
1299 % this problem, but introduces others by interfering with vertical
1300 % spacing.\footnote{Thanks to Bjoern Pedersen for diagnosing this in an old version of textpos}
1301 % \begin{macrocode}
1302 \AtEndDocument{\ifTP@displayholdbox\ifvoid\TP@holdbox \else \hbox{}\fi\fi}
1303 \fi
1304 % \end{macrocode}
1305 % All the dimensions (except the optional argument of the textblock
1306 % environment) are in terms of the modules |\TPHorizModule| and
1307 % |\TPVertModule|.
1308 % \changes{v1.1}{1999/02/22}{Distinguish horizontal and vertical modules}
1309 % \begin{macrocode}
1310 \newdimen\TPHorizModule
1311 \newdimen\TPVertModule
1312 % \end{macrocode}
1313 %
1314 % \begin{macro}{\TPMargin}
1315 % Macro |\TPMargin| specifies the amount of space left between the
1316 % box, as positioned by the \texttt{textblock}, and the enclosed
1317 % text. The argument is a dimension, which may as usual be given in
1318 % units of |\TP*Module|. We signal this to the rest of this package
1319 % by making |\TP@margin| positive (we demand that the argument is
1320 % positive). The companion dimension |\TP@absmargin| is just the
1321 % absolute value of |\TP@margin|, for convenience.
1322 % \begin{macrocode}
1323 \newdimen\TP@margin
1324 \TP@margin=0pt
1325 \newdimen\TP@absmargin
1326 \TP@absmargin=0pt
1327 \newcommand{\TPMargin}{%
1328 \@ifstar\TPMargin@outer\TPMargin@inner
1329 }
1330 \newcommand{\TPMargin@inner}[1]{%
1331 \TP@margin=#1\relax
1332 \ifdim\TP@margin < 0pt
1333 \PackageError{textpos}
1334 {\protect\TPMargin\space must have a positive argument}
1335 {\protect\TPMargin\space must have a positive argument}
1336 \fi
1337 \TP@absmargin=\TP@margin
1338 }
1339 % \end{macrocode}
1340 % \end{macro}
1341 % \begin{macro}{\TPMargin*}
1342 % Partnered to this, the |\TPMargin*| command also specifies a margin
1343 % between the text and its enclosing box, but this time the
1344 % \emph{text} is at the position specified by the \texttt{textblock},
1345 % and the box, delimited either by a line or by a panel of colour,
1346 % extends outside this position by an amount specified in the argument
1347 % to this macro. We signal this to the rest of this package by making
1348 % the margin negative.
1349 % \begin{macrocode}
1350 \newcommand\TPMargin@outer[1]{%
1351 \TP@margin=-#1\relax
1352 \ifdim\TP@margin > 0pt
1353 \PackageError{textpos}
1354 {\protect\TPMargin*\space must have a positive argument}
1355 {\protect\TPMargin*\space must have a positive argument}
1356 \fi
1357 \TP@absmargin=-\TP@margin
1358 }
1359 % \end{macrocode}
1360 % \end{macro}
1361 %
1362 % \begin{macro}{\TPGrid}
1363 % Rather than declare the modules to be specific sizes, they can be
1364 % declared to be proportions of the paper size. The command
1365 % |\TPGrid{16}{10}| would declare the horizontal module to be a
1366 % sixteenth of the paper size, and the vertical one to be a tenth of
1367 % the paper height. Set the textblockorigin if the optional arguments
1368 % were provided.
1369 % \changes{v1.1c}{1999/03/09}{Add optional argument to TPGrid}
1370 % \begin{macrocode}
1371 \def\TPGrid{%
1372 \@ifnextchar[{\@tempswatrue\TP@Grid}{\@tempswafalse\TP@Grid[0pt,0pt]}}
1373 \def\TP@Grid[#1,#2]#3#4{
1374 \setlength{\@tempdima}{#1}
1375 \multiply\@tempdima by 2
1376 \TPHorizModule=\paperwidth
1377 \advance\TPHorizModule by -\@tempdima
1378 \divide\TPHorizModule by #3
1379 \setlength{\@tempdima}{#2}
1380 \multiply\@tempdima by 2
1381 \TPVertModule=\paperheight
1382 \advance\TPVertModule by -\@tempdima
1383 \divide\TPVertModule by #4
1384 \ifTP@chatter
1385 \typeout{Grid set #3 x #4 = \the\TPHorizModule\space x \the\TPVertModule}%
1386 \fi
1387 \ifTP@abspos\if@tempswa \textblockorigin{#1}{#2}\fi\fi
1388 }
1389 % \end{macrocode}
1390 % \end{macro}
1391 % And use this to initialise initialise the modules to a suitable
1392 % default -- one sixteenth of the paper width and height.
1393 % \begin{macrocode}
1394 \TPGrid{16}{16}
1395 % \end{macrocode}
1396 %
1397 % The rules round the boxes are of width |\TPboxrulesize|, and the
1398 % label text within them is |\normalsize|. For the colour, see
1399 % |\textblockrulecolour|.
1400 % \begin{macrocode}
1401 \newdimen\TPboxrulesize
1402 \setlength{\TPboxrulesize}{0.4pt}
1403 \def\showtextsize{\normalsize}
1404 % \end{macrocode}
1405 %
1406 % In order to make it easy to visualise the grid, the
1407 % |\TPShowGrid| macro displays it on the page. There's a starred
1408 % version, which shows the coordinates, and an unstarred version,
1409 % which doesn't.
1410 % \begin{macrocode}
1411 \def\TPShowGrid{\@ifstar{\@tempswatrue\@TPShowGrid}{\@tempswafalse\@TPShowGrid}}
1412 % \end{macrocode}
1413 % And the implementation
1414 % \begin{macrocode}
1415 \def\@TPShowGrid#1#2{
1416 \begin{textblock}{#1}(0,0)
1417 \lineskip=0pt % abut boxes directly
1418 \setbox0=\hbox{(0)}%
1419 \@tempdima=\TPVertModule
1420 \advance\@tempdima -1.1\ht0
1421 \@tempcnta=0
1422 \hrule
1423 \loop
1424 \vbox to \TPVertModule{\noindent
1425 \@tempcntb=0
1426 \vrule
1427 \loop
1428 \hbox to \TPHorizModule{%
1429 \if@tempswa\raise\@tempdima\hbox{(\the\@tempcntb,\the\@tempcnta)}\fi
1430 \hfil \vrule height \TPVertModule}%
1431 \advance\@tempcntb 1
1432 \ifnum\@tempcntb<#1 \repeat
1433 \vss \hrule}
1434 \advance\@tempcnta 1
1435 \ifnum\@tempcnta<#2 \repeat
1436 \end{textblock}}
1437 % \end{macrocode}
1438 %
1439 % \begin{macro}{\textblockorigin}
1440 % If we're producing a single page of text, it can be convenient to
1441 % set an origin. This command may only be used in absolute mode.
1442 %
1443 % First, we need two dimensions, to hold the position of the origin.
1444 % These are relative to the top-left corner of the page, so we need to
1445 % shift them by (1in,1in) to make them relative to the \TeX\ origin.
1446 % \begin{macrocode}
1447 \ifTP@abspos
1448 \newdimen\TP@ox
1449 \newdimen\TP@oy
1450 \fi
1451 % \end{macrocode}
1452 % The |\textblockorigin| command sets the origin of the page. It may
1453 % only be called if the package was loaded with the \Lopt{absolute}
1454 % option, so output an error message if that's not the case.
1455 % \begin{macrocode}
1456 \def\textblockorigin#1#2{%
1457 \ifTP@abspos
1458 \TP@ox=-1in \addtolength\TP@ox{#1}
1459 \TP@oy=-1in \addtolength\TP@oy{#2}
1460 \ifTP@chatter\typeout{TextBlockOrigin set to #1 x #2}\fi
1461 \else
1462 \PackageError{textpos}
1463 {The \protect\textblockorigin\space command\MessageBreak
1464 may only be used if the package was given\MessageBreak
1465 the`absolute' option when it was invoked}
1466 {If you want to use the \protect\textblockorigin\space command, then
1467 \MessageBreak
1468 invoke the package with the syntax\MessageBreak
1469 \protect\usepackage[absolute]{textpos}}
1470 \fi
1471 }
1472 % \end{macrocode}
1473 % \end{macro}
1474 %
1475 % \begin{macro}{\textblocklabel}
1476 % When we're only displaying rules boxes, instead of the text contents
1477 % of the blocks, it's useful to be able to identify which block is
1478 % which. The contents of |\textblocklabel| are ignored except when
1479 % the \Lopt{noshowtext} option has been used.
1480 % \begin{macrocode}
1481 \def\textblocklabel#1{\gdef\TP@textblocklabel{#1}}
1482 % (should I use \@bsphack...\@esphack for this?)
1483 % \end{macrocode}
1484 % \end{macro}
1485 %
1486 % \begin{macro}{\textblockcolour}
1487 % \changes{v1.3}{2003/06/25}{Add textblockcolour}
1488 % \changes{v1.3a}{2003/06/25}{Fix textblockcolour so it works when {color} not loaded}
1489 % \begin{macrocode}
1490 \def\textblockcolour#1{%
1491 \@ifundefined{color}%
1492 {\PackageWarning{textpos}{command textblockcolour used,\MessageBreak
1493 but {color} package not loaded.\MessageBreak
1494 Colour changes ignored.}}
1495 {\gdef\TP@blockcolour{#1}
1496 \ifx\TP@defaultblockcolour\@undefined
1497 \gdef\TP@defaultblockcolour{#1}
1498 \fi
1499 }}
1500 \def\TP@blockcolour{} % safe initial default
1501 % \end{macrocode}
1502 % \end{macro}
1503 % \begin{macro}{\textblockcolor}
1504 % Add a synonym for those who follow Webster's half-hearted spelling reforms.
1505 % \begin{macrocode}
1506 \let\textblockcolor\textblockcolour
1507 % \end{macrocode}
1508 % \end{macro}
1509 % \begin{macro}{\tekstblokkulur}
1510 % \dots and one for the hard-core reformers, too.
1511 % \begin{macrocode}
1512 \let\tekstblokkulur\textblockcolour
1513 % \end{macrocode}
1514 % \end{macro}
1515 %
1516 % \begin{macro}{\textblockrulecolour}
1517 % We select the colour of the box rules using |\color| (since v1.7).
1518 % However we don't want to depend on the `color' package, so if we're
1519 % showing box rules, and so would be selecting box colours, then give
1520 % a warning but do not fail. Note the faking of that package's
1521 % commands below.
1522 % \changes{v1.7}{2006/08/24}{Add textblockrulecolour}
1523 % \begin{macrocode}
1524 \def\textblockrulecolour#1{%
1525 \@ifundefined{color}%
1526 {\PackageWarning{textpos}{command textblockrulecolour used,\MessageBreak
1527 but {color} package not loaded.\MessageBreak
1528 Colour changes ignored.}}
1529 {\gdef\TP@rulecolour{#1}}}
1530 \def\TP@rulecolour{black}
1531 % \end{macrocode}
1532 % Plus spelling-reform variants:
1533 % \begin{macrocode}
1534 \let\textblockrulecolor\textblockrulecolour
1535 \let\tekstblokroolkulur\textblockrulecolour
1536 % \end{macrocode}
1537 % \end{macro}
1538 %
1539 % We don't want to create a dependency on the \pstyle{color} package,
1540 % so we shouldn't fail if that package isn't loaded. Don't check that
1541 % here, since the document, or another package, may load the color
1542 % package later. Instead, define a command which will create dummy
1543 % no-op definitions for the package commands we use, and invoke this
1544 % at the beginning of the document, unless the color package is in
1545 % fact loaded.
1546 % Note that the |\@ifundefined{color}| test is redundant in the
1547 % \LaTeX3 case; we retain it for the \LaTeXiie\ case.
1548 % \begin{macrocode}
1549 \gdef\TP@color[#1]#2{}
1550 \def\TP@dummycolorpackage{
1551 \@ifundefined{color}
1552 {\globaldefs=1
1553 \DeclareRobustCommand\color[2][]{}
1554 \def\color@block##1##2##3{}
1555 \globaldefs=0 }
1556 {}
1557 }
1558 \ifTP@Liii
1559 \AddToHook{env/document/before}{\TP@dummycolorpackage}
1560 \AddToHook{file/color.sty/after}{\let\TP@dummycolorpackage\relax}
1561 \else
1562 \AtBeginDocument{\TP@dummycolorpackage}
1563 \fi
1564 % \end{macrocode}
1565 %
1566 % Default the reference position, and support the command to override it.
1567 % \begin{macrocode}
1568 \def\TP@referenceposition{0,0}
1569 \def\TPReferencePosition#1{\def\TP@referenceposition{#1}}
1570 % \end{macrocode}
1571 %
1572 % \begin{macro}{\textblock}
1573 % Now define the start of the textblock environment. Read the first
1574 % argument, and save it for the moment as |\@tempdima|. If we are
1575 % not in vertical mode, then issue a |\par| to make us so. The
1576 % environment is documented to create this paragraph break in this
1577 % case, so we don't neet to warn the user about this.
1578 % Then call |\TP@textblock| to read the remaining arguments and start
1579 % off the |\vbox| the body text will be set in.
1580 % \changes{v1.1}{1999/02/22}{Add par here, to put us back into vertical mode}
1581 % \changes{v1.4}{2003/09/05}{Remove warning about par}
1582 % \begin{macrocode}
1583 \def\textblock#1{%
1584 \@tempdima=#1\TPHorizModule
1585 \TP@begintextblock
1586 }
1587 % \end{macrocode}
1588 % \end{macro}
1589 % \begin{macro}{\textblock*}
1590 % |\begin{textblock*}| is a variant of |\begin{textblock}| which takes
1591 % absolute values for its arguments. It uses |\setlength| throughout,
1592 % and is therefore compatible with the \pstyle{calc} package.
1593 % \changes{1.2a}{2002/04/28}{Added textblock* env}
1594 % \begin{macrocode}
1595 \def\TP@textblockstar#1{%
1596 \setlength{\@tempdima}{#1}%
1597 \TP@begintextblock
1598 }
1599 \expandafter\let\csname textblock*\endcsname\TP@textblockstar
1600 % \end{macrocode}
1601 % \end{macro}
1602 % Common code for |textblock| and |textblock*|.
1603 % \begin{macrocode}
1604 \def\TP@begintextblock{%
1605 \ifvmode
1606 \TP@vmodetrue
1607 \else
1608 \ifmmode
1609 \PackageError{textpos}
1610 {You cannot use textblock in maths mode}
1611 {You may use the textblock environment only in \MessageBreak
1612 vertical mode or horizontal mode. You cannot use it in maths mode.}
1613 \else % in horizontal mode
1614 \TP@vmodefalse
1615 \@bsphack
1616 \unskip
1617 \fi
1618 \fi
1619 \@ifnextchar[{\TP@textblock}{\expandafter\TP@textblock\expandafter[\TP@referenceposition]}%] bracematch
1620 }
1621 % \end{macrocode}
1622 %
1623 % \begin{macro}{\TP@textblock}
1624 % Command |\TP@textblock| saves all its arguments in a token list, for
1625 % use in |\TP@endtextblock| later, then it starts a vbox. Arguments~1
1626 % and~2 are the coordinates of the reference point, as proportions of
1627 % the box's horizontal and vertical size, and arguments~3 and~4 are
1628 % the position of the box in units of the horizontal and vertical modules.
1629 % \begin{macrocode}
1630 \newtoks\TP@tbargs
1631 \def\TP@textblock[#1,#2](#3,#4){%
1632 \TP@tbargs={{#1}{#2}{#3}{#4}}%
1633 % \end{macrocode}
1634 %
1635 % Now (re)define |\@xfloat| and |\@xympar| to be the stub ones defined
1636 % above. Do this in all cases, even those where the |\figure|
1637 % environment is not defined: if there's no figure environment, this
1638 % will end up otiose rather than wrong, plus this will cope with the
1639 % rather peculiar case where there are some floats defined
1640 % \emph{other} than |\figure|.
1641 % \begin{macrocode}
1642 \let\@xfloat\TP@xfloat
1643 \let\@xympar\TP@xympar
1644 % \end{macrocode}
1645 %
1646 % Start the |\TP@textbox|, which contains the contents of the textblock.
1647 % Below, let the `textblock' refer to the block of text inside this
1648 % box, and `specwidth' the width provided as argument to the
1649 % \Lenv{textblock} environment.
1650 % \begin{macrocode}
1651 \setbox\TP@textbox=\vbox\bgroup
1652 % \end{macrocode}
1653 % If we're showing boxes, then draw a rule here
1654 % \begin{macrocode}
1655 \ifTPshowboxes
1656 {\color{\TP@rulecolour}\hrule height0pt depth \TPboxrulesize }%
1657 \vskip-\TPboxrulesize
1658 \fi
1659 % \end{macrocode}
1660 % Cases:
1661 % \begin{itemize}
1662 % \item When |\TP@margin| is zero, then `specwidth', the width of the
1663 % `textblock', and the actual width of |\TP@textbox|, are all equal.
1664 % \item When |\TP@margin| is positive, then `specwidth' is the width
1665 % of |\TP@textbox|, and the `textblock' is narrower (and shorter) than
1666 % this by a margin |\TP@margin| all round (|\hsize| is `specwidth'
1667 % minus 2|\TP@margin|).
1668 % \item When |\TP@margin| is negative, then `specwidth' is the width
1669 % of the `textblock' (|\hsize| is `specwidth'), and |\TP@textbox| is
1670 % wider than this by minus |\TP@margin|.
1671 % \end{itemize}
1672 % Here, when |\TP@margin| is non-zero, we set the `textblock' inside a
1673 % box of appropriate |\hsize|, and put that inside the |\TP@textbox|,
1674 % spaced appropriately (this seems more robust than using
1675 % left- and rightskip, which some environment redefine).
1676 % \changes{v1.7b}{2007/03/21}{Fixed lists inside boxes with non-zero margins}
1677 % \begin{macrocode}
1678 \ifdim\TP@margin = 0pt
1679 \hsize=\@tempdima
1680 \textwidth\hsize \columnwidth\hsize \linewidth\hsize
1681 \else
1682 \vskip\TP@absmargin
1683 \@tempdimb=\@tempdima % \@tempdimb is outer box width
1684 \hsize=\@tempdima % \hsize is inner box width
1685 \ifdim\TP@margin < 0pt
1686 \advance\@tempdimb by 2\TP@absmargin % bigger box
1687 \else
1688 \advance\hsize by -2\TP@absmargin % narrower content
1689 \fi
1690 \hbox to \@tempdimb\bgroup
1691 \hskip\TP@absmargin\vbox\bgroup
1692 \textwidth\hsize \columnwidth\hsize \linewidth\hsize
1693 \fi
1694 }
1695 % \end{macrocode}
1696 % \end{macro}
1697 %
1698 % \begin{macro}{\endtextblock}
1699 % \begin{macro}{\endtextblock*}
1700 % We have two slight variants of the end-block code, depending on
1701 % whether we're in a |{textblock}| or a |{textblock*}| environment.
1702 % The |\if@tempswa| set here is tested below, in |\TP@endtextblock|.
1703 % \changes{1.2a}{2002/04/28}{Added commonendtextblock, and starred variant}
1704 % \begin{macrocode}
1705 \def\endtextblock{\global\@tempswatrue\TP@commonendtextblock}
1706 \@namedef{endtextblock*}{\global\@tempswafalse\TP@commonendtextblock}
1707 % \end{macrocode}
1708 % \end{macro}
1709 % \end{macro}
1710 %
1711 % \begin{macro}{\TP@commonendtextblock}
1712 % At the end of the environment, draw the matching horizontal rule
1713 % (if we're showing boxes),
1714 % and finish off the vbox begun in |\TP@textblock|. Then call
1715 % |\TP@endtextblock| with the arguments we saved in the token register
1716 % in |\TP@tbargs|.
1717 %
1718 % Now we can handle the end of the textblock. When |\TP@margin| is
1719 % non-zero, include a final skip which is the size of the absolute
1720 % value of this margin.
1721 % \begin{macrocode}
1722 \def\TP@commonendtextblock{%
1723 \ifdim\TP@margin = 0pt
1724 \relax
1725 \else
1726 \egroup % end of inner vbox
1727 \hskip\TP@absmargin % (just \hfil would work here, too)
1728 \egroup % end of inner hbox
1729 \vskip\TP@absmargin
1730 \fi
1731 \ifTPshowboxes
1732 \vskip-\TPboxrulesize
1733 {\color{\TP@rulecolour}\hrule depth 0pt height \TPboxrulesize}%
1734 \fi
1735 \egroup % end of \TP@textbox
1736 % \end{macrocode}
1737 %
1738 % Finally, call |\TP@endtextblock| to do the work of putting the text
1739 % on the page, directly or indirectly.
1740 % \begin{macrocode}
1741 \expandafter\TP@endtextblock\the\TP@tbargs
1742 }
1743 % \end{macrocode}
1744 % \end{macro}
1745 %
1746 % \begin{macro}{\TP@endtextblock}
1747 % This is where most of the calculations are. Set temporary dimensions
1748 % a and b to be the coordinates (again, in units of the modules), and
1749 % then adjust them by subtracting the position of the `reference point'
1750 % given by parameters~1 and~2. These dimensions are pure numbers,
1751 % fractions of the width and height, respectively, of the text block.
1752 % Parameters~3 and~4 indicate where the reference point will be
1753 % positioned. In the unstarred case (|\if@tempswa| true), these are
1754 % pure numbers, indicating dimensions in units of the |\TPHorizModule|
1755 % and |\TPVertModule| respectively; in the starred case (|\if@tempswa|
1756 % false), they're dimensions.
1757 %
1758 % Position the box |\TP@textbox|, which was build up between
1759 % |\TP@textblock| and |\endtextblock|, at (x,y)=|(#3,#4)|.
1760 % The point that is so positioned is at |(#1\wd,#2\ht)| of
1761 % |\TP@textbox|, so that |(#1,#2)| =(0,0) means top left.
1762 %
1763 % If we're in the absolute-position mode, then we need to make further
1764 % adjustments to these dimensions.
1765 %
1766 % Below, |\@tempdima| and |\@tempdimb| are the $x$- and
1767 % $y$-coordinates of the framebox.
1768 % \changes{v1.5b}{2005/06/13}{Fixed control of reference point, broken in 1.5}
1769 % First, we set these coordinates to be |(#3,#4)|.
1770 % \begin{macrocode}
1771 \def\TP@endtextblock#1#2#3#4{%
1772 \if@tempswa % modular/unstarred endtextblock
1773 \@tempdima=#3\TPHorizModule
1774 \@tempdimb=#4\TPVertModule
1775 \else % absolute/starred endtextblock
1776 \setlength{\@tempdima}{#3}%
1777 \setlength{\@tempdimb}{#4}%
1778 \fi
1779 % \end{macrocode}
1780 % Next, we adjust them so that the position |(#1,#2)| is at this
1781 % coordinate. The |\TP@textbox| is the box including the lines
1782 % \emph{and} margin.
1783 %
1784 % Case 1: |\TP@margin| is negative: the `textblock' is `specwidth'
1785 % wide, and box |\TP@textbox| is wider and deeper than
1786 % the `specwidth', by |\TP@margin| all round; we want the position
1787 % |(#1,#2)| to be fractions of the textblock size, not |\TP@textbox|
1788 % \begin{macrocode}
1789 \ifdim\TP@margin < 0pt
1790 \advance\@tempdima \TP@margin
1791 \advance\@tempdimb \TP@margin
1792 \@tempdimc=\wd\TP@textbox
1793 \advance\@tempdimc 2\TP@margin % now \@tempdimc is width of textblock
1794 \multiply\@tempdimc #1
1795 \advance\@tempdima -\@tempdimc
1796 \@tempdimc=\ht\TP@textbox
1797 \advance\@tempdimc 2\TP@margin % now \@tempdimc is height of textblock
1798 \multiply\@tempdimc #2
1799 \advance\@tempdimb -\@tempdimc
1800 % \end{macrocode}
1801 % Case 2: |\TP@margin| is positive or zero: the |\TP@textbox| is
1802 % `specwidth' in width; the text inside the box is
1803 % narrower than this width; the coordinates |(#1,#2)| are
1804 % fractions of |\TP@textbox| size (ie, `specwidth').
1805 % \begin{macrocode}
1806 \else
1807 \@tempdimc=#1\wd\TP@textbox
1808 \advance\@tempdima -\@tempdimc
1809 \@tempdimc=#2\ht\TP@textbox
1810 \advance\@tempdimb -\@tempdimc
1811 \fi
1812 % \end{macrocode}
1813 % FInally, shift the origin if we're in absolute-positioning mode.
1814 % \begin{macrocode}
1815 \ifTP@abspos
1816 \advance\@tempdima by \TP@ox
1817 \advance\@tempdimb by \TP@oy
1818 \fi
1819 % \end{macrocode}
1820 % Then create an hbox inside a vbox, both of size 0pt, in each case
1821 % with the contents prefixed by a skip of the appropriate size, and
1822 % suffixed by |\hss| or |\vss| respectively. Put the result into the
1823 % temporary box~0
1824 % \changes{v1.3}{2003/06/25}{Add colouring of textblocks}
1825 % \begin{macrocode}
1826 \setbox0=\vbox to 0pt{\vskip\@tempdimb
1827 \hbox to 0pt{\hskip\@tempdima
1828 \ifx\TP@blockcolour\@empty \else
1829 {\color{\TP@blockcolour}%
1830 \color@block{\wd\TP@textbox}{\ht\TP@textbox}{\dp\TP@textbox}%
1831 }%
1832 \fi
1833 \ifx\TP@defaultblockcolour\@undefined \else
1834 \global\let\TP@blockcolour\TP@defaultblockcolour
1835 \fi
1836 \ifTPshowboxes
1837 {\color{\TP@rulecolour}\vrule width \TPboxrulesize}%
1838 \hskip -\TPboxrulesize
1839 \fi
1840 \ifTP@showtext
1841 \box\TP@textbox
1842 \else
1843 \vbox to\ht\TP@textbox{%
1844 \ifTPshowboxes
1845 {\color{\TP@rulecolour}\hrule depth 0pt height \TPboxrulesize \vskip-\TPboxrulesize}%
1846 \fi
1847 \vskip\smallskipamount
1848 \hbox to\wd\TP@textbox{%
1849 \ifx\TP@textblocklabel\undefined
1850 \hbox{}%
1851 \else
1852 \hskip\smallskipamount
1853 \fbox{\showtextsize \TP@textblocklabel}%
1854 \global\let\TP@textblocklabel\undefined
1855 \fi
1856 \hss
1857 }%
1858 \vss
1859 \ifTPshowboxes
1860 \vskip -\TPboxrulesize
1861 {\color{\TP@rulecolour}\hrule depth 0pt height \TPboxrulesize}%
1862 \fi
1863 }%
1864 \fi
1865 \ifTPshowboxes
1866 \hskip -\TPboxrulesize
1867 {\color{\TP@rulecolour}\vrule width \TPboxrulesize}%
1868 \fi
1869 \hss}%
1870 \vss
1871 }% end of box0
1872 % \end{macrocode}
1873 %
1874 % \subsection{Sending the boxes to the output}
1875 %
1876 % Now switch behaviour depending on whether or not we're in the
1877 % absolute-position mode.
1878 %
1879 % If we are in absolute position mode, then add the newly-constructed
1880 % box 0 to (the end of) the holdbox. The order matters in some
1881 % (many?, all?) circumstances, since this way means that later
1882 % textblock environments go `on top of' earlier ones, which is
1883 % generally more intuitive. I \emph{think} this would be true for all
1884 % drivers. Does this have some interaction with the \Lopt{overlay}
1885 % option, and if so, should it be coupled to that? I haven't
1886 % documented this one way or the other, and I think that ambiguity is
1887 % probably useful.
1888 % \begin{macrocode}
1889 \ifTP@abspos
1890 \global\setbox\TP@holdbox\vbox{%
1891 \unvbox\TP@holdbox
1892 \box0
1893 }%
1894 % \end{macrocode}
1895 % Else, place the box on the page immediately, and restore the value
1896 % of the quantity |\prevdepth| to what it was before we started
1897 % accumulating material for the textblock. This will mean (a) that
1898 % we can list several textblock environments one after another, and have them
1899 % all offset from the same point, and (b) that we are invisible with
1900 % respect to any |\parskip| or |\baselineskip| calculations that were
1901 % relevant at the time we started the textblock.
1902 % See the discussion of interline glue
1903 % (ie, |\baselineskip| and |\prevdepth|)
1904 % in Chapter~12 (p.~80) of the \TeX book.
1905 % \begin{macrocode}
1906 \else
1907 \ifTP@vmode
1908 \@tempdima=\prevdepth
1909 \prevdepth=-1000pt % = \nointerlineskip, supressing interline glue
1910 \box0 % zero height+depth
1911 \prevdepth=\@tempdima
1912 \else
1913 \vadjust{\box0}%
1914 \@esphack
1915 \fi
1916 \fi
1917 }
1918 % \end{macrocode}
1919 % \end{macro}
1920 %
1921 % Finally, and only if we are in the absolute-position mode,
1922 % set the textblockorigin to the (default) upper-left corner of the paper,
1923 % and organise the shipout mechanism to place the |\TP@holdbox| in a suitable place.
1924 %
1925 % There are two cases here, one when we are using \LaTeX3, and one
1926 % with \LaTeXiie.
1927 %
1928 % First, the \LaTeX3 case: use the `ltshipout' mechanism..
1929 % \begin{macrocode}
1930 \ifTP@abspos
1931 \ifTP@Liii
1932 \ifTP@overlay
1933 \AddToHook{shipout/foreground}{%
1934 \ifTP@displayholdbox\put(\strip@pt\dimexpr1in,-\strip@pt\dimexpr1in){\box\TP@holdbox}\fi}
1935 \else
1936 \AddToHook{shipout/background}{%
1937 \ifTP@displayholdbox\put(\strip@pt\dimexpr1in,-\strip@pt\dimexpr1in){\box\TP@holdbox}\fi}
1938 \fi
1939 % \end{macrocode}
1940 %
1941 % Second, the \LaTeXiie\ case: use the macros provided by the \pstyle{everyshi} package.
1942 % We set up the output routine with |\EveryShipout|.
1943 %
1944 % Respect the \Lopt{overlay} option by putting the |\TP@holdbox| contents
1945 % \emph{after} the |\@cclv| contents, putting the latter into a size-0
1946 % box (could this cause a problem with spacing? I don't think so, at
1947 % this stage).
1948 %
1949 % Box 255 should be either a vbox or void (see \TeX Book pp.~125
1950 % or~253), but if it is an hbox, because some package has misbehaved,
1951 % then we ought to try not to simply collapse. Work round this by
1952 % testing explicitly whether box~255 is a vbox or not.
1953 % If |\ifTP@displayholdbox| is false, then both of these should be no-ops.
1954 % \changes{v1.2b}{2002/07/01}{Defend against box 255 not being a vbox}
1955 % \begin{macrocode}
1956 \else
1957 \ifTP@overlay
1958 \EveryShipout{\ifTP@displayholdbox
1959 \global\setbox\@cclv\vbox{%
1960 \vbox to 0pt{\ifvbox\@cclv \unvbox\@cclv \else \box\@cclv \fi \vss}%
1961 \unvbox\TP@holdbox % TP@holdbox is now void
1962 }%
1963 \fi}%
1964 \else
1965 \EveryShipout{\ifTP@displayholdbox
1966 \global\setbox\@cclv\vbox{%
1967 \unvbox\TP@holdbox
1968 \ifvbox\@cclv \unvbox\@cclv \else \box\@cclv \fi
1969 }%
1970 \fi}%
1971 \fi
1972 \fi % ifTP@Liii
1973 % \end{macrocode}
1974 % Finally, set the textblockorigin to the (default) upper-left corner of the paper.
1975 % \begin{macrocode}
1976 \textblockorigin{0pt}{0pt}%
1977 \fi % ifTP@abspos
1978 % \end{macrocode}
1979 % Done!
1980 % \begin{macrocode}
1981 %</package>
1982 % \end{macrocode}
1983 %
1984 % \Finale
1985 %
1986 \endinput