==============================================================================
Velthuis Devanagari for TeX                                 Installation Notes
Version 2.14                                                       27 May 2006
==============================================================================


This package provides support for typesetting texts in Devanagari script
(Sanskrit and Hindi) in plain TeX and LaTeX. the text is entered in Velthuis
transliteration.

The package is included in famous TeX distributions such as TeX Live and
MikTeX. You have to install this package separately only if:

1. A bug that bothers you was discovered and fixed and the corrected version
   of this package is not yet available in your favourite distribution.

2. A new feature that is important for you was added to the package and it is
   not yet included in the TeX distribution of your choice.

3. You use a distribution which comes without this package.

4. You wish to test our work before it is released for inclusion in standard
   distributions.

5. You wish to help us with develompment.


Release numbering scheme
========================

The project is hosted on a CVS server which means that each file has its own
version number. This is not practical for milestone releases prepared for
publishing on Sarovar, CTAN or elsewhere. Moreover, the preprocessor has its
own version number advanced manually when a new feature is added or a bug is
fixed. Since release 2.14 the whole package shares version number of the
preprocessor. If only macros and/or fonts were changed since the previous
release and the preprocessor remains unchanged, another digit is added to the
version number. Thus release 2.14.1 would mean that the preprocessor remained
at version 2.14 but some macros and/or fonts were modified. Users who update
their distributions will thus know whether they have to compile a new version
of the preprocessor or whether they can keep the existing executable.


Obtaining the package
=====================

The project is officially hosted at http://devnag.sarovar.org and the package
may be downloaded from there. The package may also be downloaded from the
Comprehensive TeX Archive Network (CTAN). Its primary location in UK TUG is
ftp://ftp.tex.ac.uk/tex-archive/language/devanagari/velthuis/

The development version may also be obtained by anonymous CVS. Set your
CVSROOT variable to :pserver:anonymous@cvs.devnag.sarovar.org:/cvsroot/devnag
and log to the server by:

cvs login

When you are asked for the pasword, just press ENTER.

Get the package by:

cvs -z3 co -P velthuis

If you wish to update your existing working copy, "cd" to its top directory
(default is "velthuis") and type:

cvs -z3 up -P


Unpacking
=========

Since version 2.14 the package conforms to the TeX Directory Structure (TDS).
This structure is used in modern TeX distributions on all platforms. Unless
you are a TeXpert we recommend you to keep the package in a separate
directory. If you do it this way, you can easily remove it after you install
upgraded TeX distribution with a new version of Velthuis Devanagari.


Compiling the preprocessor
==========================

The CVS version contains the source code and the Windows executable in the
"bin" directory. Users of other platforms are supposed to compile the
preprocessor themselves. See important notes inside devnag.c.

Releases both on devnag.sarovar.org and CTAN contain also an executable for
OS/2 (eComStation) and statically linked executable for Linux.

Enter the directory with the executable to the PATH variable or move or
symlink the executable to a directory listed in PATH. In UNIX systems you can
verify by "which devnag" that the file can be located.


Install the macros and fonts
============================

You must instruct your TeX distribution to include your directory into the
beginning of search paths. If you have web2c based system (TeX Live, teTeX),
find file texmf.cnf (typically in texmf/web2c directory) and modify the TEXMF
variable. It typically contains:

TEXMF = {!!$TEXMFLOCAL,!!$TEXMFMAIN}

Define the location of the package (before definition od TEXMF) as:

DEVNAG = /path/to/velthuis

and then modify the TEXMF definition as:

TEXMF = {!!$DEVNAG,!!$TEXMFLOCAL,!!$TEXMFMAIN}

Rebuild the file database either by running mktexlsr from the command prompt
or from the texconfig menu (be sure that mktexlsr and/or texconfig come from
the same distribution as tex, latex, etc.).

If you are a MikTeX user, find MikTeX menu, open MikTeX Options, select the
Roots tab, use the Add button to add the "velthuis" directory, move it to the
top location by the Up button. MikTeX also needs to know about the fonts.
Locate your updmap.cfg file. It usually resides in X:\texmf\web2c directory (X:
is the drive with your MikTeX installation) or you may have a local copy in
X:\localtexmf\web2c. The file must contain the following line:

MixedMap dvng.map

If it is not present, put it to the end of the file. Finally refresh the file
database pushing the Refresh FNDB button.

Note: We rarely add new files or remove files or change their locations. Once
you install the package from CVS and update it by "cvs up -P" without removing
the "ls-R" file, TeX will immediatelly use the new files. It is NOT necessary
to rebuild the database.

Test your installation
======================

The kpathsea library now should be able to find your files. Try the following
commands:

kpsewhich dev.sty
kpsewhich dvng10.tfm
kpsewhich dvng10.mf
kpsewhich dvng10.pfb

If the files are not found or if files from other directories are found
instead, there is something wrong with your installation. It makes no sense to
continue. Return to the previous step and fix the installation.


Make font information files
===========================

Drivers dvips, dvipdfm, pstopk as well as pdftex require information on fonts.
Create them by:

updmap --enable=MixedMap dvng.map

If it says that the fonts are already known and nothing will be changed, it
means that updmap knows some older version. In such a case just run updmap
without any arguments.

This step is not necessary with MikTeX because it was already done during macro
installation (updmap just adds the mentioned line to updmap.cfg and generates
necessary *.map files).


Run a sample document
=====================

Make a copy of a sample file doc/generic/velthuis/misspaal.dn into another
directory. Now "cd" to that directory and run the file through the
preprocessor by:

devnag misspaal

The resulting misspaal.tex file can then be processed by latex into
misspaal.dvi or by pdflatex directly to misspaal.pdf. If you get the same
result as doc/generic/velthuis/misspaal.pdf, then -- {\dn "saabaa"s} -- your
installation is correct. Now you can read the manual (available both as
manual.tex and manual.pdf in the doc/generic/velthuis/ directory) and create
your own Devanagari documents.


Frequent errors
===============

* (La)TeX cannot find files (*.sty, *.fd, dnmacs.tex)

  Make sure that the directory with Velthuis Devanagari is mentioned in the
  TEXMF variable (teTeX, TeX Live) or selected in MikTeX options in the Roots
  tab. Refresh the filename database (it never harms anything).

* PostScript files created by dvips does not contain Type 1 fonts, they are
  replaced by roman fonts although dv*.pfb were loaded

  You probably have an old version of dvng.map earlier in the search path or
  different version of Type 1 fonts earlier in the search path. The PostScript
  names of the fonts have changed. PdfTeX can often cope with it but dvips
  cannot and the resulting PostScript file is damaged and unusable. Be sure
  that the directory with the Velthuis Devanagari package is at the beginning
  of the TEXMF variable (teTeX, TeX Live) or selected in MikTeX options in the
  Roots tab as the first one. Then refresh the filename database. Non-MikTeX
  users should also run updmap without arguments.
