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.

  1. Applets Group
  2. Bookmarks Group
  3. Browser Group
  4. Disk Cache Group
  5. History Group
  6. Landmarks Group
  7. Parsing HTML Group
  8. Preferences Group
  9. Presentation Group
  10. Printing Group
  11. Proxies Group
  12. 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.

General Instructions for adding fonts to Grail
To add a font size:
To add a font family:

Styles preferences - Grail font parameters
sizestring
One of the sizes named in all-sizes style pref, it designates the font size class for all browser text.
Example: medium
familystring
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-sizestring
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-familystring
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-sizesstring
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>-sizesstring
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-familiesstring
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>-italicstring
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-namesstring
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>-sizesstring
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-common preferences - Grail anchor presentation
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 preferences - Templates for Grail font construction
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.