SITE: UK.AC.RHBNC.VAX
DIRECTORY:UHAH:[208.CRUDE]

FILE:  AAAREAD.ME.  This file lists the intended contents of this directory.
Note that not all these will be included when I send files out; you can get
the missing ones if you have FTP access to this site.

**********************************  NOTE  **********************************

COPYRIGHT ( C ) R.M.Damerell, 1988.

Permission is given to any person to make and distribute copies of this
software, subject to the following conditions:

1. All copies of the software must carry an exact copy of this notice.

2. This software is distributed free of charge, "AS IS" with absolutely no
guarantee of performance. Any persons receiving or using this software must do
so entirely at their own risk. Neither the authors nor their institutions
accept any liability for any defects of this software, or for any consequential
loss or damage however caused.

3. Any person who changes this software must clearly mark it as modified and
add a note describing the changes made. Anybody making substantial additions or
improvements is requested to give copies to me (RMD).

****************************** VERSION 3 (1990) ********************************


First, I want to thank G-H Knauf, M Rawohl, J Warbrick, A Trevorrow and P King,
for many improvements which I have tried to incorporate into the WEB program.
At present, this version runs on VMS and SUN-OS3.5 and "similar" versions of
Unix. I have tried to adapt it to web2c; but the language that web2c translates
is still nothing like Standard Pascal. The main changes include:

Several new coding schemes;

Separate horizontal and vertical magnifications;

Two flavours of screenview

Barring bugs, I intend V3 to support the Level 0 device driver standard,
except as follows:

2.6.1.  (Location of origin). This must be allowed to move or else a
negative \hoffset would force off the paper text which on a proper printer
would be on the paper.

2.6.3. (Range of movement). Standard specifies 2^31 units in any direction;
Crudetype only allows 2^31-1 because that is VMS Pascal's maxint.

3. Configuration. /D lets you specify the location of fonts. I dont know
what the Standard means by changing the "naming scheme" for fonts, but I am
sure you cannot do this without recompiling.

4.1. Font formats. Since Crudetype does not use raster data, it reads TFM
files only.

5. For reasons explained in my original paper (Tugboat v7) you cannot get
tolerable results on a lineprinter by merely rounding DVI units to printer
units. Crudetype has to do something much more complicated.

I have only seen a draft of the Standard, I dont know what changes may have
been made since.


                                   CRUDETYPE

is written in PASCAL and WEB. In order to reduce the confusion of file names,
I have had to try to introduce a definite scheme for naming files. In general,
all files that belong to any particular operating system will have names that
start with the system's name (truncated if necessary), and end with a (system-
dependent) suffix indicating the type of file.  Any exceptions should be
documented here.  e.g. the Unix Makefile ought to be called UNIX.COM or
similar.  Each file will start with a comment giving its name.

CRUDETYPE.WEB       the program, now Version 3
CRUDETYPE.CH        Dummy change file. (Its purpose is to let you weave
                        Crudetype, see below).


VMS.CH              VMS Change file.
VMS.COM             Command file giving some idea how to build Crudetype on VMS.
                        I am getting less and less interested in VMS; I dont
                        expect to make any serious attempt to debug this.
VMSUSER.TEX         Users documents. These are VMS-specific and will need to
VMSHPGF.TEX             be rewritten on other sites. 


UNIX.CH             Unix Change file (written by Peter King, Heriot-Watt,
                        and copyrighted by him on the same terms. Altered by RMD.
                        I have made so many changes to all these files that I 
                        think any bug reports should come to me ).
Makefile            Unix Makefile for the above. (ditto)
UNIXEXT.C           Routines in C to bypass defects in Unix Pascal. Mostly
                        copied from H.Trickey's   DVITYEXT.C
UNIX.CAP            printcap file for some printers. buggy. I cannot get X-OFF flow
                        control to work properly.
UNIXCRU.MAN         Attempt at Unix style man page. This must be edited to reflect
                        local conditions.


PRIMOS.CH           Primos change file, by J.Warbrick.
PRIMOS.CPL              Command file for building this version. 


NOSVE.CH            change file for NOS/VE, by courtesy of G-H Knauf
                        and M.Rawohl, University of Hannover.
                        (Provisional. Please send bug reports to RMD)
NOSVE.DOC           Document for this, 
NOSVE.COM           a NOS/VE system procedure to call this program
                        (Needs rewriting, I dont know how)
