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