HIFF FORMAT SPECIFICATION

HYPERMEDIA INTERCHANGE FILE FORMAT

Revision history

Who can use HIFF

This document is Copyright The HyperMedia Group, 1990. You may copy and redistribute it freely, provided you do so only in its entirety, including this section. The names Hypermedia Interchange File Format and HIFF are trademarks of The HyperMedia Group. You can obtain a royalty-free license to use these trademarks by certifying that your product is fully compatible with published HIFF standards. (See Contacts information below.)

The products, algorithms, and techniques developed by The HyperMedia Group and its licensees for writing and reading HIFF files are proprietary and may be used only by those who have purchased or licensed them fromThe HyperMedia Group or its authorized resellers or relicensors.

Contacts

The HyperMedia Group
HIFF Specification
5900 Hollis Street, Suite O
Emeryville, CA 94608
AppleLink, Connect, MCI: HMG

Overview

• Exporting the document from its source environment;
• Transporting the resulting HIFF file physically or electronically, if necessary, to a computer where the target environment is available;
• Importing the HIFF data into the target environment.

Once a document has been exported to HIFF form, the resulting HIFF file can, in theory, be imported into any number of target environments that have an importer available.

Design philosophy

HIFF files are presently specified to be in readable (and, optionally, editable) text format , limited to the printable ASCII character set to maximize their transportability among environments.

Wherever possible, HIFF derives its terms for object types, properties and property values from existing hypermedia environments. In choosing terms for HIFF, the general rule of thumb was to adopt the term used in the earliest generally available product that incorporated a particular object type property or value. For example, while the terms card (usedby HyperCard from Apple Computer, Inc., and SuperCard from Silicon Beach Software, Inc.) and page (used by HyperPAD from Brightbill-Roberts, Inc. and ToolBook from Asymetrix Corp.) both refer to approximately the same object type, HIFF documents exported from all these environments would use card as the standard term for that object type. It is the responsibility of HIFF importers to map terms appropriately for their environment.

EXPORTERS AND IMPORTERS

Responsibilities of a HIFF exporter

• Examine a selected document, created in a source environment that the exporter is equipped to interpret, to determine its form and content. (In addition to individual documents, an exporter may operate on selected sets of documents. Each document, however, will yield a separate HIFF file.)
• Itemize and describe all (or a user-selected subset of) the objects comprising the document, their properties, and the values of those properties. Data or content (e.g. the text of a field) is considered a separate object or property (depending on context) for this purpose.
• Order the descriptions in a hierarchical structure paralleling the structure of the source document.
• Render the structured description into HIFF text format, with all objects, properties and values described in readable words where appropriate, and in hexidecimal text form where the data is of an essentially binary nature.
• Write the resulting description to a plain text file.

Responsibilities of an importer

• Determine from the header information in a text file whether it contains HIFF data in a version the importer is equipped to recognize.
• If so, create a new document in the target environment.
• Proceed object-by-object through the descriptions in the file. If an object has an analog in the target environment, create that analog in the new document; set analogous properties for the object to analogous values.
• Ignore and pass over all object, property, and value descriptions that do not have an analog in the target environment or that are unknown to the interpreter.
• Report to the user any anomalies or incompletely-translated elements in the new document that may require further attention to make the new document fully functional.

What HIFF does not translate to a common format

Scripting languages - Object scripts are presently exported unchanged from their native form in their creator environment. It is the responsibility of a HIFF importer to identify the source scripting language and version of a HIFF file, and either to employ its own cross-compiler for translating scripts to its environment, or to "comment out" any imported scripts that it cannot identify as executable in its environment.

Graphics - Rather than defining its own interchange format for graphics, HIFF relies on exisiting standardized graphics formats that can be incorporated within the HIFF framework, such as the Macintosh PICT format and the Windows bitmap format. Any graphic object in a HIFF file is required to have a property that specifies the format in which its image is encoded. It is the responsibility of a HIFF importer to provide or be able to access tools to interpret any standardized formats that the interpreter supports.

Externals - Machine-specific extensions to a hypermedia application may be exported as unmodified binary data if a user desires. Importers, however, are not expected to translate them or install them into the target environment. An importer may include facilities for mapping calls to externals from a source environment to comparable externals or native features in its target environment.

Resources - Data structures for information that are defined not by a hypermedia application but by the operating environment in which it exists, such as fonts, cursors and sounds, are either omitted or (generally at user option) exported in their native form into a HIFF file. It is the responsibility of an importer to determine if exported resources are relevant in its environment, and if so, to provide the capability to install them. As with externals (which are a special instance of the general category resources), an importer may include facilities for mapping uses of resources from a source environment to comparable resources or alternative structures in its target environment.

Audio-visual data - Video images and motion sequences, analog audio or digitized audio stored in other than a standard resource format, external device control capabilities (other than by standard script calls to an input or outport port where supported by a source environment), and event time sequence information (e.g. SMPTE time code) are presently beyond the scope of HIFF.

SPECIFICATION FORMAT

Typographic conventions

This is a single line of HIFF information 
	too long to be shown here on one line.
	Its continuation lines are indented.
This is a second line of HIFF text

Terms

• Alphabetic character - the letters A....Z and a...z, and the underscore character _ (ASCII 95 decimal) .
• Numeric character - the numerals 0....9, the character - precedes a numeral, and the character . (period) when it appears between two numerals.
• Alphanumeric character - either an alphabetic or numeric character.
• Nonalphabetic character, nonnumeric character, nonalphanumeric character - any printable ASCII character (i.e. in the range 32 to 126 decimal) not belonging to the respective sets defined above.
• Backslash - the character \ (ASCII 47 decimal)
• Open-brace - the character { (ASCII 123 decimal)
• Close-brace - the character } (ASCII 125 decimal)

Scope

THE HIFF FILE

Form

The standard extension for a HIFF file in DOS and OS/2 environments is .HIF, though HIFF importers should also automatically recognize files with the extension .TXT. The standard filetype in the Macintosh environments (and any other using similar filetype conventions) is HIFF, though HIFF importers should also automatically recognize files of filetype TEXT. There is no specified file creator for HIFF files.

A HIFF file uses only the standard ASCII printable character set, and the standard control codes for <CR>, <LF> and <TAB>. All other control codes and characters are represented in "escaped" format as detailed below, and interpreted according to the file's character_set property. Newline characters are significant structure information within a HIFF file, however HIFF importers are insensitive to whether <CR>, <LF>, <CR><LF> or <LF><CR> is used to delimit lines, so long as their usage is consistent throughout a file. Line delimiters may be translated freely to conform to a particular environment's convention for convenience in reading and editing the file with a text editor.

Information that has no meaningful text representation is encoded in hexadecimal form, two characters per byte , with 16 bytes per line followed by a newline. The final line may contain fewer than 16 bytes, and is concluded with a newline. HIFF does not add any length or error-correction information to the raw data. Here is an example of the format:

000001000300050009f8100820084008
2008100809f805000300010000000000
0007000a

HIFF (tm)
HyperMedia Interchange File Format -- TM, The HyperMedia Group
\HIFF_version {1.0}
\end_HIFF

If scripts of objects exist in both text and compiled forms, it is the text form that is exported to the HIFF file.

Syntax

The characters \, {, and } are defined, sometimes in conjunction with a newline, as special characters used to indicate the start and grouping of control words and symbols, object and property declarations, and property values. Where these characters appear in the data for other than their special HIFF purposes, they are respresented in "escaped" form as defined below.

The {, and } characters are used to indicate a group, which may be either data comprising a property value, or properties associated with an object. Structures or collections of objects larger than one object are not presently grouped by HIFF.

Defined HIFF words are case-insensitive. Thus \end_HIFF is equivalent to \end_hiff or \end_Hiff.

Blank lines (i.e. lines containing only a newline character) are not significant within HIFF except when contained within a property value. They may be included as desired to enhance readability, or omitted.

"Escaped" character format

Character	Escaped character/
Any below ASCII 32, except <CR>, <LF> or <TAB>	\'nn - where nn = the hex ASCII value 00 > 1f, left-padded with a zero if needed, e.g. \'02 or \'1c
Any above ASCII 127	\'nn - where nn = the hex ASCII value 7f > ff e.g. \'80 or \'a5
\	\\
{	\{
}	\}

Header Information

HIFF (tm)

followed by a newline.

The second nonblank line of a HIFF file must be

HyperMedia Interchange File Format -- TM, The HyperMedia Group

followed by a newline.

The third nonblank line of a HIFF file must contain the control word \HIFF_version and a value. The value for files conforming to this version of the specification is 1.0, thus:

\HIFF_version {1.0}

Following this header, the next nonblank line begins the object descriptions.

Control words

Control word	Meaning / Defined values
\HIFF_version	Version of the HIFF specification to which a file conforms; currently 1.0
\end_HIFF	End of a HIFF file; no significant data beyond this line

