diff options
Diffstat (limited to 'Master/texmf-dist/source/generic/xypic/xynecula.doc')
-rw-r--r-- | Master/texmf-dist/source/generic/xypic/xynecula.doc | 594 |
1 files changed, 594 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/xypic/xynecula.doc b/Master/texmf-dist/source/generic/xypic/xynecula.doc new file mode 100644 index 00000000000..2185441aa29 --- /dev/null +++ b/Master/texmf-dist/source/generic/xypic/xynecula.doc @@ -0,0 +1,594 @@ +%% $Id$ +%% +%% Xy-pic ``Necula extensions'' option. +%% Copyright (c) 1998 George C. Necula <necula@cs.cmu.edu> +%% +%% This file is part of the Xy-pic package for graphs and diagrams in TeX. +%% See the companion README and INSTALL files for further information. +%% Copyright (c) 1991-1998 Kristoffer H. Rose <krisrose@ens-lyon.fr> +%% +%% The Xy-pic package is free software; you can redistribute it and/or modify +%% it under the terms of the GNU General Public License as published by the +%% Free Software Foundation; either version 2 of the License, or (at your +%% option) any later version. +%% +%% The Xy-pic package is distributed in the hope that it will be useful, but +%% WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +%% or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +%% for more details. +%% +%% You should have received a copy of the GNU General Public License along +%% with this package; if not, write to the Free Software Foundation, Inc., +%% 675 Mass Ave, Cambridge, MA 02139, USA. +%% +\ifx\xyloaded\undefined \input xy \fi + +\xyprovide{necula}{Necula's extensions}{\stripRCS$Revision: 0.0 $}% + {George C. Necula}{necula@cs.cmu.edu}% + {School of Computer Science, + Carnegie Mellon University, + 5000 Forbes Avenue, + Pittsburgh, PA 15213-3891, USA} + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph*{Header:}\leavevmode +\DOCHEADER +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + This option contains two extensions of the \Xy-pic kernel: A way to + expand \TeX\ macros in object <modifier>s, and a way to specify + arbitrary polygons as the <shape> of an object. + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Expansion} + + The special syntax ??c![e|]<macros>|||| is introduced in + an object ??w![<modifier>]s and ??w![<coord>]inates. It + expands the given \TeX\ <macros> (with |\edef|) before + reinterpretation as a <modifier> of <coord>, respectively. + +\DOCMODE( +\def\expandbeforenext@#1{% + \DN@ e|##1|{\edef\tmp@{##1}\expandafter\xyFN@\expandafter#1\tmp@}% +} + +\xylet@\xy@oldOBJECT@=\OBJECT@ +\xydef@\xy@newOBJECT@{% + \ifx \space@\next \expandafter\DN@\space{\xyFN@\xy@newOBJECT@}%gobble spaces + \else\ifx e\next + \expandbeforenext@\OBJECT@ + \else + \DN@{\xy@oldOBJECT@}\fi\fi + \next@}% +\let\OBJECT@=\xy@newOBJECT@ + +\xylet@\xy@oldCOORD@=\COORD@ +\xydef@\xy@newCOORD@{% + \ifx \space@\next \expandafter\DN@\space{\xyFN@\xy@newCOORD@}%gobble spaces + \else\ifx e\next + \expandbeforenext@\COORD@ + \else + \DN@{\xy@oldCOORD@}\fi\fi + \next@}% +\let\COORD@=\xy@newCOORD@ +\DOCMODE) + + This code may become part of the \Xy-pic kernel at a certain point. + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Polygon shapes} + + A polygon <shape> is specified as +% +\begin{defs1} +% + ??c![[P:]<pos>|,|\dots|,|<pos>|]| +% +\end{defs1} +\noindent\unskip +% + where |[P:|$p_1$|,|\dots|,|$p_n$|]| denotes the shape obtained by + tracking the edge with each $p_i$ a position relative to the object + reference point. <vector>s and <corner>s can be used + directly; otherwise use |-p| to get the relative position. + + \NOTE: Do not use |{}| or |[]| in the <pos>itions. + + \BUG: The algorithm assumes that the reference point is always inside + the polygon. + + It is possible to frame polygons is also possible. + +\DOCMODE( +% Define the polygon as a stylechar so that it is deferred +\xydefcsname@{*stylechar@P@}#1{\Pshape@#1@} +\xynew@{count}\c@poly@count \c@poly@count=\z@ % Polygon identifiers + +\xydef@\Pshape@:#1@{% Strip the mandatory : + \addtotoks@{% +% \xy@showthe c{Before parse}\xy@showthe p{Before parse}% +% \xy@showdim{Before parse}% + \def\poly@list{@}% + \poly@parse #1,\relax,%Sets the poly@list + \def\poly@cache{}% + \edef\poly@id{\the\c@poly@count}% + \global\advance\c@poly@count\@ne + \poly@setEdge + % Save the old values of Lc for shifting + \edef\poly@saveLcshape{\the\L@c}% + \polygonEdge@Outer% Set U,R,D,L + \poly@setEdge + % Now shift the object to keep it centered + \dimen@=\poly@saveLcshape\advance\dimen@-\L@c + \advance\R@p -\dimen@ +% \xy@showthe c{After parse}% +}} + +% Set the edge +% A polygonal edge is represented as \polygonEdge x1,y1;x2,y2;...;xn,yn@id@ +% where xi,yi define the vertices of the polygonal edge as displacement from +% the object reference point (xn=x1,yn=y1), and id is a numerical id used for +% caching the result of the last intersection operation. The cached values for +% polygon id are stored in the global macro poly@cache<id>. +\xydef@\poly@setEdge{\expandafter\poly@setEdge@\poly@list\poly@id} +\xydef@\poly@setEdge@#1@#2{\Edge@c={\polygonEdge#1@#2@}% + \expandafter\xdef\csname poly@cache#2% + \endcsname{\poly@cache}} + +% Define the polygon framing operations +\xydefcsname@{frm[P]{-}}{\expandafter\draw@polyframe\the\Edge@c{-}} +\xydefcsname@{frm[P]{.}}{\expandafter\draw@polyframe\the\Edge@c{.}} +\xydefcsname@{frm[P]{=}}{\expandafter\draw@polyframe\the\Edge@c{=}} + + +\xydef@\draw@polyframe\polygonEdge#1@#2@#3{% + \def\poly@dir{#3}% + \def\poly@list{#1@}% + \def\poly@id{#2}% + \edef\poly@cache{\csname poly@cache\poly@id\endcsname}% + \draw@polygon} + +% A polygon is maintained as a list of relative positions, as follows: +% poly@list = Xdimen_0,Ydimen_0;...;Xdimen_n,Ydimen_n @ +% The list is closed, i.e., the first and last element coincide +% Each polygon has an id storred in \poly@id +% Each polygon caches the result of the last intersection operation +% as d@x,d@y,x1,y1,x2,y2 where the first two values define the slope +% and the two sets of points are the two intersection points +% These values are storred in \poly@cache<id>. +% +% +% Helper function for dealing with polygon lists + +% Map over a polygon list. Make sure you define +% \let\poly@map@next=\poly@map before. Then, you can define +% \let\poly@map@next=\poly@map@stop if you want to stop the traversal + +\xydef@\poly@empty{} +\xydef@\poly@map#1#2,#3;#4@{% + #1{#2}{#3}% + \def\tmp@{#4}% + \ifx \poly@empty\tmp@ \else + \poly@map@next#1#4@% + \fi +} + +\xydef@\poly@map@stop#1@{} + +\xydef@\poly@mapExpand#1#2{% + \edef\tmp@{\noexpand\poly@map\noexpand #1#2}% + \tmp@} + +% Parse a polygon definition + +\xydef@\poly@parse #1,{% + \ifx #1\relax %Done. Copy the head of the list at its end + \poly@close + \let\next@=\relax + \else + % Save everything + \save@ + % Process the position using POS + \POS #1% + % Now add the new c to the list + \edef\tmp@{{\the\X@c}{\the\Y@c}}% + \expandafter\poly@append\tmp@ + \restore + \let\next@=\poly@parse % continue parsing + \fi + \next@ +} + % Append to the list of polygon points +\xydef@\poly@append#1#2{\expandafter\poly@append@\poly@list{#1,#2;}} +\xydef@\poly@append@#1@#2{\global\def\poly@list{#1#2@}} + + % Close the polygon +\xydef@\poly@close{\expandafter\poly@close@\poly@list} +\xydef@\poly@close@#1,#2;#3@{\poly@append{#1}{#2}} + +% Draw a polygon at the current location + +\xydef@\draw@polygon{% First separate the head +% \W@{Drawing polygon \poly@list}\xy@showthe c{ Centered at}% + \save@ + % Set the origin to point at the reference point + \X@origin=\X@c \Y@origin=\Y@c + \poly@setp % Set p at the beginning of the polygon and set poly@rest + % Zero the edges + \U@c=\z@\R@c=\z@\D@c=\z@\L@c=\z@\U@p=\z@\R@p=\z@\D@p=\z@\L@p=\z@ + \Edge@c={\zeroEdge}\Edge@p={\zeroEdge}% + \let\poly@map@next=\poly@map + \poly@mapExpand\poly@drawseg\poly@rest + \restore +} + + % Set p to the first element. Requires the origin to be + % at the reference point +\xydef@\poly@setp{\expandafter\poly@setp@\poly@list} +\xydef@\poly@setp@#1,#2;#3@{% + \X@p=#1\advance\X@p\X@origin \Y@p=#2\advance\Y@p\Y@origin% + \global\def\poly@rest{#3@}} + +\xydef@\poly@drawseg#1#2{% + \dimen@=#1\X@c=\the\dimen@\advance\X@c \X@origin + \dimen@=#2\Y@c=\the\dimen@\advance\Y@c \Y@origin +% \W@{Next segment is at offset #1,#2 and absolute \the\X@c,\the\Y@c}% + \expandafter\connect@\expandafter\dir\poly@dir% + \X@p=\X@c\Y@p=\Y@c} + +% Polygonal edge +% Requires c to be the reference point +\xydef@\polygonEdge#1@#2@#3{% + \def\poly@list{#1@}% + \def\poly@id{#2}% + \edef\poly@cache{\csname poly@cache\poly@id\endcsname}% + \ifcase#3\relax + \DN@{\polygonEdge@Inters +% \ifpoly@badinters +% \xyerror@{Could not find intersection for polygon}\fi + }%0 + \or \DN@{\polygonEdge@Under}%1 + \or \DN@{\polygonEdge@Dist}%2 + \or \DN@{\rectangleProp@}%3 I do not understand Prop! + \or \DN@{\polygonEdge@Inner}%4 + \or \DN@{\polygonEdge@Outer}%5 + \else \DN@{}\fi + \next@} + + +\newif\ifpoly@badinters + +\xydef@\polygonEdge@Inters{% +% \W@{Edge intersection with (\the\X@c, \the\Y@c) -> (\the\X@p,\the\Y@p)}% +% \W@{ for polygon: \poly@id}% +% \W@{ with list: \poly@list}% +% \W@{ with cache: \poly@cache}% + % Check the cache first + \ifx\poly@cache\poly@empty + \poly@intersdoit + \else + \expandafter\poly@intersprobecache\poly@cache @% + \fi +% \xy@showthe c{Inters res}% +} + +% +% Redefine poly@cachehit to poly@cachehitdisable to diable polygon caching +\xydef@\poly@cachehit#1#2{% +% \W@{ intersection point found in cache}% + \X@c=#1\Y@c=#2} + +\xydef@\poly@cachehitdisable#1#2{\poly@intersdoit} +%\let\poly@cachehit=\poly@cachehitdiasable% Uncomment this line to disable $ + + +% Probes the cache +% +\xydef@\poly@intersprobecache#1,#2,#3,#4,#5@{% + \dimen@=#1\advance\dimen@-\d@X + \ifdim\zz@\dimen@ + \dimen@=#2\advance\dimen@-\d@Y + \ifdim\zz@\dimen@ + \poly@cachehit{#3}{#4} + \else + \poly@intersdoit + \fi + \else + \poly@intersdoit + \fi +} + + +% Computes the intersection between the line cp and the edge. +% Both intersection points are stored in the cache, the one in the +% direction towards p first. +\xydef@\poly@intersdoit{% +% \W@{ intersection not in cache. Computing it}% + % Save A@ and B@ because we cannot change them + \edef\polyoldA@{\the\A@}\edef\polyoldB@{\the\B@}% + % Initialize the intersection points + \def\poly@intersneg{}\def\poly@interspos{}% + \save@ + \poly@setorigin % Set origin at the beginning of the polygon and + % set poly@rest + \def\zeroDivide@{\poly@badinterstrue}% Handle the division by zero except. + \let\poly@map@next=\poly@map + \poly@mapExpand\poly@interseg\poly@rest + \ifx\poly@intersneg\poly@empty + \poly@badinterstrue + \else + \ifx\poly@interspos\poly@empty + \poly@badinterstrue + \else + \poly@badintersfalse + \fi + \fi + \restore + \A@=\polyoldA@\B@=\polyoldB@ % Restore A@ and B@ + \ifpoly@badinters \else + \edef\tmp@{\poly@interspos,\poly@intersneg @}% + \expandafter\poly@intersfinish\tmp@ + \fi +} + +\xydef@\poly@intersfinish#1,#2,#3@{% + \X@c=#1\Y@c=#2\relax + \xdef\poly@cache{\the\d@X,\the\d@Y,#1,#2,#3}% + \poly@setEdge +} + + + % Set origin to the first point. Define poly@rest + % Requires c to be set to the reference point +\xydef@\poly@setorigin{\expandafter\poly@setorigin@\poly@list} +\xydef@\poly@setorigin@#1,#2;#3@{% + \X@origin=#1\advance\X@origin\X@c \Y@origin=#2\advance\Y@origin\Y@c% + \global\def\poly@rest{#3@}} + + + + +% +% Compute one intersection with a given edge +% c is set to the reference point, p is set to the end of the ray +% origin is set to the start of the segment +\xydef@\poly@interseg#1#2{% + % Default is no intersection +% \W@{ Intersection with edge (\the\X@origin,\the\Y@origin) -> (#1,#2)}% + % Compute the absolute values + \dimen@=#1\advance\dimen@\X@c \edef\poly@saveXcinters{\the\dimen@}% + \dimen@=#2\advance\dimen@\Y@c \edef\poly@saveYcinters{\the\dimen@}% + \save@ + \poly@badintersfalse + % Set R@c and U@c to the distance to end of segment + \R@c=\poly@saveXcinters \advance\R@c -\X@origin + \U@c=\poly@saveYcinters \advance\U@c -\Y@origin + % Now call intersect to set X@c and Y@c to the intersection point + \intersect@ + \A@=\X@c \B@=\Y@c % Save result + \restore + \ifpoly@badinters +% \W@{ \space failed after intersect}% + \else +% \W@{ \space after intersect@ (\the\A@,\the\B@)}% + % Verify that it is on the segment from origin to (#1, #2) + +\poly@isonseg\X@origin\Y@origin\A@\B@\poly@saveXcinters\poly@saveYcinters + \ifpoly@badinters +% \W@{ \space failed after seg check}% + \else + % Verify that (A,B) is on the ray from c to p + \poly@isonray\X@c\Y@c\A@\B@\X@p\Y@p + \ifpoly@badinters + % It is on the negative ray +% \W@{ \space a negative intersection}% + \edef\poly@intersneg{\the\A@,\the\B@}% + \else +% \W@{ \space a positive intersection}% + \edef\poly@interspos{\the\A@,\the\B@}% + \fi + \fi + \fi + % Set the origin to the start of the next segment + \X@origin=\poly@saveXcinters\Y@origin=\poly@saveYcinters +} + + +% +% Computes the distance from reference point to the intersection +% +\xydef@\polygonEdge@Dist{\xyerror@{Dist is not yet implemented for polygons}} + +% +% Checks that #1 <= #2 <= #3 or that #3 <= #2 <= #1 +% Sets ifpoly@badinters otherwise +% ifpoly@closedrange decides whether the second inequality is also checked +% All checks are done with a precision of 100*almostz@ =~ 5000sp = 0.08pt +\newif\ifpoly@closedrange +\xydef@\poly@isinrange#1#2#3{% + \ifpoly@badinters \else + \dimen@=#1\dimen@i=#2\dimen@ii=#3\relax +% \W@{check if in \ifpoly@closedrange closed\else open\fi\space +% range 1=\the\dimen@,2=\the\dimen@i,3=\the\dimen@ii}% + \advance\dimen@ii -\dimen@ \advance\dimen@i -\dimen@ + \ifdim\dimen@ii<0pt\relax + \ifdim\dimen@i>100\almostz@ + \poly@badinterstrue + \fi + \dimen@i=-\dimen@i \dimen@ii=-\dimen@ii + \else + \ifdim\dimen@i<-100\almostz@\relax + \poly@badinterstrue + \fi + \fi + \ifpoly@closedrange + \advance\dimen@ii 100\almostz@ + \ifdim\dimen@i>\dimen@ii + \poly@badinterstrue + \fi + \fi +% \ifpoly@badinters \W@{ failed}\else\W@{ succeeded}\fi + \fi} + +% +% Checks that (#3,#4) is on a segment defined by (#1,#2)->(#5,#6) +\xydef@\poly@isonseg#1#2#3#4#5#6{% + % Check X first + \poly@closedrangetrue + \poly@isinrange{#1}{#3}{#5}% + \poly@isinrange{#2}{#4}{#6}% + +} + +% +% Checks that (#3,#4) is on a ray defined by (#1,#2)->(#5,#6) +\xydef@\poly@isonray#1#2#3#4#5#6{% + % Check X first + \poly@closedrangefalse + \poly@isinrange{#1}{#3}{#5}% + \poly@isinrange{#2}{#4}{#6}% + +} +% +% Test whether (Xp,Yp) is inside the polygon (or on the edge) +% Sets \ifInside@ accordingly +\xydef@\polygonEdge@Under{% +% \W@{}\W@{Edge Under with c=(\the\X@c,\the\Y@c) and p=(\the\X@p,\the\Y@p)}% +% \W@{ for polygon: \poly@list}% + % Save A@ and B@ + \edef\polysaveA@under{\the\A@}\edef\polysaveB@under{\the\B@}% + % Save X@c and Y@c + \edef\poly@saveXcUnder{\the\X@c}\edef\poly@saveYcUnder{\the\Y@c}% + % Compute the intersection + \polygonEdge@Inters + \ifpoly@badinters% p is very close to c + \Inside@true + \else + \A@=\X@c\B@=\Y@c + % Restore c + \X@c=\poly@saveXcUnder\Y@c=\poly@saveYcUnder + % Now verify that the intersection point is on the ray c->p + \poly@isonseg\X@c\Y@c\X@p\Y@p\A@\B@ + \ifpoly@badinters \Inside@false \else \Inside@true\fi + \A@=\polysaveA@under\B@=\poly@saveB@under + \fi +% \ifInside@\W@{->inside}\else\W@{->outside}\fi +} + +% +% Compute the inner rectangle +% +\xydef@\polygonEdge@Inner{% +% \W@{}\W@{Edge Inner with (\the\X@c, \the\Y@c) -> (\the\X@p,\the\Y@p)}% +% \W@{ for polygon: \poly@list}% +% \W@{ with cache: \poly@cache}% + % Save everything except c + \enter@{\basefromthebase@ \pfromthep@ \DirectionfromtheDirection@}% + % Save c in Lc,Dc + \L@c=\X@c \D@c=\Y@c + % Compute the two intersection points + \polygonEdge@Inters + \ifpoly@badinters + \czeroEdge@ + \else + % Save the result in Rc,Uc and in X@c,Y@c + \expandafter\poly@getinterspoints\poly@cache @% + % Now compute the inner rectangle centered + \ifdim\X@c>\R@c + \L@c=\R@c \R@c=\X@c + \else + \L@c=\X@c + \fi + \X@c=0.5\L@c \advance\X@c 0.5\R@c \advance\R@c -\X@c \L@c=\R@c + \ifdim\Y@c>\U@c + \D@c=\U@c \U@c=\Y@c + \else + \D@c=\Y@c + \fi + \Y@c=0.5\D@c \advance\Y@c 0.5\U@c \advance\U@c -\Y@c \D@c=\U@c + \Edge@c={\rectangleEdge}% + \fi + \leave@ +% \xy@showthe c{After inner}% +} + +\xydef@\poly@getinterspoints#1,#2,#3,#4,#5,#6@{% + \R@c=#3\U@c=#4\X@c=#5\Y@c=#6} + +% +% Compute the outer rectangle (set Uc,Dc,Lc,Rc and Edgec). +% Does not change Xc,YC +% +\xydef@\polygonEdge@Outer{% +% \W@{Computing outer for \poly@list}\xy@showthe c{Before outer}% + % Save everything except c + \enter@{\basefromthebase@ \pfromthep@ \DirectionfromtheDirection@}% + \czeroEdge@ % Zero out c + \let\poly@map@next=\poly@map + \poly@mapExpand\poly@findextent\poly@list + \Edge@c={\rectangleEdge}% + \leave@ +% \xy@showthe c{After outer} +} + +\xydef@\poly@findextent#1#2{% +% \xy@showthe c{Before find extent}% +% \W@{ extx=#1, exty=#2}% + \dimen@=#1\dimen@=\the\dimen@% it fails if I remove the second assign + \ifdim\dimen@>\R@c \R@c=\dimen@ \fi + \ifdim -\dimen@>\L@c \L@c=-\dimen@ \fi + \dimen@=#2\dimen@=\the\dimen@% it fails if I remove the second assign + \ifdim\dimen@>\U@c \U@c=\dimen@ \fi + \ifdim -\dimen@>\D@c \D@c=-\dimen@ \fi +% \xy@showthe c{ After extent}% +} + +% Change to account for polynomial shapes, in addition to circular ones +% +\xydef@\Fshape@#1:{\def\whichframe@@{{#1}}\let\whichoptions@@=\empty + \DN@{{}}\ifx\whichframe@@\next@ \def\whichframe@@{{-}}\fi + \expandafter\xyFN@\expandafter\Fshape@whichframe\the\Edge@c} + +\xydef@\Fshape@whichframe{% + \ifx\next\circleEdge + \edef\whichframe@@{[o]\whichframe@@}% + \DN@##1{\xyFN@\Fshape@i}% + \else + \ifx\next\polygonEdge + \edef\whichframe@@{[P]\whichframe@@}% + \DN@\polygonEdge##1@##2@{\xyFN@\Fshape@i}% + \else + \DN@##1{\xyFN@\Fshape@i}% + \fi\fi + \next@ +} + +\xyendinput +\DOCMODE) + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + \BUG: This code should be merged with the `frame' and `poly' + options. + + The example at the end of \S??g[:smart] illustrates the extensions. + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\DOCMODE( +% $Log$ +% Received from George. +\DOCMODE) + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% Tell Emacs that this is a LaTeX document and how it is formatted: +% Local Variables: +% mode:latex +% fill-prefix:"\t" +% fill-column:77 +% paragraph-separate:"^[ \t\f]*$\\|^[^\t]\\|\\\\\\\\\\|\\$\\$\\|[^\n\\\\][%&]" +% paragraph-start:"^[ \t\f]*$\\|^[^\t]\\|\\\\\\\\\\|\\$\\$\\|[^\n\\\\][%&]" +% End: |