Back to files

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:

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.