diff options
author | Joachim Schrod <jschrod@acm.org> | 2007-07-05 14:26:40 +0000 |
---|---|---|
committer | Joachim Schrod <jschrod@acm.org> | 2007-07-05 14:26:40 +0000 |
commit | 5f318ef720ca53edf4f5aa92ecae7b8c5d31c29c (patch) | |
tree | 331b3a5ef9cc95c2ad37e65f8e02bbc81b92f611 /Build/source/texk/dviljk/dvilj.pod | |
parent | 61da5cc4b72cb8ca4343ffc74e61cef6849034c9 (diff) |
Release 2.6p4.
Updated documentation, man page is now generated from POD.
git-svn-id: svn://tug.org/texlive/trunk@4547 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/dviljk/dvilj.pod')
-rw-r--r-- | Build/source/texk/dviljk/dvilj.pod | 609 |
1 files changed, 609 insertions, 0 deletions
diff --git a/Build/source/texk/dviljk/dvilj.pod b/Build/source/texk/dviljk/dvilj.pod new file mode 100644 index 00000000000..c20258215c9 --- /dev/null +++ b/Build/source/texk/dviljk/dvilj.pod @@ -0,0 +1,609 @@ +=head1 NAME + +dvilj4, dvilj4l, dvilj2p, dvilj - convert a TeX DVI file to PCL, for HP LaserJet printers + +=head1 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] + +=head1 DESCRIPTION + +B<dvilj> and siblings convert TeX-output C<.dvi> files into PCL (the +Hewlett-Packard Printer Control Language) commands suitable for +printing on a HP LaserJet+, HP LaserJet IIP (using B<dvilj2p>), HP +LaserJet 4 (using B<dvilj4>), and fully compatible printers. + +B<dvilj4> also provides support for the builtin Intellifont and +TrueType fonts; TFM and VF files are provided in the distribution. +Virtual fonts are not supported directly by B<dvilj>, so you must run +dvicopy(1) first, or otherwise expand the virtual fonts + +All programs are generated from one source file F<dvi2xx.c>. They are +usually called via a shell script or as a line printer filter. One +such script, dvihp(1), is included in the distribution. It provides +command-line options similar to those of dvips(1). + + +=head1 OPTIONS + +=over + +=item B<--D>I<number> + +Debug according to the bits of I<number>; see the kpathsea(3) manual +for values. Also turns on general verbosity. + +=item B<-c>I<number> + +Print each page I<number> times (including original) + +=item B<-d>I<number> + +print in duplex mode. The option B<-d1> means long edge binding, +B<-d2> stands for short edge binding. This option is only selectable +in B<dvilj4> and B<dvilj2p>. + +=item B<-D>I<[-12]> + +Double-sided printing - see below; B<-D1> prints odd sides only, +B<-D2> is for even pages, a trailing B<-> suppresses printing of empty +padding pages. + +=item B<-E> + +Switch printer into econo mode (B<dvilj4> only). + +=item B<-e>I<outfile> + +Send output to F<outfile> instead of the basename of dvi file extended +with C<.lj>. If outfile is B<-> (as in C<-e->) the output is directed +to standard output and can be directly piped into a spooler. + +=item B<-f>I<pagenum> + +Print pages with TeX page numbers greater than or equal to I<pagenum>. + +=item B<-g> + +I<Go> mode: do not reset printer at start of job. + +=item B<-h>I<headerfile> + +Copy F<headerfile> to output before translation of the DVI file. Used +to send arbitrary commands to the laserprinter. + +=item B<-l> + +Print output in landscape mode; supported only by B<dvilj2p> and +B<dvilj4>. + +=item B<-M>I<flag> + +Do (not) call mktexpk(1) to generate fonts on demand. B<-M1> and B<-M> +are equivalent. B<-M0> enables invoking mktexpk(1). (This is the same +as in dvips(1).) The default behavior (i.e., if no B<-M> option is +given) is chosen at compile-time; as distributed, mktexpk is enabled. + +=item B<-m>I<magnification> + +Specify the magnification to use. The following are available: + + -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 + +=item B<-p>I<pagecount> + +Print I<pagecount> pages after the starting page. + +=item B<-q> + +Quiet operation: omit final statistics, etc. + +=item B<-r> + +Toggle page reversal. + +=item B<-s>I<pagesize> + +Specify the page size: + + -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 are from the PCL 5 technical reference manual. If the +B<-s> commandline option is omitted, no clipping is performed at the +bottom of the page. (But printing below the paper bottom should not +disturb any correctly behaving PCL printer.) Please remember that the +correct paper tray must be installed for selected paper size, so use +this option only if you have full control over your print destination. + +=item B<-t>I<pagenum> + +Print pages with TeX page numbers less than or equal to I<pagenum>. + +=item B<-v> + +Verbose mode: list fonts used, etc. + +=item B<-V>I<mode> + +Compatibility mode. As I<mode>, use C<K> for Kyocera, C<B> for +Brother, C<6> for LJ6 printers. + +=item B<-w> + +Omit warnings. + +=item B<-x>I<offset> + +Global x-offset in mm on output page relative to 1 inch/1 inch origin. + +=item B<-y>I<offset> + +Global y-offset in mm on output page relative to 1 inch/1 inch origin. + +=item B<-X>I<offset> + +Global x-offset in dots on output page (overrides 1 inch/1 inch +origin). + +=item B<-Y>I<offset> + +Global y-offset in dots on output page (overrides 1 inch/1 +inch origin). + +=item B<-z> + +Print a test page with the page counter at end of job. + +=back + + +=head1 OPERANDS + +If no operands are specified a brief usage message is displayed. + +=over + +=item I<filename> + +The DVI file name that shall be converted by B<dvilj>. It must always +be seekable. + +The output file name is constructed from I<filename>. Either an +extension C<.dvi> is replaced by C<.lj>, or the extension C<.lj> is +appended. + +If I<filename> is B<->, the DVI file is read from standard input and +the resulting PCL document is written to standard output. (Please +remember that thhe DVI file must be seekable, even if it's stdin.) + +=back + + +=head1 SUPPORTED TeX \special COMMANDS + +C<\special> commands supported by B<dvilj> have the generic syntax + + \special{key1=value key1="value with space"} + \special{key3 = value key4 = 'note optional spaces around equal sign'} + +I.e., specials are a sequence of key/value pairs, separated by an +equal sign. Spaces around the equal sign are ignored. The value is +either a space separated word, or a quoted string. Both double and +single quotes can be used, alternatively. There is no support for +quoting quote characters in values; if you want both double and single +quotes in one value, you're out of luck. + +The following key/value combinations are valid: + +=over + +=item B<hpfile>=I<file> + +Insert I<file> at the current position. I<file> is searched with +kpathsea(3), see below. + +The file content must be valid for this printer, i.e., it should +contain PCL escape sequences or HP-GL/2 commands. If the file is a +graphics file, this typically means that the upper left corner of the +graphics is placed at the current position. + +PCL absolute positioning escape sequences in I<file> are rewritten to +be relative positioning commands; the lowest appearing coordinate is +used as reference. + +=item B<hpfile_verbatim>=I<file> + +Insert I<file> verbatim at the current position, without any changes +of the file content. I<file> is searched with kpathsea(3), see below. + +This is mostly used to keep absolute positions in PCL files. + +=item B<psfile>=I<file> B<llx>=I<x0> B<lly>=I<y0> B<urx>=I<x1> B<ury>=I<y1> B<rwi>=I<s> + +Convert Postscript file I<file> to HP PCL, by Ghostscript with device +C<ljetplus>, and insert the resulting graphics file at the current +position, rewriting absolute position escape sequences. I<file> is +searched with kpathsea(3), see below. + +The accompanying key/value pairs are mandatory, they can be specified +in an arbitrary order. Values I<x0>, I<x1>, I<y0>, I<y1>, and I<s> are +integers. (I<x0>,I<y0>) is the lower left corner, (I<x1>,I<y1>) the +upper right corner of the image. + +B<Please note: The specific semantics of this special is not known.> +In particular, the B<rwi> parameter is some scale factor; but even +looking at the source code it is not quite clear what the special's +author intended to implement here. In addition, it is unclear what +dimensions are used to specify the corners, Postscript points or PCL +dots. + +I<If you happen to know the psfile semantics, or if you spent the work +analyzing them, please inform us at tex-k@tug.org, so that we can +update this man page with the relevant information.> + +=item B<dvilj-psfile-syntax>=I<syntax> + +where I<syntax> is either C<dvilj> or C<ignore>. This is a very crude +way to tell the driver what to do with B<psfile> specials. + +If the value is C<ignore>, all B<psfile> specials that are processed +afterwards are ignored, until the next B<dvilj-psfile-syntax> special is +processed. + +If the value is C<dvilj>, B<psfiles> specials are processed as +explained above, until the next B<dvilj-psfile-syntax> special is +processed. + +An obvious, planned, extension is the value C<dvips>, but this has not +been implemented yet. + +That special is not as simple as it sounds at first. Since its +semantics is defined by processing order, it is only of use if it is +placed on the same page as the B<psfile> special. Having it once in a +file (e.g., on the first page) does not help if you print just one +page of the document -- B<dvilj> does not do prescanning of first-page +specials like some other drivers do. (Patches would be welcome, of +course.) + +=item B<comment>=I<arbitrary text> + +=item B<comment> I<arbitrary text> + +This causes the rest of the special to be ignored; it may be used to +add meta-information to a DVI file. + +With the first form, the comment may appear anywhere in the special. +When it appears first, the processing of this special is terminated +and all other text behind is ignored. + +The second form is a speciality that has been introduced for +compatibility with other drivers. If the first keyword of the special +is B<comment> and has no value, it is taken as a valid comment syntax, +too; the rest of the special is ignored. + +=item B<orientation>=I<po> + +Position the page on the physical paper. The value I<po> may be one of +the following values: + + 0 for portrait + 1 for landscape + 2 for reverse portrait + 3 for reverse landscape + +=item B<defpoint>=I<n(x,y)> + +Define the point number I<n>. This point can be referred to later in +other special commands to specify areas that shall be filled with some +pattern. I<n> must be between 0 and 79. + +I<x> and I<y> are the position of that point and have the form C<?pt> +where C<?> is a floating point number. The positions are relative to +the DVI page origin; i.e., coordinates increase moving right and down, +the point of origin is (1in,1in) in the upper left corner, altered by +options B<-x>, B<-y>, B<-X>, and B<-Y>, but not by \hoffset and +\voffset. + +I<x> and I<y> can be omitted, i.e., the values C<3> or C<4(,)> are +valid. Then the current page position is used as position for point +I<n>. + +=item B<resetpoints>=C<all> + +This undefines all points again. + +=item B<gray>=I<gray_scale> + +=item B<grey>=I<gray_scale> + +This sets the fill mode for the next B<fill> special, the area will be +filled with gray color. (B<grey> is an alias for B<gray>.) Any pattern +specification is reset. + +I<gray_scale> is the percentage of gray that shall be used here; with +C<0> meaning white and C<100> meaning black. + +Caveat: That special is actually a misnomer. PCL names these gray +scales I<shading patterns> and they are created by placing dots in the +area. The gray scale selects how far spread the dots are. In the lower +ranges, this doesn't look very gray on close sight, but more like a +dotted background. Furthermore, the gray scales are not as +fine-grained as the value range 0..100 might make you believe. In +reality, there are only 8 different gray patterns available: + + 1 - 2% + 3 - 10% + 11 - 20% + 21 - 35% + 36 - 55% + 56 - 80% + 81 - 99% + 100% + +One of these patterns is selected according to the I<gray_scale> value. + +=item B<pattern>=I<pat> + +This sets the fill mode for the next B<fill> special, the area will be +filled with a pattern. Any gray color specification is reset. + +I<pat> is one of the following values: + + 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 + +=item B<fill>=I<a/b> + +Fill the area between the points I<a> and I<b>, according to the +current fill mode. + +Point I<a> B<must> be the upper left corner and point I<b> B<must> be the +lower left corner of the rectangle. Otherwise the result is garbage. + +The default fill mode is 10% gray color filling. + +=item I<filename> + +This is a legacy special, its use is depreciated. If the special is +just one word that names an existing file, that file is verbatim +included. Contrary to other file inclusion means, the file is not +searched with kpathsea(3). I<You are not supposed to use this special +and we won't fix any problems with it.> + +=back + +It should be noted that the special parser does sometimes accept +constructs that are not valid as in the documentation above. Then, the +output is most often damaged in some way. + + +=head2 Searching for Included Files + +Proper file include specials search the file with kpathsea(3). The +search path is configured by variable C<DVILJINPUTS> and, if the file +is not found in that search path, by variable C<TEXINPUTS>. + +Search via C<DVILJINPUTS> covers the use case that one has common +site-wide graphics that shall be included in documents, e.g., scanned +signatures. Search via C<TEXINPUTS> covers the use case that one has +graphics as part of ones current document. + +C<dvilj> is used as the C<.PROGRAM> name in F<texmf.cnf>, for all +driver variants, independent of the actual program name. + + +=head2 Unknown Specials and C<TEX_HUSH> configuration + +Kpathsea(3) has the concept of warning suppression with the +configuration variable C<TEX_HUSH>, please refer to its Info node +I<TeX support / Suppressing warnings>. That variable holds a +colon-separated identifiers that specifies the to-be-suppressed +warnings. + +If C<special> is among the listed values, B<dvilj> does not output +warnings any more about specials that it doesn't know about. But if +there is a recognized special and if that special has an invalid +parameter, then a warning is output nevertheless, independent of the +content of C<TEX_HUSH>. + + +=head1 DOUBLE PAGE PRINTING + +If the printer has a duplex unit installed, duplex printing can be +demanded with the B<-d> option. + +Otherwise, the command line option B<-D> causes the printer to print +in doublepage mode, that is, roughly speaking, printing first the even +pages and then the odd pages of a document. If B<-D> is used to print +both even and odd pages (B<-D> is used without the optional 1 or 2) +the following will happen after half of the pages is printed: LJ: the +printer stops, shows message "FEED" and switches on manual feed led. +The printer continues when either the printed pages are fed into the +manual page feeder, or the operator pushes the continue button (after +placing first the printed pages into the paper tray). + +If B<-D1> was specified only odd pages will be printed, B<-D2> can be +used for even pages. A trailing C<-> (as in B<-D->, B<-D1-> or +B<-D2->) supresses printing of empty pages which are generated for +padding otherwise. + +The driver allows the B<-D> option for both print-directions +(front-to-back or back-to-front printing). It tries to be clever in +certain cases: when a document has an odd number of pages it inserts +in the right place an empty page when a document starts with page 0 +the driver inserts an empty page after the 0-page when a piece of a +document is printed that starts with an even page-number it prints +this page at the backside of the first page to ensure that the odd +sides are always on the frontside. The 0-page is treated like an odd +page. + +The doubleside option works for all LJs, not only for the new D model +with does doubleside-printing (actually, I don't know whether it makes +much sense on the new LJ II D at all). + +Caveat on the doubleside-option: When it is used frequently or on very +large files, it might become necessary to clean the printer much more +frequently. + +The command line option B<-p>I<X> can be used to abort printing after +the output of I<X> pages (can lead to strange results together with +B<-D>). I personally dislike this option. The secure way of printing a +part of a document is using B<-f> (from) and B<-t> (to). + +=head1 ENVIRONMENT + +B<dvilj> uses the same environment variables and algorithms for finding +font files as TeX and its friends do. See the documentation for the +kpathsea(3) library for details. (Repeating it here is too cumbersome.) + +=over + +=item C<DVILJFONTS> + +If set, overrides all other font paths. + +=item C<DVILJMAKEPK> + +If set, overrides mktexpk(1) as the name of the command to execute to +create a PK file if one isn't found. + +=item C<DVILJSIZES> + +May be set to indicate which sizes of fonts are available. It should +consist of a list of numbers separated by colons. If the list begins +with a colon, the system default sizes are used, as well. Sizes are +expressed in dots per inch; decimals may be used for C<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. +B<dvilj> tries the actual size of the font before trying any of the +given sizes. + +=item C<DVILJINPUTS> + +Primary search path for include files. + +=item C<TEXINPUTS> + +Secondary search path for include files. + +=item C<TEX_HUSH> + +Colon separated list of identifiers that name situations where no +warning shall be output. The following identifiers are used: + + 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 + +=item C<KPATHSEA_DEBUG> + +Trace kpathsea(3) lookups; set to -1 for complete tracing. + +=item C<GS_PATH> + +On Windows, this may be the path to Ghostscript; there the default is +F<gswin32c.exe>. + +On Unix, this environment variable is not used. Ghostscript is called +as gs(1) and must be found over $PATH. + +=back + + +=head1 SEE ALSO + +dvihp(1), dvicopy(1), dvips(1), xdvi(1), mktexpk(1), gs(1), +kpathsea(3) + +Email bug reports to tex-k@tug.org. + +Source is at L<http://mirror.ctan.org/dviware/dviljk/>; but for +compilation the texk build environment is needed, from +L<svn://tug.org/texlive/*/Build/source>. + +As of July 2007, PCL reference documentation is found at HP's Web site +at +L<http://h20000.www2.hp.com/bizsupport/TechSupport/Document.jsp?objectID=bpl04568>. +At the end of that page are links to reference manuals for PCL and PJL. + +In case that page is changed, here are the URLs of these documents. +All have the form +L<http://h20000.www2.hp.com/bc/docs/support/SupportManual/bplE<lt>IDE<gt>/bplE<lt>IDE<gt>.pdf>, +where C<E<lt>IDE<gt>> is the following document ID: + +=over + +=item B<13205> + +PCL 5 Technical Quick Reference Guide. This is the 1st thing to look up +if you have questions about PCL escape sequences. + +=item B<13210> and B<13211> + +PCL 5 Technical Reference Manual (part I and II). This is the +full-detailled explanation that you need to look up if you don't +understand how the printer works. Part I is the actual manual, part II +explains HP-GL/2 and has overall tips. + +=item B<13208> and B<13207> + +PJL Technical Reference Manual (and addendum) + +=item B<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 B<dvilj> first.) + +=item B<13206> and B<13209> + +Comparison Guide (and addendum) that documents which PCL escape +sequences are supported on which HP printers. + +=head1 AUTHOR + +dvi2xx by Gustaf Neumann <neumann@wu-wien.ac.at>, +Wirtschaftsuniversitaet Wien + +dviljk fork by kb@mail.tug.org + +Joachim Schrod <jschrod@acm.org> supplied security fixes and updated +this man page. + + +=head1 LICENSE + +dvi2xx is public domain software. dviljk changes are covered by the +GNU General Public License. |