--- name: "genscript" section: "1" platform: "linux" package: "genscript" version: "1.2.20-2" release: "Debian 1.1 (Buzz)" platforms: ["linux"] url: "https://new.carta.tech/genscript" --- # genscript(1) convert ASCII files to PostScript ## NAME genscript - convert ASCII files to PostScript ## SYNOPSIS **genscript** \[**-12BcCegGhlmOqrRvVZ\]** **\[-b** *header*\] \[**-d** *queue*\] \[**-D** *key*\[**:***value*\]\] \[**-f** *font*\] \[**-F** *header\_font*\] \[**-i** *indent*\] \[**-L** *lines\_per\_page*\] \[**-M** *media*\] \[**-n** *copies*\] \[**-N** *newline*\] \[**-o** *outputfile*\] \[**-o -**\] \[**-p** *outputfile*\] \[**-p -**\] \[**-P** *queue*\] \[**-s** *baselineskip*\] \[**-S** *key*\[**:***value*\]\] \[**-t** *title*\] \[**-T** *tab\_size*\] \[**-u** *text*\] \[**-X** *encoding*\] \[*filename* ...\] ## DESCRIPTION **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 - **x*num*** move image's top left *x* coordinate *num* characters from current point *x* coordinate (relative position) - **x*num*a** set image's top left *x* coordinate to column *num* (absolute position) - **y*num*** move image's top left *y* coordinate *num* lines from current line (relative position) - **y*num*a** set image's top left *y* coordinate to line *num* (absolute position) - **h*num*** set image's height to *num* lines - **s*num*** scale image with factor *num* - **sx*num*** scale image in *x* direction with factor *num* - **sy*num*** 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* ## PAGE DEVICE 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. - **Collate *boolean*** how output is organized when printing multiple copies - **Duplex *boolean*** duplex (two side) printing - **ManualFeed *boolean*** manual feed paper tray - **OutputFaceUp *boolean*** print output \`face up' or \`face down' - **Tumble *boolean*** how opposite sides are positioned in duplex printing ## 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. - **genscript foo.txt** Print file **foo.txt** to the default printer. - **genscript -Possu foo.txt** Print file **foo.txt** to printer **ossu**. - **genscript -pfoo.ps foo.txt** Print file **foo.txt**, but leave PostScript output to file **foo.ps**. - **genscript -2 foo.txt** Print file **foo.txt** to two columns. - **genscript -2r foo.txt** Print file to two columns and rotate output 90 degrees (landscape). - **genscript -DDuplex:true foo.txt** Print file in duplex (two side) mode (printer dependant). - **genscript -G2r foo.c** My default code printing command: Gaudy header, two columns, landscape. ## ENVIRONMENT VARIABLES ``` 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). ## SEE ALSO [lpr(1)](/lpr/1.md), [lpq(1)](/lpq/1.md), [lprm(1)](/lprm/1.md), [gs(1)](/gs/1.md), ghostview(1) ## AUTHOR Markku Rossi \ \ Predefined EPS images by Jussi Hynninen \