=============================================================================

	teTeX-1.0 installation instructions (compiling the sources)

=============================================================================

  1) prerequisites: disk space, ANSI C and C++ compiler (with header
     files + libraries), make utility, lexical scanner, parser generator,
     clean environment
  2) getting the files
  3) install the inputs-tree
  4) unpack the sources
  5) configuring
  6) run make
  7) final configuration steps
  A) appendix: notes on some platforms
  B) appendix: note on moving the binaries around

============================================================================
  1) prerequisites: disk space, ANSI C and C++ compiler (with header files
     + libraries), make utility, lexical scanner, parser generator,
     clean environment
============================================================================

The disk space you need (approx.):
   7 MB for the tar file containing the sources
  30 MB for the tar file containing the complete fonts/macros subtree (texmf)
  30 MB for the unpacked source tree
  75 MB for the unpacked texmf tree
  80-110 MB for object files, binaries, ... during compilation
  15-30 MB for binaries, format files, bitmap fonts, ...

You'll also need an ANSI C compiler, a C++ compiler for pdftex, a make
utility, a lexical scanner and a parser generator. I have used the
GNU utilities (gcc, GNU make, flex, bison) for my tests. gawk 2.15 was
reported to fail whereas gawk 3.x worked fine. To compile xdvi / oxdvi,
you need the include files and libraries for the X Windows System (X11).

Note for Solaris 7 with Sun compilers. The following patches are needed:
  106327-04 SunOS 5.7: Shared library patch for C++
  106300-05 SunOS 5.7: Shared library patch for 64bit C++

Another note for SUN users: SUN's parallel make utility fails on some
of the Makefiles. /usr/ccs/bin/make from Solaris 2 (and later) is fine,
however.

Before building teTeX, make sure you have not inadvertently set any
of the environment variables listed in part 7 below, unless you know
exactly what you're doing.

=============================================================================
  2) getting the files
============================================================================

What you need:
    sources/teTeX-src-1.0.tar.gz    # the sources
    sources/teTeX-texmf-1.0.tar.gz  # the lib-tree with the fonts, macros, ...

The file
    sources/teTeX-texmfsrc-1.0.tar.gz
contains sources for packages that are contained in the texmf tarball.
The texmf tarball contains the files which are needed at runtime. This
archive contains additional files which are not needed, e.g. docstrip
sources of some packages.

============================================================================
  3) choose installation prefix and directory layout
============================================================================

Decide where the "root" of the installation will be, e.g. /usr/local
or /usr/local/teTeX. That directory will be named TETEXDIR in the
following.

The standard directory layout is:
  $TETEXDIR/man			% UNIX manual pages
  $TETEXDIR/share/texmf		% main tree with fonts, macros, ...
				% for tex, metafont + friends
  $TETEXDIR/info		% GNU style info manuals
  $TETEXDIR/bin/$PLATFORM	% binaries

You can omit the "share/" part for the texmf directory if you want.
$TETEXDIR/share/texmf and $TETEXDIR/texmf are auto-detected by configure.
If you choose something different, you have to specify that directory
with the --datadir option of configure.

If you want to leave out the $PLATFORM directory level (i.e. put the
binaries directly into $TETEXDIR/bin), specify the --disable-multiplatform
option for configure.

For now, you have to create the texmf directory and unpack the tar archive
there. Example (the "#" character represents the prompt of your shell,
don't type it in):

  # mkdir -p /usr/local/teTeX/share/texmf
  # gzip -dc teTeX-texmf-1.0.tar.gz \
      | (umask 0; cd /usr/local/teTeX/share/texmf; tar xvf -)

Now, optionally, unpack the texmfsrc tarball:
  # gzip -dc teTeX-texmfsrc-1.0.tar.gz \
      | (umask 0; cd /usr/local/teTeX/share/texmf; tar xvf -)

============================================================================
  4) unpack the sources
============================================================================

Unpack the sources, e.g.:
  # cd /usr/local/src
  # gzip -dc teTeX-src-1.0.tar.gz | tar xvf -

============================================================================
  5) configuring
============================================================================

