Grail Preferences Settings

Note: This document is somewhat out of date. There are many new preference settings that still need to be described in this document.

This document describes the specific preference settings defined in the standard Grail installation. The default values for each of these setting are defined in the file grail-defaults in the main directory of the distribution.

There are a number of ``preferences groups'' defined in Grail. This document is organized with a section devoted to each group. Each of these sections describes the purpose of the group and provides a list of the components within the group and information on the components' type and interpretation. Entries for individual settings will be of the form:

component-name → datatype: A brief description of the value and how it should be formatted. Rules for interpretation are provided here as well. If datatype is an enumeration, it will be shown as option1 | option2 | option3, the specific options described in the text.

Applets Group
Bookmarks Group
Browser Group
Disk Cache Group
History Group
Landmarks Group
Parsing HTML Group
Preferences Group
Presentation Group
Printing Group
Proxies Group
Styles Group

Applets Group

groups →
load →

Bookmarks Group

add-location → file-append | file-prepend | as-child-or-sib
aggresive-collapse → boolean
include-in-pulldown → boolean: If true, bookmarks are placed at the end of the Bookmarks menu. This should only be enabled for short bookmarks files. Parsing a large bookmarks file may be too slow if not already loaded in memory.

Browser Group

default-height → integer
default-width → integer
initial-geometry → string: The value of initial-geometry is an X11 geometry specification which will be used when creating the initial browser window. If this is an empty string, window manager policies will dictate window placement.
load-images → boolean: If true, in-line images will be loaded automatically while HTML pages load.
load-initial-page → boolean
show-logo → boolean
show-splash → boolean
smooth-scroll-hack → boolean

Disk Cache Group

checkpoint → boolean
directory → string
freshness-test-type → always | never | per session | periodic
freshness-test-period → real: The minimum period between automatic freshness tests for a page, in hours. This should only be used if freshness-test-type is periodic.
size → integer: The maximum size of the disk cache, in kilobytes. This does not include the size of the cache log.

History Group

view-by → titles | urls: Defines the initial display mode for the history dialog.

Landmarks Group

about-grail-page → url
cnri-home-page → url
grail-home-page → url
home-page → url
psa-home-page → url
python-home-page → url

Parsing HTML Group

The settings in this group relate to the interpretation of HTML documents. The group name may change in the next release of Grail.

format-h1 → string

format-h2 → string

format-h3 → string

format-h4 → string

format-h5 → string

format-h6 → string

These strings are used to format header numbers when the SEQNUM or SKIP attributes to the header elements is used. Each setting is a Python string literal that can contain limited formatting controls. The string is formatted against a dictionary containing the current sequence number for each header level keyed by the general identifiers for the heading tags. The dictionary might be represented as

{ 'h1': 1, 'h2': 1, 'h3': 3,
  'h4': 0, 'h5': 0, 'h6': 0 }

in Python source code. This particular value might represent the header shown in bold below:

<BODY>
<H1>...</H1>
  <H2>...</H2>
    <H3>...</H3>
    <H3>...</H3>
    <H3>this one</H3>

honor-colors → boolean

If true, the color attributes of the BODY element (ALINK, BGCOLOR, LINK, and VLINK) are honored, otherwise they are ignored.

strict → boolean

If true, advanced SGML recognition is enabled.

Preferences Group

The settings in this group are used to control the behavior of the preferences framework.

panel-order → string: The value of this setting is a space-separated list of preferences panel names. The list specifies the sequence of entries in the Preferences menu presented to the user.

Presentation Group

Settings in this group control various aspects of Grail's display which are independent of the documents being handled.

message-font → string: Font specification for the message are just below the URL entry box on the browser window.

Printing Group

The settings in this group control aspects of the printed representation of HTML documents.

command → string: Command to invoke the print spooler. The command must accept the postscript data on its standard input.
footnote-anchors → boolean: If true, footnotes are generated for hypertext links.
greyscale → boolean: If true, images are converted to greyscale for printing.
images → boolean: If true, images are printed.
to-file → boolean: If true, postscript output is written to a file by default rather than being set to the print spooler.

Proxies Group

