summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/xypic/xyrefer.man
blob: 6322060fd17225e8d037ce037d293cfa74133d64 (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
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
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: