-*-text-*- $Id: INSTALL,v 3.23 2011/03/31 06:04:02 krisrose Exp $


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


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

Contents:

-1- Copyleft
-2- Overview of files and where they should be installed
-3- Bugs & comments & where to get help


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

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

  Copyright (c) 1991-2011   Kristoffer H. Rose  <krisrose@tug.org>
  Copyright (c) 1994-2011   Ross Moore          <ross.moore@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, see http://www.gnu.org/licenses/.

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 including of your
modifications) to any of your users that request it (you may charge a
fee for this if you are so inclined).

Note: Some option files may be copyrighted by other people and use a
different (more relaxed) license but the conditions remain the same
for the entirety of Xy-pic.


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

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


IMPORTANT
---------
If you have an older system (more than 10 years) then these
instructions may not be suitable.  Go to the source directory
http://xy-pic.cvs.sourceforge.net/viewvc/xy-pic/src/Historic/
where we keep some older instructions, or ask on the mailing list.


Step 1. Availability & License
------------------------------
These eight files contain general information and should be installed
in a publicly readable place:

  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
  FONTCOPYING   Special license for fonts
  Xy-pic.html   HTML source of Xy-pic home page
  Xy-logo.png   Xy-pic logo (gotta have one of those)

TDS directory: texmf/doc/generic/xypic


Step 2. 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).

TDS directory: texmf/tex/generic/xypic


Step 3. 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 directory: texmf/fonts/tfm/public/xypic


Step 4. 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 directory: texmf/fonts/source/public/xypic


Step 5. PostScript Type1 Fonts
------------------------------
Files `type1/*.pfb' contain versions of the Xy-pic fonts in special
PostScript form 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).

NOTE: Some installations, notably teTeX 0.4, will PREFER using these
fonts over the METAFONT-generated equivalents (IMHO this is a bug in
the MakeTeXPK script).  On those systems we recommend that you ALSO
install the PK fonts to circumvent the problem.

IMPORTANT: Make sure that you do not have any old Xy-pic PostScript
`xy*.pfa' fonts floating around in your system - search for and remove
all files named `xy*.pfa' when you have installed the new fonts.  One
common way old (and wrong) fonts is manifest is when some arrowheads
appear skewed or too thin.

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


Step 6. PostScript Font Metric Files
------------------------------------

Files `pfm/*.pfm' are special files for some font handling software.
Install them if you need them.

TDS directory (usually): texmf/fonts/pfm/public/xypic


Step 7. Adobe Font Metric Files
-------------------------------
Files `afm/*.afm' are special files for the Adobe Type Manager.
Install them if you need them.

TDS directory (usually): texmf/fonts/afm/public/xypic


Step 8. 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 directory (usually): texmf/dvips/xypic


Step 9. PostScript Font Map Files
---------------------------------
Files `map/*' contain PostScript and PDF font mappings that link each
font to the used encoding.

TDS directory (usually): texmf/fonts/map/dvips/xypic


Step 10. PDF Font Encoding Files
-------------------------------
Files `enc/*' contain PDF encoding files (that name each character in
the special Xy-pic fonts).  If you plan to use the PDF backend then
you should copy these files to a place where PDFTeX will find them.

TDS directory: texmf/fonts/enc/dvips/xypic


Step 11. Documentation
----------------------
The documentation is provided in Adobe PDF files.

  doc/xyguide.pdf       User's Guide for everyone.
  doc/xyrefer.pdf 	Reference Manual for experienced users

The source code documentation is also included.

  doc/xysource.pdf	TeXnical documentation for TeXperts
  doc/xypdf.pdf         TeXnical details about PDF generation
  doc/xy*src.tar.gz	the actual source files

TDS directory: texmf/doc/generic/xypic


That's all.


---------------------------------------------------------------------------
-3- BUGS & COMMENTS & WHERE TO GET HELP
---------------------------------------------------------------------------

We 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): xy-pic@tug.org   [preferred]

  Paper mail:	Kristoffer H. Rose
                IBM T.J.Watson Research Center
                P.O.Box 704
                Yorktown Heights, NY 10598
                USA

  W3		<URL: http://sourceforge.net/projects/xy-pic/>

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

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

				    -- Ross Moore and Kristoffer Rose

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

