Advanced Printing Configuration

Grail 0.3 features a much-improved printing engine over that found in Grail 0.2. This is a product of improvements in the general formatter used for screen display and printing as well as improvements to the printing engine itself. Specific changes are listed in the news file; information on taking advantage of the extended configurability of Grail's printing is given here.

Three specific aspects of printing are addressed, each of which is designed to be configurable in some manner. Some configurations are handled at the PostScript® level rather than through preference settings, and not all preference-controlled options are represented in the dialog at this time. Information about the printing surface is generally configured via the ``Printing Preferences'' dialog while control over the headers and footers is effected via an optional PostScript file which can be set up by a user in his or her personal ~/.grail/ directory as described below. The formatting of the document content itself can only be affected by a few options which can be set in the preferences dialog or the printing dialog.

The Printing Surface

A number of parameters may be set to tell Grail about how the formatted document relates to the actual paper. The ``Printing Preferences'' dialog may be used to specify the size of the paper and orientation of the document on the page. Any of a number of standard paper sizes may be selected from the menu. This option cannot be controlled from the printing dialog, but is unlikely to need changing often. Note that Grail does not include any PostScript in its output to select a paper tray when the document is printed; the size selected should be the default tray for the printer to which the document will be sent.

The orientation of the document on the page may be controlled from either preferences or printing dialogs. This is done to ease the use of Grail both for people who prefer an orientation other than portrait as well as to allow switching the orientation for the occaisional document which lends itself to an orientation other than the default.

The margins of the page default to 1 inch on all four sides. At this time, there is no way to change this from within Grail, but the setting of the ``printing--margins'' preference may be changed manually by copying the line for this setting from the grail-defaults file to the ~/.grail/grail-preferences file and making appropriate changes. The setting for this preference consists of four numbers, one for each margin. Each value is interpreted as printer's points (1/72 inch). In order, these represent the top, bottom, left, and right margins.

Headers and Footers

Controlling the headers and footers of a document is the most difficult aspect of controlling Grail's printing. To change these parts of the printed document, new PostScript functions need to be written which use parameters to generate the appropriate output. The most important thing to remember when writing these functions is that there is little that can be done to affect the layout of content on the page from these functions; information about the page size and margins is provided in a group of variables. Information is also available on the date and time at which printing was initiated. The document title, URL, and page number are passed in to the procedures as parameters.

Grail sets up a default PostScript environment as do most applications generating PostScript output. After the default environment is established, Grail check the user preference printing--user-header; if set, this is interpreted as a space-separated list of PostScript files which should be included in the prologue. The file names are interpreted relative to ~/.grail. These files may redefine the functions which display the header and footer on each page. Examples are provided in the file SampleGrailDir/ in the Grail distribution; starting with that file may be useful. The examples defined there use a different font for the headers and footers and also demonstrate how a ``duplexing'' affect may be achieved for use with printers that support duplexing directly or for duplexing on a copier. When using this approach to augment Grail, make sure you read the example file and the file in the main Grail source directory before beginning.

User-definable Functions

url title pageno GrDecorateEvenPage -
This function is expected to add the header & footer to an even-numbered page. The default implementation simply calls GrDecorateOddPage, which is appropriate for non-duplexed output.

url title pageno GrDecorateOddPage -
Similar to GrDecorateEvenPage but called for odd-numbered pages.

Utility Functions

string1 string2 GrCatstrings string3
Concatenate two strings. This can be useful for producing interesting page-decoration functions. Hopefully there's a better way to implement this.

Interesting Variables

GrYear, GrMonth, GrDay, GrHour, GrMinute, GrSecond, GrWeekday, GrJulian, GrDST

Useful time & date information for the local time zone. All values are integers; refer to the Python Library Reference for more information on the values of these numbers.

GrUTCYear, GrUTCMonth, GrUTCDay, GrUTCHour, GrUTCMinute, GrUTCSecond, GrUTCWeekday, GrUTCJulian, GrUTCDST
Useful time & date information for Coordinated Universal Time.

Document Content

For Grail 0.3, only minimal support is provided to control the formatting of document contents. Controls are provided in the dialogs to allow anchors to be underlined or footnoted (or both), and to specify if images should be printed in greyscale (necessary on some older PostScript level 1 printers), color, or not at all.