path: root/dviware/dvipsconfig/README

Release 1.6   11 May 2006	Added mmgrid and a4grid, millimetre grids.
Release 1.5   02 Aug 2000	Added addpsctrl, a filter program which can add
				these control instructions to already existing
				PostScript files.
				Added US ledger paper.
Release 1.4   22 Mar 2000	Added tray selection.
				Thanks to Steffen Klupsch for suggesting it.
Release 1.3.2 09 Mar 2000	License change only. Modified README.
Release 1.3,  19 Feb 1999
Release 1.2,  25 Jan 1998
Release 1.13, 21 Aug 1995
Release 1.12, 02 Mar 1995
Release 1.0,  20 Feb 1995


OVERVIEW
========

This is a set of PostScript header files which can be used to control the
printer, like simplex/duplex printing, or the printing, like screen frequencies
of images, or the addition of a grid underlay. These header files work with
dvips, and can also be inserted with the addpsctrl script into existing
PostScript files.

Put together by Volker Kuhlmann <VolkerKuhlmann@gmx.de>.
This collection of files is available under the name of "dvipsconfig" from

	ftp://dante.ctan.org/tex-archive/dviware/dvipsconfig/

or from any other CTAN host under the same path.
Alternatively, from:

	http://volker.dnsalias.net/soft/texmf/

This software is copyright (C) Volker Kuhlmann, and is freely distributable
under the terms of the GNU General Public License version 2.
Parts of the code in config.psgrid are derived from previous material and are
distributed with permission. See the file for details.


LIST OF FILES
=============

README		This file.
addpsctrl	Shell script which inserts these printer control files into
		into already existing PostScript files (can also be used by
		print filters)
config.*        Configuration files *and* header files for dvips.
		Special format where each file serves both purposes.


INSTALLATION
============

Copy addpsctrl into a directory which is searched for executable programs.

Copy README and all config.* into a directory which is searched by dvips both
for configuration files AND for header files. Each of these files have a dual
function (easier maintenance) and hence must be found under each category
(dvips config and dvips header).

For current installations of web2c respectively teTeX 1.x, consult the file
texmf.cnf for search paths. Currently configured search paths can be displayed
with 
	kpsewhich --show-path "dvips config"
	kpsewhich --show-path "PostScript header"

To check up whether the place was any good, run (both!)
	kpsewhich --format "dvips config" config.duplong
	kpsewhich --format "PostScript header" config.duplong
and don't forget to run mktexlsr...
In case of problems, also check for any .dvipsrc files.

dvips(k) 5.78 kpathsea version 3.2, web2c 7.2, looks in $TEXCONFIG and
$TEXPSHEADERS.

dvips (dvipsk 5.58f, web2c 6.2) looks in $TEXCONFIG for configuration files,
and in $DVIPSHEADERS for header files. For details please see the dvips
documentation (environment variable use seems to change with dvips versions).


USAGE
=====

dvips reads the instructions in a configuration file <configfilename>
with the -P option:

	dvips -P <configfilename> ...

All these configuration files contain the PostScript code for the
respective operation as well, and can be used as header file as they are.

Now to the material provided:

Duplex printing:
---------------

-P simplex      On a duplex printer, force printing in simplex mode.
		On a simplex printer, this will be ignored.

-P duplong      On a duplex printer, force duplex printing with binding
		on the long edge.
		This is what you want for e.g. an A4 upright book.
		On a simplex printer, this will be ignored.

-P dupshort	On a duplex printer, force duplex printing with binding
		on the short edge.
		Useful for e.g. printouts in landscape.
		On a simplex printer, this will be ignored.

Paper size selection:
--------------------

-P a3		Switch the printer to use A3 paper.
		Note: "-t a3" must still be used as well!
		Only works with PS level 2 devices, ignored otherwise.

-P a4		Switch the printer to use A4 paper.
		Note: "-t a4" must still be used as well, unless it is
		the default.
		Only works with PS level 2 devices, ignored otherwise.

-P usletter	Switch the printer to use US letter paper.
		Note: "-t letter" must still be used as well, unless it
		is the default.
		Only works with PS level 2 devices, ignored otherwise.

-P usledger	Switch the printer to use US usledger paper.
		Note: "-t ledger" must still be used as well, unless it
		is the default.
		Only works with PS level 2 devices, ignored otherwise.

Screen frequencies and dot functions:
------------------------------------

-P screenN	Print images with a screen frequency of N lpi at
		45 degrees with the "dot" spot function. 
		N = {35, 50, 70, 80, 85, 90, 100, 110, 120, 130, 140, 150}

-P screen100_0	Print images with a screen frequency of 100lpi
		at 0 degrees with the "dot" spot function.
		A 0 degree screen angle is only useful as illustration!

Note:   When working with screen frequencies, it is possible that
	turning the printer off and back on solves the problem of the
	screen commands not having any effect. Previous print jobs may
	leave the printer in a different state.

Colour printer media selection:
------------------------------

-P tek550paper	Switch Tektronix 550 and 560 colour printers to print on paper.

