genscript1

Usage

Overview

Genscript converts ASCII files to PostScript and spools generated PostScript output to the specified printer or leaves it to file. Genscript can be easily extended to handle different output media and it has many options which can be used to customize printouts.

Options

-1, -2, --columns=num

Specify how many columns each page have.

Note! with long option --columns=num you can specify more than 2 columns per page.

-b header, --page-header=header

Use text header as a page header. This works only for simple (non-fancy) page headers. The default page header is constructed from file's name and last modification time.

-B, --no-header

Do not print page headers.

-c, --truncate-lines

Cut lines that are too long. As a default, genscript wraps long lines so no information is lost.

-C, --line-numbers

Precede each line with its line number.

-d queue

Spool output to the printer queue queue.

-D key[:value], --setpagedevice=key[:value]

Pass a page device definition to the generated PostScript output. If no value is given, key key is removed from definitions.

For example, command

genscript -DDuplex:true foo.txt

prints file foo.txt in duplex (two side) mode.

Page device operators are implementation dependant but they are standardized. See section PAGE DEVICE OPTIONS for details.

-e, --special-escapes

Enable special escapes interpretation (see section SPECIAL ESCAPES).

-f name, --font=name

Select font that is used for body text. Font specification name contains two parts: font's name and font's size in points. For example "Times-Roman12" selects "Times-Roman" font with size 12pt.

The default body font is Courier10, unless multicolumn landscape printing mode is selected, in which case the default is Courier7.

Note! font's size can be given as a decimal number. For example "Times-Roman10.2" selects 10.2pt "Times-Roman" font.

-F name, --header-font=name

Select font for header texts.

-g, --print-anyway

Print file even if it contains binary data. Option is here only for compatibility since genscript prints binary files anyway.

-G, --fancy-header[=name]

Print fancy page header name to top of each page. Option -G specifies the default fancy header (see section CONFIGURATION FILES to see how the default fancy header can be changed).

-h, --help

Print short help and exit.

-i num, --indent=num

Indent every line num characters.

-l, --lineprinter

Emulate lineprinter. This option is a shortcut for options: --lines-per-page=65, --no-header, --portrait, --columns=1.

-L num, --lines-per-page=num

Print only num lines per each page.

-m, --mail

Send mail notification to user after print job has been completed.

-M name, --media=name

Select output media name. Genscript's default output media is A4.

-n num, --copies=num

Print num copies of each page.

-N nl, --newline=nl

Select the newline character. Possible values for nl are: n (unix newline, 0xa hex) and r (mac newline, 0xd hex).

-o file

An alias for option -p, --output-file.

-O, --list-missing-characters

Print a listing of character codes that couldn't be printed.

-p file, --output-file=file

Leave output to file file. If file is `-', leave output to stdout.

-P queue, --queue=queue

Spool output to the printer queue queue.

-q, --quiet

Make genscript really quiet. Only fatal error messages are printed to stderr.

-r, --landscape

Print in landscape mode; rotate page 90 degrees.

-R, --portrait

Print in portrait mode (default).

-s num, --baselineskip=num

Specify the baseline skip in PostScript points. Number num can be given as a decimal number. When genscript moves from line to line, current point y coordinate is moved (font point size + baselineskip) points down (the default baselineskip is 1).

-S key[:value], --statusdict=key[:value]

Pass a statusdict definition to the generated PostScript output. If no value is given, key key is removed from definitions.

Statusdict operators are implementation dependant; see printer's documentation for details.

For example, command

genscript -Ssetpapertray:1 foo.txt

prints file foo.txt by using paper from the paper tray 1 (assuming that printer supports paper tray selection).

-t title, --title=title

Set banner page's job title to title.

-T num, --tab-size=num

Set tabulator size to num (default is 8).

-u text, --underlay=text

Print string text under every page. Text's properties can be changed with options --ul-font and --ul-gray.

-v, --verbose[=level]

Tell what genscript is doing.

-V, --version

Print genscript version and exit.

-X name, --encoding=name

Use input encoding name. Currently genscript supports following encodings:

latin1

ISO-8859/1 (ISO latin1) (genscript's default encoding).

latin2

ISO-8859/2 (ISO latin2)

ascii

7-bit ascii

asciiscands

7-bit ascii with some scandinavian extensions

ibmpc

IBM PC charset

mac

Mac charset

vms

VMS multinational charset

ps

PostScript font's default encoding

-Z, --pass-through-ps-files

Pass through all PostScript files without any modifications. This allows that genscript can be used as a lp filter. PostScript files are recognized by looking up the `%!' magic cookie from the beginning of the file. Note! Genscript recognized also the Windoze damaged `^D%!' cookie.

--download-font=fontname

Include the font description file (.pfa or .pfb file) of the font fontname to the generated output.

--list-media

List the names of all known output media and exit successfully.

--list-options

List all options and their current values. Exit successfully.

--page-label-format=format

Set page label format to format. Page label format specifies how labels for the `%%Page:' comments are formatted. Possible values are:

short

Print only page number: `%%Page: (1) 1' (default)

long

Print current filename and pagenumber within file: `%%Page: (main.c: 1) 1'

--ul-font=name

Select font for the underlay text.

--ul-gray=num

Print underlay text with gray value num (0 ... 1), the default gray is .8.

Configuration files

Genscript reads configuration information from following sources (in this order): command line options, environment variables GENSCRIPT and ENSCRIPT, user's configuration file ($HOME/.genscriptrc) and system's global configuration file (prefix/lib/genscript/genscript.cfg).

The configuration files has the following format:

Empty lines and lines starting with `#' are comments.

All other lines are option lines and have format:

OPTION [arguments ...].

Following options can be specified:

AFMPath: path

Specifies search path for the AFM files.

DefaultEncoding: name

Select the default input encoding. Encoding name name can be one of the values of the -X, --encoding option.

DefaultFancyHeader: name

Select the default fancy header. Default header is used when option -G is specified or option --fancy-header is given without an argument. System-wide default is `enscript'.

DefaultMedia: name

Select the default output media.

DefaultOutputMethod: method

Select the default target to which generated output is send. Possible values for method are:

printer

send output to printer

stdout

send output to stdout

DownloadFont: fontname

Include the font description file of the font fontname to the generated output.

LibraryPath: path

Specifies genscript's library path that is used to lookup various resources. Default path is: `prefix/lib/genscript:home/.genscript'. Where prefix is the installation prefix (usually /usr/local) and home is the user's home directory.

Media: name width height llx lly urx ury

Add a new output media with name name. Media's physical dimensions are width and height. Media's bouding box is specified by points (llx, lly) and (urx, ury). Genscript prints all graphics inside media's bouding box.

User can select this media by giving option -M name.

PageLabelFormat: format

Set page label format to format. Possible values for format are the same that can be given to the --page-label-format option.

Queue: name

Names the printer queue to spool to.

QueueParam: name

The spooler command switch for the printer queue, e.g. -P in lpr -Pps.

SetPageDevice: key[:value]

Pass a page device definition to the generated PostScript output.

Spooler: name

Names printer spooler command. Genscript pipes generated PostScript to command name.

StatusDict: key[:value]

Pass a statusdict definition to the generated PostScript output.

Customization

Users can create their own fancy headers by creating a header description file and placing it in a directory that is in genscript's library path. The name of the header file must be in format: `headername.hdr'. Header can be used by giving option: --fancy-header=headername.

Header description file contains PostScript code that paints the header. Description file must provide procedure do_header which is called by genscript at the beginning of every page.

Header description file contains two parts: comments and code. Parts are separated by a line containing text:

% -- code follows this line --

Genscript copies only the code part of description file to the generated PostScript output. The comments part can contain any data, it is not copied. If separator line is missing, no data is copied to output.

Genscript defines following constants that can be used in header description files:

d_page_w

page width

d_page_h

page height

d_header_x

header lower left x coordinate

d_header_y

header lower left y coordinate

d_header_w

header width

d_header_h

header height

d_output_w

output width (~ d_page_w)

d_output_h

output height (~ d_page_h - d_header_h)

usadatestr

date in USA format: MM/DD/YY

eurdatestr

date in european format: YY/MM/DD

findatestr

date in finnish format: DD.MM.YYYY

timestr

current time: HH:MM:SS

user_header_p

predicate that tells if user has defined his/her own header string: true/false

user_header_str

if user_header_p is true, this is the user supplied header string.

HF

standard header font (from -F, --header-font option). This can be selected simply by invoking command: `HF setfont'.

pagenum

the number of the current page

fname

the full name of the printed file (/foo/bar.c)

fdir

the directory part of the file name (/foo)

ftail

file name without the directory part (bar.c)

fmodstr

file's last modification time in format `Thu Aug 17 09:05:20 1995'

gs_languagelevel

PostScript interpreter's language level (currently 1 or 2)

According to Adobe's Document Structuring Conventions (DSC), all resources needed by a document must be listed in document's prolog. Since user's can create their own headers, genscript don't know what resources those headers use. That's why all headers must contain a standard DSC comment that lists all needed resources. For example, used fonts can be listed with following comment:

%%DocumentNeededResources: font fontname1 fontname2

Comment can be continued to the next line with the standard continuation comment:

%%+ font fontname3

Special escapes

Genscript supports special escape sequences that can be used to add some page formatting commands to ASCII documents. As a default, special escapes interpretation is off, so all ASCII files print out as anyone expects. Special escapes interpretation is activated by giving option -e, --special-escapes to genscript.

All special escapes start with the escape character ^@ (octal 000). Escape character is followed by escape's name and optional options and arguments.

Currently genscript support following escapes:

epsf

inline EPS file to the document. Escape's syntax is:

^@epsf[options]{filename}

where options is an optional sequence of option characters and values enclosed with brackets and filename is the name of the EPS file.

If filename ends to the `|' character, then filename is assumed to name a command that prints EPS data to its standard output. In this case, genscript opens a pipe to the specified command and reads EPS data from pipe.

Following options can be given to the epsf escape:

c

print image centered

r

print image right justified

n

do not update current point. Following output is printed to that position where current point was just before the epsf escape

nx

do not update current point x coordinate

ny

do not update current point y coordinate

xnum

move image's top left x coordinate num characters from current point x coordinate (relative position)

xnuma

set image's top left x coordinate to column num (absolute position)

ynum

move image's top left y coordinate num lines from current line (relative position)

ynuma

set image's top left y coordinate to line num (absolute position)

hnum

set image's height to num lines

snum

scale image with factor num

sxnum

scale image in x direction with factor num

synum

scale image in y direction with factor num

As a default, all dimensions are given in lines (vertical) and characters (horizontal). You can also specify other units by appending an unit specifier after number.

Possible unit specifiers and corresponding units are:

c

centimeters

i

inches

l

lines or characters (default)

p

PostScript points

For example to print an image one inch high, you can specify height by following options: h1i (1 inch), h2.54c (2.54 cm), h72p (72 points).

font

select current font. Escape's syntax is:

^@epsf{fontname}

where fontname is a standard font specification. Font specification is valid to the end of the current page; pagebreak resets font to the default value. Special font specification default can be used to select the default body font (genscript's default or the one specified by the command line option -f, --font).

comment

comment the rest of the line including the newline character. Escape's syntax is:

^@comment text newline_character

Options

Page device is a PostScript level 2 feature that offers an uniform interface to control printer's output device. Genscript protects all page device options inside an if block so they have no effect in level 1 interpreters. Although all level 2 interpreters support page device, they do not have to support all page device options. For example some printers can print in duplex mode and some can not. Refer to the documentation of your printer for supported options.

Here are some usable page device options which can be selected with the -D, --setpagedevice option. For a complete listing, see PostScript Language Reference Manual: section 4.11 Device Setup.

Printing examples

Following printing examples assume that genscript uses the default configuration. If default actions have been changed from the configuration files, some examples will behave differently.

Environment

GENSCRIPT		string containing default options
ENSCRIPT		string containing default options

For example, to select the default body font to be Times-Roman 7pt, set following value to the GENSCRIPT environment variable:

GENSCRIPT=-fTimes-Roman7

Environment variables are processed before the command line options, so command line options can be used to overwrite these defaults.

Note! Variable ENSCRIPT is processed only to support backward compatibility to the enscript program. It should not be used otherwise.

Files

library/*.hdr	header files
library/*.enc	input encoding vectors
library/*.eps	predefined EPS images
library/*.ps	genscript procsets
library/genscript.cfg	system-wide configuration file
library/genscript.pro	PostScript prolog
library/afm/*.afm		AFM files for PostScript fonts
library/afm/font.map	directory for the AFM files
~/.genscriptrc		personal configuration file
~/.genscript/		personal resource directory

Where library is genscript's library directory (installation prefix/lib/genscript).