test

Solaris 8 Software Developer Supplement

Customizing Existing prolog Files and Adding New prolog Files

The prolog files can be divided into two main categories:

The customization of PostScript files is discussed first:

Customization of each category of prolog files is discussed next.

Common prolog Files

The common prolog files are:

These files are the print layout prolog files, of which mp.common.ps is the common prolog file that is prepended before other prolog files.

The common prolog file, mp.common.ps, which resides in the /usr/lib/lp/locale/C/mp/ directory, contains a PostScript routine to re-encode a font from the StandardEncoding to ISOLatin1 Encoding. The .reencodeISO routine is called from the print layout prolog files to change encoding of the fonts. Usually this prolog file does not need any customization. If the users are creating their own prolog files, set the environment variable MP_PROLOGUE to point to the directory that contains the modified prolog files.

Print Layout prolog Files

The print layout prolog files, mp.*.ps files, contain routines for controlling the page layout for printing. In addition to giving a header and a footer for a print page with user name, print date, and page number, these prolog files can provide other information. For example, the prolog files can give effective print area dimensions and landscape and portrait mode of printing to be used.

A set of standard functions needs to be defined in every prolog file. These functions are called when a new print page starts, print page ends, or a new column ends. The implementations of these functions define the print attributes of the printout.

The following PostScript variables are defined at runtime by the mp(1) binary. All the print layout files can use these variables for printing dynamic information such as user name, subject, print time. This information taken from the variables normally appears in the header or footer of the print page.

User

The name of the user who is running mp, obtained from the system passwd file.

MailFor

Variable used to hold the name of the type of article to print. The possible values for this variable are:

  • “Listing for” - When the input is a text file

  • “Mail for” - When the input is a mail file

  • “Article from” - When the input is an article from a news group

Subject

The subject taken from the mail and news headers. You can use the '-s' option to force a subject to the mail and news files as well as to normal text files.

Timenow

The time of print that appears in the header and footer. This information is taken from the localtime() function.

Following are the functions implemented in print layout prolog files. All these functions can use subfunctions.

endpage

usage : page_number endpage

Called when the bottom of a printed page is reached. This function restores the graphic context of the page and issues a “showpage.” In some prolog files the header and footer information is displayed in only a page-by-page mode rather than in a column-by-column mode. You can implement this function to call subfunctions that display the header and footer gray scale lozenges.

newpage

usage : page_number newpage

Routines or commands to be executed when a new page begins. Setting landscape print mode, saving the print graphic context, and translating the page coordinates are some of the functions for routine.

endcol

usage : page_number col_number endcol

Display header and footer information. Move to the new print position, and so forth.

For adding new print layout prolog files, you need to define the following variables explicitly within the print layout prolog file.

NumCols 

<number of columns in a print page> 

PrintWidth 

<width of print area in inches> 

PrintHeight 

<height of print area in inches> 

Locale-Dependent Prolog File

The locale-dependent prolog file is /usr/openwin/lib/locale/$LANG/print/prolog.ps and it usually is a PostScript file. This file can contain included Type1 fonts that define PostScript prolog information with some additional PostScript routines. One of the main goals of the prolog file is to set the locale's fonts in an alias for a set of font names that are pre-defined and used in the mp(1).

Support for this file is provided to conform with the prolog.ps file that is used by /usr/bin/mp. If this file exists, then it is given preference and mp.conf file is not scanned for backward compatibility.

The sections about mp.conf file that follow are reprinted from the OpenWindowsTM Localization Guide.

What Is prolog.ps

The purpose of the prolog.ps file is to set up non-generic fonts. Applications use these pre-defined PostScript font names for printing. The prolog file must define at least the following font names for Desk Set Calendar manager and mp.

These fonts need to be able to print the local character set in the following example usage of those fonts:

Example of the prolog.ps File

The localization kit provides a sample prolog.ps for the Japanese environment. Alternatively, this file is found in the /usr/openwin/lib/locale/ja/print/ directory.

How to Add or Change Composite Fonts in an existing prolog.ps File

For example, the following defines a composite font called LC_Base-Font:

%
(Foo-Fine) makecodeset12 
(Base-Font) makeEUCfont
%

LC_Base-Font is a composite font of Foo-Fine and a base font called Base-Font. Foo-Fine is a font that contains the local character set. You do not need any in-depth PostScript knowledge to add or change a font.

How to Create a prolog.ps File

The best way is to study the example version. In the example prolog.ps, two routines need to be written, makecodeset12 and makeEUCfont. Makecodeset12 sets up local font encoding information. This routine might differ from locale to locale. MakeEUCfont combines the base font and the locale font to form a composite font. The creator of the prolog file should have good knowledge of PostScript in order to write makecodeset12 and makeEUCfont.

prolog.ps file support is kept for backward compatibility only. Do not create a new prolog.ps file for the printing needs of a locale. Use mp.conf instead.

Where Is prolog.ps?

The path is:

/usr/openwin/lib/locale/$LANG/print/prolog.ps

.xpr File Customization

These files are located, by default, at /usr/lib/lp/locale/C/mp/. A .xpr file corresponds to each PostScript prolog layout file, except for mp.common.ps. You can define an alternate prolog directory by defining the MP_PROLOGUE environment variable.

These files work as keyword/values pairs. Lines that start with "#" are considered comments. Spaces separate different tokens unless explicitly stated in the following description. Three main sections for each .xpr file are bound by the following keyword pairs:

Certain keyword/value pairs can be used in these three areas. Each area is described next.

STARTCOMMON/ENDCOMMON Keywords

All the keyword/value pairs that appear after the STARTCOMMON keyword and before the ENDCOMMON keyword define general properties of the print page. Different valid values for a keyword are separated by using "/".

ORIENTATION 0/1

"0" means the printing occurs in portrait and "1" means in landscape.

PAGELENGTH <unsigned integer>

A value that indicates the number of lines per logical page.

LINELENGTH <unsigned integer>

A value that indicates the number of single column characters per line.

NUMCOLS <unsigned integer>

The number of logical pages per physical page.

HDNGFONTSIZE <unsigned integer>

The heading font point size in decipoints.

BODYFONTSIZE <unsigned integer>

The body font point size in decipoints.

PROLOGDPI <unsigned integer>

The dots-per-inch scale in which the current .xpr file is created.

YTEXTBOUNDARY <unsigned integer>

This y-coordinate establishes the boundary for text printing in a page or logical page (column). This boundary is used as an additional check to see whether text printing is occurring within the expected area. This boundary is needed for Complex Text Layout and EUC printing, as character height information obtained from corresponding fonts can be wrong.

STARTTEXT <unsigned integer> <unsigned integer>

The decipoint x/y points where the actual text printing starts in the first logical page in a physical page.

PAGESTRING 0/1

The 1 indicates that a "Page" string needs to be appended before the page number in the heading.

0 indicates that only the page number is displayed.

EXTRAHDNGFONT "font string 1, font string 2, ... font string n”

The 'font string 1' to 'font string n' are X Logical Font Descriptions. The Token which separates the keyword EXTRAHDNGFONT from the comma separated font name list is '"', not spaces or tabs. These fonts are given preference over the built-in fonts when printing of the heading occurs. Usually, EXTRABODYFONT is used to assign printer-resident fonts that are configured in /usr/openwin/server/etc/XpConfig/C/print/models/<model name>/fonts directory. The fonts.dir contains the XLFD of the printer-resident fonts.

Usually a font is specified like

"-monotype-Gill Sans-Regular-r-normal- -*-%d-*-*-p-0-iso8859-2"

in the .xpr file. "%d", if present, is replaced by the mp(1) to the point size of the current heading fonts in the .xpr file. The x resolution and y resolution are specified "*" and the average width field is set as "0" to indicate selection of scalable font, if possible. You can give more specific font names also.

EXTRABODYFONT “font string 1, font string 2, ... font string n”

This is the same as EXTRAHDNGFONT, except that these fonts are used to print the page body.

XDISPLACEMENT <signed/unsigned int>

Gives the x coordinate displacement to be applied to the page for shifting the contents of the page in the x direction. This displacement can be a +ve or -ve value.

YDISPLACEMENT <signed/unsigned int>

This parameter is the same as x displacement except that the shifting happens in the y direction.

These two keywords are useful when you find that some printers have nonstandard margin widths and you need to shift the printed contents in a page.

STARTPAGE/ENDPAGE

The keyword value pairs in this section are bound by STARTPAGE and ENDPAGE keywords. This section contains drawings and heading information that is to be applied for a physical page. A physical page can contain many logical pages, but all the drawing routines that are contained between these keywords are applied only once to a physical page.

The valid drawing entities are LINE and ARC. XDrawLine and XDrawArc functions are executed on values of these keywords.

The dimensions within this section are mapped in PROLOGDPI units. Angles are in degrees.

LINE x1 y1 x2 y2

The /y unsigned coordinates define a pair of points for connecting a line.

ARC x y width height angle1 angle2

x and y are both unsigned integers that represent the arc origin. Width and height are unsigned ints that represent the width and height of the arc.

USERSTRINGPOS x y

Unsigned coordinates represent the position in which the user information is printed on the heading.

TIMESTRINGPOS x y

Unsigned coordinates represent the position in which the time for printing is printed on the heading.

PAGESTRINGPOS x y

Unsigned coordinates represent the position to print the page string for each printed page.

SUBJECTSTRINGPOS x y

Unsigned coordinates represent the position to print the subject in the page.

STARTCOLUMN/ENDCOLUMN

All keywords are the same as the previous STARTPAGE/ENDPAGE section except that the entries in this section are applied to NUMCOLS times to a physical page.

If NUMCOLS is 3, then the printable area of the physical page is divided into three, and lines, arcs, or heading decorations are three times per page.