NOSVEBIND.CYB       CYBIL routines for file handling (N.Schwarz, Ruhr
                        University Bochum).

At present the Primos and NOS-VE files are all out of date; they belong to V2
and I cannot do anything about this as I have no access to these machines.


PRO-PAS.CH          Attempted change file for MESS-DOS and Pro-Pascal. Failed
			because the program is too big for Pro-Pascal, even
			with the so-called "big" model and with some fudges
			to reduce the data size. The worst thing is that the 
			diagnostics are completely useless. There is nothing 
			to show how much too big it is, or which bit is too big. 
			You dont even get told where in the program it failed;
			the error is arbitrarily attached to the last line. 


NOSCHEME.ADD        This has to be used with TFM files that do not have coding
                        schemes. Read it first, then append it to CRUDETYPE.WEB
                        then Tangle as usual. I believe it is system-independent.


PHILIPS.CH          Obsolete change file for Philips printer.
HP.CH               Change file for Hewlett-Packard Laserjet+
HPGF.CH             Same, but uses GF files instead of PXL. This version
                    is experimental, and slow. Allows /L = Landscape, 
                    /E and /O = print even/odd pages only.


CRUDETYPE.PAS       etc. Files produced during compilation. Not distributed.

W2C.*		    Modified version of WEB2C. See below.

PHILIPS only works on a particular model of Philips GP300, with a particular
suite of resident fonts (listed in the .CH file). It is really intended as a
pattern to show what a printer change file should look like. There is a lot of
scope for improvement, especially in the design of the multi-character
commands. Because TEX characters are narrower than Philips, it seems that if
you format a document correctly for ( say) A4 paper, it falls off the paper
when printed on the Philips. This is most irritating, and I do not know any
cure.
Later: I have had to abandon any serious attempt to debug this version. The
printer has been removed.

HP cannot do landscape mode. (HPGF can) This could presumably be fixed fairly
easily, given time. Also I can no longer test HP, because all the PIXEL files
have been removed.

                                 INSTALLATION

This requires Pascal and the Stanford Tangle program (You will have Tangle if
you got your TeX software from a reputable source.) In theory, you compile
Crudetype the same way as TEX; assemble a suitable change file; then run it
through Tangle and the Pascal compiler. In order to write Crudetype in any
reasonably well-structured way I had to break the WEB rule that macros be
defined before they are used. For simple and parametric macros, this rule is an
illusion. In Tangle V4, this non-rule has been abandoned. If you use a macro
before defining it TANGLE prints an error message "This identifier has already
appeared" but expands it correctly. Such errors can therefore be disregarded.
For numeric macros it is necessary to define WEB macros before use; I have
conformed to this rule.

When Crudetype was first written, I hoped to arrange that the installer could
just take Change files for the local system and printer, concatenate them, and
go. Unfortunately, it isnt that simple. Even if you are lucky enough to have a
change file named after your system, there are often site-dependent variations.
(Some of these are mentioned below). No matter what printer or machine you have
in mind, I recommend that you get copies of ***all*** available change files.
They show several possible approaches to similar problems. The basic version of
Crudetype is designed for a lineprinter; you should start with this version
because that defers the problems caused by trying to work with two changefiles
at once.

This seems time to mention a very obscure piece of jiggery-pokery in WEAVE.
WEAVE will not work unless it can find a changefile. If WEAVE sees the command
\let\maybe=\iffalse then it inserts a something into its TEX output. The result
is that TEX prints only those modules that were altered by the changefile.
CRUDETYPE.WEB contains this command, but CRUDETYPE.CH (which is only a dummy
changefile) changes this to \iftrue. Weaving Crudetype with this will give the
whole un-changed program. All the real changefiles leave \maybe unchanged; so
these will give only the changed modules (well, maybe!!)

Initially Crudetype was written for the VMS operating system, and a lot of very
system-dependent code got into the main program. As change files started to
appear, it became clear that this is unclean. I have now tried to remove all the
most system-dependent code into the VMS change file. A typical example is the
procedure that parses file names. CRUDETYPE.WEB merely provides a hook to hang
this procedure on, saying "the changefile must define this procedure".  All
procedures that are handled in this way and all the code that is known to be not
Standard Pascal are in the section headed "system-dependent code".  Suppose that
you have to write a change file from scratch, the most simple- minded way to
begin is to choose any of the system change files and just throw the program at
the compiler and look at the flood of errors that emerge. Tne go through the
section on system-dependent code using the available change files as a model for
the parts that have to be rewritten. I would assume that all of this section has
to be rewritten for any new machine.

