README for texprL3, Version 0.0a:
=================================

This file contains some notes on installation of texprL3, as well as
some examples for the configuration of this script. But first of all,
we have to deal with the legal aspects:



1) Copyright and license for texprL3:
=====================================

Copyright (C) 1999 Albert Reiner. All rights reserved. This program is
free softare; you can redistribute it and/or modify it under the same
terms as Perl itself.



2) Prerequisites:
=================

As this is a Perl script, you will obviously need Perl. And as we are
using TeX to produce the printout, you will need an installation of
plain TeX and some way to print the *.dvi-files TeX produces. For
texprL3's defaults to work, you must be able to achieve this with the
commands "tex" and "lpr", respectively, and "which" should also work.

texprL3 has been successfully used on a PC running Linux (kernel
2.0.35) with Perl 5.00502 and teTeX.


3) Installation:
================

There are two possibilities: either you are your site's administrator,
and want to make texprL3 available to all users of your system, or you
are a user with restricted privileges who just wants to use texprL3
all by himself. These two cases will affect the choice of some paths
during installation; the corresponding examples will be labeled (a)
for the adminstrator and (u) for the ordinary user. Commands that are
not labelled should be given in either of the two cases.


(*) Unpack:

If you haven't already done so, unzip and untar the distribution file:

    tar -xzvf texprL3-0.0a.tar.gz

This will place any of the files in the distribution file in a
subdirectory texprL3-0.0a of your current directory. Now enter this
subdirectory:

    cd texprL3-0.0a


(*) Documentation:

The documentation is contained in texprL3 itself in Perl's pod format,
and of course you don't really need to make it accessible separately;
you can view it at any time using the perldoc command:

    perldoc texprL3

If, however, you want to generate texprL3's man page and to store it
where man can find it, you should use something like:

    pod2man texprL3 > /usr/local/man/man1/texprL3.1                (a)
or
    pod2man texprL3 | gzip > /usr/local/man/man1/texprL3.1.gz      (a)
or
    pod2man texprL3 > ~/man/man1/texprL3.1                         (u)
or
    pod2man texprL3 | gzip > /usr/local/man/man1/texprL3.1.gz      (u)

(assuming that, in the (u)-cases, ~/man is in your $MANPATH). Now you
should be able to view the man page by issuing

    man texprL3

From now on we will be referring to the man page, and you will know
how to view it.


(*) Placing the script in the path:

The minimum required for installation is to copy or move the Perl
script, texprL3, to a location in your $PATH. Thus you should do any
one of the following:

    mv texprL3 /usr/local/bin                                      (a)
or
    mv texprL3 /usr/bin                                            (a)
or
    mv texprL3 ~/bin                                               (u)

    
(*) Testing the script:

It's probably a good idea to test texprL3 right away; this way you
will quickly discover whether you will have to do further
configuration. So let's simply print some text file:

    texprL3 < text

(assuming text to be the name of the text file). If everything goes
well, your file will be translated and fed to TeX, and after some time
the resulting texput.dvi will be handed to lpr (which, if properly
configured, should know how to print TeX's output). If there is some
problem, you will get a meaningful (hopefully!) error message giving
you an idea of what to configure in your configuration file. See the
man page as well as section (4) "The configuration file" for details.

If this first test is passed but you want to know whether all the
characters you need in your applications are currently implemented,
you should turn to the Examples section of the man page where you can
find a simple Perl command generating suitable input for texprL3. This
should show you how the different characters appear in texprL3's
output, giving you some idea what additional configuration you will
need for texprL3 to work for you.


(*) Create a configuration file:

This is described in more detail in the man page and in the following
section. The name of the file should be

    /etc/texprL3rc                                                 (a)
or
    ~/.texprL3rc                                                   (u)

In case (u) you can also choose any different file name if you set the
environment variable TEXPRLATIN3_RC instead. See the man page for
details.

In case (a) you should take care that you only do configurations that
_all_ the other users of the system will also find useful: it is much
easier to add some functionality than to take it out again, so that
adding more than necessary to /etc/texprL3rc will make individual
users ignore this file at all; if, on the other hand, the system wide
configuration file contains only some minimum configuration,
individual users will be likely to do() your file and add precisely
what they need. If you want to make available more than just the
absolute minimum, just split the file in two and let one call the
other via do(); individual users will then be able to link or input
(via do(), once again) any of the two files.


4) The configuration file:
==========================

