path: root/dviware/ln03/rose/ln03bis.mem

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   <wherever your PXL files are>

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=<queuename> foo.ln3

This assumes your system manager has set up the LN03 as a spooled
device with queuename <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=<number> - print the file at a horizontal offset of <number> 
    pixels, i.e., moved right that many pixels. (There are 300 pixels to 
    the inch.) 

    /V=<number> - print the file at a vertical offset of <number>
    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 <filename> <options>

    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 <code> 
	Type the rasters for character code <code> from
	the PXL file currently in memory

    PPXLR <code>
	Plot the rasters for PXL character <code>
	using the "sixel" protocol accepted by 
	VT125, VT240 and VT241 terminals

    TPXLL <offset>
	Type the longword at offset <offset> in the
	PXL file currently in memory

    SPXLL <offset> <value>
	Set the longword at offset <offset> to value
	<value> in the PXL file currently in memory.
	<value> is read in HEXADECIMAL (this being
	considered the most convenient...).

    WSTR <filename>
	Write the PXL file currently in memory onto
	the file <filename>, in stream_LF format as
	desired by the LN03 and LaserWriter support.

    INITNFT <code1> <code2>
	Initialize the in-memory buffer for LN03 font files
	with information appropriate to an LN03 file
	accomodating characters from <code1> to <code2>.
	Note: the only truly legal values are 33 and 126.

    CPTONFT <code1> <count1>
	Copy characters from the PXL file in memory to
	the LN03 file in memory, beginning at <code1>
	in the PXL file and going up to <code2>. Characters
	are put at the lowest available codes in the
	LN03 file.

    RNFT <file>
	Read unsixelized LN03 format font file into buffer

    WNFT <filename>
	Write the LN03 font file in memory to a file
	<filename>. The file written out is not sixelized.

    TNFTR <code>   
	Type the rasters for LN03 character, specified
	as a decimal ascii code

    PNFTR <code>
	Plot the rasters for LN03 character <code>
	using the "sixel" protocol accepted by 
	VT125, VT240 and VT241 terminals

    TNFTL <offset>
	Type longword of LN03 file buffer at given
	byte <offset>

    SNFTL <offset> <value>
	Set longword of LN03 file buffer at given
	byte <offset> to stated <value> 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).