If you succeed in getting Crudetype to work, then you need to edit the user
document VMSUSER.TEX to reflect local conditions.

                               DIFFICULTIES

This section describes some of the difficulties that have appeared on various
systems, excluding those due to bugs in Crudetype, which I have tried to fix.
Unix presents special difficulties, see below.

1. Incompatible file formats. This disease is particularly bad on VMS systems.
TEX and related programs assume that a binary file is just a stream of bytes.
Now it seems that VMS Pascal cannot handle files of this type, so VMS TEX and
Metafont generate files in fixed length 512-byte records.  Crudetype expects
this format. Some people have started distributing files in incompatible
formats.  I have seen: files in Stream-LF format, files with the bytes in a
different order, and fixed-record files where the short record at the end is
padded with what looks like random garbage. Stream-LF has two disadvantages: (a)
there is no VMS software commonly available that can read it (b) some
TEX-related files are intended to be read from the end backwards, and VMS Pascal
can only do this with fixed-record files.  What I think is particularly
anti-social is that the authors of these files have not made any attempt to tell
the rest of the VMS TEX community what they are doing or why. Later; it appears
that somebody has cleaned this mess up. I have no idea who it was, but I am very
grateful to him or her.

When Crudetype meets a bad file, it will probably fail with a "cannot open file
(name)" error. This can happen because: the file of that name isnt there; or the
system doesnt give you permission to read it; or it has a bad record structure.
In VMS, you can check by $DIRECTORY/FULL (name) . If the data is bad (e.g. bytes
in unexpected order) you can check by dumping the first 100 bytes of the file in
octal or hex and comparing this with the format as described in TUGboat. Or you
can try running DVITYPE or TFTOPL or GFTYPE according to whatever file it was.
This is easier, but if somebody has altered both the files and these programs,
this will not be apparent. Note the (default) format of VMS DUMP is very
peculiar, consult its manual.

