summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/textpos
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2016-06-09 22:53:55 +0000
committerKarl Berry <karl@freefriends.org>2016-06-09 22:53:55 +0000
commit29b2df230459512a0f73e5769a1cfc16e4125510 (patch)
tree7ace3eb84f9786277a63ea0d04585d170d44d897 /Master/texmf-dist/source/latex/textpos
parent96152b37515359e17b9cbe19a6186cec57a15eda (diff)
textpos (8jun16)
git-svn-id: svn://tug.org/texlive/trunk@41331 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/textpos')
-rw-r--r--Master/texmf-dist/source/latex/textpos/textpos.drv16
-rw-r--r--Master/texmf-dist/source/latex/textpos/textpos.dtx749
2 files changed, 521 insertions, 244 deletions
diff --git a/Master/texmf-dist/source/latex/textpos/textpos.drv b/Master/texmf-dist/source/latex/textpos/textpos.drv
index 4e5375b98a8..d4e867177ba 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--2003, 2005-7, 2009-12, 2014, Norman Gray
+%%%% Copyright 1999, 2001-03, 2005-7, 2009-12, 2014-16., Norman Gray
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
@@ -29,13 +29,13 @@
%%
%% See the file LICENCE for a copy of the LPPL.
%%
-%% Mercurial ident: 41b12ce5565c, 2014-01-03 19:15 +0000
+%% Mercurial ident: 8aa202e2b283, 2016-06-07 23:52 +0100
%%
\documentclass{ltxdoc}
\title{Textpos: absolute positioning of text on the page}
\author{Norman Gray\\(\texttt{http://nxg.me.uk})}
-\date{Version 1.7j, 2014 January 3\footnote{Mercurial ident: 41b12ce5565c, 2014-01-03 19:15 +0000.
-This software is copyright, 1999, 2001--2003, 2005-7, 2009-12, 2014 Norman Gray.
+\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.
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}.}}
@@ -70,13 +70,13 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
}
\def\setpath#1{\ttfamily\small <\nobreak #1\nobreak>\endgroup}
\def\url{\begingroup\pathcats\setpath}
-\OnlyDescription
\begin{document}
\maketitle
\tableofcontents
-\bigskip
-\hrule
-\bigskip
+%% \bigskip
+%% \hrule
+%% \bigskip
+\newpage
\DocInput{textpos.dtx}
\end{document}
diff --git a/Master/texmf-dist/source/latex/textpos/textpos.dtx b/Master/texmf-dist/source/latex/textpos/textpos.dtx
index 4dc0270452b..1d52892300e 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--2003, 2005-7, 2009-12, 2014, Norman Gray
+%%%% Copyright 1999, 2001-03, 2005-7, 2009-12, 2014-16., Norman Gray
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
@@ -14,29 +14,29 @@
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
-%%
+%%
%% 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.
-%%
+%%
%% 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: 41b12ce5565c, 2014-01-03 19:15 +0000
+%% Mercurial ident: 8aa202e2b283, 2016-06-07 23:52 +0100
%%
%<+package>\NeedsTeXFormat{LaTeX2e}
-%<+package>\ProvidesPackage{textpos}[2014/01/03 v1.7j]
-%<+package>\typeout{Package: textpos 2014/01/03 1.7j, absolute positioning of text on the page}
+%<+package>\ProvidesPackage{textpos}[2016/06/07 v1.8]
+%<+package>\typeout{Package: textpos 2016/06/07 1.8, 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.7j, 2014 January 3\footnote{Mercurial ident: 41b12ce5565c, 2014-01-03 19:15 +0000.
-This software is copyright, 1999, 2001--2003, 2005-7, 2009-12, 2014 Norman Gray.
+\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.
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}.}}
@@ -54,7 +54,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
\def\activemeta#1>{\meta{#1}}
{\catcode`\<=\active
\gdef\cmd{\begingroup
- \catcode`\\=12 \catcode`\{=12 \catcode`\}=12
+ \catcode`\\=12 \catcode`\{=12 \catcode`\}=12
\catcode`\<=\active \let<\activemeta
\catcode`\|=12
\docmd}}
@@ -62,10 +62,10 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
%% \url macro (url.sty does this better)
\def\setpathdots{\discretionary{.}{}{.}}
\def\setpathslash{\discretionary{/}{}{/}}
-{\catcode`\.=\active
- \catcode`\/=\active
+{\catcode`\.=\active
+ \catcode`\/=\active
\gdef\pathcats{%
- \catcode`\%=12 \catcode`\~=12
+ \catcode`\%=12 \catcode`\~=12
\catcode`\.=\active \let.\setpathdots
\catcode`\/=\active \let/\setpathslash
\catcode`\#=12 \catcode`\_=12}%
@@ -73,13 +73,14 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
\def\setpath#1{\ttfamily\small <\nobreak #1\nobreak>\endgroup}
\def\url{\begingroup\pathcats\setpath}
%\RecordChanges
-\OnlyDescription
+%\OnlyDescription
\begin{document}
\maketitle
\tableofcontents
-\bigskip
-\hrule
-\bigskip
+%% \bigskip
+%% \hrule
+%% \bigskip
+\newpage
\DocInput{textpos.dtx}
\end{document}
%</driver>
@@ -116,7 +117,7 @@ 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/}
+% \url{http://www.tex.ac.uk/tex-archive/macros/latex/contrib/supported/ms/}
% or one of the other CTAN hosts.
%
% Textpos has a home page at \url{http://purl.org/nxg/dist/textpos}.
@@ -129,9 +130,9 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% drafting them in code.
%
% An article describing Textpos appeared in TUGboat in 2002:
-% Norman Gray, `Absolute Positioning with
+% Norman Gray, `Absolute Positioning with
% Textpos', TUGboat \textbf{23} (3/4), pp341--4, 2002, available at
-% \url{http://www.tug.org/TUGboat/tb23-3-4/tb75gray.pdf}.
+% \url{http://www.tug.org/TUGboat/tb23-3-4/tb75gray.pdf}.
%
% \section{Description}
%
@@ -152,26 +153,27 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% The \meta{hsize} and \meta{hpos} arguments are given in units of a
% module |\TPHorizModule|, and \meta{vpos} is given in units of a
% module |\TPVertModule|. You set these using
-% the command
+% the command
% \cmd|\setlength{\TPHorizModule}{<dimen>}|,
% and similarly for |\TPVertModule|.
% The arguments may be any dimension, and you may use the modules as
% units elsewhere in your document if you wish to, for example in
% \texttt{\bslash makebox[2\bslash TPHorizModule]\{gnus\}}. The text in the
-% environment will be set in a
+% environment will be set in a
% box \meta{hsize} modules wide, and placed on the page with its
% upper left corner at the position (\textit{hpos,vpos}). As is
% natural in \TeX, the \meta{vpos} parameter indicates distance
% \emph{down} from the `anchor point' (see below).
%
-% The \Lenv{textblock} parameters may be whole numbers or
-% fractional. If you want or need to give explicit sizes here, see
-% the \Lenv{textblock*} environment below.
+% The \Lenv{textblock} parameters \meta{hsize},
+% \meta{hpos} and \meta{vpos} are \emph{multiples or fractions of the horizontal
+% and vertical modules}, as appropriate. If you want or need to give
+% explicit sizes here, see the \Lenv{textblock*} environment below.
%
% Notice that the positioning arguments for the \Lenv{textblock}
% command -- the coordinates \cmd|...(<hpos>,<vpos>)| -- are in
-% \emph{round} brackets, not
-% curly ones. This is in imitation of the \texttt{picture}
+% \emph{round} brackets,\marginpar{Round brackets!}
+% not curly ones. This is in imitation of the \texttt{picture}
% environment, and whether or not this is sensible, it's not going to
% change now.
%
@@ -187,7 +189,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% environments one after the other, so that they are all relative to
% the same point.
%
-% If, however, your entire
+% If, however, your entire
% document is to be laid out piece by piece (which is the case in the
% canonical use of the package, to lay out a poster), then you might
% want to be more sure of where the origin is. In this case, you make
@@ -195,12 +197,14 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% the \Lopt{absolute} option: |\usepackage[absolute]{textpos}|.
% In this mode, all the block-positioning parameters are given
% relative to a single origin on the page. By default, this `anchor point' is the
-% top-left corner of the page, but you may change it with the
+% top-left corner of the page, but you may change it with the
% command \cmd|\textblockorigin{<hpos>}{<vpos>}|.
% 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{absolute-newpage}.
+% 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.
%
% The textblocks are placed on the page in the order in which they
% appear in the file. This means that later textblocks will be placed
@@ -210,6 +214,80 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% in principle). This order was unspecified before textpos 1.7e; it
% was changed, and specified, in that version.
%
+% The \Lenv{textblock} environment will most often be used in
+% vertical mode. If it is called in horizontal (ie, paragraph) mode,
+% however, it will silently create a paragraph break by inserting a
+% |\par| command before the environment; it remains in vertical mode
+% after the environment is finished. It should have no further
+% effects on spacing, and if you find that it does, that's a bug. If
+% you try to use the environment when in maths mode, the package
+% objects (as it should!).
+%
+% \subsection{Package options}
+% \label{packopts}
+%
+% There are several package options:
+% \begin{description}
+% \item[\Lopt{showboxes}]When you are laying things out, it can be
+% useful to have the boxes drawn in for you. This option draws a box
+% fitting closely round the set text.
+% \item[\Lopt{noshowtext}]This suppresses the display of the text in
+% each block (so it's not really usable without the \Lopt{showboxes}
+% option). The resulting box will be the correct size, but empty,
+% unless the |\textblocklabel| command has been given. This
+% 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.
+% \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
+% something
+% which \emph{obscures} the textblocks (for example, a block of opaque
+% colour), then the positioned textboxes disappear. In this case,
+% specify the option \Lopt{overlay}, to request that the positioned
+% blocks of text overlay any other page contents, rather
+% than being overlaid.
+% \item[\Lopt{verbose}, \Lopt{quiet}]The package writes a few messages
+% to the output, describing its calculations. These are potentially
+% irritating, so you can turn them off with the \Lopt{quiet} option or
+% on with the \Lopt{verbose} option. The default is currently
+% \Lopt{verbose}, but this might change in future.
+% \end{description}
+%
+% \subsection{Changing options on the fly}
+% \label{s:changing-options}
+%
+% \begin{macro}{\TPoptions}
+% Each of the options mentioned in the previous section can be changed within the body of the text,
+% using the command |\TPoptions| with a comma-separated list of
+% keywords
+% \textit{$\langle$keyword$\rangle$}\texttt{=true} or
+% \textit{$\langle$keyword$\rangle$}\texttt{=false}.
+% The recognised keywords are `absolute', `overlay', `verbose',
+% `showboxes' and `showtext'. Thus the command
+% \begin{quote}
+% |\TPoptions{absolute=false , showboxes = true }|
+% \end{quote}
+% will switch off \Lopt{absolute} mode, and switch on \Lopt{showboxes}
+% mode. As this example illustrates, you can include whitespace in
+% the specification; the arguments \emph{must} be either \texttt{true}
+% or \texttt{false}, or else bad things will happen.
+%
+% You can switch between absolute and relative mode within a page. If
+% a document is to use absolute mode \emph{anywhere} within it,
+% however, it must be \emph{started} in absolute mode, with the
+% \Lopt{absolute} option to the |\usepackage| command.
+% \end{macro}
+%
+% \subsection{Configuration commands, and variants}
+%
+% \subsubsection{Setting up a positioning grid}
+%
% \DescribeMacro{\TPGrid}
% You will often wish to set up a grid on your page. Rather than
% calculate and specify the two modules explicitly, you can set up the
@@ -223,7 +301,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \cmd|\TPGrid[<x>,<y>]{<nhoriz>}{<nvert>}|
% \end{raggedright}\end{quote}
% If these are present, then the modules are set
-% up to leave a border of the given size around the grid. That is,
+% up to leave a border of the given size around the grid. That is,
% |\TPHorizModule| is set to be (\meta{paper
% width}${}-{}2$\meta{x})/\meta{nhoriz}, and similarly for
% |\TPVertModule|. Further, if the package was given
@@ -238,23 +316,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% leaving 40mm of a border on the right and left sides, and a 20mm
% border top and bottom.
%
-% You may give a optional argument to the \Lenv{textblock}
-% environment, specifying which point in the box
-% is to be placed at the specified point:
-% \begin{quote}
-% \begin{raggedright}
-% \cmd|\begin{textblock}{<hsize>}[<ho>,<vo>](<hpos>,<vpos>)|\\
-% text...\\
-% |\end{textblock}|
-% \end{raggedright}
-% \end{quote}
-% The coordinates \meta{ho} and \meta{vo} are fractions of the
-% width and height of the text box, respectively, and state that the
-% box is to be placed so that the reference
-% point (\meta{ho},\meta{vo}) within the box is to be placed at the point
-% (\meta{hpos},\meta{vpos}) on the page. The default specification is
-% [0,0], the top left of the box: [0,1] would be the bottom left, and
-% [0.5,0.5] the middle.
+% \subsubsection{Box margin}
%
% \DescribeMacro{\TPMargin}
% By default, the box that is positioned by the
@@ -276,6 +338,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% |\TPHorizModule| or |\TPVertModule|. The default behaviour is
% recovered by giving a \meta{size} of \texttt{0pt}.
%
+% \DescribeMacro{\TPMargin*}
% There is a starred variant of this command,
% |\TPMargin*{|\meta{size}|}|, where the argument must again be
% non-negative. In this case, the text block inside the box is set
@@ -283,18 +346,53 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% environment, but the coloured block is increased in size, such that
% there is again a margin of the specified size around the text block.
%
-% The \Lenv{textblock} environment will most often be used in
-% vertical mode. If it is called in horizontal (ie, paragraph) mode,
-% however, it will silently create a paragraph break by inserting a
-% |\par| command before the environment; it remains in vertical mode
-% after the environment is finished. It should have no further
-% effects on spacing, and if you find that it does, that's a bug. If
-% you try to use the environment when in maths mode, the package
-% objects (as it should!).
+% \subsubsection{Choosing the textblock reference point}
+%
+% You may give an optional argument to the \Lenv{textblock}
+% environment, specifying which point in the box
+% is to be placed at the specified point:
+% \begin{quote}
+% \begin{raggedright}
+% \cmd|\begin{textblock}{<hsize>}[<ho>,<vo>](<hpos>,<vpos>)|\\
+% text...\\
+% |\end{textblock}|
+% \end{raggedright}
+% \end{quote}
+% The coordinates \meta{ho} and \meta{vo} are fractions of the
+% width and height of the text box, respectively, and state that the
+% box is to be placed so that the reference
+% point (\meta{ho},\meta{vo}) within the box is to be placed at the point
+% (\meta{hpos},\meta{vpos}) on the page. The default specification is
+% [0,0], indicating the top left of the box; the argument [0,1] (for
+% example) would specify the bottom left, and [0.5,0.5] the middle.
+%
+% If the margin is non zero, then the position identified by
+% [\meta{ho},\meta{vo}] is slightly subtle:
+% \begin{itemize}
+% \item if the margin was specified with |\TPMargin|, then these
+% coordinates are relative to the box \emph{including} the margin;
+% \item if the margin was specified with |\TPMargin*|, then the
+% coordinates are relative to the contents of the \Lenv{textblock},
+% \emph{excluding} the margin.
+% \end{itemize}
+% For example, in the default case where the positioning argument is
+% [0,0], |\TPMargin| will cause the top-left of the surrounding box to
+% be at position (\meta{hpos},\meta{vpos}) (and the text to be
+% narrower), but |\TPMargin*| will cause the top left of the enclosed
+% text to be at (\meta{hpos},\meta{vpos}) (and the enclosing box to be
+% wider).
+%
+% 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 previous behaviour.
+%
+% \subsubsection{Specifying textblocks with absolute sizes}
+% \label{s:textblock-absolute}
%
% \DescribeEnv{textblock*}
% There is an alternative, starred, form of the \Lenv{textblock}
-% environment. In the argument to the \Lenv{textblock*} environment, the
+% environment. In the argument to the \Lenv{textblock*} environment, the
% block width, and the block position (but \emph{not} the
% specification of the block reference point) are given as absolute
% dimensions, rather than as numbers in units of the horizontal and
@@ -308,7 +406,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \end{quote}
% produces a textblock of the given size, where this time \meta{hsize},
% \meta{hpos} and \meta{vpos} are absolute dimensions, but \meta{ho}
-% and \meta{vo} are pure-number offsets (that is, fractions of the
+% and \meta{vo} are still pure-number offsets (that is, fractions of the
% width and height of the textblock), as above.
%
% Each \Lenv{textblock} environment takes up zero space on the page (which
@@ -335,7 +433,97 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% the width and location arguments to the (unstarred) \Lenv{textblock}
% environment.
%
-% \pstyle{Textpos} changes\marginpar{Figure and table environments}
+% \subsection{Package parameters}
+% \begin{raggedright}
+% \begin{description}
+% \item[\texttt{\bslash TPHorizModule}]
+% \DescribeMacro{\TPHorizModule}
+% The length unit which is used for the horizontal positioning and
+% size parameters of the \Lenv{textblock} environment. Set it using
+% the command \cmd|\setlength{\TPHorizModule}{<dimen>}| (or indeed
+% |\addtolength|).
+% The default is one sixteenth of the paper width.
+% \item[\texttt{\bslash TPVertModule}]
+% \DescribeMacro{\TPVertModule}
+% The length unit which is used for the vertical positioning and
+% size parameters of the \Lenv{textblock} environment. Set it using
+% the command \cmd|\setlength{\TPVertModule}{<dimen>}| (or |\addtolength|).
+% The default is one sixteenth of the paper height.
+% \item[\texttt{\bslash TPshowboxestrue} and \texttt{\bslash TPshowboxesfalse}]
+% You can control whether text blocks have the rule around them by
+% using the |\TPshowboxestrue| and |\TPshowboxesfalse| commands. The
+% \Lopt{showboxes} option simply sets the initial value of this switch.
+% \item[\texttt{\bslash TPboxrulesize}]
+% \DescribeMacro{\TPboxrulesize}
+% When you use the \Lopt{showboxes} option,
+% the lines drawn are of this width. If this too small to show up
+% when you are previewing your document, or if you simply like bold
+% 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.
+% \item[\texttt{\bslash textblocklabel}]
+% \DescribeMacro{\textblocklabel}
+% This may be used within any \Lenv{textblock}
+% environment. It is ignored, unless the \Lopt{noshowtext} option has
+% been specified, when it will be used to label the textblock it is
+% inside. Use: |\textblocklabel{Identifying text}|.
+% \item[\texttt{\bslash showtextsize}]
+% \DescribeMacro{\showtextsize}
+% When |\textblocklabel| is being
+% shown, the text appears in size |\showtextsize|, which is
+% defined by default to be |\normalsize|. If this is too
+% small, you may adjust it using |\newcommand{\showtextsize}{\large}|, or
+% whatever size you prefer.
+% \item[\texttt{\bslash textblockorigin}]
+% \DescribeMacro{\textblockorigin}
+% Sets the position of the top-left of the
+% printable area. See above.
+% \end{description}
+% \end{raggedright}
+%
+% \DescribeMacro{\textblockcolour}
+% The text blocks can be coloured in. If you load the \pstyle{color}
+% package, then the commands of that package, |\textcolor|,
+% |\pagecolor| and the like, should work as usual. The
+% \pstyle{textpos} package adds a new command,
+% |\textblockcolour|. If you give the command
+% \begin{quote}
+% |\textblockcolour{|\meta{colour}|}|
+% \end{quote}
+% all text blocks following will have their background filled with the
+% specified colour, which must be one of the standard colours or have
+% been declared in a
+% |\definecolor| declaration in the document preamble. This colour
+% may be overridden for individual text blocks by giving this command
+% within the \Lenv{textblock} environment. If you wish a block not to
+% have any background colour, you can suppress it, again for one block
+% at a time, with the command |\textblockcolour{}| inside the
+% \Lenv{textblock} environment.
+%
+% \DescribeMacro{\textblockrulecolour}
+% You can similarly change the colour of the borders around the text
+% block. If you give the command
+% \begin{quote}
+% |\textblockrulecolour{|\meta{colour}|}|
+% \end{quote}
+% then following text blocks will have their border in the given
+% colour, which must again be either one of the standard ones of
+% declared in the document preamble.
+%
+% \DescribeMacro{\textblockcolor}
+% For the benefit of those who observe Mr.\ Noah Webster's spelling
+% reforms, |\textblockcolor| is defined as a synonym for
+% |\textblockcolour|, but those who would condemn such anaemic half measures
+% \DescribeMacro{\tekstblokkulur}
+% can use |\tekstblokkulur| instead.
+% \DescribeMacro{\textblockrulecolor}
+% \DescribeMacro{\tekstblokroolkulur}
+% There are also the corresponding spelling-reform variants of
+% |\textblockrulecolour|.
+%
+% \subsection{Figure and table environments}
+%
+% \pstyle{Textpos} changes
% the behaviour of any \Lenv{figure} and \Lenv{table} environments
% \emph{within} instances of the \Lenv{textblock} environment, in such
% a way that the figure or table contents do not float away from the
@@ -389,133 +577,9 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% after the end of the current page (thanks to Matthias Gloede for
% this technique).
%
-% \DescribeMacro{\textblockcolour}
-% The text blocks can be coloured in. If you load the \pstyle{color}
-% package, then the commands of that package, |\textcolor|,
-% |\pagecolor| and the like, should work as usual. The
-% \pstyle{textpos} package adds a new command,
-% |\textblockcolour|. If you give the command
-% \begin{quote}
-% |\textblockcolour{|\meta{colour}|}|
-% \end{quote}
-% all text blocks following will have their background filled with the
-% specified colour, which must be one of the standard colours or have
-% been declared in a
-% |\definecolor| declaration in the document preamble. This colour
-% may be overridden for individual text blocks by giving this command
-% within the \Lenv{textblock} environment. If you wish a block not to
-% have any background colour, you can suppress it, again for one block
-% at a time, with the command |\textblockcolour{}| inside the
-% \Lenv{textblock} environment.
-%
-% \DescribeMacro{\textblockrulecolour}
-% You can similarly change the colour of the borders around the text
-% block. If you give the command
-% \begin{quote}
-% |\textblockrulecolour{|\meta{colour}|}|
-% \end{quote}
-% then following text blocks will have their border in the given
-% colour, which must again be either one of the standard ones of
-% declared in the document preamble.
-%
-% \DescribeMacro{\textblockcolor}
-% For the benefit of those who observe Webster's spelling
-% reforms, |\textblockcolor| is defined as a synonym for
-% |\textblockcolour|, but those who would condemn such anaemic half measures
-% \DescribeMacro{\tekstblokkulur}
-% can use |\tekstblokkulur| instead.
-% \DescribeMacro{\textblockrulecolor}
-% \DescribeMacro{\tekstblokroolkulur}
-% There are also the corresponding spelling-reform variants of
-% |\textblockrulecolour|.
-%
-% \subsection{Package options}
-% \label{packopts}
-%
-% There are several package options:
-% \begin{description}
-% \item[\Lopt{showboxes}]When you are laying things out, it can be
-% useful to have the boxes drawn in for you. This option draws a box
-% fitting closely round the set text. You can turn this on and off
-% within the file using the |\TPshowboxestrue| and |\TPshowboxesfalse|
-% commands.
-% \item[\Lopt{noshowtext}]This suppresses the display of the text in
-% each block (so it's not really usable without the \Lopt{showboxes}
-% option). The resulting box will be the correct size, but empty,
-% unless the |\textblocklabel| command has been given. This
-% 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.
-% \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
-% something
-% which \emph{obscures} the textblocks (for example, a block of opaque
-% colour), then the positioned textboxes disappear. In this case,
-% specify the option \Lopt{overlay}, to request that the positioned
-% blocks of text overlay any other page contents, rather
-% than being overlaid.
-% \item[\Lopt{verbose}, \Lopt{quiet}]The package writes a few messages
-% to the output, describing its calculations. These are potentially
-% irritating, so you can turn them off with the \Lopt{quiet} option or
-% on with the \Lopt{verbose} option. The default is currently
-% \Lopt{verbose}, but this might change in future.
-% \end{description}
-%
-% \subsection{Package parameters}
-% \begin{raggedright}
-% \begin{description}
-% \item[\texttt{\bslash TPHorizModule}]
-% \DescribeMacro{\TPHorizModule}
-% The length unit which is used for the horizontal positioning and
-% size parameters of the \Lenv{textblock} environment. Set it using
-% the command \cmd|\setlength{\TPHorizModule}{<dimen>}| (or indeed
-% |\addtolength|).
-% The default is one sixteenth of the paper width.
-% \item[\texttt{\bslash TPVertModule}]
-% \DescribeMacro{\TPVertModule}
-% The length unit which is used for the vertical positioning and
-% size parameters of the \Lenv{textblock} environment. Set it using
-% the command \cmd|\setlength{\TPVertModule}{<dimen>}| (or |\addtolength|).
-% The default is one sixteenth of the paper height.
-% \item[\texttt{\bslash TPshowboxestrue} and \texttt{\bslash TPshowboxesfalse}]
-% You can control whether text blocks have the rule around them by
-% using the |\TPshowboxestrue| and |\TPshowboxesfalse| commands. The
-% \Lopt{showboxes} option simply sets the initial value of this switch.
-% \item[\texttt{\bslash TPboxrulesize}]
-% \DescribeMacro{\TPboxrulesize}
-% When you use the \Lopt{showboxes} option,
-% the lines drawn are of this width. If this too small to show up
-% when you are previewing your document, or if you simply like bold
-% 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.
-% \item[\texttt{\bslash textblocklabel}]
-% \DescribeMacro{\textblocklabel}
-% This may be used within any \Lenv{textblock}
-% environment. It is ignored, unless the \Lopt{noshowtext} option has
-% been specified, when it will be used to label the textblock it is
-% inside. Use: |\textblocklabel{Identifying text}|.
-% \item[\texttt{\bslash showtextsize}]
-% \DescribeMacro{\showtextsize}
-% When |\textblocklabel| is being
-% shown, the text appears in size |\showtextsize|, which is
-% defined by default to be |\normalsize|. If this is too
-% small, you may adjust it using |\newcommand{\showtextsize}{\large}|, or
-% whatever size you prefer.
-% \item[\texttt{\bslash textblockorigin}]
-% \DescribeMacro{\textblockorigin}
-% Sets the position of the top-left of the
-% printable area. See above.
-% \end{description}
-% \end{raggedright}
-%
% \section{Notes}
% \subsection{Suggestions: Producing large-format posters}
-%
+%
% If you are producing a large-format poster, such as A0 size, you
% might want to use Gerlinde Kettl and Matthias Weiser's \cmd|a0poster|
% class, which painlessly deals with the miscellaneous hassles of
@@ -537,7 +601,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% You can sometimes get rather puzzling behaviour when you use
% |\newpage| in absolute mode.
%
-% When using the \Lopt{absolute} option, you most typically
+% When using the \Lopt{absolute} option, you will often
% have all of the text on your page inside \Lenv{textblock}
% environments. In this case, \TeX\ does not believe that you have
% anything on the page at all, and so if you give a |\newpage| command
@@ -545,7 +609,8 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% poster space allocation at your conference, or you are filling out a
% form), \TeX\ thinks it is redundant, and ignores it, so that all
% your \Lenv{textblock} environments end up on just one page. To work
-% round this, use |\null\newpage| instead: this is enough to persuade
+% round this, use |\null\newpage| instead: the |\null| (which produces
+% a zero-width box) is enough to persuade
% \TeX\ to respect the page-break.
%
% This happens for the same reason that, also quite surprisingly, two
@@ -555,7 +620,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \label{s:interactions}
%
% Textpos does not appear to get on terribly well with
-% Prosper\marginpar{textpos \& prosper} (a
+% 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}
@@ -568,9 +633,11 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% relative mode as long as the \Lenv{textblock} environment is the
% first thing on the slide.
% \marginpar{\dots \& beamer}
-% The same appears to be true with the beamer package in some circumstances,
-% though Marius Arenz reports that Textpos works OK with beamer,
-% as long as you supply the \Lopt{overlay} and \Lopt{absolute} options.
+% 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)
@@ -605,15 +672,180 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% There is a vivid example of using Textpos along with Rolf's
% \texttt{eso-pic} package and the \texttt{calc} package on the
% Textpos web pages, at
-% \url{http://purl.org/nxg/dist/textpos}.
+% \url{http://purl.org/nxg/dist/textpos}, and an example of how to
+% create a grid with TikZ at \url{http://tex.stackexchange.com/a/85088/96}.
%
% Finally, Robert Wenner reported a problem when using Textpos along
% with the \texttt{texdraw} package\marginpar{textpos \& texdraw}, with
-% |\move(0,0)| apparently
+% |\move(0,0)| apparently
% making a difference when it should be a no-op. I haven't worked out
% what's going on here, and further reports of this, ideally with a
% minimal example, would be most welcome.
%
+% \subsection{Troubleshooting}
+%
+% \begin{description}
+% \item[Switching to absolute mode with \texttt{$\backslash$TPoptions} doesn't work]
+% In order for the \Lopt{absolute} mode to work anywhere, the document
+% has to be \emph{started} in absolute mode (see Sect.~\ref{s:changing-options}).
+% This is a hard-to-avoid limitation of the way that this mode is implemented.
+%
+% \item[Error: `Missing number, treated as zero']
+% If you give absolute values (that is, values with units) to the
+% \Lenv{textblock} environment, then you will be confronted with the
+% rather opaque error `Missing number, treated as zero'. Remember
+% that the \Lenv{textblock} environment requires relative sizes, and
+% the \Lenv{textblock*} environment requires sizes with units; see
+% Sect.~\ref{s:textblock-absolute}. You get a similar error message
+% if you give relative sizes to the \Lenv{textblock*} environment.
+%
+% \end{description}
+%
+% \section{History}
+% \iffalse @RELEASENOTES@ \fi
+% \begin{description}
+% \item[\textbf{1.8, 2016 June 5}]\relax
+% \begin{itemize}
+% \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
+% 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.
+% \end{itemize}
+%
+% \item[1.7j, 2014 January 3]\relax
+% Re-released under the LPPL.
+%
+% \item[1.7i, 2012 November 10]\relax
+% Bugfix: further change to the way the {color} package is loaded
+% (fixes issue 2); now finally fixed?
+%
+% \item[1.7h, 2012 June 1]\relax
+% Bugfix: further change to the way the {color} package is loaded.
+% Some documentation tweaks.
+% Pointers to bitbucket repository.
+%
+% \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.
+% Thanks to Joseph Wright for the bugreport.
+% Also adjusted documentation of reference points.
+%
+% \item[1.7f, 2009 May 28]\relax
+% The change in behaviour introduced in v1.7e is now documented (it
+% was unspecified before, and 1.7e didn't commit itself one way or the
+% other).
+%
+% \item[1.7e, 2009 March 29]\relax
+% Daniel Richard G noted that the order in which textblock contents
+% was laid down on the page was counter-intuitive, since one would
+% expect that later environments go 'on top of' earlier ones. This
+% order was unspecified before this version, but I've changed this,
+% satisfying a principle of least surprise (later ones now go 'on
+% top').
+%
+% \item[1.7d, 2007 March 30]\relax
+% Axel Sommerfeldt suggested a further alternative approach, even more
+% lightweight, and I incorporated a version of that.
+%
+% \item[1.7c, 2007 March 29]\relax
+% Giovanni Radilla reported a problem with captions, which meant that the
+% captions weren't appearing properly in the list of figures. Dan
+% Luecking and Axel Sommerfeldt analysed the problem precisely, and the
+% latter provided code which I've incorporated in this fix.
+%
+% \item[1.7b, 2007 March 21]\relax
+% 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.
+% 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
+% failing. Textpos will give you a warning in this case, reminding you
+% 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
+% display of the rules around the text blocks.
+%
+% \item[1.6b, 2006 August 10]\relax
+% Minor documentation fixes
+%
+% \item[1.6a, 2005 October 13]\relax
+% The overriding of the figure and table environments now also works
+% 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|
+% environments, to avoid their surprising and undesirable interaction
+% with |{textblock|.
+%
+% \item[1.5b, 2005 June 13]\relax
+% The 1.5 release broke the textblock environment's optional
+% argument, controlling the position of the reference point within the
+% block. Fixed.
+%
+% \item[1.5a, 2005 March 26]\relax
+% Documentation fixes: added a section on the
+% interaction between absolute mode and LaTeX's |{\newpage|
+% command.
+%
+% \item[\textbf{1.5, 2005 March 23}]\relax
+% 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.
+%
+% \item[\textbf{1.4, 2003 September 7}]\relax
+% Changes in the handling of vertical spacing; inconsistent in some
+% circumstances before. Slight (consequent) change to the algorithm
+% which ensures that material is output in absolute mode even when the
+% page is otherwise empty. See README for details. Version 1.3a will
+% remain available for some time in case these fixes break things.
+%
+% \item[1.3a, 2003 June 24]\relax
+% Added the |{\textblockcolour| command, to set
+% the background colour of text blocks
+%
+% \item[\textbf{1.3, 2003 June 24}]\relax
+% (there was a release 1.3, but it was broken, and immediately
+% replaced by 1.3a)
+%
+% \item[1.2b, 2002 July 1]\relax
+% Works around a bug present in at least one package,
+% which leaves box255 holding an hbox at the wrong moment
+%
+% \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
+% expressions in the parameters to the unstarred
+% |{{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
+%
+% \item[Version 1.1]\relax
+% Released in 1999
+%
+% \end{description}
+%
% \section{Credits}
%
% Olaf Maibaum, \texttt{Olaf.Maibaum@informatik.uni-oldenburg.de},
@@ -648,12 +880,14 @@ 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 bugreports and other suggestions to
+% Thanks also for general bugreports and other suggestions to
% Jozef Bednarcik,
-% Daniel Richard G,
+% Richard G Daniel,
% Wolfgang Fleischer,
% Greg Petriccione,
% Giovanni Radilla,
+% Richard Schreiber,
+% Brian Stephanik,
% Robert Whittaker,
% Joseph Wright,
% and Joachim Wuttke,
@@ -703,13 +937,15 @@ located at that point, rather than the top-left corner.
% \StopEventually{}
% \section{Implementation}
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
%
%
% \subsection{Options}
%
% Allow the user to switch on display of boxes round the text.
% \begin{macrocode}
-%<*package>
\newif\ifTPshowboxes
\TPshowboxesfalse
\DeclareOption{showboxes}{\TPshowboxestrue}
@@ -721,13 +957,15 @@ located at that point, rather than the top-left corner.
\DeclareOption{noshowtext}{\TP@showtextfalse}
% \end{macrocode}
%
-% User may declare that the positions given to the |\textblock|
+% The user may declare that the positions given to the |\textblock|
% environment are to be absolute on the page, rather than relative to
-% the current position.
+% the current position. Relative mode is, and will remain, the
+% default, so the \Lopt{relative} option is redundant, but is here for symmetry.
% \begin{macrocode}
\newif\ifTP@abspos
\TP@absposfalse
\DeclareOption{absolute}{\TP@abspostrue}
+\DeclareOption{relative}{\TP@absposfalse}
% \end{macrocode}
%
% When using the absolute-position mode, the holdbox is placed into
@@ -769,6 +1007,18 @@ located at that point, rather than the top-left corner.
\ifTP@abspos
\RequirePackage{everyshi}
\fi
+\RequirePackage{keyval}
+% \end{macrocode}
+%
+% \subsection{Changing options within the text}
+%
+% \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}
+\def\TPoptions{\setkeys{tp}}
% \end{macrocode}
%
% \subsection{Other initialisation}
@@ -1030,6 +1280,7 @@ located at that point, rather than the top-left corner.
\let\textblockrulecolor\textblockrulecolour
\let\tekstblokroolkulur\textblockrulecolour
% \end{macrocode}
+% \end{macro}
%
% We don't want to create a dependency on the \pstyle{color} package,
% so we shouldn't fail if that package isn't loaded. Don't check that
@@ -1047,7 +1298,7 @@ located at that point, rather than the top-left corner.
\def\color@block##1##2##3{}%
\globaldefs=0 }{}%
\global\let\TP@checkdummycolorpackage\relax % don't come here again
-}
+}
% \end{macrocode}
%
% \begin{macro}{\textblock}
@@ -1069,7 +1320,7 @@ located at that point, rather than the top-left corner.
{You cannot use textblock in maths mode}
{You may use the textblock environment only in \MessageBreak
vertical mode or horizontal mode (when it triggers a\MessageBreak
- new paragraph). You cannot use it in maths mode.}
+ new paragraph). You cannot use it in maths mode.}
\else % in horizontal mode
\par % force us back into vertical mode
\fi
@@ -1080,18 +1331,18 @@ located at that point, rather than the top-left corner.
% \end{macro}
%
% \begin{macro}{\textblock*}
-% |\begin{textblock*}| is a variant of |\begin{textblock}| which takes
-% absolute values for its arguments. It uses |\setlength| throughout,
+% |\begin{textblock*}| is a variant of |\begin{textblock}| which takes
+% absolute values for its arguments. It uses |\setlength| throughout,
% and is therefore compatible with the \pstyle{calc} package.
% \changes{1.2a}{2002/04/28}{Added textblock* env}
% \begin{macrocode}
\def\TP@textblockstar#1{%
\setlength{\@tempdima}{#1}
- \ifvmode\else
+ \ifvmode\else
\PackageWarning{textpos}{environment textblock* not in vertical mode.
\MessageBreak
Environment textblock* should not have any text\MessageBreak
- or printable material appearing before it.\MessageBreak
+ or printable material appearing before it.\MessageBreak
Alignment may work out wrongly.}%
\par % force us back into vertical mode
\fi
@@ -1125,27 +1376,36 @@ located at that point, rather than the top-left corner.
% \end{macrocode}
%
% Start the |\TP@textbox|, which contains the contents of the textblock.
+% Below, let the `textblock' refer to the block of text inside this
+% box, and `specwidth' the width provided as argument to the
+% \Lenv{textblock} environment.
% \begin{macrocode}
\setbox\TP@textbox=\vbox\bgroup
% \end{macrocode}
% If we're showing boxes, then draw a rule here
% \begin{macrocode}
\ifTPshowboxes
- \TP@checkdummycolorpackage
+ \TP@checkdummycolorpackage
{\color{\TP@rulecolour}\hrule height0pt depth \TPboxrulesize }%
\vskip-\TPboxrulesize
\fi
% \end{macrocode}
-% Set the |\hsize| to the temporary dimension set in |\textblock|
-% above, and set the other \LaTeX{} parameters to match. If
-% |\TP@margin| is positive, then the the value in |\@tempdima| is to
-% be the width of the box including its left and right margins; if
-% |\TP@margin| is negative, then the box should be bigger by twice the
-% absolute value of this margin. In both the cases where |\TP@margin|
-% is non-zero, then (a) increase the left- and rightskip by the absolute value
-% of the margin, to set the text in a block which is that much smaller
-% than the enclosing box, and (b) include the same amount of vertical
-% skip before and after the text block.
+% Cases:
+% \begin{itemize}
+% \item When |\TP@margin| is zero, then `specwidth', the width of the
+% `textblock', and the actual width of |\TP@textbox|, are all equal.
+% \item When |\TP@margin| is positive, then `specwidth' is the width
+% of |\TP@textbox|, and the `textblock' is narrower (and shorter) than
+% this by a margin |\TP@margin| all round (|\hsize| is `specwidth'
+% minus 2|\TP@margin|).
+% \item When |\TP@margin| is negative, then `specwidth' is the width
+% of the `textblock' (|\hsize| is `specwidth'), and |\TP@textbox| is
+% wider than this by minus |\TP@margin|.
+% \end{itemize}
+% Here, when |\TP@margin| is non-zero, we set the `textblock' inside a
+% box of appropriate |\hsize|, and put that inside the |\TP@textbox|,
+% spaced appropriately (this seems more robust than using
+% left- and rightskip, which some environment redefine).
% \changes{v1.7b}{2007/03/21}{Fixed lists inside boxes with non-zero margins}
% \begin{macrocode}
\ifdim\TP@margin = 0pt
@@ -1169,7 +1429,7 @@ located at that point, rather than the top-left corner.
% \end{macro}
%
% \begin{macro}{\endtextblock}
-% \begin{macro}{\endtextblock*}
+% \begin{macro}{\endtextblock*}
% We have two slight variants of the end-block code, depending on
% whether we're in a |{textblock}| or a |{textblock*}| environment.
% The |\if@tempswa| set here is tested below, in |\TP@endtextblock|.
@@ -1203,11 +1463,11 @@ located at that point, rather than the top-left corner.
\relax
\else
\egroup % end of inner vbox
- \hskip\TP@absmargin
+ \hskip\TP@absmargin % (just \hfil would work here, too)
\egroup % end of inner hbox
- \vskip \TP@absmargin
+ \vskip\TP@absmargin
\fi
- \ifTPshowboxes
+ \ifTPshowboxes
\vskip-\TPboxrulesize
{\color{\TP@rulecolour}\hrule depth 0pt height \TPboxrulesize}%
\fi
@@ -1245,12 +1505,12 @@ located at that point, rather than the top-left corner.
% fractions of the width and height, respectively, of the text block.
% Parameters~3 and~4 indicate where the reference point will be
% positioned. In the unstarred case (|\if@tempswa| true), these are
-% pure numbers, indicating dimensions in units of the |\TPHorizModule|
-% and |\TPVertModule| respectively; in the starred case (|\if@tempswa|
+% pure numbers, indicating dimensions in units of the |\TPHorizModule|
+% and |\TPVertModule| respectively; in the starred case (|\if@tempswa|
% false), they're dimensions.
%
% Position the box |\TP@textbox|, which was build up between
-% |\TP@textblock| and |\endtextblock|, at (x,y)=|(#3,#4)|.
+% |\TP@textblock| and |\endtextblock|, at (x,y)=|(#3,#4)|.
% The point that is so positioned is at |(#1\wd,#2\ht)| of
% |\TP@textbox|, so that |(#1,#2)| =(0,0) means top left.
%
@@ -1260,35 +1520,52 @@ located at that point, rather than the top-left corner.
% Below, |\@tempdima| and |\@tempdimb| are the $x$- and
% $y$-coordinates of the framebox.
% \changes{v1.5b}{2005/06/13}{Fixed control of reference point, broken in 1.5}
+% First, we set these coordinates to be |(#3,#4)|.
% \begin{macrocode}
\def\TP@endtextblock#1#2#3#4{%
\if@tempswa % modular/unstarred endtextblock
\@tempdima=#3\TPHorizModule
- \@tempdimb=#4\TPVertModule
+ \@tempdimb=#4\TPVertModule
\else % absolute/starred endtextblock
\setlength{\@tempdima}{#3}
\setlength{\@tempdimb}{#4}
\fi
+% \end{macrocode}
+% Next, we adjust them so that the position |(#1,#2)| is at this
+% coordinate. The |\TP@textbox| is the box including the lines
+% \emph{and} margin.
+%
+% Case 1: |\TP@margin| is negative: the `textblock' is `specwidth'
+% wide, and box |\TP@textbox| is wider and deeper than
+% the `specwidth', by |\TP@margin| all round; we want the position
+% |(#1,#2)| to be fractions of the textblock size, not |\TP@textbox|
+% \begin{macrocode}
\ifdim\TP@margin < 0pt
\advance\@tempdima \TP@margin
\advance\@tempdimb \TP@margin
- % #1,#2 are proportions of \TP@textbox size
- \@tempdimc=-#1\wd\TP@textbox
- \advance\@tempdima\@tempdimc
- \@tempdimc=-#2\ht\TP@textbox
- \advance\@tempdimb\@tempdimc
- \else
- % \TP@margin is positive
- % #1,#2 are proportions of \TP@framebox size = \TP@textbox+2\TP@margin
\@tempdimc=\wd\TP@textbox
- \advance\@tempdimc 2\TP@margin
- \@tempdimc=#1\@tempdimc
+ \advance\@tempdimc 2\TP@margin % now \@tempdimc is width of textblock
+ \multiply\@tempdimc #1
\advance\@tempdima -\@tempdimc
\@tempdimc=\ht\TP@textbox
- \advance\@tempdimc 2\TP@margin
- \@tempdimc=#2\@tempdimc
+ \advance\@tempdimc 2\TP@margin % now \@tempdimc is height of textblock
+ \multiply\@tempdimc #2
+ \advance\@tempdimb -\@tempdimc
+% \end{macrocode}
+% Case 2: |\TP@margin| is positive or zero: the |\TP@textbox| is
+% `specwidth' in width; the text inside the box is
+% narrower than this width; the coordinates |(#1,#2)| are
+% fractions of |\TP@textbox| size (ie, `specwidth').
+% \begin{macrocode}
+ \else
+ \@tempdimc=#1\wd\TP@textbox
+ \advance\@tempdima -\@tempdimc
+ \@tempdimc=#2\ht\TP@textbox
\advance\@tempdimb -\@tempdimc
\fi
+% \end{macrocode}
+% FInally, shift the origin if we're in absolute-positioning mode.
+% \begin{macrocode}
\ifTP@abspos
\advance\@tempdima by \TP@ox
\advance\@tempdimb by \TP@oy
@@ -1319,7 +1596,7 @@ located at that point, rather than the top-left corner.
\box\TP@textbox
\else
\vbox to\ht\TP@textbox{%
- \ifTPshowboxes
+ \ifTPshowboxes
{\color{\TP@rulecolour}\hrule depth 0pt height \TPboxrulesize \vskip-\TPboxrulesize}%
\fi
\vskip\smallskipamount
@@ -1334,7 +1611,7 @@ located at that point, rather than the top-left corner.
\hss
}%
\vss
- \ifTPshowboxes
+ \ifTPshowboxes
\vskip -\TPboxrulesize
{\color{\TP@rulecolour}\hrule depth 0pt height \TPboxrulesize}%
\fi
@@ -1355,7 +1632,7 @@ located at that point, rather than the top-left corner.
% textblock environments go `on top of' earlier ones, which is
% generally more intuitive. I \emph{think} this would be true for all
% drivers. Does this have some interaction with the \Lopt{overlay}
-% option, and if so, should it be coupled to that. I haven't
+% option, and if so, should it be coupled to that? I haven't
% documented this one way or the other, and I think that ambiguity is
% probably useful.
% \begin{macrocode}