teTeX uses one large directory tree which you have unpacked in step 3.
You can add additional texmf trees to the configuration by editing the
file teTeX-1.0/texk/kpathsea/texmf.in, e.g. set up a tree where you
store your local additions (TEXMFLOCAL) or all variable data such as
configuration files, format files etc. (VARTEXMF).

That texmf.in will be installed as web2c/texmf.cnf in your main texmf
tree. You can edit that file later, too. Don't forget to remove the word
"original" in the first line of the file if you do any changes.

Have a look at the output of ./configure --help and the files INSTALL in
various subdirectories for instructions. The file texk/kpathsea/INSTALL
explains which environment variables configure uses in determining your
system's characteristics. The list there lacks the variables for C++
which are:
   `CXX':      The C++ compiler to use.
   `CXXFLAGS': Options to give the C++ compiler.
Make sure, the shell variable "noclobber" is not set, then type something
like:

  # cd teTeX-1.0
  # sh -c './configure --prefix=/usr/local/teTeX >configure.log 2>&1' &

Environment variables can be passed the following way:
  # env CC=cc CXX=CC CFLAGS='-O -g' \
      sh -c './configure --prefix=/usr/local/teTeX >configure.log 2>&1' &

You can watch the output of configure by running
  tail -f configure.log

============================================================================
  6) run make
============================================================================

Make sure, the shell variable "noclobber" is not set, then type "make
world" and relax :-) I also suggest to log all the output, e.g. by running
  # sh -c 'make world >world.log 2>&1' &

Before you think that everything is ok, please check the log file for
errors (GNU make always uses the string "Error:" whenever a command returns
an error code) and check if all binaries are build:
  # cd /usr/local/teTeX/bin/i586-pc-linux-gnulibc1
  # ls | wc -l  # should be 125

(The number is only valid if you configure was run with default values
without turning off any of the sub-packages like pdftex.)

The complete list of binaries generated with "ls | sed s@^@\ \ @ | fmt" is:
  MakeTeXPK access afm2tfm allcm allec allneeded bibtex dialog dmp
  dvi2fax dvicopy dvihp dvilj dvilj2p dvilj4 dvilj4l dvilj6 dvips dvired
  dvitomp dvitype e2pall einitex elatex epstopdf etex evirtex fmtutil
  fontexport fontimport fontinst gftodvi gftopk gftype gsftopk inimf
  inimpost iniomega initex install-info kpsepath kpsestat kpsetool
  kpsewhich kpsexpand lambda latex mag makeindex makeinfo makempx mf
  mft mfw mkfontdesc mkindex mkocp mkofm mktexlsr mktexmf mktexpk
  mktextfm mpost mpto newer odvicopy odvips odvitype ofm2opl omega
  opl2ofm otangle otp2ocp outocp ovf2ovp ovp2ovf oxdvi oxdvi.bin patgen
  pdfeinitex pdfelatex pdfetex pdfevirtex pdfinitex pdflatex pdftex
  pdfvirtex pfb2pfa pk2bm pktogf pktype pltotf pooltype ps2frag ps2pk
  pslatex readlink rubibtex rumakeindex tangle tex texconfig texdoc
  texexec texhash texi2dvi texi2html texi2pdf texindex texlinks texshow
  texutil tftopl thumbpdf tie ttf2afm vftovp virmf virmpost viromega
  virtex vptovf weave xdvi xdvi.bin

"make world" is equivalent to
  make all install strip

If you need special previleges for 'make install' and 'make ini', you can
run two make in two separate runs:
  make all
  su
  make install strip

Please note that calling make with an absolute path breaks the configure
scripts.

The following example _does_not_work_:
	/usr/local/bin/make world
	...
	checking whether /usr/local/bin/make sets $MAKE... ./configure:
	${ac_cv_prog_make_/usr/bin/make_set+set}: bad substitution
	...

============================================================================
  7) final configuration steps
============================================================================

Overview:
  - set up PATH
  - check environment
  - configure teTeX using texconfig
  - generate fonts with a batch job
  - set up area for automatic font generation

Set up PATH:
===========
Set up your PATH to include the directory containing the just installed
binaries (e.g. /usr/local/teTeX/bin/sparc-sunos4.1.3); similarly, MANPATH
and INFOPATH to include the relevant newly installed subdirectories,
i.e. $TETEXDIR/man resp. $TETEXDIR/info.


Check environment
=================
Note, that the run-time search paths for all programs that use
the Kpathsea library can be configured by changing the paths in
TEXMFMAIN/web2c/texmf.cnf and changes to these paths does not require
to recompile any of the programs. Therefore, you hardly need to set
extra environment variables. If you define some environment variables,
they overrule the search paths in texmf.cnf unless they have an empty
path component (i.e. a colon at the beginning or end or a doubled colon
in the middle).

The variables to check are:
  AFMFONTS BIBINPUTS BSTINPUTS DVILJFONTS DVIPSFONTS DVIPSHEADERS GFFONTS
  GLYPHFONTS INDEXSTYLE MFBASES MFINPUTS MFPOOL MFTINPUTS MPINPUTS
  MPMEMS MPPOOL MPSUPPORT OCPINPUTS OFMFONTS OPLFONTS OTPINPUTS OVFFONTS
  OVPFONTS PKFONTS PSHEADERS T1FONTS T1INPUTS TEXBIB TEXCONFIG TEXDOCS
  TEXFONTMAPS TEXFONTS TEXFORMATS TEXINDEXSTYLE TEXINPUTS TEXMFCNF
  TEXMFDBS TEXMFINI TEXPICTS TEXPKS TEXPOOL TEXPSHEADERS TEXSOURCES
  TFMFONTS TRFONTS VFFONTS XDVIFONTS XDVIVFS

A simple way to check them is to run
  texconfig confall
once you have set up your PATH. Be careful if some variables are non-empty
and have a look at the locations of the binaries. Not all binaries are
checked, only some.

Configure teTeX using texconfig
===============================
Texconfig allows you to set the defaults for hyphenation, paper size,
print command, metafont mode, etc. You should run theis command
interactively and see what options it offers.

For example, if you are not using A4 format paper, you should make
"lettersize" the default using:
    texconfig dvips paper letter
    texconfig xdvi us

Generate fonts with a batch job
===============================
After you have configured the resolution for the previewer and printers,
you might want to generate some bitmap fonts in a batch job. There are
scripts like allneeded(1), allcm(1) and allec(1) which can generate the
fonts that most users need. For details, have a look at the teTeX
documentation that can be found via
  texdoc TETEXDOC
or the teTeX-FAQ:
  texconfig faq

Set up area for automatic font generation
=========================================
Now, after optionally generating a large set of standard fonts, you
might want to set up an area that other users in your system can use to
put automatically generated fonts into.

If you don't mind that every use puts automatically generated fonts into
the main system tree, just make the main tree writable for that. It can be
done by the command:
  texconfig font rw

If you want the global tree to be read-only (this is the default), just do
  texconfig font ro

But, you should set up some varfonts area and enable the varfonts feature
in that case (replace the string "/some/varfonts/area" by the name of the
directory, where all the generated fonts should go):
  texconfig font vardir /some/varfonts/area
  texconfig font options appendonlydir varfonts

=============================================================================
 A) appendix: notes on some platforms
=============================================================================

teTeX-1.0 was successfully build on the following platforms:

=============================================================================
 B) appendix: note on moving the binaries around
=============================================================================

If you move the binaries to a different location after "make install", you have
to consider the following two things:

- make sure that the texmf.cnf file is still found. If
      kpsewhich texmf.cnf
  fails, you have to set the TEXMFCNF variable. If, for example the
  texmf tree is rooted in /usr/share/texmf, you should set the TEXMFCNF
  variable to
      .:/usr/share/texmf/web2c
  to make sure that all programs will wind the texmf.cnf file. After
  setting the TEXMFCNF variable, try the kpsewhich command again and
  verify that the texmf.cnf file will be found.

- make sure that TEXMFMAIN is defined correctly in the texmf.cnf file.
  Execute the command
      kpsewhich -expand-var='$TEXMFMAIN'
  If this does not give you the root of your texmf directory, you have to
  correct the TEXMFMAIN variable. Juch change the line which defines
  TEXMFMAIN in the texmf.cnf file and set it to the correct directory.
  In the above example you would set:
      TEXMFMAIN = /usr/share/texmf
