edc2html

edc2html is a Perl program that generates an HTML document (composed of several files) to allow hypertext navigation through a FrameBuilder Element Catalog specified in a Frame Maker Interchange Format (MIF) file.

It may help the reader to have a basic knowledge of FrameBuilder, the Element Catalog, and how to export a file to MIF. Knowledge of MIF markup is an added bonus, but not necessary.

Note:: Later versions of edc2html may come out without a public announcement (especially for bux fix releases). For the latest release and information on edc2html, look at my home page at the University of California: Irvine.

Description

edc2html generates various HTML files for hypertext navigation of a FrameBuilder Element Catalog. The files generated are as follows:

EDC-HOME.html: This file is the home page of the HTML document. This file contains to the basic links to start navigating through the Element Catalog. The name of this file can be changed with the -homename option.

TOP-ELEM.html: This file lists the top-most elements of the Element Catalog, and contains the links to element pages describing each top-most element. The name of this file can be changed with the -topname option.

ALL-ELEM.html: This file contains a list of all elements defined in the Element Catalog. This page allows quick access to any individual element description page. The name of this file can be changed with the -allname option.

element.html: For each element defined in the Element Catalog, an element description file is generated with a filename of the element name suffixed by ".html".

element.rule.html: For each element defined in the Element Catalog, a file is generated listing the content model decleration of the element as declared in the Element Catalog.

Once all the files are generated, one needs only to create a link in the Web server being used to the EDC-HOME page.

Note: If you have a Web client that can load local files, than linking the EDC-HOME page to the Web server is unnecessary.

More information on the content of each file is in the HTML File Descriptions section.

Usage

edc2html is invoked from a Unix shell, with the following syntax:

% edc2html [options] filename

filename is the FrameBuilder Element Catalog, represented in Frame MIF, to be parsed for generating the HTML files. The following is the list of options available:

-allname filename: Set the filename for file listing all elements in the Element Catalog to filename. The default name is "ALL-ELEM.html".

-careful: Tells edc2html to be wary of end-of-line comments and imported data. Normally, edc2html assumes that the MIF file has no MIF markup characters (`<`, `>') in end-of-line comments and contains no imported data. This assumption increases the processing speed of the MIF considerably. However, if the MIF file you give to edc2html contains questionable characters in comments and/or imported data, then specify this option.
The MIF generated directly by FrameBuilder does not have markup characters in end-of-line comments, so the -careful option is only needed if import data is included in the MIF.

-descfile filename: Use filename as the source for element descriptions in the Element Catalog. If this argument is not specified, no description file is used. See Element Description File for more information.

-docurl URL: Use URL for location of documentation on edc2html. The default URL is "edc2html.doc.html".

-edcname string: Set the name of the Element Catalog to string. If not specified, edc2html determines the name of the Element Catalog by its filename with the extension stripped off. If reading from standard input, then this argument should be specified. Otherwise, "Unknown" is used.
The string " Element Catalog" will be appended to the name of the Element Catalog.

-elemlist: Generate a blank element description file (see Element Description File) to STDOUT. No HTML files are generated and all other options are ignored when this option is specified.

-help: Print out a terse description of all options available. No HTML files are generated and all other options are ignored when this option is specified.

-homename filename: Set the filename for the HTML home page for the Element Catalog to filename. The default name is "EDC-HOME.html".

-outdir path: Set destination of generated HTML files to path. Defaults to the current working directory.

-topname filename: Set the filename for file listing the top-most elements in the Element Catalog to filename. The default name is "TOP-ELEM.html".

-verbose: Print status messages to STDERR of what edc2html is doing.

HTML File Descriptions

All HTML files/pages generated contain hypertext links at the end of the page to the EDC-HOME, TOP-ELEM, and ALL-ELEM pages, unless stated otherwise.

EDC-HOME

This page is the root of the HTML document. It contains the links to the other main pages as described above.

One can add documentation to the home page via the Element Description File or by manually editting the file.

TOP-ELEM

This page contains the list of all top-most elements defined in the Element Catalog. A top-most element is defined as: An element which cannot be contained by another element or can be only contained by itself.

ALL-ELEM

This page contains a list of all elements defined in the Element Catalog.

element

element.html is the file describing the content of element. The element page is divided into the following sections:

element description (optional, see Element Description File).
Links to subelements broken into three parts:
- Base content
- Inclusions (if defined)
- Exclusions (if defined)
Element type. The following element types are possible:
- Anchored Frame
- Container
- Cross-reference
- Empty
- Empty Paragraph
- Imported Graphic Object
- Marker
- Math Equation
- Table
- Variable
Link to general rule (element.rule) page.
Statement if element may be highest in a flow.
Links to all possible parent elements.
Links to main pages as described above.

Special Note: Frame element names are case-sensitive and may contain spaces. Therefore, the filenames appear in the same lettercase as the element name, and spaces are converted into commas. Example: An element called "Foo Bar" will have its element page filename called "Foo,Bar.html". The same convention applies to the element.rule page.

`element`.rule

element.rule.html is the file giving the element's general rule as it appears in the Element Catalog. The element.rule page is divided into the following sections:

General rule.
Inclusion elements (if defined).
Exclusion elements (if defined).
Link back to element page.

This page is not created if element's type implies an empty general rule.

See Special Note in the element page description on the actual filename of the element.rule page.

Element Description File

edc2html supports the ability to add documentation to the HTML files generated from an Element Catalog through the -descfile option.

The basic syntax of the description file is as follows:

         <?EDC2HTML identifier>

         Description of identifier here.

         <P>

         <?EDC2HTML identifier>

         Description of identifier here.

         <P>

         ...

The line <?EDC2HTML identifier> signifies the beginning of the description text. All text up to the next <?EDC2HTML identifier> line or end-of-file is used as the identifier description.

The identifier can be one of the following formats:

element: An element name in the Element Catalog. The following description text will go at the top of the element's page.

identifier,identifier,...: A sequence of identifiers separated by commas, `,'. This allows a description to be shared among muliple identifiers. NOTE: there should be NO whitespace between the identifiers and the commas.

If the special element, -HOME-, is specified in the description file, then its description text will be put on the EDC-HOME page.

SGML comments are also supported in the description file. Comments are skipped by edc2html. The syntax for a comment is the following:

         <!-- This is a comment -->

Warning: edc2html can only handle a comment that spans a single line (to make the parsing simple). Therefore, the following will cause edc2html to add the comment text beyond the first line of the comment to an element description:

         <!-- This is a comment

              that spans more than one line.

           -->

If you want to put line breaks in the description file without them being applied to an element description, then use the SGML short comment: <!>.

The description text can be any valid HTML markup. It is recommended to end each description with the <P> tag so the description is separated from any other HTML markup generated by edc2html.

Example:

Miscellaneous Notes:

If duplicate descriptions exist, the latest one defined is used.
edc2html ignores element descriptions that contain only the <P> tag.
To get started with a description file for an Element Catalog, one can use the -elemlist option to edc2html to generate a file with all elements Element Catalog with empty descriptions (i.e they only contain the <P> tag).
Element descriptions are not possible for element names with beginning and/or trailing whitespaces.

Tips

edc2html only cares about the Element Catalog, "<ElementCatalog...>", statement in the MIF file. Therefore, it is best to give edc2html a MIF file that defines an empty document so unnecessary processing is avoided. Actually, all you need is a file with only the Element Catalog statement.
Do not give the EDD to edc2html. You will only get the information of the elements defined for EDD editting/generation. Of course, if you interested in the Element Catalog used in EDDs ...