summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/xypic/xyps-ps.doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/generic/xypic/xyps-ps.doc')
-rw-r--r--Master/texmf-dist/source/generic/xypic/xyps-ps.doc750
1 files changed, 750 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/xypic/xyps-ps.doc b/Master/texmf-dist/source/generic/xypic/xyps-ps.doc
new file mode 100644
index 00000000000..c4c4bb4d35c
--- /dev/null
+++ b/Master/texmf-dist/source/generic/xypic/xyps-ps.doc
@@ -0,0 +1,750 @@
+%% $Id: xyps-ps.doc,v 3.7 1999/02/16 15:12:50 krisrose Exp $
+%%
+%% Xy-pic ``PS-PS'' PostScript support.
+%% Copyright (c) 1993-1997 Ross Moore <ross@mpce.mq.edu.au>
+%%
+%% 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-1997 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.
+%%
+%% As a special exception, you may use this file and all files derived
+%% from it without restrictions. This special exception was added with
+%% version 3.7 of Xy-pic.
+%%
+\expandafter\ifx\csname xyps-psloaded\endcsname\empty
+ \message{not reloaded}\endinput \fi
+\expandafter\let\csname xyps-psloaded\endcsname=\empty \xycatcodes
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+The included file |xyps-ps.tex| (version\stripRCS$Revision: 3.7 $)
+provides support for \PS\ |\special| commands used by the |ps| backend
+extension as well as \PS-based options, to produce special effects
+not available directly with \TeX.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\paragraph*{Header:}\leavevmode
+\DOCHEADER
+
+\paragraph*{\PS\ {\tt\string\special} commands}
+
+The \PS\ |\special|s which are used by \Xy-ps fall into four broad
+classes:
+%
+\begin{enumerate}
+\item execute a piece of code, e.g. to draw some graphic object;
+\item add a new \PS\ definition to the existing dictionary of commands;
+\item change the value of some parameters, storing them for later use; and
+\item read \PS\ commands from a pre-existing file.
+\end{enumerate}
+
+Since different drivers may provide different syntax for these classes
+of command, \Xy-ps has different macros to optimize to interface to the
+different drivers. Initially these control-sequence names are bound to
+macros that do nothing. Upon specifying a driver, they will be bound
+to a macro appropriate for that driver.
+
+\DOCMODE(
+\xylet@\PSmacro@@=\eat@
+\xylet@\PSdict@@=\eat@
+\xylet@\PSspecial@@=\eat@
+\xylet@\PSread@@=\eat@
+\xylet@\PSinclude@@=\eat@
+\xylet@\PSraw@@=\eat@
+\xylet@\xyPSobeylines@@=\relax
+\xylet@\PSspecialdict@@=\eat@
+
+\xydef@\UnloadPSps@{%
+ \let\PSmacro@@=\eat@
+ \let\PSdict@@=\eat@
+ \let\PSspecial@@=\eat@
+ \let\PSread@@=\eat@
+ \let\PSinclude@@=\eat@
+ \let\PSraw@@=\eat@
+ \let\xyPSobeylines@@=\relax
+ \let\PSspecialdict@@=\eat@
+}
+\DOCMODE)
+
+Unloading \PS\ requires also turning off the \PS-backend,
+if it has been loaded.
+
+\DOCMODE(
+\xydef@\UnloadPS@{\UnloadPSps@
+ \expandafter\ifx\csname xypsloaded\endcsname\unknown\PSspecials@false
+ \else\expandafter\NoPSspecials\fi}
+\xylet@\UnloadPS@@=\UnloadPS@
+
+%\xyaddunsupport{ps}\UnloadPS@@
+\DOCMODE)
+
+\DOCMODE(
+\ifx\undefined\dvitype@\xydef@\dvitype@{null}\fi
+\DOCMODE)
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Some drivers, in particular versions of \Textures\ earlier than 1.7, require
+the \PS\ dictionary to be included with every page shipped out.
+We do this by providing a routine which rebinds the |\shipout| primitive to
+a macro |\xyPSshipout@| which prepends the \Xy-ps \PS\ dictionary to the box
+being shipped-out. This routine |\@PSshipout| is called, if necessary, when
+the driver has been specified.
+
+\DOCMODE(
+\xylet@\xyrealshipout@=\shipout
+\xydef@\xyPSshipout@{\setbox9=\copy\voidb@x
+ \afterassignment\xyPSshipout@i\setbox9=}
+\xydef@\xyPSshipout@i{\ifvoid9 \expandafter\aftergroup\fi\xyPSshipout@ii}
+\xydef@\xyPSshipout@ii{\xyrealshipout@\vbox{\XYpredict@@\box9}}
+
+\xydef@\@PSshipout{\global\let\shipout=\xyPSshipout@ }
+\DOCMODE)
+
+The box register |\box9| is assumed to be a scratch register, used globally
+according to \TeX\ conventions.
+
+When the \PS\ backend is loaded then we need to rebind |\shipout| to include
+the full dictionary.
+
+\DOCMODE(
+\xydef@\xyPSshipout@PSii{%
+ \ifUsePSdict@@\let\XYshipdict@=\includeXYPSdict@@
+ \else\def\XYshipdict@{\XYpredict@@\XYdict@@}\fi
+ \xyrealshipout@\vbox{\XYshipdict@\box9}}
+\DOCMODE)
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+These two control sequences are used in the DVI-driver files
+to control when the \PS\ <driver> can be altered.
+
+\DOCMODE(
+\xydef@\firstPS@{%\fixedxydriver@
+ \global\let\firstPS@@=\relax \global\let\firstPS@=\relax}
+\xylet@\firstPS@@=\firstPS@
+\DOCMODE)
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+\subsection{Installation}
+%
+To install use of \PS\ requires loading the \PS\ dictionary.
+However this can only be done when a <driver> is known to be able to
+support it. Hence the |\installxyps@| command should be called only from
+within a <driver>-file.
+
+Furthermore, the <driver>-file should define a value for |\installxyps@@|
+to including anything specific to that <driver>; even if only
+|\let\installxyps@@=\relax|. If |\dumpPSdict| has been specified,
+then the dictionary must be written first, so it can be used with the
+subsequent processing (see the subsection below).
+
+\DOCMODE(
+\ifx\undefined\dumpPSdict@@ \xylet@\dumpPSdict@@=\relax \fi
+
+\xydef@\installxyps@{%
+ \xyinputorelse@{xyps-ps}{\xydrivernoload@{ps-ps}}\xycatcodes
+ \installxyps@@ \installxyps@x }
+
+\xylet@\installxyps@@=\relax
+\xylet@\setupxyPS@@=\relax
+\xywithoption{ps}{\let\setupxyPS@@=\setupxyPS@}
+
+\xydef@\installxyps@x{\dumpPSdict@@
+ \ifx\xyrealshipout@\undefined \let\xyrealshipout@=\shipout\fi
+ \ifx \shipout \xyrealshipout@
+ \ifUsePSdict@@ \DN@{\includePSmessage@\includeXYPSdict@\message{>}}%
+ \else \DN@{\XYdict@\endXYdict@}\fi
+ \else \DN@{\let\xyPSshipout@ii=\xyPSshipout@PSii \@PSshipout}\fi
+ \let\firstPS@=\relax \next@
+ \let\XYpredict@=\relax
+ \setupxyPS@@ }
+
+\let\realinstallxyps@x=\installxyps@x
+\ifx\undefined\AfterBeginDocument
+ \def\installxyps@x{\xysetup@@{\realinstallxyps@x}}%
+\else
+ \def\installxyps@x{\AfterBeginDocument{\realinstallxyps@x}}%
+\fi
+\DOCMODE)
+
+In case no <driver> was known when a call to the |\installxyps@| method
+was queued, e.g. by |\dumpPSdict{}| before any |\xyoption{|<driver>|}|,
+then a check is made to see there is now a known <driver> which
+supports \PS. If so then this installation is cancelled since another
+should follow, otherwise the default <driver> of |dvips| is assumed.
+The command |\xyPSdriver#1| is provided to allow users to change this
+default <driver>. This may be necessary when multiple <driver>s are
+required and the final one specified does not support \PS.
+
+\DOCMODE(
+\xydef@\xydefaultdriver@{dvips}
+\xydef@\xyPSdriver#1{\def\xydefaultdriver@{#1}}
+
+\xydef@\installxyps@orig{\DN@{}%
+ \ifx\xydriversselected@@\empty
+ \DN@{\expandafter\defaultinstallps@\expandafter{\xydefaultdriver@}}%
+ \else \def\do##1{%
+ \expandafter\ifx\csname##1@xy@ps\endcsname\relax
+ \DN@{\defaultinstallps@{##1}}}%
+ \xydriversselected@@
+ \else \DN@##1{}\fi\fi \next@ }
+
+%\xylet@\installxyps@@=\installxyps@orig
+
+\xydef@\defaultinstallps@#1#2{%
+ \xywarning@{no driver specified, using #1 }%
+ \xyrequire{#1}\csname #1@xy@ps\endcsname{}}
+
+\xydef@\null@xy@ps{\installxyps@}
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection*{\PS\ escape}
+??=[postscript escape]
+
+An extra <shape> modifier key allows arbitrary \PS\ code
+to be applied to the current <object>.
+%
+\begin{defs}
+ |[!|<postscript code>|]| & for special effects\cr
+ |[psxy]| & stores current location.\cr
+\end{defs}
+
+\DOCMODE(
+\xydefcsname@{shape [!...]}#1{%\tracingall%
+ \expandafter\ifx\csname xyps-sloaded\endcsname\empty \DN@{\xyPSescapestyle@{#1}@@}%
+ \else\ifxyPSshapes@\DN@{\xyPSshapechar@{#1}@@}%
+ \else \DN@{\xyPScharwarning@}\fi\fi \next@ }
+\xydefcsname@{shape [psxy]}{\ifxyPSshapes@\DN@{\xyPSpsxy@}%
+ \else \DN@{\xyPScharwarning@}\fi \next@ }
+\DOCMODE)
+%
+\noindent
+Normally the <postscript code> will be a simple command to alter the
+\PS\ graphics state:
+e.g. |[!1 0 0 setrgbcolor]| changes the colour used to render parts of
+the <object>.
+Any number of such <shape> modifiers is allowable,
+however it is more efficient
+to combine them into a single modifier, whenever possible.
+
+It is very important that braces |{| and |}| do not
+appear explicitly in any <postscript code>, as this may upset the
+\Xy-pic <object> parsing. However it is acceptable to have a
+control sequence name here, expanding into more
+intricate \PS\ code. This will not be expanded until
+a later (safe) time.
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+Due to differences within the DVI-drivers, such simple \PS\
+commands need not affect every part of an <object>.
+In particular the lines, curves and arrowheads generated
+by \Xy-pic use a different mechanism,
+which should give the same result with all drivers.
+This involves redefining some \PS\ procedures
+which are always read prior to rendering one of these objects.
+One simple way to specify a red line is as follows;
+the |xycolor| extension provides more sophisticated support for colour.
+The <shape> modifiers described in the previous section also use
+this mechanism, so should work correctly with all drivers.
+
+\begin{code}
+\def\colorxy(#1){%
+ /xycolor{#1 setrgbcolor}def}
+...
+\connect[!\colorxy(1 0 0)]\dir{-}
+...
+\end{code}
+\displaycode
+
+\noindent
+Note how the braces are inserted within the expansion of the
+control sequence |\colorxy|,
+which happens after parsing of the <connection>.
+The following table shows which graphics parameters are
+treated in this way, their default settings, and the type of
+\PS\ code needed to change them.
+%
+\begin{defs}
+colour &|/xycolor{0 setgray}def| \cr
+line-width&|/xywidth{.4 setlinewidth}def|\kern-7pt \cr
+dashing &|/xydash{[] 0 setdash}def| \cr
+line-cap &|/xycap{1 setlinecap}def| \cr
+line-join &|/xyjoin{1 setlinejoin}def|\kern-7pt \cr
+\end{defs}
+%
+\noindent
+This feature is meant primarily for modifying the rendering
+of objects specified in \TeX\ and \Xy-pic, not for drawing new objects
+within \PS. No guarantee can be given of the current location,
+or scale, which may be different with different drivers.
+However a good \PS\ programmer will be able to overcome
+such difficulties and do much more. To aid in this the special
+modifier |[psxy]| is provided to record the location where the
+reference point of the current <object> will be placed.
+Its coordinates are stored with keys |xyXpos| and |xyYpos|.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+When the |\special| is placed the following registers contain important
+values:
+|\L@p| = horizontal displacement of \Xy-pic reference point from
+the \TeX\ reference point (i.e. left-hand end of the box)
+ of the initial object;
+|\D@p| = vertical displacement of \Xy-pic reference point from
+ the \TeX\ reference point (i.e. the baseline) of the initial object;
+|\R@p| = horizontal offset, resulting from <shape> modifiers;
+|\U@p| = vertical offset, initially |-\D@p| but alterable
+ by <shape> modifiers.
+
+\DOCMODE(
+\xydef@\xyPSpsxy@{%
+ \setboxz@h{\dimen@=\L@p \advance\dimen@-\R@p
+ \dimen@ii=-\U@p \raise\dimen@ii\hbox to\z@{%
+ \kern\dimen@\xyPScurrpt@\kern-\dimen@}\boxz@}}%
+
+\xydef@\xyPScurrpt@{\ifxyPSshapes@\expandafter\xyPScurrpt@@\fi}
+\DOCMODE)
+
+It is necessary to know the current \PS\ location.
+Unfortunately the |currentpoint| operator frequently has no value.
+The following code overcomes this difficulty.
+
+Some drivers may need to define this differently...
+
+\DOCMODE(
+\xydef@\xyPScurrpt@@@{\PSspecial@@{xyi}\PSraw@@{userdict begin xyx end}}
+\ifx\undefined\xyPScurrpt@@ \xylet@\xyPScurrpt@@=\xyPScurrpt@@@ \fi
+
+%\xydef@\xyPScurrpt@@@{\PSspecial@@{userdict begin
+% 0 0 transform grestore gsave itransform
+% /xyYpos exch def /xyXpos exch def end}}
+
+%\xydef@\xyPScurrpt@@@{%
+% \PSspecial@@{0 0 transform grestore gsave itransform }%
+% \PSraw@@{userdict begin /xyYpos exch def /xyXpos exch def end}}
+\DOCMODE)
+
+The \PS\ operator called |xyx| is defined below, for storing the
+location placed on the stack by |xyi|.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsubsection{Technical Note}:
+The scoping is achieved by using two |\specials| so that the
+resulting \PS\ file should ultimately look like:
+\begin{defs1}
+|... {| special code before|}| <object> |{|special code after|} ...|
+\end{defs1}
+The ``code after'' is to cancel the effect, returning the graphics
+state to what it was prior to the ``code before''.
+Not all DVI-drivers can achieve this sequencing. In particular \OzTeX\
+collects all |\specials| in the DVI-file and places their contents
+at the beginning of the \PS\ file: any effect would be cancelled
+immediately after it has been established.
+
+The user can add code to both parts by expressing the <shape> modifier
+as follows:
+%
+\begin{defs1}
+ ??c![*]\dots|!|<code before>|<>|<code after>|]|\dots\ .\cr
+\end{defs1}
+%
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsubsection*{Further Technical Note}:
+The ``code before'' does two things in addition to that code given
+explicitly by the user. Firstly it issues a |gsave| then it opens
+a new dictionary on the dictionary stack. The ``code after''
+contains the matching |grestore| after closing the new dictionary.
+
+Since objects can be built as |\composite|s and diagrams can be nested,
+there is the possibility of generating long chains of nested
+\PS\ dictionaries. For this reason the dictionary is kept
+small, allowing only 8 key-value pairs to be |def|ined within it.
+If more are required, the user should define a private
+dictionary to hold the extra key-value pairs, making sure that it is
+open when its entries need to be accessed.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\DOCMODE(
+\xywarnifdefined\xyPSshapechar@
+\xywarnifdefined\xyPSsplitshape@
+
+{\xyuncatcodes \catcode`@=11
+ \gdef\xyPSshapechar@#1@@{\xyPSsplitshape@#1<><>@@}%
+ \gdef\xyPSsplitshape@#1<>#2<>#3@@{\xyPSsplitPS@{#1}{#2}}}
+
+%\xydef@\xyPSsplitPS@#1#2{%\aftergroup\show\aftergroup\relax
+% \def\xyPSpre@{#1}\def\xyPSpost@{#2}\modPSboxz@ }
+
+\xydef@\xyPSrawA@#1{\expandafter\xyPSrawAA@ #1{}}%
+\xydef@\xyPSrawAA@#1#2{\PSraw@@{{pu #1}xyg #2}%
+ \PSmessage{{pu #1}xyg #2}}%
+\xydef@\xyPSrawZ@#1{\PSraw@@{{#1 pp}xyf}\PSmessage{{#1 pp}xyf}}%
+\DOCMODE)
+
+The \PS\ operators |pu|, |pp|, |xyg| and |xyf| are defined below,
+for push/pop of the |XYddict| stack, preceded/followed by a
+|gsave|/|grestore| of the \PS\ graphics state.
+
+\DOCMODE(
+\xydef@\modPSboxz@{%
+ \expandafter\DN@\expandafter{\xyPSpre@{}}\ifx\next@\empty\else
+ \setboxz@h{\expandafter\xyPSrawA@\expandafter{\xyPSpre@{}}\boxz@
+ \expandafter\xyPSrawZ@\expandafter{\xyPSpost@}}\DN@{}\fi}%
+
+\xydef@\modPSdrop@{%
+ \expandafter\DNii@\expandafter{%
+ \expandafter\xyPSrawA@\expandafter{\xyPSpre@{}}}%
+ \DN@##1{\expandafter\def\expandafter\tmp@\expandafter{\nextii@ ##1}}%
+ \expandafter\next@\expandafter{\Drop@@}%
+ \expandafter\DNii@\expandafter{%
+ \expandafter\xyPSrawZ@\expandafter{\xyPSpost@}}%
+ \DN@##1{\expandafter\def\expandafter\Drop@@\expandafter{\tmp@ ##1}}%
+ \expandafter\next@\expandafter{\nextii@}}%
+
+\xydef@\modPSconnect@{%
+ \expandafter\DNii@\expandafter{%
+ \expandafter\xyPSrawA@\expandafter{\xyPSpre@{}}}%
+ \DN@##1{\expandafter\def\expandafter\tmp@\expandafter{\nextii@ ##1}}%
+ \expandafter\next@\expandafter{\Connect@@}%
+ \expandafter\DNii@\expandafter{%
+ \expandafter\xyPSrawZ@\expandafter{\xyPSpost@}}%
+ \DN@##1{\expandafter\def\expandafter\Connect@@\expandafter{\tmp@ ##1}}%
+ \expandafter\next@\expandafter{\nextii@}}%
+
+\xydef@\xyPSpre@{{}{}}
+\xydef@\xyPSpost@{}
+\DOCMODE)
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Some utility macros for controlling writing to the log-file.
+
+\DOCMODE(
+\xydef@\PSmessage@#1{\W@{PS: #1, direction=\the\Direction}}
+\xydef@\PSignore@#1{}%
+\xydef@\showPSmessages{\let\PSmessage=\PSmessage@}
+\xydef@\hidePSmessages{\let\PSmessage=\PSignore@}
+\xylet@\PStracing=\showPSmessages
+\hidePSmessages
+
+\xydef@\PSmacro@#1{\PSmacro@@{#1}\PSmessage{#1}}
+\DOCMODE)
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection*{\PS\ Header file}
+
+This creates a flag to indicate whether the user wishes to get the \PS\
+dictionary from an external header file.
+
+\DOCMODE(
+\xydef@\includeXYPSdict@@{%
+ \expandafter\PSinclude@@\expandafter{\xyPSdictname}}
+\xydef@\includeXYPSdict@r{\message{PS: includeXYPSdict}\includeXYPSdict@@
+ \let\includeXYPSdict@=\relax}
+\xylet@\includeXYPSdict@\includeXYPSdict@r
+
+\xydef@\endXYdict@{}
+
+\xydef@\includePSmessage@@{\message{<xyps: including \xyPSdictname}}
+\xylet@\includePSmessage@=\includePSmessage@@
+
+\xydef@\xyPSdictknown@{%
+% \immediate\closein\xyPSdictread@
+ \immediate\closein\xyread@
+ \xywarning@{File \xyPSdictname\space already exists}
+ \message{ Do you wish to overwrite it \string? y/n }%
+ \read16 to \next
+ \DNii@{\xywarning@{You did not type Y or N -- try again please}%
+ \xyPSdictknown@}%
+ \DN@{Y }\ifx\next@\next \DNii@{\writePSdict@@}%
+ \else\DN@{y }\ifx\next@\next \DNii@{\writePSdict@@}%
+ \else\DN@{n }\ifx\next@\next \DNii@{\cancelPSdict@}%
+ \else\DN@{N }\ifx\next@\next \DNii@{\cancelPSdict@}%
+ \fi\fi\fi\fi \nextii@ }
+
+\xydef@\cancelPSdict@{%
+ \xywarning@{cancelling dump of PostScript dictionary}}
+
+\xydef@\noDictmessage@{%
+ \xywarning@{\dvitype@\space does not support the use of a header file}}
+\DOCMODE)
+
+These macros are also defined in |xyps.doc|. To avoid warning messages
+about redefinitions, that mechanism has been disabled.
+
+\DOCMODE(
+\DN@{\csname newif\endcsname\ifUsePSdict@@\DN@{}}
+ \ifx\undefined\UsePSdict@@true\else\DN@{}\fi \next@
+
+\ifx\undefined\xyPSdefaultdict
+ \xydef@\xyPSdefaultdict{%
+ \DN@##1.##2.##3@{\gdef\xyPSdictname{xy##1##2dict.pro}}%
+ \expandafter\next@\xyversion.@}%
+\fi
+
+\ifx\undefined\UsePSheader@
+ \xydef@\UsePSheader@#1{%
+ \DN@{#1}\ifx\next@\empty
+% \ifx\xyPSdictname\undefined\xyPSdefaultdict\fi
+ \else \gdef\xyPSdictname{#1}\fi
+ \ifx\xyPSdictname\undefined\xyPSdefaultdict\fi
+ \gdef\xyHeaderMessage@{%
+ It includes a reference to the PostScript file \xyPSdictname.^^J}%
+ \UsePSdict@@true}%
+ \let\UsePSheader=\UsePSheader@
+\fi
+\DOCMODE)
+
+This is used to write the dictionary to a file, suitable for inclusion
+as a resource within any \PS\ document. It is fully conforming to
+Adobe's document structuring guidelines.
+
+\DOCMODE(
+\xywarnifdefined\xyPS@@
+\xywarnifdefined\xyPS@@@
+{\catcode`|=14 \catcode`\%=12 \catcode`\<=1 \catcode`\>=2 |
+ \gdef\xyPS@@<%%>\gdef\xyPS@@@<%!>}
+
+%\xydef@\writePSdict@@{\writePSdict@ \let\writePSdict@@=\relax}
+\xydef@\writePSdict@@{\message{PS: writePSdict@@}\writePSdict@
+ \def\writePSdict@@{\message{write PS relaxed}}}
+{\catcode`|=14 \catcode`\%=12
+ \gdef\writePSdict@{{\begingroup|
+ \immediate\openout\xywrite@=\xyPSdictname \relax
+ \message{<xyps: dumping \xyPSdictname}|
+ \def\PSdict@@@##1{\immediate\write\xywrite@{##1}}|
+ \let\xyPSobeylines@@=\obeyoutlines@
+ \let\firstPS@@=\relax
+ \let\endXYdict@=\relax
+ \PSdict@@@{\xyPS@@@ PS-Adobe-3.0 Resource-procset}|
+ \PSdict@@@{\xyPS@@ Title: \xyPSdictname}|
+ \PSdict@@@{\xyPS@@ Version: REPLACEWITHVERSION}|
+ \PSdict@@@{\xyPS@@ Creator: Xy-ps backend to Xy-pic}|
+ \PSdict@@@{\xyPS@@ DocumentSuppliedProcSets: XYdict}|
+ \ifx\dvitype@\undefined
+ \PSdict@@@{\xyPS@@ For: use with Xy-pic}\else
+ \PSdict@@@{\xyPS@@ For: \dvitype@ use of Xy-pic}\fi
+ \PSdict@@@{\xyPS@@ BeginResource: procset XYdict}|
+ \def\PSspecialdict@@##1{\PSdict@@@{##1^^J}}|
+ \let\PSdict@@=\PSdict@@@ \let\xy@begindvi=\literal@|
+ \UsePSdict@@false\XYpredict@@|
+ \XYdict@@|
+ \PSdict@@@{\xyPS@@ EndResource}|
+ \immediate\closeout\xywrite@
+ \message{>}|
+ \endgroup}}}
+\DOCMODE)
+
+Within the expansion of |\XYdict@| the end-of-line tokens are still active.
+The following expansion seems to work on all systems so far tested.
+
+\DOCMODE(
+\xywarnifdefined\obeyoutlines@
+{\catcode`\^^M=\active%
+ \gdef\obeyoutlines@{\catcode`\^^M=\active \def^^M{^^J}%
+ \newlinechar=`\^^J\obeyspaces}}
+\DOCMODE)
+
+The dictionary of \PS\ commands is split into two pieces according to whether
+they are relevent to general \PS\ effects or only to the \PS\ backend.
+These pieces are generated from code within the files |xyps-pro.tex| and
+|xypsdict.tex|.
+These files have corresponding |.doc| versions for documentation.
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+The following commands cause the parts of the \PS\ dictionary to be read
+from the appropriate files. If |\ifUsePSdict@@| gives |\iftrue| then there
+may be no need to do anything, since the definitions will be subsequently
+loaded from the header file. Normally it is only necessary to read these
+files once, using |\XYpredict@|. However some <driver>s may need it more
+frequently, so instead call |\XYpredict@@| directly.
+
+\DOCMODE(
+\xydef@\XYpredict@@{\ifUsePSdict@@\DN@{}\else
+ \DN@{\xy@begindvi{\xyinputorelse@{xyps-pro}%
+ {\xyerror@{Could not load xyps-pro}{}}\xyuncatcodes}}%
+ \next@
+ \DN@{\xy@begindvi{\xyinputorelse@{xypspatt}%
+ {\xyerror@{Could not load xypspatt}{}}\xyuncatcodes}}\fi
+ \next@ }
+
+\xydef@\XYpredict@r{\XYpredict@@ \let\XYpredict@=\relax \installxyps@}
+\xylet@\XYpredict@\XYpredict@r
+
+\xydef@\XYdict@{\XYdict@@\def\XYdict@{\message{PS relaxed}}}%
+\xydef@\XYdict@@{\DN@{\xyinputorelse@{xypsdict}%
+ {\xyerror@{Could not load xypsdict}{}}\xyuncatcodes}%
+ \expandafter\xy@begindvi\expandafter{\next@}}
+
+\DOCMODE)
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+This command is for use in macro-packages, providing an easy way to force
+the dictionary to load, when it has not done so using the usual mechanisms.
+
+\DOCMODE(
+
+\xydef@\forceload@XYdict{%
+ \let\includeXYPSdict@=\includeXYPSdict@r
+ \let\XYpredict@=\XYpredict@r
+ \let\XYdict@=\XYdict@@ \expandafter\installxyps@ }
+
+\DOCMODE)
+
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Extensions}
+
+Several included files handle standard \PS\ implementations of
+\Xy-pic extensions.
+
+A conditional |\ifxyPSshapes@| is used to indicate whether the special shape
+effects implemented in |xyps-r.tex| can actually be fully supported by the
+current driver. When not available, then an attempt to use these effects
+simply results in a warning message.
+After two attempts the warning message ``turns itself off'';
+subsequent attempts are simply ignored cleanly.
+
+\DOCMODE(
+\xynew@{if}\ifxyPSshapes@ \xyPSshapes@true
+
+\xydef@\xyPScharwarning@@{\xyPScharmessage@
+ \gdef\xyPScharwarning@@{\xyPScharmessage@
+ \xywarning@{...no further PostScript warnings will be given}%
+ \global\let\xyPScharwarning@@=\relax }}
+
+\xydef@\xyPScharmessage@{\xywarning@{%
+ the current <driver> does not fully support PostScript effects}}%
+\DOCMODE)
+
+\paragraph*{Allow new \PS\ effects to be defined.}
+%
+This section describes how |\newxyPSshape| is used to define a new effect
+which is available only in \PS; \ie\ having no analogue elsewhere within
+\Xy-pic.
+
+The new effect will be called via |[|<name>|]|, which gets interpreted as
+referring to |\csname xyshape@|<name>|@\endcsname|.
+Hence a control sequence of this form must first be created,
+if it does not already exist.
+Its initial expansion is simply |\xyundefinedEffect@{|<name>|}{}@@|
+which produces a warning message.
+
+\DOCMODE(
+\xydef@\newxyshape#1#2#3{%
+ \DN@{#3}\ifx\next@\empty
+ \xydefcsname@{shape [#1]}{\csname xyshape@#1@\endcsname}%
+ \else \expandafter\def\csname shape [#1]\endcsname{%
+ \csname xyshape@#1@\endcsname}\fi
+ \DN@{#2}\ifx\next@\empty
+ \expandafter\def\csname xyshape@#1@\endcsname{%
+ \xyundefinedEffect@{#1}{}@@}%
+ \else \expandafter\def\csname xyshape@#1@\endcsname{#2}\fi }
+
+\xydef@\xyundefinedEffect@#1#2@@{%
+ \xywarning@{The #1 #2 effect is not implemented with the current driver}}%
+\DOCMODE)
+
+When an implementation of the effect is available then
+|\csname xyshape@|<name>|@\endcsname| is rebound
+to |\csname xyPSshape@|<name>|@\endcsname|,
+which expands to the contents of |#2| in |\newxyPSshape#1#2|.
+If |#2| is empty then the expansion is the |\xyPSnotimplemented@@`|<name>|'@@|
+warning message, which is especially useful during development.
+
+\DOCMODE(
+\xydef@\newxyPSshape#1#2{%
+ \expandafter\DN@\expandafter{\csname shape [#1]\endcsname}%
+ \DNii@{\relax}\ifx\next@\nextii@ \newxyshape{#1}{}\relax\fi
+ \expandafter\DNii@\expandafter{\csname xyPSshape@#1@\endcsname}%
+ \expandafter\def\nextii@{#2}%
+ \ifx\nextii@\empty\expandafter\def\next@{\xyPSnotimplemented@@`#1'@@}%
+ \else
+ \edef\tmp@{\noexpand\let\expandafter\noexpand\next@
+ \expandafter\noexpand\nextii@}%
+ \expandafter\tmp@\fi }
+
+\xydef@\xyPSnotimplemented@@#1@@{%
+ \xywarning@{This PostScript effect is not implemented yet}}%
+
+\xydef@\xyPSnotfinished@@{%
+ \xywarning@{This effect is not reliable yet; box sizes may be wrong}}%
+\DOCMODE)
+
+\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\paragraph*{The end \& Log}\leavevmode
+
+\DOCMODE(
+\endinput
+
+% $Log: xyps-ps.doc,v $
+% Revision 3.7 1999/02/16 15:12:50 krisrose
+% Interim release (Y&Y fonts now free).
+%
+% Revision 3.6 1998/03/06 01:28:05 krisrose
+% Releasing (with Y&Y fonts).
+%
+% Revision 3.4 1997/05/18 01:13:24 ross
+% Essential bugfixes.
+%
+% Revision 3.3 1996/12/19 03:50:08 ross
+% Maintenance release.
+%
+% Revision 3.3 1996/12/18 09:55:56 ross
+% improvements to the file-loading commands
+% more robust installation procedures
+% shorter tracing messages
+% dictionary no longer loads multiply
+%
+% Revision 3.2 1995/09/19 18:21:41 ross
+% Bug fix release.
+%
+% Revision 3.1 1995/09/05 20:36:33 ross
+% Release!
+%
+% Revision 3.0 1995/07/07 20:13:19 ross
+% Major release w/new User's Guide!
+%
+% Revision 2.13 1995/07/04 15:04:51 ross
+% Ready for release of v3.
+%
+%
+% NEW for version 3.1 by by Ross Moore.
+\DOCMODE)
+
+\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Tell Emacs that this is a LaTeX document and how it is formatted:
+% Local Variables:
+% mode:latex
+% fill-column:77
+% fill-prefix:""
+% End: