summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/xypic/xyrefer.man
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/generic/xypic/xyrefer.man')
-rw-r--r--Master/texmf-dist/source/generic/xypic/xyrefer.man509
1 files changed, 509 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/xypic/xyrefer.man b/Master/texmf-dist/source/generic/xypic/xyrefer.man
new file mode 100644
index 00000000000..6322060fd17
--- /dev/null
+++ b/Master/texmf-dist/source/generic/xypic/xyrefer.man
@@ -0,0 +1,509 @@
+%% $Id: xyrefer.man,v 3.7 1999/02/16 15:12:50 krisrose Exp $
+%%
+%% Wrapper to print ``Xy-pic Reference Manual''.
+%% Copyright (c) 1994-1998 Kristoffer H. Rose <krisrose@brics.dk>.
+%% All rights reserved.
+
+\documentclass{article}
+\usepackage{xydoc}
+\xyoption{knot}
+\xyoption{crayon}
+\xyoption{tile}
+\makeindex
+\begin{document}
+
+\title{ \Xy-pic Reference Manual }
+
+\author{
+ Kristoffer H. Rose\\<krisrose@brics.dk>\thanks{%
+ BRICS, Computer Science, Aarhus University (bld. 540),
+ Ny Munkegade, DK--8000~Aarhus C, Denmark.}
+ \and
+ Ross Moore\\<ross@mpce.mq.edu.au>\thanks{%
+ MPCE (Mathematics dept.), Macquarie University,
+ North Ryde, Sydney, Australia NSW~2109.}
+}
+\date{Version \xyversion\quad<\xydate>}
+\maketitle
+
+\begin{abstract}
+ This document summarises the capabilities of the \Xy-pic package for
+ typesetting graphs and diagrams in \TeX. For a general introduction
+ as well as availability information and conditions refer to the
+ User's Guide~\cite{R95:Xy-picUG}.
+
+ A characteristic of \Xy-pic is that it is built around a "kernel
+ drawing language" which is a concise notation for general graphics,
+ \eg,
+%
+\begin{code}
+\xy (3,0)*{A} ; (20,6)*+{B}*\cir{} **\dir{-}
+ ? *_!/3pt/\dir{)} *_!/7pt/\dir{:}
+ ?>* \dir{>} \endxy
+\end{code}
+%
+$$\docode$$
+%
+ was drawn by the \Xy-pic kernel code
+%
+\displaycode\noindent
+%
+ It is an object-oriented graphic language in the most literal sense:
+ `objects' in the picture have `methods' describing how they typeset,
+ stretch, etc. However, the syntax is rather terse.
+
+ Particular applications make use of "extensions" that enhance the
+ graphic capabilities of the kernel to handle such diagrams as
+%
+\begin{code}
+\xy *[o]=<40pt>\hbox{Round}="o"*\frm{oo},
+ +<5em,-5em>@+,
+ (46,11)*+\hbox{Square}="s" *\frm{-,},
+ -<5em,-5em>@+,
+ "o";"s" **{} ?*+\hbox{Bend}="b"*\frm{.},
+ "o";"s"."b" **\crvs{-},
+ "o"."b";"s" **\crvs{-} ?>*\dir{>}
+\endxy
+\end{code}
+\vspace{-2pc}
+$$\docode$$
+%
+ which was typeset by
+%
+\displaycode
+\noindent
+%
+ using the `curve' and `frame' extensions.
+
+ All this is made accessible through the use of "features" that provide
+ convenient notation such that users can enter special classes of
+ diagrams in an intuitive form, \eg, the diagram
+%
+\begin{code}
+\xymatrix{
+ U \ar@/_/[ddr]_y \ar[dr] \ar@/^/[drr]^x \\
+ & X \times_Z Y \ar[d]^q \ar[r]_p
+ & X \ar[d]_f \\
+ & Y \ar[r]^g & Z }
+\end{code}
+$$\docode$$
+%
+ was typeset using the `matrix' features by the \Xy-pic input lines
+%
+\displaycode
+
+ Features exist for many kinds of input; here is a knot typeset using
+ the `knots and links' feature:
+%
+\begin{code}
+\xygraph{!{0;/r1pc/:/u.7pc/::}="A"
+ "A" [u(2.5)r]!{\xcapv[-1.5]}
+ [u]!{\xcaph\xcapv[1.5]|(-.15)\khole}
+ "A" [u]!{\xcapv[-3]}
+ [u]!{\xcaph[3]>(-.035)\khole}[rr]!{\xcapv[3]}
+ "A" [ur] !{\xunderh}
+ "A" [r] !{\xcapv-} [ur] !{\xcapv}
+ "A" [dr] !{\xunderh}
+ "A" [dd] !{\xoverh} [r]!{\xoverh}
+ "A" [rddd] !{\xunderh} [r] !{\xcapv}
+ "A" [ddd] !{\xcapv-\xcaph-} [r] !{\xcaph-}}
+\end{code}
+$$\docode$$
+%
+ The current implementation is programmed entirely within
+ ``standard \TeX\ and \MF'', \ie, using \TeX\ macros (no |\special|s)
+ and with fonts designed using \MF. Optionally special `drivers' make
+ it possible to produce DVI files with `specials' for extra graphics
+ capabilities, \eg, using \PS.
+\end{abstract}
+
+\pagebreak
+\tableofcontents
+\listoffigures
+
+\begin{figure}[b]
+\hbox to\hsize{%
+ \includegraphics{kris.eps}
+ \raise2em\hbox{Kristoffer Rose}\hss
+ Ross Moore
+ \includegraphics{ross.eps}}
+\end{figure}
+
+
+\section*{Preface}
+
+ This reference manual gives concise descriptions of the modules of
+ \Xy-pic, written by the individual authors. Please direct any
+ \TeX\-nical question or suggestion for improvement directly to the
+ author of the component in question, preferably by electronic mail
+ using the indicated address. Complete documents and printed
+ technical documentation or software is most useful.
+
+ The first part documents the \Xy-pic kernel which is always loaded.
+ The remaining parts describe the three kinds of options: "extensions"
+ in part~??g[:extensions] extend the kernel graphic capabilities,
+ "features" in part~??g[:features] provide special input syntax for
+ particular diagram types, and "drivers" in part~??g[:drivers] make it
+ possible to exploit the printing capabilities supported by DVI driver
+ programs. For each option it is indicated how it should be loaded.
+ The appendices contain answers to all the exercises, a summary of the
+ compatibility with version~2, and list some reasons why \Xy-pic might
+ sometimes halt with a cryptic \TeX\ error.
+
+\paragraph*{License.}
+%
+ \Xy-pic is free software in the sense that it is available under the
+ following ??w![license]??w[copyright] conditions:
+$$
+\xy*+[F-]\txt{\Xy-pic: Graphs and Diagrams with \TeX\\
+ \copyright~1991--1998\quad Kristoffer H. Rose\\
+ \copyright~1994--1998\quad Ross Moore\hglue2.75em\hglue1bp}\endxy
+$$
+\begin{quotation}
+%
+ The \Xy-pic package is ??w![free software]; you can redistribute it
+ and/or modify it under the terms of the ??w![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 ??w![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.
+%
+\end{quotation}
+%
+ In practice this means that you are free to use \Xy-pic for your
+ documents but if you distribute any part of \Xy-pic (including
+ modified versions) to someone then you are obliged to ensure that the
+ full source text of \Xy-pic is available to them (the full text of
+ the license in the file ??c![COPYING] explains this in somewhat more
+ detail~\smiley~).
+
+\paragraph*{Notational conventions.}
+%
+ We give descriptions of the "syntax" of pictures as \BNF??w[BNF]
+ rules; in explanations we will use upper case letters like $X$ and
+ $Y$ for <dimen>sions and lower case like $x$ and $y$ for <factor>s.
+
+
+
+\part{The Kernel}
+??g=[kernel]
+\subsubsection*{\noindent\rlap{\small\bf
+ Vers. \xyversion\ by Kristoffer H. Rose <krisrose@brics.dk>}}
+\def\GROUP{part}\def\FILE{part}
+\CompilePrefix{xy.doc-}
+\inputdoc!{xy.doc}
+
+
+
+\part{Extensions}
+??g=[extensions]
+\def\GROUP{part}\def\FILE{section}%
+
+ This part documents the graphic capabilities added by each standard
+ extension option. For each is indicated the described version
+ number, the author, and how it is loaded.
+
+ Many of these are only fully supported when a suitable "driver"
+ option (described in part~??g[:drivers]) is also loaded, however, all
+ added constructions are always "accepted" even when not supported.
+
+\OSECTION{xycurve.doc}
+\OSECTION{xyframe.doc}
+\OSECTION{xytips.doc}
+\OSECTION{xyline.doc}
+\OSECTION{xyrotate.doc}
+\OSECTION{xycolor.doc}
+\OSECTION{xytile.doc}
+\OSECTION{xyimport.doc}
+\OSECTION{xymovie.doc}
+\OSECTION{xyps.doc}
+\OSECTION{xytpic.doc}
+\OSECTION{xyemtex.doc}
+\OSECTION{xynecula.doc}
+
+
+
+
+\part{Features}
+??g=[features]
+\def\GROUP{part}\def\FILE{section}%
+
+ This part documents the notation added by each standard feature
+ option. For each is indicated the described version number, the
+ author, and how it is loaded.
+
+ The first two, `all' and `dummy', described in~\S\S??g[:all]
+ and~??g[:dummy], are trivial features that nevertheless prove useful
+ sometimes. The next two, `arrow' and `2cell', described
+ in~\S??g[:arrow] and~??g[:2cell], provide special commands for
+ objects that `point'. The following, `matrix' in~\S??g[:matrix],
+ `graph' in~\S??g[:graph], `poly' in~\S??g[:poly], and `knot'
+ in~\S??g[:knot], are "input modes" that support different overall
+ structuring of (parts of) \Xy-pictures.
+
+\OSECTION{xyall.doc}
+\OSECTION{xydummy.doc}
+\OSECTION{xyarrow.doc}
+\OSECTION{xy2cell.doc}
+\OSECTION{xymatrix.doc}
+\OSECTION{xygraph.doc}
+\OSECTION{xypoly.doc}
+\OSECTION{xyweb.doc}
+\OSECTION{xyarc.doc}
+\OSECTION{xyknot.doc}
+\OSECTION{xysmart.doc}
+
+
+
+\part{Drivers}
+??g=[drivers]
+\def\GROUP{part}\def\FILE{sub-section}%
+
+ This part describes `drivers' that customise the parts of the DVI
+ file generated from \Xy-pictures to exploit special capabilities of
+ particular DVI driver programs through \TeX\'s |\special| command.
+ This makes the DVI files non-portable but is needed for full support
+ of some of the \Xy-pic extensions (described in
+ part~??g[:extensions]).
+
+ Figure~??g[:f-drivers] at the end of this part summarises the
+ extensions supported by all drivers.
+
+%Alphabetically...
+\makeatletter
+\def\@listD{\leftmargin1em
+ \parsep 4\p@ \@plus2\p@ \@minus\p@
+ \topsep 4\p@ \@plus2\p@ \@minus4\p@
+ \itemsep\z@ \@plus\p@ }
+\let\@listi\@listD
+\let\PS@orig=\PS
+\def\PS{{\small\PS@orig}}
+\makeatother
+
+\section{Support for Specific Drivers}
+
+\DSECTION{xydvidrv.doc}
+\DSECTION{xydvips.doc}
+\DSECTION{xydvitops.doc}
+\DSECTION{xyoztex.doc}
+\DSECTION{xy17oztex.doc}
+\DSECTION{xytextures.doc}
+\DSECTION{xy16textures.doc}
+\DSECTION{xyxdvi.doc}
+
+\begin{figure*}[bt]
+\begin{center}
+%
+{\makeatletter \global\let\DoXXX=\xydriver@unload@support@@}
+%
+\def\beginXXX{\def\next{\otherbar c\otherbar}%
+ \def\doii##1##2{%
+ \expandafter\def\expandafter\next\expandafter{\next c\otherbar}}%
+ \DoXXX\relax
+ \def\1##1{\begin{tabular}{##1}}\expandafter\1\expandafter{\next}}
+%
+\def\ClearXXX{%
+ \def\doii##1##2{\expandafter\gdef\csname##1XXX\endcsname{-}}%
+ \DoXXX}
+%
+\def\SetXXX#1{%
+ \def\doii##1##2{\expandafter\gdef\csname##1XXX\endcsname{+}}%
+ \csname xydriver@#1@support@@\endcsname}
+%
+\def\XXXentry#1#2{#1&#2}
+\def\XXXlastentry#1#2{#1\\\hline}
+%
+\def\EchoXXX{\gdef\doii##1##2##3{%
+ \ifx##3\relax \expandafter\XXXlastentry \else \expandafter\XXXentry\fi
+ {\tt##1}{##3}}}
+%
+\def\PrintXXX{\gdef\doii##1##2##3{%
+ \ifx##3\relax \expandafter\XXXlastentry \else \expandafter\XXXentry\fi
+ {\csname##1XXX\endcsname}{##3}}}
+%
+\def\Head{\hline \EchoXXX \DRIVERvsEXTENSION &\DoXXX\relax}
+\def\do#1{\expandafter\ifx\csname xydriver@#1@support@@\endcsname\DoXXX
+ \expandafter\dontdoRow\else\expandafter\doRow\fi{#1}}
+\def\doRow#1{{\tt#1}\ClearXXX\SetXXX{#1}\PrintXXX&\DoXXX\relax}
+\def\dontdoRow#1{}
+\def\Rows{\csname xydriversloaded@@\endcsname}
+%
+\def\DRIVERvsEXTENSION{\hbox{\kern.1em %
+ \lower.25ex\hbox{\tiny<driver>}%
+ \kern-.15em$\bigm\backslash$\kern-.11em %
+ \raise.5ex\hbox{\tiny<extension>}}}
+%
+\beginXXX
+ \Head\relax\Rows
+\end{tabular}
+\end{center}
+\caption{Extension implementation replaced by use of \protect<driver\protect>
+ specials.}??g=[f-drivers]
+\end{figure*}
+
+\makeatletter
+\let\do=\eat@ \def\doii#1#2{}
+\let\xyrequire=\eat@
+\makeatother
+
+\medskip\noindent
+The following \TeX\ implementation is also supported,
+but currently uses the \dvips\ driver.
+
+\DSECTION{xycmactex.doc}
+%\DSECTION{xydvipub.doc}
+%\DSECTION{xydviwindo.doc}
+
+Other implementations not specifically mentioned here
+may well work with one of the named <driver>s, though
+perhaps not all features will actually be supported.
+
+\makeatletter
+\let\@listi\@listI
+\let\PS=\PS@orig
+\makeatother
+
+\section{Extra features using \PS\ drivers}
+
+ This section acknowledges the support for extra features available
+ when using a <driver> that supports use of |\special| commands with
+ native \PS. Extra macros are required to take advantage of this;
+ these are loaded automatically in conjunction with extensions
+ specified using the |\xyoption| command, provided a <driver> which
+ supports the extension, as indicated in ??g[:f-drivers], has also been
+ specified.
+
+ Commands are also provided to turn off/on use of these features.
+ Such switches are particularly useful when developing complicated
+ diagrams, or when the intended output device does not support \PS;
+ e.g. for on-screen display. Alternatively, when attempting to use
+ drivers for which no explicit support has been provided, some
+ features may work others may not. Please inform the authors of
+ \Xy-pic of any successes or failures of such attempts.
+
+\inputdoc!{xyps-ps.doc}
+\inputdoc!{xyps-c.doc}
+\inputdoc!{xyps-f.doc}
+\inputdoc!{xyps-l.doc}
+\inputdoc!{xyps-r.doc}
+\inputdoc!{xyps-t.doc}
+
+\section{Extra features using \TPIC\ drivers}
+
+ Similarly a few extensions are supported better when |\special|
+ commands in the \TPIC\ format are supported.
+
+\inputdoc!{xytp-f.doc}
+
+
+
+\part*{Appendices}\label{Appendices}
+\addtocontents{toc}{\protect\contentsline
+ {part}{Appendices}{\protect\pageref{Appendices}}}%
+
+\appendix
+\def\GROUP{appendices}\def\FILE{appendix}%
+
+\ANSWERS
+
+\OSECTION{xyv2.doc}
+
+\section{Common Errors}
+
+ In this appendix we describe some common cases where small mistakes
+ in \Xy-pictures result in \TeX\ error messages that may seem cryptic.
+
+\paragraph*{! Box expected.\\*%
+ ! A <box> was supposed to be here.}
+
+ This message is common when an \Xy-pic <object> is mistyped such that
+ \Xy-pic expects but does not find a \TeX\ <box> construction.
+
+\paragraph*{! LaTeX Error: Bad math environment delimiter.\\*%
+ ! File ended while scanning use of \texttt{\string\xycompiled}.\\*
+ ! Argument of \texttt{\string\codeof@} has an extra \}.}
+
+ These errors can happen while reading an incomplete compiled picture
+ (such a beast is created when \Xy-pic crashes during compilation due
+ to a syntax error or other such problem).
+
+\paragraph*{! Missing \} inserted.}
+
+ This happens when |\endxy| was left out.
+
+
+\bigskip\TODO: Also include the more obscure ones\dots
+
+
+
+\ANSWERS
+\BIBLIOGRAPHY
+\INDEX
+
+\end{document}
+
+% $Log: xyrefer.man,v $
+% Revision 3.7 1999/02/16 15:12:50 krisrose
+% Interim release (Y&Y fonts now free).
+%
+% Revision 3.5 1997/05/29 21:02:36 krisrose
+% Fixed "missing breaks"...and tidied up documentation!
+%
+% Revision 3.4 1997/05/18 04:59:43 krisrose
+% Essential bugfixes.
+% Also includes preliminary movie extension...
+%
+% Revision 3.3 1996/12/19 03:31:56 krisrose
+% Maintenance release
+%
+% Revision 3.2 1995/09/19 18:22:27 kris
+% Bug fix release.
+%
+% Revision 3.1 1995/09/05 20:31:32 kris
+% Releasing!
+%
+% Revision 3.0 1995/07/07 20:14:21 kris
+% Major release w/new User's Guide!
+%
+% Revision 2.14 1995/07/05 22:21:32 kris
+% Buglets...
+%
+% Revision 2.13 1995/07/04 15:11:17 kris
+% Ready to release v3?
+%
+% Revision 2.12 1994/10/25 11:34:25 kris
+% Interim release just before v3 [works with AMS-LaTeX 1.2]...
+%
+% Revision 2.11 1994/07/05 10:37:32 kris
+% Third 3beta release [bug fixes].
+% Experimental graph feature included (for ECCT-94 presentation).
+%
+% Revision 2.10 1994/06/15 12:55:07 kris
+% Second 3beta release: bug fixes.
+%
+% Revision 2.9 1994/06/09 14:59:19 kris
+% Release 3beta.
+%
+% Revision 2.8 1994/04/08 04:30:00 kris
+% Second (bug fix) 3alpha release.
+%
+% Revision 2.7 1994/03/08 02:11:01 kris
+% Release 3alpha.
+%
+% NEW for version 2.7.
+
+% 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: