               Installation Instructions for the ITRANS 4.04
                to work with the ITRANS Song Book (ISB) 3.1,
                      TeX/LaTeX and the devnag font 
                            (on Unix systems)

=============================================================================
If you have a Unix machine which has ghostview, dvips, a c-compiler, lex,
and yacc installed,  you can follow the instructions I have given below 
as a first try to get ITRANS working with the ISB.  I hope these detailed
instructions will get things working for you but if they don't, help is 
available from me or from Avinash Chopde (avinash@acm.org).

This is a heavily modified version of the file install.unx which comes with
ITRANS.

If you are installing ITRANS/ISB on a PC or a Mac and need help, get in
touch with Avinash Chopde (avinash@acm.org).
=============================================================================

Ok, ready?  Here we go (I am assuming that % below is the Unix prompt):  

1: Ftp and Untar the Archive:

   Go to your home directory (~), and do:

   % mkdir itrans
   % cd itrans

   Now anonymous ftp the ITRANS archive (files itrans40.tar.Z and 
   itransps.tar.Z) in dir /pub/itrans-4), the devnagari fonts (file
   devnag.tar.gz in /pub/devnag), and the ITRANS Song Book source 
   (file isongs-3.1_src.tar.gz in /pub/isongs) from the anon ftp server 
   chandra.astro.indiana.edu.   Once done, you should have:

   ~/itrans/itrans40.tar.Z
   ~/itrans/itransps.tar.Z
   ~/itrans/devnag.tar.gz
   ~/itrans/isongs-3.1_src.tar.gz

   Unpack them:

   % zcat itrans40.tar.Z | tar xvf -
   % zcat itransps.tar.Z | tar xvf -
   % gunzip -c devnag.tar.gz | tar xvf -
   % gunzip -c isongs-3.1_src.tar.gz| tar xvf -

   This will create: 

   a) ITRANS stuff - the directories doc/, lib/, src/, devnagri/ and a 
   bunch of other files in ~/itrans, and

   b) ITRANS Song Book stuff - the directory isongs-3.1/ and its descendants.

   Don't delete the *.tar.(gz,Z) files yet, you may need them later if you
   mess things up (unless disk space is getting low).

2: Make and install ITRANS:

   Do the following:

   % cd src
   % cp makefile.unx makefile

   Now you have to edit the makefile to tell it all the local stuff.
   We will go through it step-by-step to help you do this:

   a)  If your machine is running system V-ish Unix (almost all machines
       do that nowadays, except perhaps Suns running SunOS 4.1.*), make
       sure that the line

       SYS = -DSYSV

       is uncommented.

   b)  Specify the paths for ITRANS like this:

       BINDIR = ~/itrans/bin
       TFMDIR = ~/itrans/lib
       HEADERDIR = ~/itrans/lib
       MANDIR = ~/itrans/doc

   c)  Follow the directions about specifying libraries (FLIBS) and do 
       what the makefile says.  If you don't know what all this means,
       just leave it alone.

   d)  Tell it the name of your c compiler (usually cc):

       CC = cc
  
   We are doing good!  Now keep your fingers crossed and type:

   % make		# or, "make noansi" if you compiler is non-ansi
   % make install

   IF YOU GET ERRORS DURING THE MAKE:

   If the make in the src directory fails (due to a non-ansi compiler),
   you will need to re-edit the makefile (in some cases, even the sources)
   to get it to compile (what a drag!).  If you are not a c-hacker, you have 
   two options:  (1) Save all the error output and send it either to me or
   to Avinash so we can help you, or (2) Give up (there are better things to 
   do in life than installing ITRANS).
   
   If, on the other hand, the make works, great.  You should have an executable 
   called "itrans" in the ~/itrans/src directory if you did a "make" or in 
   the ~/itrans/bin dir if you did a "make install".  In any case, make sure 
   that the executable ends up in ~/itrans/bin. 

   We are now ready to start the real work of getting ITRANS to work with TeX.

3: Set up the Environment Variables and Paths Required for ITRANS:

   The most important environment variable that must be set is ITRANSPATH.
   It must be set to the directory where the *.ifm, *.afm, *.tfm files reside.  
   This should be set in .cshrc, .profile, or .login:

   ITRANSPATH=~/itrans/lib;export ITRANSPATH (if you are using sh)
   
   or 

   setenv ITRANSPATH ~/itrans/lib (if you are using csh or tcsh)

   See the file named "shenv" in the lib directory for all the variables 
   that need to be set.

   Now add the itrans bin path to your PATH environment variable, so that the
   command "itrans" can be found:

   set path=($path ~/itrans/bin)

   At this point, everything is set for ITRANS to work on its own (but not
   with TeX/LaTeX yet).

4: Make ITRANS work with TeX/LaTeX:

   To use the system with the TeX  language, you need to setup the files
   and fonts so that TeX/LaTeX and dvips can locate them.  The following 
   steps are necessary.

   The files mentioned in this section all reside in the ~/itrans/lib directory
   (or, in the TFMDIR directory, if set differently in the Makefile), of this 
   itrans package.

   Do the following to set up the fonts as well as the subsidiary files
   that ITRANS needs (this assumes that TeX on your machine is using the
   fonts in the pk format; ask your sysadmin if this is true):

   a) Do

   % cd ~/itrans/lib
   % ln -s ../devnagri/*.tfm .
   % ln -s ../devnagri/pkfiles/*.pk .
   % ln -s ../devnagri/*.mf .
   % ln -s ../devnagri/dev.sty .
   % cp ../isongs-2.12/idevn.tex .
   

   b) Edit your .cshrc file (or .profile) to set the following environment
   variables (the following is for .cshrc):

   setenv TEXCONFIG .:~/itrans/lib:
   setenv TEXINPUTS .:~/itrans/lib:
   setenv TEXFONTS :~/itrans/lib
   setenv TEXPKS :~/itrans/lib
   setenv MFINPUTS :~/itrans/lib

   You'd have to source the .cshrc file or the .profile to enable these,
   of course.

   Steps 2-4 are to set up ITRANS to work with TeX/LaTeX.  Now we
   have to make sure it works with dvips (for PostScript output generation).

5: Make sure you have the correct DVIPS: 

   You must have the dvips version that handles PostScript fonts.  (Tomas 
   Rokicki's version 5.41 or newer, see the FAQ in comp.text.tex for more 
   information.)

   If you have the right dvips, great.  You are all set up, at least 
   theoretically, for both TeX/LaTeX and PostScript output generation.

6: Try it out:

   Print out the document vnehru.itx in ~/itrans/doc (it is the user's manual
   for the "itrans" program).  idoc.itx contains transliterated hindi/tamil 
   text, so it has to be converted to a normal TeX file.

   Run these commands:

   % itrans -i vnehru.itx -o vnehru.tex
   % latex vnehru
   % dvips vnehru
   % lp (or lpr) vnehru.ps (to print it, assumes lp or lpr sends data to 
                          a PostScript printer)
     or

   % gs (or ghostview) vnehru.ps (to preview it)

   Do the same for the reference manuals, devn.itx and tamil.itx, if you want.

   You can also test the sample data by transliterating the sample docs in
   ~/itrans/doc.  Use the above examples given to print or preview the files.
   Files ending in .itx are TeX/LaTeX files, and files ending in .ips are
   PostScript files meant for the dumb interface of itrans (see install.unx
   which comes with ITRANS to see how to deal with *.ips files - I am not 
   particularly intested in supporting this format since it is already 
   obsolete).  Follow the appropriate command sequences mentioned earlier to 
   print out the files.

   If you get errors at this point, first see if you can figure them out.
   If not, save the error output and send mail to me or to Avinash.

7. Set up the ITRANS Song Book:

   Congratulations!  If you got here ok, you have successfully installed ITRANS 
   to work with TeX/LaTeX and dvips.  You are almost ready to convert an ISB 
   document.  There are a few things which need to be set up first though.

   a) Edit your .cshrc and set up the following alias

    alias song 'make -f ~/itrans/isongs-3.1/makefile.unx \!*.ps'

   This allows you to type "song filename_prefix" to start the transliteration
   on a *.s, *.itx, or *.tex file (such that to convert 1.s, you would say 
   "song 1").

   b)  Go to ~/itrans/isongs-3.1.  You have to edit the makefile here a 
   little.  Go down the file and specify the following variables:

    ITHOME=~/itrans
    ITRANS=$(ITHOME)/bin/itrans
    ISHDR=$(ITHOME)/isongs-3.1/isitx.hdr
    ISONGCAT=$(ITHOME)/isongs-3.1/isongcat
  
   c)  Find the .s.ps: section.  I'd make sure it looks like this:

        cat $(ISHDR) $*.s > $*.itx
        echo "\\end{document}" >> $*.itx
        $(ITRANS) -i $*.itx -o $*.tex
        -$(RM) $*.itx
        latex $*
        -$(RM) $*.tex
        -$(RM) $*.log
        -$(RM) $*.aux
        #xdvi $*
        dvips $* -o $*.ps
        -$(RM) $*.dvi
        gs $*.ps
        #xpsview $*.ps
        #lp $*.ps
        -$(RM) $*.ps

    This takes a *.s song, converts it into *.tex, itrans'es it, LaTeX's
    it, dvips's it, and preview it on the screen.

    d) Try it now:

    % cd hindi/0
    % song 1

    If everything works, you should see it churn and finally display the
    song in hindi on your screen.  If not, save the output of the "song 1" 
    command and send it to me or to Avinash for debugging.

8.  If everything works, go ahead and delete the *.tar.(gz,Z) files.

Good luck!
--
Anurag Shankar                               (anurag@chandra.astro.indiana.edu)
Astronomy Department, Indiana University               812-855-4838 
Swain West 319, Bloomington, IN, 47405, USA            812-855-8725 (fax)
WWW home page: http://chandra.astro.indiana.edu
