edc2html

#

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 ...

## 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.