DVILJ(1)

🎀 DVILJ(1) · TeX Live manual 🎀

okay bestie, welcome to dvilj, the tool that turns your TeX .dvi files into PCL so an HP LaserJet can actually print them 🖨️✨ it's giving old-school printer queen energy and I'm obsessed 💅

💖 NAME 💖

dvilj4, dvilj4l, dvilj2p, dvilj - convert a TeX DVI file to PCL, for HP LaserJet printers 🌸

🦋 SYNOPSIS 🦋

dvilj [--Dnumber] [-ccopies] [-dmode] [-D] [-E] [-eoutputfile]
      [-ffrompage] [-g] [-hheaderfile] [-l] [-Mflag] [-mmag] [-ppages]
      [-q] [-r] [-ttopage] [-spagesize] [-v] [-Vmode] [-w] [-xxoff(mm)]
      [-yyoff(mm)] [-Xxoff(dots)] [-Yyoff(dots)] [-z] [filename]

🧚 DESCRIPTION 🧚

okay so dvilj and its siblings take TeX-output ".dvi" files and turn them into PCL (that's the Hewlett-Packard Printer Control Language) commands. they're made for printing on an HP LaserJet+, an HP LaserJet IIP (using dvilj2p), an HP LaserJet 4 (using dvilj4), and any fully compatible printers 🖨️💜

dvilj4 also has support for the builtin Intellifont and TrueType fonts, and TFM and VF files come with the distribution 🔥 virtual fonts aren't supported directly by dvilj, so you have to run dvicopy(1) first, or otherwise expand the virtual fonts yourself 🙈

⚠️ all the programs come from one source file, dvi2xx.c. they're usually called through a shell script or as a line printer filter. one of those scripts, dvihp(1), ships with the distribution, and it gives you command-line options that are pretty similar to dvips(1) 🫶

👑 OPTIONS 👑

• --Dnumber — debug stuff based on the bits of number. check the kpathsea(3) manual for the values 🐛 it also turns on general verbosity, so it's extra chatty.
• -cnumber — prints each page number times, counting the original too 📄
• -dnumber — duplex printing! -d1 is long edge binding and -d2 is short edge binding. this one only works in dvilj4 and dvilj2p 🦋
• -D[-12] — double-sided printing (see below). -D1 prints the odd sides only and -D2 does the even pages. slap a trailing - on there and it skips printing those empty padding pages ✨
• -E — switches the printer into econo mode. dvilj4 only 🍃
• -eoutfile — sends the output to outfile instead of the basename of your dvi file with ".lj" on the end. if outfile is - (like -e-), the output goes to standard output so you can pipe it straight into a spooler 🌈
• -fpagenum — prints pages whose TeX page numbers are greater than or equal to pagenum 🌸
• -g — go mode! the printer doesn't get reset when the job starts 🚀
• -hheaderfile — copies headerfile to the output before the DVI file gets translated. it's how you sneak arbitrary commands to the laser printer 😈
• -l — prints in landscape mode. only dvilj2p and dvilj4 support this 🌅
• -Mflag — decides whether mktexpk(1) gets called to make fonts on demand. -M1 and -M mean the same thing, and -M0 turns on invoking mktexpk(1) (same as dvips(1), bestie) 🔧 if you don't give any -M option, the default gets picked at compile-time, and as shipped, mktexpk is enabled ✅
• -mmagnification — picks the magnification you want. here's the whole menu:

-m#usermag e.g., #900
-m0 equivalent to -m#1000
-mh equivalent to -m#1095
-m1 equivalent to -m#1200
-mq equivalent to -m#1250
-m2 equivalent to -m#1440
-m3 equivalent to -m#1728
-m4 equivalent to -m#2074
-m5 equivalent to -m#2488

• -ppagecount — prints pagecount pages after the starting page 📑
• -q — quiet mode! the final statistics and all that extra stuff get left out 🤫
• -r — toggles page reversal 🔄
• -spagesize — sets the page size. the options are:

-s1: Executive (7.25" x 10.5")
-s2: Letter (8.5" x 11")
-s3: Legal (8.5" x 14")
-s6: Ledger (11" x 17")
-s25: A5 paper (148mm x 210mm)
-s26: A4 paper (210mm x 297mm)
-s27: A3 (297mm x 420mm)
-s45: JIS B5 paper (182mm x 257mm)
-s46: JIS B4 paper (250mm x 354mm)
-s71: Hagaki postcard (100mm x 148mm)
-s72: Oufuku-Hagaki postcard (200mm x 148mm)
-s80: Monarch Envelope (3 7/8" x 7 1/2")
-s81: Commercial Envelope 10 (4 1/8" x 9 1/2")
-s90: International DL (110mm x 220mm)
-s91: International C5 (162mm x 229mm)
-s100: International B5 (176mm x 250mm)

these values come straight from the PCL 5 technical reference manual 📚 if you leave out the -s commandline option, no clipping happens at the bottom of the page. (printing below the paper bottom shouldn't bother any correctly behaving PCL printer, but still 💀) and please remember the correct paper tray has to be installed for whatever paper size you pick, so only use this option if you have full control over where your print is going 🫶

---

✨ SUPPORTED TeX \special COMMANDS ✨

okay so dvilj has its own little list of \special commands it actually understands 💅🎀 and they all follow the same generic vibe:

\special{key1=value key1="value with space"}
\special{key3 = value key4 = 'note optional spaces around equal sign'}

basically a special is a bunch of key/value pairs, each joined by an equal sign 🦋 spaces around the = get ignored, so do what makes you happy 🫶 the value is either one space separated word or a quoted string, and you can use double or single quotes, your choice 💖 there's no way to escape quote characters inside a value, so if you want both kinds of quotes in one value, sorry bestie, you're out of luck 😭

the valid key/value combos are below ✨

• hpfile=file — inserts file right at the current position 🌸 dvilj hunts for file with kpathsea(3) (more on that later).

The file has to make sense for this printer, so it should be full of PCL escape sequences or HP-GL/2 commands 🧚 if it's a graphics file, the upper left corner of the graphic usually lands on the current position.

Heads up: PCL absolute positioning escape sequences inside file get rewritten into relative positioning commands, and the lowest coordinate that shows up is used as the reference 👑

• hpfile_verbatim=file — inserts file exactly as it is, zero changes 🍓 file is searched with kpathsea(3) too.

This one is mostly for keeping absolute positions in PCL files intact 💜

• psfile=file llx=x0 lly=y0 urx=x1 ury=y1 rwi=s — converts the PostScript file into HP PCL using Ghostscript with the ljetplus device, then inserts the resulting graphics at the current position and rewrites absolute position escape sequences along the way ✨ file gets searched with kpathsea(3).

all of the key/value pairs here are mandatory, but they can come in any order 🙈 x0, x1, y0, y1, and s are all integers. (x0,y0) is the lower left corner and (x1,y1) is the upper right corner of the image.

This special is kind of a mystery, not gonna lie 💀 nobody really knows what it's supposed to do. The rwi parameter is some sort of scale factor, but even reading the source code it's not clear what the author was going for. It's also unclear whether the corners are measured in PostScript points or PCL dots.

if you actually know how psfile works, or you've put in the work to figure it out, please tell us at tex-k@tug.org so we can update this man page with the real info 🫶🌈

• dvilj-psfile-syntax=syntax — syntax is either "dvilj" or "ignore" 🔥 this is a super crude way of telling the driver what to do with psfile specials.

if the value is "ignore", every psfile special processed after this one gets ignored, until the next dvilj-psfile-syntax special shows up 😴

if the value is "dvilj", psfile specials get handled the way we explained above, until the next dvilj-psfile-syntax special is processed 💅

there's a planned extension called "dvips", but it hasn't been built yet, so don't hold your breath ✨

this one is trickier than it sounds ngl 😭 since its meaning depends on processing order, it only works if it's on the same page as the psfile special. putting it once in a file (like on the first page) won't help if you only print one page, because dvilj doesn't prescan first-page specials the way some other drivers do. (patches welcome, obviously 🙌)

• comment=arbitrary text and comment arbitrary text — everything after this gets ignored 🦋 it's a handy spot for meta-information in a DVI file.

with the first form, the comment can show up anywhere in the special. if it's the very first thing, processing stops and all the text after it is ignored 🙈

the second form is a speciality added for compatibility with other drivers 🌸 if the first keyword is comment and it has no value, it still counts as a valid comment, and the rest of the special gets ignored.

• orientation=po — puts the page on the physical paper in the orientation you pick 📄 po can be one of these:

0  for portrait
1  for landscape
2  for reverse portrait
3  for reverse landscape

• defpoint=n(x,y) — defines point number n 📍 later specials can point at this to pick areas to fill with a pattern. n has to be between 0 and 79.

x and y are the position of that point and they look like "?pt", where ? is a floating point number ✨ positions are relative to the DVI page origin, so coordinates go right and down. The origin is (1in,1in) in the upper left corner, and it gets moved by the -x, -y, -X, and -Y options, but not by \hoffset or \voffset.

x and y can be left out, so 3 or "4(,)" are both valid 🧚 when they're missing, the current page position becomes the position for point n.

• resetpoints="all" — undefines every point again 🧹
• gray=gray_scale and grey=gray_scale — sets the fill mode for the next fill special so the area gets filled with gray 🩶 (grey is just an alias for gray.) any pattern you set before gets reset.

gray_scale is the percentage of gray you want, where 0 means white and 100 means black 🖤

caveat time 💀 this special is kind of a misnomer. PCL calls these gray scales shading patterns, and they're made by placing dots in the area. The gray scale controls how spread out the dots are. At the low end it doesn't look very gray up close, more like a dotted background 🌫️ also, the gray scales aren't as fine-grained as a 0..100 range makes it seem. There are really only 8 gray patterns available:

  1 -  2%
  3 - 10%
 11 - 20%
 21 - 35%
 36 - 55%
 56 - 80%
 81 - 99%
    100%

one of these patterns gets picked based on your gray_scale value 🎯

• pattern=pat — sets the fill mode for the next fill special so the area gets filled with a pattern 🎨 any gray color you set before gets reset.

pat is one of these:

1  horizontal lines
2  vertical lines
3  diagonal lines, from lower left corner to upper right corner
4  diagonal lines, from upper right corner to lower left corner
5  crossed lines, vertically
6  crossed lines, diagonally

• fill=a/b — fills the area between points a and b using the current fill mode 🪣

point a has to be the upper left corner and point b has to be the lower left corner of the rectangle. get them mixed up and the result is garbage 🗑️

the default fill mode is 10% gray color filling ✨

• filename — a legacy special that's now deprecated 🦕 if the whole special is just one word naming a file that exists, that file gets included verbatim. Unlike the other file inclusion options, this one does not search with kpathsea(3). You really shouldn't use this, and we're not going to fix any problems with it 🙅‍♀️

Also: the special parser sometimes accepts stuff that isn't valid according to the docs above. When that happens, the output is usually messed up somehow 😭

Searching for Included Files

proper file include specials search for the file with kpathsea(3) 🗂️ the search path gets set by the variable DVILJINPUTS, and if the file isn't in that path, dvilj checks the variable TEXINPUTS next 🔍

DVILJINPUTS is for the case where a site has shared graphics everyone should be able to use, like scanned signatures 🖋️ TEXINPUTS is for graphics that are part of your own current document 📚

also, dvilj is the .PROGRAM name used in texmf.cnf for all the driver variants, no matter what the actual program is called 🧚

Unknown Specials and "TEX_HUSH" configuration

kpathsea(3) has a concept called warning suppression, set with the configuration variable TEX_HUSH 🤫 check out its Info node TeX support / Suppressing warnings for the details. The variable holds a colon-separated list of identifiers, and each one names a warning to suppress 🌈

if special is in that list, dvilj stops complaining about specials it doesn't recognize 🙈 but if a special is recognized and has an invalid parameter, a warning still gets printed no matter what's in TEX_HUSH ⚠️

---

🖨️ DOUBLE PAGE PRINTING 🖨️

if your printer has a duplex unit installed, you can ask for duplex printing with the -d option 🦋

otherwise, the -D option makes the printer do doublepage mode 📄 roughly speaking, that means it prints the even pages first and then the odd ones 🌸 if you use -D to print both even and odd pages (so -D with no optional 1 or 2), here's what happens once half the pages are done: LJ: the printer stops, shows the message "FEED", and switches on the manual feed LED 💡 it keeps going once you either feed the printed pages into the manual page feeder, or push the continue button (after putting the printed pages into the paper tray first) 🫶

if you go with -D1, only odd pages get printed, and -D2 does even pages 🔢 adding a trailing - (like -D-, -D1-, or -D2-) stops dvilj from printing the empty pages it would otherwise make as padding 🙅‍♀️

the driver lets you use -D for both print directions, front-to-back or back-to-front 🔄 it also tries to be extra clever in a few cases 🧠:

• when a document has an odd number of pages, it puts an empty page in the right spot
• when a document starts with page 0, the driver inserts an empty page after the 0-page
• when a piece of a document gets printed that starts with an even page number, that page gets printed on the back of the first page, so the odd sides always end up on the front
• the 0-page gets treated like an odd page

the doubleside option works on all LJs, not just the new D model that does doubleside printing by itself (honestly, I don't know whether it even makes sense on the new LJ II D 🤷‍♀️).

Caveat on the doubleside option: if you use it a lot, or on really big files, you might need to clean the printer way more often 🧹😭

the -pX option can stop printing after X pages 🛑 it can lead to weird results when combined with -D. Personally I'm not a fan of this one 🙄 the safe way to print just part of a document is with -f (from) and -t (to) 💖

✨ ENVIRONMENT ✨

okay so dvilj uses the same environment variables and font-finding algorithms that TeX and its friends use 🧚 for the full scoop, check out the documentation for the kpathsea(3) library. (Repeating it all here would be way too cumbersome, so I'm not gonna. 🙈)

• DVILJFONTS — if this is set, it overrides all the other font paths. main character behavior 👑
• DVILJMAKEPK — if this is set, it overrides mktexpk(1) as the command that gets run to make a PK file when one isn't found. 🛠️
• DVILJSIZES — this tells dvilj which font sizes are available 📏. It should be a list of numbers separated by colons. If the list starts with a colon, the system default sizes get used too. Sizes are in dots per inch, and decimals are allowed for pxl files. For example, a 300 dots per inch file magnified by half a step comes out to 1643 dots per five inches, which should be encoded as 328.6. dvilj tries the actual size of the font before trying any of the sizes you gave it. ✨
• DVILJINPUTS — the primary search path for include files. 📂
• TEXINPUTS — the secondary search path for include files. 📁
• TEX_HUSH — a colon-separated list of identifiers that name situations where no warning gets output. 🤫 These are the identifiers:

checksum  suppress mismatched font checksum warnings
readable  suppress warnings about unreadable files
special   suppress warnings about unknown specials
all       suppress all warning classes above
none      suppress no warnings

• KPATHSEA_DEBUG — traces kpathsea(3) lookups. Set it to -1 for complete tracing. 🔍
• GS_PATH — on Windows, this may be the path to Ghostscript, and the default there is gswin32c.exe. 🪟

On Unix, GS_PATH is not used at all 🙅‍♀️ Ghostscript gets called as gs(1) and has to be found over $PATH, so make sure it's on there, bestie.

---

✨ SEE ALSO ✨

okay so if you want more, go check out dvihp(1), dvicopy(1), dvips(1), xdvi(1), mktexpk(1), gs(1), and kpathsea(3) 📚🦋

Email bug reports to tex-k@tug.org 💌

The source lives at <http://mirror.ctan.org/dviware/dviljk/>, but for compiling you need the texk build environment, which you can grab from <svn://tug.org/texlive/*/Build/source>. 🛠️

As of July 2007, the PCL reference docs were on HP's website at <http://h20000.www2.hp.com/bizsupport/TechSupport/Document.jsp?objectID=bpl04568>. At the bottom of that page are links to reference manuals for PCL and PJL. 🌸

In case that page ever changes, here are the URLs for these docs directly. They all follow the form <http://h20000.www2.hp.com/bc/docs/support/SupportManual/bpl<ID>/bpl<ID>.pdf>, where <ID> is the document ID listed below. 🫶

• 13205 — PCL 5 Technical Quick Reference Guide. This is the first thing to look up if you have questions about PCL escape sequences. 👀
• 13210 and 13211 — PCL 5 Technical Reference Manual (part I and II). This is the fully detailed explanation you need when you don't understand how the printer works. Part I is the actual manual, and part II explains HP-GL/2 and has overall tips. 📖
• 13208 and 13207 — PJL Technical Reference Manual (and addendum). 💜
• 13212 — PCL 5 Color Manual. This explains color specials for the newer HP printers. (Not of much use today; for practical purposes we would need to add color specials to dvilj first. 💀)
• 13206 and 13209 — Comparison Guide (and addendum), which documents which PCL escape sequences are supported on which HP printers. 🦋

---

✨ AUTHOR ✨

dvi2xx was made by Gustaf Neumann, Wirtschaftsuniversitaet Wien. 👑

The dviljk fork is by Karl Berry. 🌈

Joachim Schrod <jschrod@acm.org> supplied security fixes and updated this man page. 🔥

dviljk is currently maintained as part of TeX Live. 💖

---

✨ LICENSE ✨

dvi2xx is public domain software. The dviljk changes are covered by the GNU General Public License. ⭐

---

Version 2.6p5, dated 2022-08-30, DVILJ(1) — and that's a wrap, bestie! Stay iconic out there 💅🎀🌸