Man page for psdim(1)

NAME

psdim - calculate optimal page format for n-up printing from a postscript file

SYNOPSIS

psdim [options] [filename]

DESCRIPTION

psdim is a small utility to be used in conjunction with pstops. It looks at the contents of a postscript document to determine the size of the printed pages. From this, it calculates the optimal placement of the pages for n-up printing. It outputs a format string suitable for processing by pstops.

In order to determine the size of the pages in a postscript document accurately, psdim uses the ghostscript interpreter to render the document. For this reason, psdim is relatively slow, but yields very accurate results that could not be obtained by just naively looking at the postscript headers. For psdim to work, gs must be installed on your system.

OPTIONS

The following options are supported:

-h, --help

Print usage information and exit.

-v, --version

Print version information and exit.

-l, --license

Print license information and exit.

-q, --quiet

Suppress printing progress information. Normally, psdim prints page numbers to stderr for each page processed.

-x, --width dim

Specify the physical width of the output paper.

-y, --height dim

Specify the physical height of the output paper.

-p, --page format

Specify the format of the output paper: one of a4, a3, a5, b5, letter, legal, tabloid, statement, executive, folio, quarto, 10x14. The default is letter. Paper formats are case insensitive. The -p option is equivalent to a corresponding pair or -x and -y options.

-m, --margin dim

Set the width of the margins between the document and the edge of the paper. The default is 0.5in.

-n, --hmargin dim

Like -m, but only set the horizontal (left and right) margins.

-o, --vmargin dim

Like -m, but only set the vertical (top and bottom) margins.

--lmargin dim

Like -m, but only set the left margin.

--rmargin dim

Like -m, but only set the right margin.

--tmargin dim

Like -m, but only set the top margin.

--bmargin dim

Like -m, but only set the bottom margin.

-s, --sep dim

Set the width of the white space separating input pages when they are combined on a single output page. The default is 0.5in.

-t, --hsep dim

Like -s, but only set the space in the horizontal direction.

-u, --vsep dim

Like -s, but only set the space in the vertical direction.

-L, --landscape

Select the landscape orientation (pages are rotated to the left). This is the default for 2-up and 8-up printing. Note that the printed text is rotated, not the physical page.

-R, --seascape

Select the seascape orientation (pages are rotated to the right). Note that the printed text is rotated, not the physical paper.

-U, --upside-down

Select the upside-down orientation.

-P, --portrait

Select the portrait (upright) orientation. This is the default for 4-up, 9-up, and 16-up printing.

-f, --format nxm

Arrange pages in n rows and m columns.

-a, --hpolicy n

Select the horizontal alignment policy. For n=0, the horizontal alignment of pages follows a rigid grid. For n=1, the pages in each column are aligned, but each column is centered in its available horizontal space. For n=2, each page is centered horizontally in its column. n=3,4 behave like n=1,2, except the width of the columns is variable.

-b, --vpolicy n

Select the vertical alignment policy. For n=0, the vertical alignment of pages follows a rigid grid. For n=1, the pages in each row are aligned, but each row is centered in its available vertical space. For n=2, each page is centered vertically in its row. n=3,4 behave like n=1,2, except the height of the rows is variable.

-c, --columnmode

Arrange the pages in columns (default is in rows). For instance, in 4-up printing, pages 1 and 2 will normally appear above pages 3 and 4. If -c is selected, pages 1 and 2 will appear to the left of pages 3 and 4.

-d, --righttoleft

Arrange the pages with page numbers increasing from right to left (default is from left to right).

-e, --bottomtotop

Arrange the pages with page numbers increasing from bottom to top (default is from top to bottom).

-C, --color

Handle colored backgrounds. This option must be given when the document uses a background color other than white. Color processing is significantly slower than black-and-white processing, and should only be used when necessary. Note: while psdim will calculate the correct document dimensions, pstops is very bad at cropping colored backgrounds and will probably do a bad job with such documents.

-i, --clip

Output page clipping instructions. Some PostScript documents specify an opaque background color, instead of leaving the background transparent. This happens particularly with scanned documents. In this case, pstops often overwrites all or part of one page in 2-up mode. The --clip option solves this problem by outputting additional page clipping instructions that can be understood by pstops-clip.

-F, --fudge [L|R|T|B]n

Set the percentage of pixels that are allowed out of bounds. The default is 0. When calculating the bounding box of a document, a small amount of text or pixels protruding into the margins can mess up the computation. The --fudge option makes the bounding box slightly smaller by allowing a percentage of the pixels to be outside the bounding box. This threshold can be set separately for the left (L), right (R), top (T), and bottom (B) margins.

Note that --fudge=20 is equivalent to --fudge=LRTB20. This means 20 percent of the pixels are allowed to be in each of the left, right, top, and bottom margins. Therefore up to 80 (and not 20) percent of the pixels can be outside the bounding box.

-H, --ladjust dim

-I, --radjust dim

-J, --tadjust dim

-K, --badjust dim

Shrink the input document's bounding box by moving the respective edge (left, right, top, bottom) by an additional amount towards the center of the page. This adjustment is applied after any fudging. Sometimes it is difficult to find the correct fudge percentage, and it is easier to just look at the document and specify an absolute dimension. A negative argument causes the bounding box to be enlarged instead of shrunk.

-S, --shrink

Only shrink, never enlarge page.

-1, --1up

Fit to size. Equivalent to -f1x1 --portrait.

-2, --2up

Equivalent to -f1x2 --landscape.

-4, --4up

Equivalent to -f2x2 --portrait.

-8, --8up

Equivalent to -f2x4 --landscape.

-9, --9up

Equivalent to -f3x3 --portrait.

-6, --16up

Equivalent to -f4x4 --portrait.

OPERANDS

If a filename is given, then a postscript document is read from that file. Otherwise, a postscript document is read from standard input.

DIMENSIONS

Several command line options take a dimension argument. Dimensions can carry one of the optional units in, cm, mm, or pt. Here, 1pt is a postscript point, or 1/72 inches. The default unit is in.

ALIGNMENT POLICIES

In n-up printing, several input pages are rearranged into rows and columns on a single output page. If all the input pages are of equal width, height, and margins, then it is a straightforward task to arrange them in a grid. However, if the input pages are of variable width, height, and/or margins, then several choices arise regarding their optimal placement. These choices are governed by the horizontal and vertical alignment policies, which are specified by the -a and -b options. The horizontal alignment policy affects only the x-coordinates of the pages in the output, and the vertical policy affects only the y-coordinates.

EXAMPLES

In the simplest case, psdim can be used to figure out an optimal format string for 2-up printing:

> psdim --2up test.ps
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10]
2:0@0.93L(9.79in,-1.13in)+1@0.93L(9.79in,4.09in)

The resulting format string can be fed directly to pstops:

> pstops `psdim --2up test.ps` test.ps test.2up.ps
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10]
[1] [2] [3] [4] [5]
Wrote 5 pages, 155746 bytes

EXIT STATUS

On successful completion, 0 is returned, otherwise a positive error number.

VERSION

1.8

AUTHOR

Peter Selinger <selinger at users.sourceforge.net>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. See also http://www.gnu.org/.