-*-text-*- $Id: INSTALL,v 3.2 1995/09/19 18:22:27 kris Exp $

	   ================================================
	   INSTALLING THE Xy-pic DIAGRAM TYPESETTING MACROS
	   ================================================

This file explains how you install the files in the `run' distribution
of Xy-pic.  See `README' for general information.

Contents:

  -1- Copyleft
  -2- Updating from version 2.6 (and earlier)
  -3- Overview of files and where they should be installed
  -4- Information for specific systems
  -5- Bugs & comments


----------------------------------------------------------------------
  -1- COPYLEFT
----------------------------------------------------------------------

Note that the entire Xy-pic package is distributed with copyleft:

  Copyright (c) 1991-1995	 Kristoffer H. Rose  <kris@diku.dk>
  Copyright (c) 1994-1995	 Ross Moore   <ross@mpce.mq.edu.au>

  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.

(Some option files are copyright by other people but the conditions
remain the same for any file distributed as part of Xy-pic).

What this means is that if you install Xy-pic then you should (1) make
sure that the file COPYING is accessible to the users, and (2) be
prepared to provide Xy-pic (including sources) to any of your users
that request it (you may charge a fee for this if you are so
inclined).


----------------------------------------------------------------------
  -2- UPDATING FROM VERSION 2.6 (AND EARLIER)
----------------------------------------------------------------------

IMPORTANT: If you have installed release 3.0-3.1 or 2.7-2.12 then you
should skip this section. If you have not and use version 2.6 THEN READ
IT !

Xy-pic release 2.7 was almost a complete rewrite of Xy-pic; later
releases are updates to this version.  If you are using version 2.6 (or
some earlier version) then note the following:

* All the fonts have been redone AND renamed (except two that have not
  changed).  Thus installing version 2.12 will not break any DVI files
  you already have that were typeset using the old fonts.

* The distribution contains new versions of the files `xypic.tex' and
  `xypic.sty' that load Xy-pic 2.12 in a special compatibility mode.
  Thus retypesetting your documents will create DVI files using the
  new fonts.  If you wish to keep the old `xypic.tex' and `xypic.sty'
  then you should rename them before installation; we suggest naming
  them `xypic-2.tex' and `xypic-2.sty' and REMEMBER to change the line
  `\input xypic' in `xypic-2.sty' to `\input xypic-2' !

* There are a few points where the backwards compatibility is not
  perfect -- these are noted in the documentation.


----------------------------------------------------------------------
  -3- OVERVIEW OF FILES AND WHERE THEY SHOULD BE INSTALLED
----------------------------------------------------------------------

In this section I explain where the different groups of Xy-pic files in
the `run' distribution should be installed.  For each file category I
indicate the location recommended by TDS, the TeX Directory Standard (as
formed by a TUG working group of that name).

IMPORTANT: If you have users currently using version 2.6 then make sure
you read the preceeding section before this!  PLEASE also check the next
section for any system specific considerations.

SPACE REQUIREMENTS: The complete installed Xy-pic, excluding manuals,
bitmap fonts, and sources, takes up 690k; the majority (618k) is used
for the actual macros, the rest is TeX font metrics and other support
files.


AVAILABILITY & LICENSE: These seven files contain general information
and should be installed in a publicly readable place (if necessary you
may give them an `xy' prefix):

  README	generic information on Xy-pic
  CATALOG	version information and summary
  TRAILER	announcement and availability
  INSTALL	how to install (this file)
  MANIFEST	list of all files
  VERSIONS	the RCS version ids of all source files
  COPYING	GNU General Public License

TDS location: texmf/doc/generic/xypic


MACROS: Files `texinputs/*' are TeX and LaTeX macro files that must be
installed in a place which TeX and LaTeX will search (e.g., with un*x
TeX, a directory users include in the TEXINPUTS environment variable).
The `.sty' files should go in a directory searched by the LaTeX only;
all other files in a directory searched by all formats.

TDS location: texmf/tex/generic/xypic


FORMAT GENERATION FILES: Files `texinputs/*.ini' make it possible to
create TeX formats for with Xy-pic preloaded (usually this involves
running a special `initex' program; consult your system documetation for
details).

TDS location (I think): texmf/tex/generic/xypic


TeX FONT METRIC: Files `texfonts/*.tfm' should be installed in a
directory that TeX will search for fonts (e.g., with un*x TeX, a
directory users include in the TEXFONTS environment variable).

TDS location: texmf/fonts/tfm/public/xypic


METAFONT SOURCES: Files `mfinputs/*.mf' should be installed in some
directory where the METAFONT program will search for them (e.g., with
un*x TeX, a directory included in the MFINPUTS environment variable).

NOTE: The METAFONT source files are only useful on installations where
the printer driver and previewer can utilise them to generate the
required bitmap fonts `on-line'.  If this is possible on your
installation then please use it: it saves substantial amounts of space
and means that you will automatically use fonts optimised for each
printer (provided evrything is correctly set up, of course).

TDS location: texmf/fonts/source/public/xypic


BITMAP FONTS: Files `pkfonts/cx<N>/*.<N>pk', where <N> is some number,
contain bitmap font files and should be installed where DVI previewers
and printer drivers will find them (e.g., with un*x, the `xdvi' program
should see them through the XDVIFONTS environment variable).

NOTE: These are only needed (and only recommended) for installations
that can't use the METAFONT sources directly but do have a 300 dpi
laserprinter driver that accepts PK bitmap font files.  The bitmaps
where generated using the standard `cx' METAFONT mode.

TDS location: texmf/fonts/pk/cx/public/xypic/dpi<N>


PostScript TYPE1 FONTS: Files `psfonts/*.pfa' contain versions of the
Xy-pic fonts in a special PostScript format that may be useful on some
installations.  They should be installed where the applications using
them look for such fonts (if used with DVIPS then the `ps/xypic.map'
file from the next group should also be installed).

TDS location: texmf/fonts/type1/public/xypic


PostScript HEADER FILES: Files `ps/*' contain PostScript header files.
If you plan to use the PostScript extension option then you should copy
these files to a place where your PostScript DVI driver will find them.

TDS location (usually): texmf/dvips


DOCUMENTATION: Finally, the typeset User's Guide is distributed as a
DVI file which you should be able to print (or preview) once you have
installed the fonts (as source or bitmaps as applicable for your
system):

  doc/xyguide.dvi	User's Guide, typeset using the kernel Xy-pic fonts

Similarly, the reference manual for the kernel and the distributed
options is included in the same format:

  doc/xyrefer.dvi	Reference Manual, using Xy-pic fonts

Notice that these are portable and thus do not exploit any of the
non-portable extensions: in order to get documents with all features
enabled you should get the PostScript version as described in `TRAILER'
or generate them from the sources.

TDS location: texmf/doc/generic/xypic


SOURCES: are NOT included with the `run' distribution (they take up
another 1700k), however, they should be available from where you got
this file (see TRAILER for the names).


----------------------------------------------------------------------
  -4- INFORMATION FOR SPECIFIC SYSTEMS
----------------------------------------------------------------------

UN*X: The above procedure except the documentation can be done
automatically by the commands `make install' if you get the source
distribution as described in TRAILER and change the configuration
section of the provided Makefile to reflect your local file system
conventions.  See the `MAKE' file of the source distribution for details
on how to generate the entire system from the sources alone.

If you use a TDS conformant setup then all you have to do is run the
command `make TEXMF=texmf install' where you should replace `texmf' with
the full path to your `texmf' directory.


VMS (thanks to Austin Benson <austin@shapel.ug.eds.com> and Ralf
Gaertner <gaertner@cthulhu.rhein-main.de>):

(1) VMS tfm and pk files are in a funny file format, which means they
    EITHER should be generated from the mf source on a VMS machine, OR
    be converted by a conversion program such as BILF (part of the 1995
    DECUS TeX distribution and the ZOO distribution although the latter
    is reported to only work on VAXen).

    FIX: Install .mf sources and pregenerate .tfm and .pk files
    manually OR convert with BILF or a similar program.

(2) At least some (OLD) versions of TeX for VMS has a `buglet' to do
    with searching for input files: if you go \input <filename> on VMS
    then TeX prepends the filename with a chained logical "tex_inputs:"
    - equivalent to a Unix path. Unfortunately \openin does _not_ do
    this - although on Unix systems \openin will search the TEXINPUTS
    path just as \input does.

    FIX: Change lines .... in xy.tex from

\xydef@\xyinputorelse@#1#2{\openin\xyread@=#1
 \ifeof\xyread@ \DN@{\openin\xyread@=#1.doc
 \ifeof\xyread@ \DN@{#2}\else \DN@{\closein\xyread@\input#1.doc }\fi \next@}%
 \else \DN@{\closein\xyread@\input#1 }\fi \next@}

    to

\xydef@\xyinputorelse@#1#2{\openin\xyread@=#1
 \ifeof\xyread@ \DN@{\openin\xyread@=tex_inputs:#1.doc
 \ifeof\xyread@ \DN@{#2}\else \DN@{\closein\xyread@\input#1.doc }\fi \next@}%
 \else \DN@{\closein\xyread@\input#1 }\fi \next@}


MAC WITH Textures:  See the special file `INSTALL.Textures'.


MAC WITH OzTeX:  See the special file `INSTALL.OzTeX'.


----------------------------------------------------------------------
  -5- BUGS & COMMENTS
----------------------------------------------------------------------

I will appreciate reports on any problems you may encounter and
opinions you have on how the usefulness of Xy-pic can be improved.
Please report using either

  Electronic mail (Internet): kris@diku.dk	[preferred]

  Paper mail:	Kristoffer H. Rose
		DIKU, University of Copenhagen
		Universitetsparken 1
		DK--2100 K{\o}benhavn {\O}
		DENMARK

  Phone:	+45 35321420
  Fax:		+45 35321401 att. K.Rose / K.Outzen

You can get the latest news of my whereabouts by opening my WWW home
page quoted below.

----------------------------------------------------------------------

This is the end of INSTALL.  I hope you'll enjoy Xy-pic!

----------------------------------------------------------------------

	       Kristoffer H{\o}gsbro ROSE  <kris@diku.dk>

      DIKU, Universitetsparken 1, 2100 K{\o}benhavn {\O}, DANMARK
      Phones: +45 35321400 direct: +45 35321420 fax: +45 35321401

	    World Wide Web  <URL: http://www.diku.dk/~kris/>

----------------------------------------------------------------------