ftp_proxy → http url: URL that acts as the FTP URL relay. Example: http://foo.mumble.edu:8080
http_proxy → http url: URL that acts as the HTTP URL relay. Example: http://foo.mumble.edu:8080
manual_proxy_enabled → -1 | 0 | 1: Specifies weither manual proxying is unspecified (i.e. factory defaults), disabled, or enabled. When manual_proxy_enabled is -1, grail looks for http_proxy and ftp_proxy environment variables to bootstrap the proxy preferences. manual_proxy_enabled is set to 1 if it finds either ftp_proxy or http_proxy defined and non-NULL in the environment, 0 otherwise.
no_proxy_enabled → -1 | 0 | 1: Specifies weither the no-proxy exception mechanism is unspecified (i.e. factory defaults), disabled, or enabled. When no_proxy_enabled is -1, grail looks for no_proxy defined and non-NULL in the environment. Upon finding it, grail sets the no_proxy preference to match the environment variable and sets no_proxy_enabled to 1, otherwise,, no_proxy_enabled is set to 0.
no_proxy → string: A comma separated list of hosts that do not require the proxy service for access. Example: ftp.python.org, ftp.dlib.org, www.python.org

Styles Group

The font parameter styles preferences provides a means of specifying fonts to be used for the text entities (plain text, headers, links, and so forth) according to font family and size class parameters. The parameters will be combined with the font templates styles-fonts group to specify the browser text entities. The anchor presentation styles-common preferences provide the means to customize the rendition of text anchors.

By following the following instructions you can add specifications for new font families and sizes to a grail preferences file, so it will automatically be recognized for use by the Styles preference panel.

To add a font size:

Create a name-sizes style pref, specifying the respective point-sizes.
Include the name on the all-sizes style pref.
Optionally, set the size and/or default-size style pref to this size name.

To add a font family:

Choose a font family name that is valid for your display.
Create a <name>-italic style pref, specifying the character to use for an oblique slant for that family.
Include the family name on the all-families style pref.
Optionally, set the family and/or default-family style pref to this family name.

size → string: One of the sizes named in all-sizes style pref, it designates the font size class for all browser text.
Example: medium
family → string: One of the families named in the all-families style pref, it designates the font family for all excepting fixed-width browser text.
Example: helvetica
default-size → string: Specifies a stable, system-default size name for fallback when the specified font size (which should be one of those listed on the all-sizes style pref) is invalid.
default-family → string: Specifies a stable, system-default value for fallback when the specified font family (which should be one of those listed on the all-families style pref) is invalid.
all-sizes → string: White-space delimited sequence of valid size names. For each name there should be a corresponding <name>-sizes entry, detailing the point-size values corresponding to the size-names style pref.
Example: tiny small medium large huge
<name>-sizes → string: One of this class of style pref should be created for each size name specified in all-sizes. The values should be numbers, corresponding to each of the with a value of either 'i' or 'o', indicating the character indicating the oblique slant for the font family.
all-families → string: White-space delimited sequence of valid family names. Each name should be a font family supported by your display. This dictates the valid set of values for the family and default-family style prefs. For each family name, you must create a <name>-italic style preference. Example: helvetica times
<name>-italic → string: An instance of this style pref class should be created for each font family name specified in all-families, with a value of either 'i' or 'o', indicating the character indicating the oblique slant for the font family.
size-names → string: White-space delimited names of text tags used by the text widget for the various text entity renderings. This is used to correlate the components of the various <name>-sizes style prefs with tag font sizes. Items would be added here, and on the respective <name>-sizes, when new text tag entities are created, or existing ones are changed.
Example: default h1_b h2_b h3_b h4_b h5_b h6_b _b _i _b_i _tt _tt_i _tt_b _tt_b_i
<name>-sizes → string: An instance of this style pref class should be created for each size name specified in all-sizes, with components designating the point-sizes of the corresponding size-names text tag entity.
Example: 14 18 18 14 12 12 12 14 14 14 14 14 14 14

styles-a-foreground → string
styles-a-underline → Boolean: Unvisited anchor's foreground color (e.g., #0000EE) and underline presentation style.
styles-ahist-foreground → string
styles-ahist-underline → Boolean: Already visited anchor's foreground color (e.g., #551A8B) and underline presentation style.
styles-atemp-foreground → string
styles-atemp-underline → Boolean: Currently-pursued anchor's foreground color (e.g., #FF0000) and underline presentation style.

styles-fonts--default-font → string
styles-fonts--styles-h1_b-font → string
styles-fonts--styles-h2_b-font → string
styles-fonts--styles-h3_b-font → string
styles-fonts--styles-h4_b-font → string
styles-fonts--styles-h5_b-font → string
styles-fonts--styles-h6_b-font → string
styles-fonts--styles-_i-font → string
styles-fonts--styles-_b-font → string
styles-fonts--styles-_b_i-font → string
styles-fonts--styles-_tt-font → string
styles-fonts--styles-_tt_i-font → string
styles-fonts--styles-_tt_b-font → string
styles-fonts--styles-_tt_b_i-font → string: Templates by which the text widget styles are determined, by combination with the font parameters described above. These templates should not be changed unless you are changing the repertoire of Grail text-widget tag entities.