summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/textpos/textpos.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/textpos/textpos.dtx')
-rw-r--r--Master/texmf-dist/source/latex/textpos/textpos.dtx152
1 files changed, 98 insertions, 54 deletions
diff --git a/Master/texmf-dist/source/latex/textpos/textpos.dtx b/Master/texmf-dist/source/latex/textpos/textpos.dtx
index 7b43236da42..b8a4fd10cf2 100644
--- a/Master/texmf-dist/source/latex/textpos/textpos.dtx
+++ b/Master/texmf-dist/source/latex/textpos/textpos.dtx
@@ -9,7 +9,7 @@
%% conditions of the LaTeX Project Public License, either version 1.3
%% of this license or (at your option) any later version.
%% The latest version of this license is in
-%% http://www.latex-project.org/lppl.txt
+%% https://www.latex-project.org/lppl.txt
%% and version 1.3 or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
@@ -25,21 +25,19 @@
%%
%% See the file LICENCE for a copy of the LPPL.
%%
-%% Mercurial ident: c834991c867a (1.10+1), 2020-09-26 17:44 +0100
+%% Mercurial ident: 1.10.1 (@VCSINFO)
%%
%<+package>\NeedsTeXFormat{LaTeX2e}
-%<+package>\ProvidesPackage{textpos}[2020/09/26 v1.10]
-%<+package>\typeout{Package: textpos 2020/09/26 1.10, absolute positioning of text on the page}
+%<+package>\ProvidesPackage{textpos}[2022/07/23 v1.10.1]
%
%<*driver>
\documentclass{ltxdoc}
\title{Textpos: absolute positioning of text on the page}
\author{Norman Gray\\(\texttt{https://nxg.me.uk})}
-\date{Version 1.10, 2020 September 26\footnote{Mercurial ident: c834991c867a (1.10+1), 2020-09-26 17:44 +0100.
-This software is copyright, 1999-2020 Norman Gray.
+\date{Version 1.10.1, 2022 July 23\footnote{This software is copyright, 1999-2020 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}.}}
+The latest version of this license is at \texttt{https://www.latex-project.org/lppl.txt}.}}
\newcommand\Lopt[1]{\textsf {\small [#1]}}
\newcommand\file[1]{\texttt {#1}}
\newcommand\Lcount[1]{\textsl{\small#1}}
@@ -122,8 +120,8 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \url{https://www.ctan.org/pkg/everyshi}.
%
% The canonical CTAN URL for Textpos is \url{https://ctan.org/pkg/textpos}.
-% Textpos has a home page at \url{http://purl.org/nxg/dist/textpos}.
-% The source is held at \url{https://code.nxg.name/nxg/tex/textpos}.
+% Textpos has a home page at \url{https://purl.org/nxg/dist/textpos}.
+% The source is held at \url{https://heptapod.host/nxg/textpos}.
% \iffalse and there is an issues list there, for bug reports.\fi
% Code
% contributions or fixes are welcome, but note that I feel that
@@ -135,7 +133,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% An article describing Textpos appeared in TUGboat in 2002:
% 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{https://www.tug.org/TUGboat/tb23-3-4/tb75gray.pdf}.
%
% \section{Description}
%
@@ -276,19 +274,24 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% 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.
+% \item[\Lopt{discardcontent}] This discards box content in a way
+% which might make the |{textblock}| content compatible with TikZ.
+% This behaviour is still somewhat experimental (since v1.9), should
+% probably be used only rarely, and is more fully discussed in Sect.~\ref{s:absrelmode}.
% \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,
+% Each of the options mentioned in the previous section can be changed
+% within the body of the text\footnote{Available since v1.8},
% 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
+% The recognised keywords are `absolute', `verbose',
+% `showboxes', `showtext', and `discardcontent'. Thus the command
% \begin{quote}
% |\TPoptions{absolute=false , showboxes = true }|
% \end{quote}
@@ -301,6 +304,12 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% 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.
+%
+% Note that (at least in v1.10), the presence or absence of the \texttt{overlay}
+% package option takes effect at the time the package is loaded, and
+% it cannot be changed thereafter. It's not impossible that this would
+% change in future, but I have no current plans to implement that.
+%
% \end{macro}
%
% \subsection{Configuration commands, and variants}
@@ -639,7 +648,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% printing to a large-format postscript printer.
%
% I have a collection of suggestions for producing such posters at
-% \url{http://purl.org/nxg/note/posters}.
+% \url{https://purl.org/nxg/note/posters}.
%
% The text on a large poster will typically use a very large font. It
% can be a hassle to create (or have dvips create) these fonts, and
@@ -667,7 +676,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \TeX\ to respect the page-break.
%
% This happens for the same reason that, also quite surprisingly, two
-% |\newline| commands in a row do not produce a blank page.
+% |\newpage| commands in a row do not produce a blank page.
%
% \subsection{Absolute or relative mode?}
% \label{s:absrelmode}
@@ -698,9 +707,9 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% |{textblock}| boxes, in a way which should make it compatible with
% TikZ. This option is \emph{experimental} in Textpos v1.9, and may
% change or disappear in future versions -- the author would be
-% particular interested to get feedback regarding this
+% particular interested in feedback regarding this
% option.\footnote{My understanding of the problem here is derived from an excellent Stackoverflow answer
-% by `JLDiaz' \url{http://tex.stackexchange.com/a/66853}, a Textpos
+% by `JLDiaz' \url{https://tex.stackexchange.com/a/66853}, a Textpos
% bugreport by Michael H\"upkes, and a discussion on the PGF bugparade
% \url{https://github.com/pgf-tikz/pgf/issues/393}.}
%
@@ -740,16 +749,18 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% for the initial report, and to Heiko Oberdiek for one of the
% workarounds}.
%
+% In older versions of the beamer package,\marginpar{textpos \&
+% beamer} there were at least some cases where beamer's background
+% frame would overlay textpos material. It appears this is no longer
+% the case (at least with beamer 3.59), and the packages are fully
+% compatible. But if you see a problem here you should use the
+% \Lopt{overlay} option to tell textpos to delay its
+% work.\footnote{Thanks to Marius Arenz for the explanation here, and
+% to Matthias Braun for reporting that the problem has gone away.}
+%
% \subsection{Other interactions}
% \label{s:interactions}
%
-% The Beamer package's\marginpar{textpos \& beamer}
-% background frame overlays the textpos material, unless the
-% \Lopt{overlay} option is used to tell textpos to delay it.
-% Therefore, you should use the \Lopt{overlay,absolute}
-% options with Beamer.\footnote{Thanks to Marius Arenz for
-% the explanation here.}
-%
% Gabriel Zachmann suggested having Textpos put a grid on the
% page\marginpar{page grid}, so
% that it is easier to work out \Lenv{textblock} coordinates. I have
@@ -759,8 +770,8 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \texttt{eso-pic} package. 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}, and an example of how to
-% create a grid with TikZ at \url{http://tex.stackexchange.com/a/85088/96}.
+% \url{https://heptapod.host/nxg/textpos}, and an example of how to
+% create a grid with TikZ at \url{https://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
@@ -791,6 +802,19 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \section{History}
% \iffalse @RELEASENOTES@ \fi
% \begin{description}
+% \item[\textbf{Release 1.10.1, 2022 July 23}]\relax
+%
+% \begin{itemize}
+% \item Mildly improve the handling of a missing |{color}| package.
+% \item The |overlay| option isn't changeable in
+% |\TPoptions|; attempting to do so now produces a
+% warning.
+% \item Various mild documentation improvements.
+% \item The code repository has moved again, to
+% heptapod\footnote{\url{https://heptapod.host/nxg/textpos}}.
+% \end{itemize}
+%
+%
% \item[\textbf{1.10, 2020 September 26}]\relax
%
% \begin{itemize}
@@ -986,8 +1010,7 @@ The latest version of this license is at \texttt{http://www.latex-project.org/lp
% \item[Version 1.1]\relax
% Released in 1999
%
-% \end{description}
-%
+% \end{description}%
% \section{Credits}
%
% Olaf Maibaum, \texttt{Olaf.Maibaum@informatik.uni-oldenburg.de},
@@ -1158,11 +1181,17 @@ located at that point, rather than the top-left corner.
%
% This code aims to be compatible with both \LaTeXiie\ and \LaTeX3. This
% means that it must use the \pstyle{everyshi} package in the \LaTeXiie\
-% case, and can use the corresponding built-in \LaTeX3 mechanism otherwise.
-% For documentation on the latter, see the `ltshipout' package documentation.
+% case, and must use the corresponding built-in \LaTeX3 mechanism otherwise.
+% For documentation on the latter, see the `ltshipout' package
+% documentation.\footnote{Thanks to Ulrike Fischer for detailed advice
+% on the steps to take here}
%
% There are a couple of places in where we must switch behaviour.
% Conditionalise them with a single switch.
+% Note that we can't use the (apparently preferable)
+% |\IfFormatAtLeastTF| command to do this test: we want to continue to
+% work even when we're using a \LaTeX\ which is too old for this
+% command to be defined.
% \begin{macrocode}
\newif\ifTP@Liii
\@ifl@t@r\fmtversion{2020/10/01}\TP@Liiitrue\TP@Liiifalse
@@ -1171,13 +1200,11 @@ located at that point, rather than the top-left corner.
%
% \subsection{Required Packages}
%
-% To manipulate |\box255| when using \LaTeXiie,
-% this package needs the package
-% \pstyle{everyshi}, which provides the command |\EveryShipout|.
+% To manipulate |\box255| when using \LaTeXiie (and only in that case),
+% this package needs the package \pstyle{everyshi},
+% which provides the command |\EveryShipout|.
% \begin{macrocode}
-\ifTP@Liii
- % avoid everyshi package
-\else
+\ifTP@Liii\else
\ifTP@abspos
\RequirePackage{everyshi}
\fi
@@ -1188,14 +1215,21 @@ located at that point, rather than the top-left corner.
% \subsection{Changing options within the text}
%
% Define a |\TPoptions| macro which supports constructions like |\TPoptions{verbose=true}|.
+% \iffalse This was I think prompted by the SE question https://tex.stackexchange.com/questions/172902/
+% It was a comment to question
+% https://tex.stackexchange.com/questions/248504/ that made me realise
+% the overlay option wasn't changeable here.
+% \fi
% \begin{macrocode}
\define@key{tp}{absolute}{\csname TP@abspos#1\endcsname}
-\define@key{tp}{overlay}{\csname TP@overlay#1\endcsname}
+\define@key{tp}{overlay}{\PackageWarning{textpos}{The overlay option
+ to TPoptions is not implemented and has been ignored}}
\define@key{tp}{verbose}{\csname TP@chatter#1\endcsname}
\define@key{tp}{showboxes}{\csname TPshowboxes#1\endcsname}
\define@key{tp}{showtext}{\csname TP@showtext#1\endcsname}
-\define@key{tp}{discardcontent}{\csname @tempswa#1\endcsname
- \if@tempswa\TP@displayholdboxfalse\else\TP@displayholdboxtrue\fi}
+\define@key{tp}{discardcontent}{%
+ \csname @tempswa#1\endcsname
+ \if@tempswa\TP@displayholdboxfalse\else\TP@displayholdboxtrue\fi}
\def\TPoptions{\setkeys{tp}}
% \end{macrocode}
%
@@ -1507,18 +1541,26 @@ located at that point, rather than the top-left corner.
% here, since the document, or another package, may load the color
% package later. Instead, define a command which will create dummy
% no-op definitions for the package commands we use, and invoke this
-% just before we invoke any of the color package's commands (see above
-% for usage).
+% at the beginning of the document, unless the color package is in
+% fact loaded.
+% Note that the |\@ifundefined{color}| test is redundant in the
+% \LaTeX3 case; we retain it for the \LaTeXiie\ case.
% \begin{macrocode}
\gdef\TP@color[#1]#2{}
-\def\TP@checkdummycolorpackage{%
- \@ifundefined{color}%
+\def\TP@dummycolorpackage{
+ \@ifundefined{color}
{\globaldefs=1
- \DeclareRobustCommand\color[2][]{}%
- \def\color@block##1##2##3{}%
- \globaldefs=0 }{}%
- \global\let\TP@checkdummycolorpackage\relax % don't come here again
+ \DeclareRobustCommand\color[2][]{}
+ \def\color@block##1##2##3{}
+ \globaldefs=0 }
+ {}
}
+\ifTP@Liii
+ \AddToHook{env/document/before}{\TP@dummycolorpackage}
+ \AddToHook{file/color.sty/after}{\let\TP@dummycolorpackage\relax}
+\else
+ \AtBeginDocument{\TP@dummycolorpackage}
+\fi
% \end{macrocode}
%
% Default the reference position, and support the command to override it.
@@ -1611,7 +1653,6 @@ located at that point, rather than the top-left corner.
% If we're showing boxes, then draw a rule here
% \begin{macrocode}
\ifTPshowboxes
- \TP@checkdummycolorpackage
{\color{\TP@rulecolour}\hrule height0pt depth \TPboxrulesize }%
\vskip-\TPboxrulesize
\fi
@@ -1785,8 +1826,7 @@ located at that point, rather than the top-left corner.
\setbox0=\vbox to 0pt{\vskip\@tempdimb
\hbox to 0pt{\hskip\@tempdima
\ifx\TP@blockcolour\@empty \else
- {\TP@checkdummycolorpackage
- \color{\TP@blockcolour}%
+ {\color{\TP@blockcolour}%
\color@block{\wd\TP@textbox}{\ht\TP@textbox}{\dp\TP@textbox}%
}%
\fi
@@ -1899,8 +1939,9 @@ located at that point, rather than the top-left corner.
% \end{macrocode}
%
% Second, the \LaTeXiie\ case: use the macros provided by the \pstyle{everyshi} package.
-% We set up the output routine with |\EveryShipout|, and . Respect the
-% \Lopt{overlay} option by putting the |\TP@holdbox| contents
+% We set up the output routine with |\EveryShipout|.
+%
+% Respect the \Lopt{overlay} option by putting the |\TP@holdbox| contents
% \emph{after} the |\@cclv| contents, putting the latter into a size-0
% box (could this cause a problem with spacing? I don't think so, at
% this stage).
@@ -1928,9 +1969,12 @@ located at that point, rather than the top-left corner.
}%
\fi}%
\fi
- \fi
+ \fi % ifTP@Liii
+% \end{macrocode}
+% Finally, set the textblockorigin to the (default) upper-left corner of the paper.
+% \begin{macrocode}
\textblockorigin{0pt}{0pt}%
-\fi
+\fi % ifTP@abspos
% \end{macrocode}
% Done!
% \begin{macrocode}