Control symbols

Hierarchical structure

Once the first object at a given level has been described, all objects belonging that object (such as all card buttons or card fields belonging to a particular card) are described before any further descriptions of objects at the given level. This pattern is recursive for each level of objects being described. An example of such a structure is:

document
	background 1
		non-card object 1 of background 1
		card 1 of background 1
			object 1 of card 1 of background 1
			object 2 of card 1 of background 1
			.
			.
			.
			object n of card 1 of background 1
		card 2 of background 1
			object 1 of card 2 of background 1
			object 2 of card 2 of background 1
			.
			.
			.
			object n of card 2 of background 1
    .
    .
    .
		card n of background 1
	background 2
	.
	.
	.
end-of-document

Objects belonging to lower hierarchical levels are assumed by HIFF to belong to the immediately-preceding higher-level object capable of "owning" an object of the type being described.

At a given level, all objects of a particular object type are described in sequence before any other object types at that level are described. The sequence used is whatever sequence the source application interprets the objects to be in. The order in which object types are described at a given hierarchical level may be arbitrary.

Thus, objects are grouped by their sequence in the HIFF file , which reflects the source document's implicit hierarchy. No additional punctuation or formatting is used, for example, to make explicit a grouping of objects that all reside on a particular card or background.

Default hierarchy: A HIFF file is assumed to have the following object hierarchy if no object_hierarchy property is included in the file:

file
resources
parent_file_information
backgrounds
background objects
cards
card objects

OBJECTS, PROPERTIES, AND VALUES

Objects

Properties

Implicit \HIFF_id property

1. This property is assumed implicitly for every object encoded in a HIFF file, though it may be encoded explicitly at the option of the exporter. It is a sequential numbering of all objects described in the file, beginning with 1 for the initial \file object, and incremented by 1 for each subsequent object described. Files subject to editing in which objects descriptions may be removed or added should include explicit \HIFF_id numbering. This property may be useful in resolving object ownership ambiguities, when used in conjunction with the \parent_object property.

File

1. The HIFF name of an application is the name appearing with the primary emphasis on the product's packaging or documentation, omitting any trademark or similar "bugs" and any descriptive phrases.
2. Note that if the document contains objects, properties, or script commands which were added by editing the document in a later version of the application, the importer may not recognize them.
3. A character set specification at the file level can theoreticaly be overridden by a property specified for a particular object containing text information, but this ability is not presently supported.
4. Throughout HIFF, \name property values (and \id property values) are in the format that HyperCard terms the "short" name or ID, that is the name or ID data by itself, with no qualifying words or punctuation.
5. This information may, to some degree, duplicate information encoded as \resource objects. It is provided because it is likely that users will choose to omit code resources from HIFF files, but script importer/translators will need to identify calls to externals that are no longer available in their original form, so that they can replace them or map them to alternatives available in the target environment.

Parent_file

Resource

Window

1. Where documents have only one window, or no defined window structure, the window name and the file name are the same.

Background

Background_graphic

1. The encoded data in the graphic description may define a smaller frame positioned within that defined by the rect property.
2. Throughout HIFF, the \layer property is reserved for defining the visual layering hierarchy for all objects belonging to a parent object, considered as a group without regard to object type.

Background_button

1. HyperCard uses the value 0 (zero) to indicate no icon is attached to the button. HIFF maps this value to a null or empty value to avoid confusion with any icon resource that happens to be numbered 0.
2. This can be somewhat redundant if the icon resource exists in the source document (rather than elsewhere in a resource chain). However, it also provides for capture of the images of icons that are in parent files or elsewhere in a resource chain, allowing the button graphic to be reconstructed even in the absence of the resource. And it provides flexibility for handling environments where icons are managed differently than in the resource model used by Macintosh.

Background_field

1. The text properties associated with fields in this version of the HIFF specification are oriented toward HyperCard 1.x fields limited to a single text style for the entire contents. However the \data_format property reserved for future definition will enable specification of an encoding scheme for styled text, such as a subset of Microsoft's RTF.

Card

Card_graphic

Card_button

1. See the description of \background_button properties for notes that apply also to the \card_button object.

Card_field

1. See the description of \background_field properties for notes that apply also to the \card_field object.

Background_field_data

POSSIBLE FUTURE ENHANCEMENTS

• SuperCard, from Silicon Beach Software
• Plus, from Spinnaker Software
• HyperPad, from Brightbill-Roberts, Inc.
• HyperCard 2.0 and future versions, from Apple Computer, Inc.