See the man page. But here are some more hints:


(1) Suppose that you know that character number X can be represented
by PLAIN TeX's command \Y. Here is what you should do:

(1.1) Add the following line to your configuration file:

        push (@RegExp, [chr(X), '{\\Y}']);

(1.2) Contact the author (see below) and mention that your solution
only uses PLAIN TeX.


(2) In a similar vein, let us suppose that you have a TeX file
"defs.tex" containing some definitions that let you typeset some of
the characters that texprL3 does not currently support. You should:

(2.1) Add the TeX statement

        \input defs

to your $texSetup in the configuration file. If you have been using
the default setting for this variable up to now, you will have to
include those, too:

        $texSetup = <<"ASDF"
        \\tt\\parindent0pt
        \\tolerance50000
        \\input defs
        ASDF

Here, the lines starting \\tt and \\tolerance are the default setting,
and we have only added the \\input defs line.

(2.2) For every character X with a control sequence \Y defined in file
defs, add the following line to your configuration file:

        push (@RegExp, [chr(X), '{\\Y}']);

(2.3) If your solution is sufficiently general and you want to share
it with the rest of the world, you might want to contact the author
(see below).


(3) Suppose that your installation of plain TeX is actually
/usr/bin/TeX/tex.  Then you should add the following line to your
configuration file:

        $TeX = "/usr/bin/TeX/tex";

This will be necessary if `which tex` does not yield the correct path
to the command for starting plain tex, and it will be more secure.


(4) Suppose that the program for printing the *.dvi file cannot be
called just by "lpr" but that you have to issue
"/absolute/path/command -option filename.dvi" instead. Then you should
simply add the following line to your configuration file:

        $printDvi = '/absolute/path/command -option $workDir/texput.dvi'

For another example (using a pipeline to send dvips' output to lpr),
see the man page. This will also make using texprL3 slightly more
secure.


5) The version numbering scheme:
================================

You may wonder what a version number like the current 0.0a does
mean. Well, the scheme for texprL3 is the following: the first number
goes up by 1 when basic new functionality is added, or when changes
are made that break compatibility with earlier versions; the second
number goes up by one at every release changing the Perl code; and the
final letter(s) go up by one (when interpreted in a number system with
the 26 digits "a" through "z") at every release with changes to the
documentation.


6) Contacting the author:
=========================

You can send an e-mail to forgesu@geocities.com (though a reply you
may receive will probably not come from that same account). If you
want to make sure that your mail does not go to /dev/null immediately,
you should put "texprL3" on the subject line, and you should not write
in a language other than German, English, Esperanto, or Latin.

You should definitely consider contacting the author if one of the
following is true:

(*) You want to be notified at the release of any new version;

(*) Point (1) of section (4) ("The configuration file") tells you so;

(*) Point (2) of section (4) ("The configuration file") tells you so;

(*) You have found a bug;

(*) You cannot get texprL3 to work even though you have thoroughly
studied the documentation and the Perl code (but if you are using a
system rather different from the one mentioned in section (2), the
author is likely to be unable to help you);

(*) You have found some configuration that you think might be useful for
a number of other people;

(*) You are willing to contribute to texprL3 by translating or writing
some of the documentation;

(*) You are willing to take over maintenance of texprL3;

(*) You simply like texprL3 and would like to tell the author so;

(*) You think that texprL3 is completely superfluous, as there is a
much simpler solution (that you want to point out to the author).

You should not consider contacting the author if one of the following
is true:

(*) You are just having a bad day, and you want to tell the author so;

(*) You feel like insulting someone, and the author's e-mail address
seems to be calling out for this;

(*) You don't see why anyone would want to use a language other than
English;

(*) You think that texprL3 is completely superfluous, as there is a
much simpler solution (that you do not want to point out to the
author).


And now: proceed to produce great printouts!

Albert Reiner.
1999-04-23.
