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:

       
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:

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:

       

Tips


See Also

mif.pl
A Perl library to parse Frame MIF.
dtd2html
A Perl program to generate an HTML document to allow people to navigate through the structure of an SGML DTD.

Earl Hood, ehood@convex.com
edc2html 1.0.0