Customizing GFF

Most aspects of GFF are configured by modifying the gff.ini file in the same directory as the executable.[2] This is a plain text file that can be edited with any text editor you wish. If you edit this file using a word processor, make sure that you save the file in plain text mode so that additional control codes are not inserted by your application.

[2] On UNIX systems, where there may be multiple users, you can create a copy of the global configuration in your home directory and modify that file. Ask your system administrator where the global configuration file is on your system.

WARNING:
Modifying the configuration file has a direct impact on the performance of GFF. Inappropriate changes to the configuration file will completely cripple GFF. Always make a backup copy before you make any changes.

Please visit the GFF Web Center for late-breaking news and the most up-to-date customization information.

The install process creates a default gff.ini, and you should not need to make any changes in order to get GFF to run.

Format of the gff.ini File

The following rules define the format of the gff.ini file:

gff.ini is a plain text file divided into named sections. Each section begins with its name in square brackets. The order of sections within the file is irrelevant.
Within each section, variable-value pairs are stored by assignment in the form variable=value.
Section and variable names are case-insensitive.
The names of variables must be unique within each section. The order of variables within a section is mostly irrelevant. However, in the [ format list ] and [ software list ] sections, the order is relevant. The variables in each of these sections are used to construct lists; items are placed in the lists in the order that they appear in these sections.
The names of sections must be unique within the file.
Lines beginning with a semicolon are comments; they are ignored.

Note: changes to the initialization file while GFF is running have no effect. In the 1.0 release of GFF, GFF never makes any changes to the gff.ini file.

Sections in the gff.ini File

Unless otherwise noted, a section is used by all implementations of GFF (Windows, Macintosh, and UNIX). The following sections occur within the file:

[ config ]

This section defines general configuration options for GFF.

CDROMRoot

Defines the root directory of the CD-ROM drive. On a PC running Windows, this should be the drive letter of the CD-ROM drive that contains the GFF CD-ROM followed by a slash (for example, d:/). On the Macintosh, this should be the volume name of the GFF CD-ROM followed by a slash (for example, OReilly_GFF_1_0/). On UNIX, this should be the name of the CD-ROM mount point (for example, /cdrom).

GFFDir

Defines the root directory of the Encyclopedia of Graphics File Formats. It is set to /gff/graphics during installation. If you prefer the text-only version of GFF, set it to /gff/textonly (also change the ``substitution'' sections of the gff.ini file, described below, if you do this).

HomePage

Defines the initial file displayed by GFF, relative to the root directory of the Encyclopedia. When GFF is installed, this is set to ../textonly.htm, which displays the GFF ``splash screen.'' You can bypass this screen by changing HomePage to main.htm.

LogFile

Under UNIX, setting this value to the name of a file will cause GFF to write a log of transactions and some additional status information to that file. This variable is not supported on any other platforms in GFF 1.0.

CloseBrowser

Normally, GFF does not close the browser if you exit GFF directly (as opposed to closing the browser yourself, which automatically ends GFF). If this variable is set to 1, GFF will close the browser if it started it.

[ DDE ]

This section identifies browsers that GFF can communicate with. It is only used by the Windows implementations of GFF.

In this section, each variable should be the DDE (Dynamic Data Exchange) name registered by an SDI-compliant browser. The value of that variable should be the full path and filename of that browser.

When GFF starts, it searches for a running instance of each of these browsers, in order. If it fails to find one, it attempts to start each of them, in order.

[ UnixSockets ]

This section identifies browsers that GFF can communicate with. It is only used by the UNIX implementations of GFF.

At present, this section is unused. GFF determines which browser it can communicate with by examining environment variables at run time. Consult the INSTALL file in the directory containing your UNIX implementation of GFF for more information.

[ AppleEvents ]

This section identifies browsers that GFF can communicate with. It is only used by Macintosh implementation of GFF.

In this section, each variable should be the name of an SDI-compliant browser, for example ``Mosaic'' or ``Netscape''. The name is not really relevant, it is simply a mnemonic for the user. The value of that variable should be the creator code of the browser.

When GFF starts, it searches for a running instance of each of these browsers, in order. If it fails to find one, it attempts to start each of them, in order.

[ imagemap mapname ]

This section of the file is used internally by GFF. Do not change any values in this section.

[ pages ]

This section of the file is used internally by GFF. Do not change any values in this section.

[ substitute ]

This section of the file is used internally by GFF. Do not change any values in this section. If you plan to use the text-only version of GFF, rename this section to [ graphics substitute ].

[ textonly substitute ]

This section of the file is used internally by GFF. Do not not change any values in this section. If you plan to use the text-only version of GFF, rename this section to [ substitute ].

[ format list ]

Each of the variables in this section is a short name, a key, for a file format. The value of each key is the full name of that format. When additional formats become available on the GFF Web Center, you will be able to incorporate them into your installed version of GFF by adding a new section to the gff.ini file and updating this list. For now, don't make any changes to this section.

[ formatkey ]

There is one section for each key variable defined in the [ format list ], described above. Within this section, the following variables are defined:

Names

A comma-separated list of alternate names for this format. All of the names of the format should be listed here. This is the list that GFF searches when you search for a particular format by name.

File

If you set the file to the complete path name of a file, GFF will display that file when you view this format, instead of trying to display the version on the CD-ROM.

Several other variables are defined for each format in the gff.ini file that is created during installation. In GFF 1.0, these variables are not used.

[ software ]

The variables in this section determine how software on the CD-ROM is displayed when you view a particular format. By default, all packages are displayed.

Message

Defines the text of the message displayed before the list of software.

Platforms

Defines the platforms that should be displayed. This is a simple space-delimited list of values. In GFF 1.0, only the following values are defined: mac, mswin, msdos, os2, and unix.

If a platform occurs in this list, software for that platform will be displayed when you view a format. Regardless of the value that you use here, you can always look at all of the software packages from the Software page.

platform-value

Defines the full name of each platform.

[ software list ]

Each of the variables in this section is a short name, a key, for a software package. The value of each key is the full name of that package. Additional packages can be incorporated into your installed version of GFF by adding a new section to the gff.ini file and updating this list. For more complete instructions about how to do this, please check the GFF Web Center.

[ softwarekey ]

There is one section for each key variable defined in the [ software list ], described above. Within this section, the following variables are defined:

Name

Defines the full name of the software package.

Platform

Defines the platform that the software package runs on. In GFF 1.0, only the following values are defined: mac, mswin, msdos, os2, and unix. Also, in GFF 1.0, only a single platform may be defined.

Formats

A simple space-delimited list of the formats which this software package understands. These values must be key variables in the [ format list ] section of gff.ini in order to be of any use.

Additional Customization for the UNIX Version

While the Macintosh and Windows versions of GFF use information in the gff.ini file to find the browser, the UNIX version uses environment variables. This is the more common means of customization under UNIX. Four variables may be set:

GFF_HOST

Defines the name of the host where the browser is running. The default is localhost. This variable is of dubious utility since GFF and the browser must each have access to the CD-ROM. In most cases, GFF and the browser run on the same host, so the default value, localhost, is correct.

GFF_BROWSER

Defines the command line which must be executed in order to start your browser. This command line should include the full pathname of the browser executable and any arguments required to start the SDI. The default value is /path/emosaic -sdi.

GFF_SDIFILE

In order to communicate with the browser, GFF must know what port the browser is ``listening'' to for SDI requests. Spyglass Mosaic, the only browser known to support the SDI under UNIX at this time, stores the port number in a file in the users home directory. The default value for the name of this file is stored in GFF. GFF_SDIFILE is provided so that you can specify an alternate name, in case some other browser supports the SDI specification under UNIX in the future.

GFF_DEBUG

If this value is set to 1, additional messages are displayed while GFF initializes.