The purpose of this file is to explain how to print TeX files on your LN03 laser printer. To do this, you must have at least one optional RAM cartridge in your LN03. The TeX to LN03 driver has been changed substantially compared to the ones in previous distributions. Error reporting has been revamped, and the driver now reads PXL format font files as well as LN03 format font files. The TeX-to-LN03 driver described here requires VAX/VMS V4.2. (It has also been tested on Ultrix-32 V1.2 and on 4.3bsd Unix; see section 12, "Unix", below.) Most of the things described below probably also work on VAX/VMS V4.0 or V4.1, if you do your linking on a system which has VAX C installed. 0. BILL OF MATERIALS The present file is: ln03.mem These are the files that comprise the TeX to LN03 driver: dvi2ln3.c dvi2ln3nft.c specials.c clink.opt These other files comprise an auxiliary program that can be helpful: newffc.c Depending on circumstances, you may have received .obj files corresponding to the different .c's, or you may need to regenerate them using a C compiler. 1. INSTALLATION The basic steps to install the DVI to LN03 driver are as follows: A. Link the driver program. B. Set up your font raster directories. C. Have users set up certain definitions in their login.com, or put them in the system login file. No VMS privileges are needed to install the driver. STEP A, LINKING DVI2LN3. Type: $ link dvi2ln3,dvi2ln3nft,specials,clink/opt STEP B, PXL FILES. If you don't already have a collection of font files in PXL format, you need to assemble one. The usual way to get PXL files is either off a TeX tape, or by running the GFtoPXL program which is supplied with Metafont. Your PXL fonts must have extensions .yyyyPXL, where yyyy is the magnification times 1500. For example, the fonts that are at 100% magnification have extension .1500PXL, and those that are at 120% magnification have extension .1800PXL. Be sure, of course, that the fonts are suitable for 300 dot per inch printers, because that's what the LN03 is. VMS allows two files to have the same data bytes, which are interpreted in different ways depending on the "record format", "record attributes", and "record size". There are many possibilities for these parameters. Dvi2ln3 has been tested with PXL files of the following two types: record format: stream_LF or record format: fixed, record size: 4 You determine these characteristics of a given file by doing a VMS DIRECTORY /FULL on the file. I believe the files come off the TeX tape in the second format. If for some reason, your PXL files are not in one of these formats, you should test dvi2ln3 to see if it works. If it doesn't, you will have to convert your files somehow. Please consult section 9 below for some hints on how to do this. STEP C, DEFINITIONS. Everyone who uses the DVI to LN03 converter must have the following definitions: $ dvi2ln3 == "$tex$:dvi2ln3" $ define tex$pxldir The logical names tex$ and tex$fonts are also needed; these should be defined as for running TeX itself. 2. USING THE DVI TO LN03 DRIVER To convert foo.dvi to an LN03 format file (extension .ln3), type $ dvi2ln3 foo Print the file foo.ln3 on your LN03 by saying $ print/nofeed/queue= foo.ln3 This assumes your system manager has set up the LN03 as a spooled device with queuename . The /nofeed is very important, for if you omit it, you may get unwanted page breaks in your output file. 3. COMMAND LINE OPTIONS FOR DVI2LN3 The DVI2LN3 program has some options. These are typed on the command line, after the file name FOO, and separated from it by at least one space. /S=page number - the output file will only contain the pages in the DVI file that start at the given page number. The page number is the value of counter 0. /N=number of pages - the output file will only contain that many pages from the DVI file. For example, to cause only pages 20 through 22 of FOO to be converted to LN03 form, say $ DVI2LN3 FOO /S=20 /N=3 /H= - print the file at a horizontal offset of pixels, i.e., moved right that many pixels. (There are 300 pixels to the inch.) /V= - print the file at a vertical offset of pixels, i.e., moved down that many pixels. The values given with /V and /H are ADDED to the TeX parameters \hoffset and \voffset; they do not replace these parameters. /L - print the entire file in landscape mode (with text running along the long direction of the paper). The size of the text is not changed. Thus you have only about 8 inches from top to bottom - make sure your .tex file does not produce pages which are longer than that. 4. WARNINGS ABOUT THE LN03 DRIVER Now, some caveats and warnings about the LN03 driver for TeX. The driver is copyrighted data of Digital Equipment Corporation. Because Digital makes this software available for free, it does not promise that the software works or does anything. A different, supported TeX to LN03 driver may be available from Kellerman and Smith in Portland, Oregon. The most common problem people encounter when first using the LN03 support is forgetting to print the .ln3 files with the /nofeed qualifier. This can cause a page of output to be split into two or more pages. There are some limitations to the LN03 support: - Your LN03 should have at least one RAM cartridge plugged in. Otherwise, it is unlikely that any but the smallest documents will print successfully. - The landscape support is very recent. - The code that reads PXL files is relatively recent. (Formerly, the driver read LN03 format files only.) - One cannot access the preloaded or ROM fonts in an LN03. - DVI2LN3 has limitations on the size of a font load, which may be exceeded by TeX files. This rarely occurs. - The LN03 also has limitations on the complexity of a page, which may be exceeded by TeX files. This is very rare. - Very large fonts such as AMINCH cannot be handled. (The LN03 can't handle them anyway.) - For TeX's \magstephalf, the PXL files should have extension .1642PXL. I believe this to be the correct extension, but some distributions give the \magstephalf fonts extension .1643PXL. - The VMS spooler for the LN03 has to be set up properly with $ SET TERMINAL and $ SET QUEUE commands. Here are some settings that have been found to work: Terminal queue LN03$B12, on BOSTON$TTE6: /BASE_PRIORITY=4 /DEFAULT=(FEED) /NOENABLE_GENERIC /FORM=DEFAULT Lowercase /OWNER=[SYSTEM] /PROTECTION=(S:E,O:D,G:R,W:RW) /SCHEDULE=(NOSIZE) /SEPARATE=(FLAG,RESET=(PORTRAIT)) Terminal: _TTE6: Device_Type: Unknown Owner: SYMBIONT_0001 Username: SYSTEM Terminal Characteristics: Interactive Echo Type_ahead No Escape No Hostsync TTsync Lowercase No Tab No Wrap Scope No Remote Eightbit No Broadcast No Readsync Form Fulldup No Modem No Local_echo No Autobaud No Hangup No Brdcstmbx No DMA No Altypeahd Set_speed No Line Editing Overstrike editing No Fallback No Dialup No Secure server Disconnect No Pasthru No Syspassword No SIXEL Graphics No Soft Characters No Printer Port Numeric Keypad No ANSI_CRT No Regis No Block_mode No Advanced_video No Edit_mode No DEC_CRT No DEC_CRT2 Device spooled to _CECIL$DUA7: 6. MORE ABOUT FONTS If you should acquire LN03-format fonts by some means other than PXL file manipulation, you can use them with dvi2ln3. Just put them in a directory and define a logical tex$ln03dir to point to them. You will need to get TFM files for those fonts by some means. The NEWFFC program can help you (a little). If you have a font foo.ln03, and you want to know what the character with code xx looks like in that font, you can type: $ run newffc FFC>rnft foo.ln03 FFC>tnftr xx [Types rasters and tells you the width of the character] FFC>exit $ Using the raster width information, you can then compose a PL format file, which can then be converted to TFM format by running the PLtoTF program on it. PLtoTF is distributed with TeX. If you have a VT125, VT240 or VT241 terminal, you can type pnftr instead of tnftr; that plots the rasters on the screen using the terminal's graphics capabilities. To link newffc, type $ link newffc,clink/opt or else $ link newffc,sys$library:vaxcrtl/lib 7. \special COMMANDS DVI2LN3 interprets certain \special commands. Right now, the following \special's are implemented: ln03:defpoint integer ( [dimension] , [dimension] ) ln03:connect integer [/ integer] integer [/ integer] [dimension] ln03:plotfile filename ln03:resetpoints integer integer A dimension is a number with optional decimal point, followed by one of pt, in, pc, cm, mm, bp, dd, cc, and mi. The peculiar syntax of these commands is due to a request to emulate certain commands invented by Textset, Inc. (Ann Arbor, Michigan). Ln03:plotfile includes the named file literally in the .LN3 output file. No parsing whatsoever of the file is done, nor are any defaults applied to the filename. The remaining specials work with an array of 255 points, numbered 1 to 255. Each point is a location on the paper. Initially, the array is uninitialized; and any contiguous segment of the array may be returned to the uninitialized state using ln03:resetpoints a b, which uninitializes points a through b inclusive. A point value may be assigned to a particular position in the array using ln03:defpoint. In using ln03:defpoint, one may specify the coordinates of the point, or one may omit either the x- or the y-coordinate or both, in which case they are taken to be the current values at the time the \special call occurs. The ln03:connect special is used to draw a rule connecting two points. The two points must have either the same x-coordinate or the same y- coordinate. The optional dimension is the thickness of the rule; if none is specified, the rule is 2 pixels thick. 8. DVI2LN3 ERROR MESSAGES Dvi2ln3 internal error, bad txfno or lnfno Indicates a bug in dvi2ln3. Couldn't find good font file: using blanks There was neither an LN03 format font file nor a PXL format font file for the specified font and magnification. Dvi2ln3 is making a font load which replaces all the glyphs in that font with blanks of the appropriate width. Check that the font file directories TEX$LN03DIR or TEX$PXLDIR exist and are readable to you. Error while reading PXL file There was some problem reading the PXL file for the specified font and magnification. Perhaps the file is not in correct format. No more room in LN03 font load buffer (xxx bytes long) Dvi2ln3 is trying to build a font load, and the font load has become so large that it has exceeded the size of a buffer in the program. The probable cause of this is that your document uses one or more very large fonts. Dvi2ln3 is not designed to work with fonts larger than 36pt. -- Bad NFT file, lacks FONT. -- bad NFT file, not enough character parameters -- bad NFT file, bad character range. LN03 font file bad, using blanks The LN03 font file found for the specified font has some problem (probably it is not in the right format). Dvi2ln3 will build a font load in which the glyphs for that font are replaced by appropriately sized blanks. Use NEWFFC to examine the LN03 font file and track down what might be wrong with it. Usage: Dvi2ln3 You have called dvi2ln3 without giving it a parameter (the name of the file it has to process). Couldn't open dvi file Couldn't rewind dvi file. Dvi2ln3 is having trouble accessing the dvi file you have asked it to read. Check that the file exists and that you have read access to it. You could also get this message if you forgot the space between the dvi file and the options on the command line. E.g. if you typed dvi2ln3 foo/h=10 then dvi2ln3 would try to open a file named "foo/h=10" and would obviously fail in the attempt. Bad DVI file - check it with DVItype There is something wrong with the dvi file which Dvi2ln3 is trying to read. Run DVItype on that file to find out what is wrong. Since TeX writes correct DVI files, it is unlikely you will get this message... Couldn't open output file Dvi2ln3 couldn't open the .ln3 file it is trying to create. Perhaps you don't have write access in the current directory; perhaps your disk quota is exceeded. Can't construct a font load: Dvi file uses too many glyphs from too many different fonts. The LN03 has limits on how many glyphs and fonts it can handle. Dvi2ln3 tries to make best use of the LN03 within those limits. However, if you get the above message, it means Dvi2ln3 has been unable to figure out how to print your file within those limits. Solution: print your file a few pages at a time using the /s and /n command line options. If this problem occurs even when you try to print just a single page, then you will have to simplify that page. Font xxx uses > 188 characters. Can't handle that. Fonts could have as many as 256 characters. However, dvi2ln3 assumes you will only use 188 of them in any one document. If you get tris message, try to print your file a few pages at a time. Stack too deep for Dvi2ln3 The dvi file has a stack, and Dvi2ln3 is designed only to allow that stack to go 100 entries deep. This is essentially a design error in the program. Solution: recompile dvi2ln3 with a larger STACKSIZE parameter. Too many fonts for Dvi2ln3 Dvi2ln3 is designed to handle only 100 fonts in your document. Again this is essentially a desing error in the program. Solution: recompile dvi2ln3 with a larger MAXTEXFONTS parameter. Font xxx has a bad scaled size Font xxx has a bad design size This indicates a bad DVI file format. Can't open TFM file for font xxx If you use a font named foo, there has to exist a file foo.tfm in tex$fonts. If you get the above message, make sure that file exists and is readable to you. Bad TFM file for font xxx The TFM file is in a bad format. Check it with the TFtoPL program, which will tell you what is wrong with it. \special too long (over xxx bytes). \special's are limited to a certain length (2048 bytes or something like that). There is no need for a \special to be anything like that long, so if you get this message, obviously you have coded the \special in some weird way. Unrecognized option 'xxx' ignored in \special command This means you have a \special with a command ln03:xxx and xxx means nothing to dvi2ln3. Invalid point number (xxx) The \special's that deal with points are only designed to handle 255 of them, numbered 1 to 255. If you get the above message, it means you have probably tried to use a point number outside the range 1 to 255. Unable to open plotfile xxx You used the ln03:plotfile \special, but dvi2ln3 was incapable of reading the plotfile you told it to read. No such unit of measure: xxx You have used xxx in a context in which \special syntax is expecting a unit of measure (such as "in", "cm", "pt"). Can't connect along a diagonal. The ln03:connect \special can only connect two points which are either at the same horizontal coordinate or at the same vertical coordinate. ERRORS THAT DVI2LN3 DOES NOT CATCH. There are a number of possible errors in processing your document that Dvi2ln3 does not catch. You have to detect them by looking at the printed output. These include: errors in the use of TeX commands to achieve the formatting effects you desire (of course); misuse of the /h= and /v= command line options in such a way that margins are too small or text material is set off the page; errors in font files that cause rasters to be wrong (e.g. if a font file has rasters for a "2" in the position where there ought to be a "1"); gross discrepancies between the raster font files and the .tfm files; certain font file format errors in which a font file contains bad pointers. In general, if any part of your document seems to look wrong, check that you are using TeX correctly, then check carefully which fonts are involved in the part that comes out wrong. 9. PXL FILE CONVERSION If your PXL files are not in one of the acceptable record formats described in section 1, you will need to perform some conversion. There are many possibilities, so we can only suggest one approach that may be helpful. This approach seems to work if your PXL files were written by GFtoPXL. (a) Link the newffc program by saying: $ link newffc,clink/opt or else $ link newffc,sys$library:vaxcrtl/lib (b) Convert the resulting file to stream_LF as follows: $ run newffc FFC> rpxl foo.pxl FFC> wstr foo.pxl FFC> exit $ (c) You can also check out your PXL file using newffc. $ run newffc FFC> rpxl foo.pxl FFC> txplr nn [types rasters corresponding to character code nn on terminal] 10. NEWFFC COMMANDS EXIT The obvious (control-Z also works) RPXL Read a PXL file into memory. The code tries to accomodate a wide range of VMS file formats. TPXLR Type the rasters for character code from the PXL file currently in memory PPXLR Plot the rasters for PXL character using the "sixel" protocol accepted by VT125, VT240 and VT241 terminals TPXLL Type the longword at offset in the PXL file currently in memory SPXLL Set the longword at offset to value in the PXL file currently in memory. is read in HEXADECIMAL (this being considered the most convenient...). WSTR Write the PXL file currently in memory onto the file , in stream_LF format as desired by the LN03 and LaserWriter support. INITNFT Initialize the in-memory buffer for LN03 font files with information appropriate to an LN03 file accomodating characters from to . Note: the only truly legal values are 33 and 126. CPTONFT Copy characters from the PXL file in memory to the LN03 file in memory, beginning at in the PXL file and going up to . Characters are put at the lowest available codes in the LN03 file. RNFT Read unsixelized LN03 format font file into buffer WNFT Write the LN03 font file in memory to a file . The file written out is not sixelized. TNFTR Type the rasters for LN03 character, specified as a decimal ascii code PNFTR Plot the rasters for LN03 character using the "sixel" protocol accepted by VT125, VT240 and VT241 terminals TNFTL Type longword of LN03 file buffer at given byte SNFTL Set longword of LN03 file buffer at given byte to stated in hex. 11. BUG REPORTS Please report any bugs you may find. You may phone (617) 467-7545, send Arpanet mail to Rose%dvinci.dec@decwrl.arpa, or Usenet mail to ...!decwrl!dec-rhea!dec-dvinci!rose. The best way to report a bug is to mail the TeX file that evokes it together with a description of what is wrong with the printed output. If you should wish to port this software to operating systems other than VAX/VMS, please do not hesitate to contact me. 12. UNIX The sources for dvi2ln3 and newffc may be recompiled under Unix on a VAX, and will probably run there. This has been tried and tested (to a limited extent) under Ultrix-32 and 4.3bsd. When running under Unix, Dvi2ln3 expects three "environment variables" to be defined: TEX_FONTS wherever the tfms are TEX_LN03DIR wherever the LN03 format font files are TEX_PXLDIR wherever the PXL format files are Define these with setenv. You may need to modify dvi2ln3 and newffc to run on your Unix system. In particular, if your Unix runs on a 68000 or PC RT or something like that, you may have to make serious modifications. Look in particular at all C "union" constructs in the source; the code that manipulates them may need to be redefined because of the machine architecture (this is necessary, e.g., on a 68000).