⟦1b87279af⟧

TextFile

SITE: UK.AC.RHBNC.VAXA
DIRECTORY: SYS$USERDISK2:[UHAH208.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).

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

                                   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,
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).


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.


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

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. 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.

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.

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.

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.

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. 

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. 







                                  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.
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.


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


MYTANGLE.WEB, .CH, etc.

My version of TANGLE, more-or-less as described in TUGboat. (altered to give
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.


***************************************************************************
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦1b87279af⟧ TextFile

Derivation

TextFile