2. Missing coding schemes. The TFM files that come on tapes from Stanford
contain a piece of data called a `coding scheme'. Essentially, this tells you
what letter to expect to find in each cell of the font table, if you ignore
topological differences of slant, blackness etc. Each table in Appendix F of the
TEXbook gives a different scheme; and there are a few more schemes in fonts in
common use.  Unfortunately, some font designers have been producing fonts with
this information lacking. It is not actually illegal to omit the coding scheme
because the specification for TFM font files describes the coding scheme as
optional. But in my opinion this is a bad practice. If a site cannot provide
file space for every conceivable font, they will probably want to save space by
some form of font-substitution. The coding scheme is an essential tool for
trying to decide whether Font A is an acceptable substitute for B.

If your TFM files do not have coding schemes, Crudetype should give a "no coding
scheme" error. You can examine TFM files by TFTOPL or (in VMS) by DUMP. The file
NOSCHEME.ADD gives code to tackle this problem. To use it, simply append it to
CRUDETYPE.WEB. This essentially lists the schemes of each of the fonts I happen
to have seen on a particular distribution. This will clearly go wrong if anybody
starts writing TFM files of the same names with different schemes, and these new
schemes are not written into the TFM file.  V3 adds support for some Postscript
fonts (due to J.Warbrick). The Postscript fonts on our site all have coding
schemes but they were clearly inserted by somebody who didnt know what a coding
scheme was.  The schemes written into the files are like this: "HELVETICA LIGHT
ITALIC", but the scheme actually used is nearly always "TEX TEXT". So when
Crudetype finds an unknown scheme, it defaults to "TEX TEXT".

3.  Another difficulty (on VMS) was to find some way to get the output file
across to the printer. I cannot give any useful advice on this because it is
not merely system- but site-dependent. To get output on the HP, I had to
connect it as a terminal because it was impossible to drive printers across
our network. This needed the command:
                     $set terminal/eight_bit/form/pasthru
to allow data to be tramsmitted correctly. 
                                  VMSSPEW.COM
works at our site, as follows: user has to log in, then invoke the .COM file.
This asks for the file to be printed, then pauses. Then it types the .HPL file
at the terminal. Meanwhile the user must switch output onto the printer. Messy,
but it works, and waiting for network software to be debugged is a job for
Methuselah. 

In Unix I had to write a "printcap" file for similar reasons. My attempt at this
was very buggy.

4. Defects of PASCAL. In order to overcome some of the defects of Berkeley
Pascal Peter King had to use some C programs which are part of the standard Unix
Tex distribution (and needed for the same purpose there.) I could not get the
regular versions of these to work, so I hacked them until they did work (on our
machines). Essentially, I just deleted everything whose purpose was not obvious,
but there was also a peculiar bug in passing strings from Pascal into C. These
routines come in a file called "unixext.c".  Eventually he or I might do the
proper thing and make everything use the Pascal-to-C-converter. Meanwhile
consult the Makefile for instructions. Similarly, the NOS-VE version uses a
whole suite of "CYBIL" routines originally written for TEX by N.Schwarz. I
gather that it is a complicated job to attach these to the program, at any rate
I have no idea how it is done. You can go back to just using Pascal binding by
redefining the macros in the changefile.

5. Fortran carriage control. Originally there were bugs in this, I hope they
are fixed. The code does work on VMS. 

6. In V3, the /i flag is extremely system-dependent. I got it to work on VMS
and SUN-OS 3.5.





                                  OTHER FILES

In order to ease the process of installing the program on another system, I
have prepared some test files. I am not sending any binary files as these get
damaged in transit.

SAMPLE.TEX               A small piece of straightforward TEX text, copied from
a Stanford tape.

SAMPLE.DVI               Its DVI file, produced by the VMS version of TEX,
(also from a Stanford tape). Logically a DVI file is just a long stream of
8-bit bytes, but it appears that VMS cannot handle that type of file properly.
So VMS TEX writes DVI files in fixed-length 512 byte records.

SAMPLE.PRI               Same file, passed through Crudetype. Here again there
is a peculiarity in the file format. Normal VMS text files have "list"
carriage control, which means ( roughly speaking) that VMS will insert a CR
and a LF at the end of each record when it prints the file. Crudetype has to
use carriage control = NONE , which means that all carriage controls must be
explicitly inserted by the program.
           
SAMPLE.PHI               Philips printer output.
SAMPLE.HPL               Laserjet printer output, generated by PHILIPS.EXE
                        and HPGF.EXE  respectively.

NASTY.TEX               A selection from MYTANGLE.TEX .  This contains some of
                        the modules from TANGLE; I chose several fragments
                        that gave me trouble when I tried to print them using
                        Crudetype.

NASTY.DVI, etc.         As for SAMPLE.

TABLES.TEX, etc.        Tries to print all the font tables from the TEXbook.
                        The purpose is to help installers to check any
                        font data that they enter.

TINY.TEX                A tiny piece of straight text. Provided to generate
                        the file
TINY.DMP                which is a hexadecimal dump of TINY.HPL  . The idea is
                        that when you get a horrible mess coming out on your
                        printer, you can compare this file with a dump of your
                        locally-produced output. Reading VMS dump files is
                        somewhat of a black art: I have added comments.

Another excellent test is to extract the quotation from Galileo from Page
101 of the TEXbook. (copyright, so I cannot copy it here.) You need to set
                            \varunit=1.078pt
to get it to work. The line-printed output looks best magnified by about 50%.


                          RECENT CHANGES

1. Added extra magnification, described above.
2. (Lineprinter) Improved horizontal & vertical positioning. Previously the
line spacing jumped from double to triple quite unpredictably. Also WEB-style
tables of contents used to come out excessively wide because the thin spaces
between dots got expanded to whole lineprinter spaces. I have made a fix.
3. (Lineprinter) Support for coding schemes "AEFMNOT ONLY" and "TEX TEXT
WITHOUT F-LIGATURES".
4. Improved sort routine. This makes the program at least 3 x faster; I think
because it now takes advantage of runs in the input, and TEX DVI output is
very "runny".
5. I had to abandon the use of PXL files as they are too large.  So I have
cobbled together a GF-using version of HP. It needs a lot more work done on
it; it is too slow.
6. Fixed the "no-scheme" bug (caused Crudetype to crash if a TFM file has no
coding scheme). If you have this sort of TFM file, you will need the file
NOSCHEME.CH instead of CRUDETYPE.CH  .   Also some minor fixes.
7. New version (Version 1, Jan '88). Fixes all bugs so far notified to me.
Note: it also renders obsolete all previous Change files. The new versions
all refer to Crudetype v.1.
8. Tried to make the Lineprinter print TEX MATH EXTENSION characters.
9. Unix Change file written by Peter King.
10. NOS/VE Change file by courtesy of G-H Knauf and M.Rawohl.
11. Version 2. Again, all existing change files are obsolete. Many bugfixes,
code to read and parse a command line, and (I hope) a much cleaner interface
to the operating system.
12. HPGF altered to allow landscape mode printing. Also, print even- or odd-
numbered pages. In theory this will allow double sided printing, but with
difficulty. 
13. Some extra characters now get printed.
14. Primos change file, courtesy J.Warbrick.
15. After tremendous struggle, got it through web2c.
16. Version 3.0. Bugfixes. Added flags /x, /y, /d, /b, /i. Try to conform to
all relevant parts of the draft DVI driver standard (Level 0). Several extra 
coding schemes, courtesy J.Warbrick. Screenview versions, (also originally 
due to J.Warbrick).

V3 makes all older changefiles obsolete. I have adapted vms.ch and unix.ch,
but cannot deal with primos or nos-ve. I have added Emacs type labels to all
changefiles. 

17. Version 3.01. Modified web2c so it will compile Crudetype. Further details
below. Tiny change to the WEB file, does not affect any changefile I have seen.




***************************************************************************

MYTANGLE.WEB, .CH, etc.

My version of TANGLE, more-or-less as described in TUGboat. (altered to give
much better diagnostics than regular TANGLE). The change file is aimed at 
VMS. I hope my alterations might work with other sites versions of TANGLE.CH.
Recently upgraded to Tangle V4; the VMS version has bugs which I hope to
fix "soon".


***************************************************************************
  
                           RUNNING CRUDETYPE on Unix

This presents special difficulties because many Unix Pascal compilers are very
bad and also very variable. There is in fact no such language as Unix Pascal;
instead, there are many languages of the same name.  Therefore some members of
the Unix TEX community wrote a package called WEB2C that translates a very
specialised and peculiar dialect of Pascal into C.  Many constructions of
Standard Pascal are rejected; others are incorrectly translated. In order to get
around this I had to write my own version of Web2c; I have called it W2C to
reduce confusion. The changes are all intended to make W2C more like Standard
Pascal, but there is still an enormous difference. Also the change files for TEX
etc contain many fudges to adapt these programs to Web2c; therefore I think it
very unlikely that you could successfully compile TEX using my W2C. I hope
sometime to rectify some of the following known defects. All of these and more
are also in Web2c.

The following constructions of Standard Pascal are mishandled by W2C:

Procedures nested inside procedures; Procedure parameters; Redeclaration of
identifiers in nested blocks (you can only redefine variables as variables);
With statements; Variant records; Conformant array parameters; Enumerated types;
Pointers; Arrays of dimension > 2; File^ for current member of a file; Non-local
goto.

Also W2C makes no attempt to detect run-time errors or various compile-time
errors.

Because the diagnostics are poor, I think W2C is only tolerable for use on a
program that has already been extensively tested on a genuine Pascal compiler;
so P.King's Unix changefile is still an essential tool for anybody who needs to
test or debug Crudetype. On the other hand, using W2C does seem likely to work
on a much wider range of Unixes that using Pascal, and the compiled program is
roughly twice as fast (comparing unoptimised  pc  against unoptimised  gcc ).
W2C works on all Unix machines I have access to (not many).

The procedure to build Crudetype from the sources is:

1. On your TEX directory there should be a file called  site.h  that describes
local conditions. Either use this or create a local site.h . Edit Makefile to
point to this file.

2. Edit other macros at the start of Makefile to describe local practice. In
particular you need to edit the IMAGES macro to say what version(s) you want to
build. 

In Makefile the POSSIBLE_IMAGES  are:

crudetype		the main version, compiled with W2C.
crude-p   		Ditto, compiled with pc
noscheme-p noscheme-c  	Use these if your fonts dont have schemes.
hpgf			Attempt at HP LJ+ driver.


3. Then run make; make install; and (optional) make clean or veryclean .

This is a long messy process and requires YACC and LEX. If you dont want to do
all this, I have included the files crude-c.c and noscheme-c.c; if you are
clever you can probably bypass the w2c stage:

touch crude-c.c
make crudetype