-P tek550transparency	Switch Tektronix 550 and 560 colour printers to print
			on transparency.

Paper tray selection:
--------------------

-P manualfeed	Print on paper from the manual feeder.
		The printer waits for the paper to be loaded after receiving
		the job.
		This should work with almost any printer.

-P envelope	Print on paper from the envelope feeder.
		This should at least work with most HP laser printers.

-P tray1	Print on paper from "tray 1".
		This often is the manual feeder / upper tray / multipurpose
		tray (at least for HP laser printers).

-P tray2	Print on paper from "tray 2".
		This often is the lower tray (at least for HP laser printers).

-P tray3	Print on paper from "tray 1".
		This often is the large capacity / lower cassette (at least for
		HP laser printers).

Note: Tray selection is very printer-dependent. tray1..3 will not work for all
printers. Possible effects of them if the tray doesn't exist, or if the command
is simply wrong for the printer, include the print job being cancelled, or at
best the command being ignored. Email me with any problems and I might be able
to fix it - I don't have that many printers for testing :-)

Reported behaviour:
  HP Laserjet 5M, -P envelope: print job cancelled if tray doesn't exist.
  HP Laserjet 4000N, -P envelope and -P tray3 don't exist: job is printed on 
	paper from the standard tray instead.

Thanks to Steffen Klupsch <steffen@vlsi.informatik.tu-darmstadt.de> for initial
suggestions about the tray selection material, and some beta testing.

Misc:
----

-P psgrid	Print a PostScript coordinate grid onto the page. This can be
		very useful for checking by how much the printer shifts the
		image on the paper, or to check whether things end up in the
		correct place.

-P mmgrid	Print a millimetre grid onto the page. Much more userfriendly.
		Otherwise the same as -P psgrid.

-P a4grid	Print a millimetre grid onto the page, starting in the top-left
		corner. Much more useful for checking page layout.

-P inv          Print all pages inverted, i.e. white letters on black
		background.
		Note: this currently does not work properly. Any
		      hints/fixes greatly appreciated!


CONTROLLING SCREEN FREQUENCIES
==============================

Various PostScript commands for controlling the screen frequencies of
images exist, but not all work on all printers. See fragments of
PostScript code and comments below. The form working on most printers is

	LPI DEGREES {FUNCTION} setscreen

Insert numbers for LPI and DEGREES, and a function for FUNCTION about
which I only know (right or wrong?):

	"Should read 2 values from the stack (x, y coordinates in a
	halftone cell), and return one in the range -1 to 1. The return
	values determine the order in which pixels within a halftone
	cell are whitened to produce any desired shade of gray."

The simplest function is {pop}, creating a "linescreen" pattern. There
is also a function "Dot" (currently used) and "Ellipse". For any other
frequencies/angles/functions put the instructions in a file, and load
the file with

	dvips -h <filename>

Thanks to osakari@unda.fi (Olavi Sakari) for some help, and the "Dot"
and "Ellipse" code.

Notes follow:


%currentscreen 3 1 roll pop pop 70 45 3 -1 roll setscreen
% Works on HP LJ3Si, HP LJ4m. Ignored on HP LJ4mv (VK).


%currentscreen 3 1 roll pop pop 70 45 3 -1 roll sethalftone
% Ignored on HP LJ4mv (VK).


%70 45 {pop} setscreen
% Produces a funny, 1-diagonal pattern ("linescreen") on HP LJ4mv (VK).


% "Dot":
%70 45 {abs exch abs 2 copy add 1 gt {1 sub dup mul exch 1 sub dup mul add 1
%    sub }{dup mul exch dup mul add 1 exch sub }ifelse} setscreen
% Works on HP LJ3Si, HP LJ4m, HP LJ4mv (VK).


% "Ellipse":
%70 45 {dup 5 mul 8 div mul exch dup mul exch add sqrt 1 exch sub} setscreen
% Works on HP LJ4mv (VK).


%70 45
%<<
%     /HalftoneType 1
		%  0 gives range check error, 2 gives undefined error (VK).
%     /Frequency 150
%     /Angle 20
		% the values for /Frequency, /Angle are irrelevant
%     /SpotFunction {pop}
%>>
%setscreen	
% 70 45 seem to replace /Frequency and /Angle in dict
% - Note: NO curly braces around the dict!
% Works on HP LJ4m, produces errors with HP LJ3Si, 
% Produces "linescreen" on HP LJ4mv caused by {pop} (VK).


%<<
%     /HalftoneType 1
%		%  0 gives range check error, 2 gives undefined error (VK).
%     /Frequency 70
%     /Angle 45
%     /SpotFunction {pop}
%>>
%sethalftone  % Level 2 only
% Produces "linescreen" on HP LJ4mv caused by {pop} (VK).


ADDPSCTRL
=========

The addpsctrl program works as a filter. The given controls are inserted into
the PostScript data. The config.* files are located by running kpsewhich, or
by specifying the directory they're in. This allows to use addpsctrl without
having to have a TeXMF installation. For further info run addpsctrl --help.


TODO
====

Control the screen frequency without altering the dot function.

Supply separate controls for setting the dot function.