summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pst-abspos/pst-abspos-doc.tex
blob: 057e61b95d532f64cd9841c79a969d0a5ec1a3ac (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
%% $Id: pst-abspos-doc.tex 135 2009-09-27 12:33:57Z herbert $
\documentclass[11pt,english,BCOR10mm,DIV12,bibliography=totoc,parskip=false,smallheadings
    headexclude,footexclude,oneside]{pst-doc}
\usepackage[utf8]{inputenc}
\usepackage[absolute]{pst-abspos}

\let\pstFV\fileversion
\lstset{pos=l,wide=false,language=PSTricks,
    morekeywords={multidipole,parallel},basicstyle=\footnotesize\ttfamily}
%
\definecolor{myGray}{rgb}{0.9,0.9,0.9}
\newcommand\x{blah blub laber text nonsense }
\begin{document}

\title{\texttt{pst-abspos}}
\subtitle{A PSTricks package for using abolute or relative coordinates of a page; v.\pstFV}
\author{Herbert Vo\ss}
\docauthor{}
\date{\today}
\maketitle

\tableofcontents

\newpage
\pstSetAbsoluteOrigin
A Nonsense text line with \verb|\noindent|.

\section{Introduction}
\pstPutAbs[position=rb,unit=1pt](0.95\paperwidth,-10){\texttt{pst-abspos}}
The package \LPack{pst-abspos} allows absolute positioning of objects. In \TeX{} the
actual ''cursor'' position is the \Index{origin} of the \Index{paper plane}. This makes it difficult
to put objects into absolute positions. The only constant position is the
origin of the paper plane, the upper left corner, which is 1 inch right
and 1 inch down. This absolute PostScript origin is not the one for the textarea
of \TeX, because it adds the horizontal margins \Lcs{oddsidemargin} and for the first 
line \Lskip{parskip}. In the vertical direction there are added \Lskip{topskip},
\Ldim{headheight} and \Ldim{headsep}. This is a bit confusing because there are different
origins of the paper plane:
\begin{itemize}
\item the upper left corner of the paper \pstPutAbs[position=lt](0,0){\qdisk(0,0){5pt}%
		\raisebox{-2ex}{\red Absolute Paper Origin}}
\item the PostScript origin 1 inch from left and 1 inch from top
		\pstPutAbs[unit=1in,position=lC](1,-1){\qdisk(0,0){5pt}\red ~~PostScript Origin}
\item the \TeX{} origin, adding \verb|\oddsidemargin| or \verb|\evensidemargin| to 1 inch and
		 substract \verb|\topskip|, \verb|\headheight| and \verb|\headsep| from the top
		 \qdisk(pstTextOrigin){5pt}\rput[rC](pstTextOrigin){\red Text Origin~~}
\item the \TeX{} relative origin, which describes the actual ''cursor'' position, like here: \qdisk(0,0){5pt}\rput[lC](0,0){\red "Cursor" Origin}.
\end{itemize}

\section{Package Options}

\begin{tabularx}{\textwidth}{lX}
\Loption{notitlepage} & When there is no titlepage it is easier to run the
	initialisation macros. In this case the user has only to set the package option.\\
\Loption{absolute} & the origin is the upper left paper corner\\
\Loption{lowerleft} & the origin is mirrored to the lower left of the paper plane\\
\Loption{PostScript} & the origin is 1inch from the left and 1 inch from the top of the paper\\
\Loption{relative}   & the origin is the upper left text area
\end{tabularx}

Especially the \Loption{lowerleft} option may be useful. Together with the \Loption{absolute}
option the origin of the paper plane is at the lower left corner (see section~\ref{sec:lowerleft}).

\section{The Macros}
The package tries to set the origin immediately after a newpage. This is not possible
with a \Index{title} because of an additional \Lcs{newpage} of the \Lenv{titlepage} environment. 
In this case the user should controll the setting manually with
the macros

\noindent
\begin{tabularx}{\linewidth}{@{}lX@{}}
\Lcs{pstSetAbsoluteOrigin}    &  the new origin is the upper left corner of the paper\\
\Lcs{pstSetPostScriptOrigin}  & the new origin is 1 inch from left and 1 inch from top of the upper left corner of the paper\\
\Lcs{pstSetRelativeOrigin}\Largr{\CAny} & the new origin is the current point for $(0;0)$. All other values are relative to this one.\\
\Lcs{pstPutAbs}\OptArgs\Largr{\CAny}\Largb{object} &  puts any object depending to the option at $(x;y)$.
\end{tabularx}

The first two macros have to be used immediately after a newpage.

\subsection{Optional Parameters}
The \Lcs{pstPutAbs} macro can be called with all vaild \verb|pstricks| options and additionally 
with \Lkeyword{position}\verb+=position+, where \Larg{position} can be replaced by the usual placing
values \Lnotation{lt}, \Lnotation{lC}, \Lnotation{lB}, \Lnotation{lb}, \ldots\ of the well known \Lcs{rput} macro. Important is the
setting of the \Lkeyword{unit} parameter, because \LPack{pst-abspos} knows nothing about
the unit. A valid call may be like

\begin{Xverbatim}{\xLcs{pstPutAbs}}
\pstPutAbs[unit=1in,position=lC](1,-1){%
  \qdisk(0,0){5pt}\textcolor{red}{~PostScript Origin}}
\end{Xverbatim}

\section{Examples}
It is no problem to switch between the different origin settings when calling the
macros immediately aften a \Lcs{newpage}. If you want to set the origin at the ''cursor''
position, then the macro can be called just on ''cursor'' position.

\newpage
\pstSetAbsoluteOrigin
\section{Absolute Coordinates}
The point (0,0) is in the upper left corner and is set by the package option \Loption{absolute}.

\begin{BDef}
\Lcs{usepackage}\Largs{absolute}\Largb{pst-abspos}
\end{BDef}

\psset{unit=1in}%
\pstPutAbs(0,0){\qdisk(0,0){2pt}\rput(0,0){\red Origin}}Nonsense Text\pstPutAbs(1,-2){\qdisk(0,0){4pt}\red Point(1,-2)}%
\verb|\pstPutAbs(1,-2){\qdisk(0,0){4pt}\red Point(1,-2)}|\\
Nonsense Text\\
Nonsense Text\pstPutAbs(0,-2){\qdisk(0,0){4pt}\red Point(0,-2)}%
\verb|\pstPutAbs(0,-2){\qdisk(0,0){4pt}\red Point(0,-2)}|\\
Nonsense Text\\
Nonsense Text\pstPutAbs(0,-1){\qdisk(0,0){4pt}\red Point(0,-1)}%
\verb|\pstPutAbs(0,-1){\qdisk(0,0){4pt}\red Point(0,-1)}|
\pstPutAbs(1,-10){\scalebox{8}{\textcolor{myGray}{pst-abspos}}}
\pstPutAbs(1,-10){\qdisk(0,0){4pt}\red Point(1,-10)}%
\verb|\pstPutAbs(1,-10){\scalebox{8}{\textcolor{myGray}{pst-abspos}}}|
\verb|\pstPutAbs(1,-10){\qdisk(0,0){4pt}\red Point(1,-10)}|

\vspace*{\fill}
\parbox{\textwidth}{%
  \x\x\x\x\textcolor{red}{\texttt{\textbackslash pstPutAbs(3,0.5)\{\textbackslash qdisk(0,0)\{4pt\}\textbackslash blue Point(3,0.5)\}}}%
  \pstPutAbs(3,0.5){\qdisk(0,0){4pt}\blue Point(3,0.5)}\x\x\x\x%
  \texttt{\textcolor{red}{\textbackslash pstPutAbs(3,-5)\{\textbackslash qdisk(0,0)\{4pt\}\textbackslash blue Point(3,-5)\}}}\x\x\x%
  \pstPutAbs(3,-5){\qdisk(0,0){4pt}\blue Point(3,-5)}}

\clearpage
\pstSetRelativeOrigin(0,0)%

\section{Relative Coordinates}
The point (0,0) is set as the relative origin and is set by the package option
\Loption{relative}.

\begin{BDef}
\Lcs{usepackage}\Largs{relative}\Largb{pst-abspos}
\end{BDef}

This relative point is the beginning of the first textline, which depends to all margins.
It allows to place the relative origin elsewhere depending to the relative point \verb|(0,0)|.

\psset{unit=1in}%
\pstPutAbs(0,0){\qdisk(0,0){2pt}\rput(0,0){\red Origin}}
Nonsense Text\pstPutAbs(1,-2){\qdisk(0,0){4pt}\red Point(1,-2)}%
\verb|\pstPutAbs(1,-2){\qdisk(0,0){4pt}\red Point(1,-2)}|\\
Nonsense Text\\
Nonsense Text\pstPutAbs(0,-2){\qdisk(0,0){4pt}\red Point(0,-2)}%
\verb|\pstPutAbs(0,-2){\qdisk(0,0){4pt}\red Point(0,-2)}|\\
Nonsense Text\\
Nonsense Text\pstPutAbs(0,-1){\qdisk(0,0){4pt}\red Point(0,-1)}%
\verb|\pstPutAbs(0,-1){\qdisk(0,0){4pt}\red Point(0,-1)}|
\pstPutAbs(1,-10){\scalebox{8}{\textcolor{myGray}{pst-abspos}}}
\pstPutAbs(1,-10){\qdisk(0,0){4pt}\red Point(1,-10)}%
\verb|\pstPutAbs(1,-10){\scalebox{8}{\textcolor{myGray}{pst-abspos}}}|
\verb|\pstPutAbs(1,-10){\qdisk(0,0){4pt}\red Point(1,-10)}|

\vspace*{\fill}
\parbox{\textwidth}{%
  \x\x\x\x\textcolor{red}{\texttt{\textbackslash pstPutAbs(3,0.5)\{\textbackslash qdisk(0,0)\{4pt\}\textbackslash blue Point(3,0.5)\}}}%
  \pstPutAbs(3,0.5){\qdisk(0,0){4pt}\blue Point(3,0.5)}\x\x\x\x%
  \texttt{\textcolor{red}{\textbackslash pstPutAbs(3,-5)\{\textbackslash qdisk(0,0)\{4pt\}\textbackslash blue Point(3,-5)\}}}\x\x\x%
  \pstPutAbs(3,-5){\qdisk(0,0){4pt}\blue Point(3,-5)}}

\clearpage
\pstSetPostScriptOrigin%
\section{PostScript Origin}
The point (1in,-1in) is set as the absolue PostScript origin and is set by the package option
\Loption{relative}.

\begin{Xverbatim}{\xLcs{usepackage}\xLoption{absolute}}
\usepackage[PostScript]{pst-abspos}
\end{Xverbatim}

The coordinates (1in; -1in) have some historical
background and have nowadays no more real sense. If all horizontal and vertical 
margins inside \TeX{} are set to zero, then this point
is (0,0).

\psset{unit=1in}%
\pstPutAbs(0,0){\qdisk(0,0){2pt}\rput(0,0){\red Origin}}%
Nonsense Text\pstPutAbs(1,-2){\qdisk(0,0){4pt}\red Point(1,-2)}%
\verb|\pstPutAbs(1,-2){\qdisk(0,0){4pt}\red Point(1,-2)}|\\
Nonsense Text\\
Nonsense Text\pstPutAbs(0,-2){\qdisk(0,0){4pt}\red Point(0,-2)}%
\verb|\pstPutAbs(0,-2){\qdisk(0,0){4pt}\red Point(0,-2)}|\\
Nonsense Text\\
Nonsense Text\pstPutAbs(0,-1){\qdisk(0,0){4pt}\red Point(0,-1)}%
\verb|\pstPutAbs(0,-1){\qdisk(0,0){4pt}\red Point(0,-1)}|
\pstPutAbs(1,-10){\scalebox{8}{\textcolor{myGray}{pst-abspos}}}
\pstPutAbs(1,-10){\qdisk(0,0){4pt}\red Point(1,-10)}%
\verb|\pstPutAbs(1,-10){\scalebox{8}{\textcolor{myGray}{pst-abspos}}}|
\verb|\pstPutAbs(1,-10){\qdisk(0,0){4pt}\red Point(1,-10)}|\\

\vspace*{\fill}
\parbox{\textwidth}{%
  \x\x\x\x\textcolor{red}{\texttt{\textbackslash pstPutAbs(3,0.5)\{\textbackslash qdisk(0,0)\{4pt\}\textbackslash blue Point(3,0.5)\}}}%
  \pstPutAbs(3,0.5){\qdisk(0,0){4pt}\blue Point(3,0.5)}\x\x\x\x%
  \texttt{\textcolor{red}{\textbackslash pstPutAbs(3,-5)\{\textbackslash qdisk(0,0)\{4pt\}\textbackslash blue Point(3,-5)\}}}\x\x\x%
  \pstPutAbs(3,-5){\qdisk(0,0){4pt}\blue Point(3,-5)}}

\newpage
\makeatletter
\pst@lowerlefttrue
\makeatother
\pstSetAbsoluteOrigin

\section{Absolute Coordinates with an Origin in the Lower Left}\label{sec:lowerleft}
The point (0,0) is in the lower left corner and is set by the package option
\Loption{lowerLeft}. This is only useful for absolute coordinates. This is the reason why
this option should implie also the option \Loption{absolute}.


\begin{Xverbatim}{\xLcs{usepackage}\xLoption{lowerLeft}\xLoption{absolute}}
\Lcs{usepackage}\Largs{lowerLeft,absolute}\Largb{pst-abspos}
\end{BDef}


\psset{unit=1in}%
\pstPutAbs(0,0){\qdisk(0,0){4pt}\rput(0,0){\red Origin}}%
Nonsense Text\pstPutAbs(1,2){\qdisk(0,0){4pt}\red Point(1,2)}%
\verb|\pstPutAbs(1,2){\qdisk(0,0){4pt}\red Point(1,2)}|\\
Nonsense Text\\
Nonsense Text\pstPutAbs(0,2){\qdisk(0,0){4pt}\red Point(0,2)}%
\verb|\pstPutAbs(0,2){\qdisk(0,0){4pt}\red Point(0,2)}|\\
Nonsense Text\\
Nonsense Text\pstPutAbs(0,1){\qdisk(0,0){4pt}\red Point(0,1)}%
\verb|\pstPutAbs(0,1){\qdisk(0,0){4pt}\red Point(0,1)}|
\pstPutAbs(1,10){\scalebox{8}{\textcolor{myGray}{pst-abspos}}}
\pstPutAbs(1,10){\qdisk(0,0){4pt}\red Point(1,10)}%
\verb|\pstPutAbs(1,10){\scalebox{8}{\textcolor{myGray}{pst-abspos}}}|\\
\verb|\pstPutAbs(1,10){\qdisk(0,0){4pt}\red Point(1,10)}|\\

\vspace*{\fill}
\parbox{\textwidth}{%
  \x\x\x\x\textcolor{red}{\texttt{\textbackslash pstPutAbs(3,-0.5)\{\textbackslash qdisk(0,0)\{4pt\}\textbackslash blue Point(3,-0.5)\}}}%
  \pstPutAbs(3,-0.5){\qdisk(0,0){4pt}\blue Point(3,-0.5)}\x\x\x\x%
  \texttt{\textcolor{red}{\textbackslash pstPutAbs(3,5)\{\textbackslash qdisk(0,0)\{4pt\}\textbackslash blue Point(3,5)\}}}\x\x\x%
  \pstPutAbs(3,5){\qdisk(0,0){4pt}\blue Point(3,5)}}

\newpage
\pstSetPostScriptOrigin

\section{Absolute PostScript Coordinates with an Origin in the Lower Left}
The origin point (0,0) is in the lower left corner with 1in from the left and 1inch
from the bottom and is set by the package option
\Loption{lowerLeft}. This is only useful for \Index{absolute coordinate}s.

\begin{Xverbatim{\xLcs{usepackage}\xLoption{lowerLeft}\xLoption{PostScript}}
\usepackage[lowerLeft,PostScript]{pst-abspos}
\end{Xverbatim}


\psset{unit=1in}%
\pstPutAbs(0,0){\qdisk(0,0){4pt}\rput(0,0){\red Origin}}%
Nonsense Text\pstPutAbs(1,2){\qdisk(0,0){4pt}\red Point(1,2)}%
\verb|\pstPutAbs(1,2){\qdisk(0,0){4pt}\red Point(1,2)}|\\
Nonsense Text\\
Nonsense Text\pstPutAbs(0,2){\qdisk(0,0){4pt}\red Point(0,2)}%
\verb|\pstPutAbs(0,2){\qdisk(0,0){4pt}\red Point(0,2)}|\\
Nonsense Text\\
Nonsense Text\pstPutAbs(0,1){\qdisk(0,0){4pt}\red Point(0,1)}%
\verb|\pstPutAbs(0,1){\qdisk(0,0){4pt}\red Point(0,1)}|
\pstPutAbs(1,10){\scalebox{8}{\textcolor{myGray}{pst-abspos}}}
\pstPutAbs(1,10){\qdisk(0,0){4pt}\red Point(1,10)}%
\verb|\pstPutAbs(1,10){\scalebox{8}{\textcolor{myGray}{pst-abspos}}}|\\
\verb|\pstPutAbs(1,10){\qdisk(0,0){4pt}\red Point(1,10)}|\\

\vspace*{\fill}
\parbox{\textwidth}{%
  \x\x\x\x\textcolor{red}{\texttt{\textbackslash pstPutAbs(3,-0.5)\{\textbackslash qdisk(0,0)\{4pt\}\textbackslash blue Point(3,-0.5)\}}}%
  \pstPutAbs(3,-0.5){\qdisk(0,0){4pt}\blue Point(3,-0.5)}\x\x\x\x%
  \texttt{\textcolor{red}{\textbackslash pstPutAbs(3,5)\{\textbackslash qdisk(0,0)\{4pt\}\textbackslash blue Point(3,5)\}}}\x\x\x%
  \pstPutAbs(3,5){\qdisk(0,0){4pt}\blue Point(3,5)}}

\section{List of all optional arguments for \texttt{pst-abspos}}

\xkvview{family=pst-abspos,columns={key,type,default}}


\bgroup
\raggedright
\nocite{*}
\bibliographystyle{plain}
\bibliography{\jobname}
\egroup

\printindex
\end{document}


\end{document}