3.1 Description
The express2html converter creates a web-browsable version of an EXPRESS information model. The tool preserves the layout, indentation and comments in the EXPRESS while adding hypertext links and cross reference information. This is not just a pretty-printer, but rather generates a report for each entity in the information model giving a more complete picture of the inheritance and attributes than is available explicitly in the EXPRESS.
In normal operation, the express2html tool reads the EXPRESS source files specified on the command line, and generates one HTML page for each EXPRESS definition in a schema (entity, type, function, procedure, etc.) as well as a frame page that ties everything together. Each definition has a table of links to other definitions that use it, and ENTITY types also have tables listing all attributes, (both inherited and local) supertypes and subtypes.
3.2 Command Line
express2html [options] expfile1 [expfile2 ...]
-help- Display usage information
-version- Display the version number of the tool.
-title <text>- Set the title of the generated HTML to the specified string.
-exit <url>- Set the target URL for the exit link. An exit link is only created if this option is specified.
-exittext <text>- Specify the text to be the exit link. The default is [Exit] . This option is ignored if the -exit option is not specified.
-terse- Eliminate the sentences describing the sections from the HTML.
-hide- Eliminate empty section from the report. For example if an entity has no supertypes, and this option is selected. the Supertypes section will not appear in the output for that entity.
-nojs- Eliminate the JavaScript from the output. By default, JavaScript is emitted to enable the tables to be sorted by column.
-maxsubtypes <number>- Specify the maximum number of subtypes to include as a vertical list. If an entity has more subtypes than this number, they are listed horizontally to save space. The default value is 10.
-nocredit- Do not include ST-Developer credits on the summary page.
-onefile- Generate a single output file. In this case, the output consists of only the HTML marked-up EXPRESS, and does not include any summary information.
-frames- Generate multiple output files with summary information. (This is the default operation of the tool.)
-o <path>- Set the output location. If
-onefile
is in effect, this option specifies the HTML file where the output is written. If not specified, the output will be written to
express.html
- If -frames is in effect, this option specified a directory into which the output files are written. If not specified, the output will be written to the express_html directory.
-truncate- When creating frames, limit files names to 10 characters (excluding the .html file extension). This is helpful when generating HTML for publication on CD-ROM or other file systems.
-comment-before- Comments appear before the definition to which they apply. (This is the default)
-comment-after- Comments appear after the definition to which they apply.
-comment-global- Used to indicate that comments in the global scope do not apply to either the preceding or the following definition.
3.3 Output files
The processor generates an HTML page for each entity, defined type, or other definition. In addition, it generates a number of index pages and a frameset to simplify navigation. The left panel provides an alphabetized index of either entities, defined types, functions or procedures. The right frame contains the formatted definition. The bottom frame is used to select an index to be displayed in the left frame. The [all definitions] tag in the bottom frame selects the summary page.
In the output directory, the frameset is written into a file named index.html . You should point your web browser at this file when you want to view the hypertext version of the information model. If you desire a frameless output, you can begin navigating at the summary page: schema.html . In this case, you will not have the indices available to assist with navigation, but you will be able to access all the other information generated by the tool.
The summary page contains the HTML for the global information in the EXPRESS source. This includes the SCHEMA / END_SCHEMA declaration, CONSTANT s, USE and REFERENCE statements, and comments that appear in the global scope that the processor did not include on an HTML page for a definition. In place of those definitions the summary page includes a hypertext link to the page containing the definition.
The processor places all entities, defined types, global rules, subroutines and functions on their own HTML pages. In addition to the hyperlinked EXPRESS source, the pages for entity and defined types include a cross reference report at the bottom of the page. This report includes attribute summaries, subtypes and supertypes, and the types and entities that reference the entity.
The express2html tool generates tables for each entity to summarize the entity's attributes. For each entity, the tool generates summaries for explicit, derived, and inverse attributes. These tables give the attribute name, the attribute's type and the entity (possibly a supertype) that defined the attribute. The explicit attributes in the table are listed in the same order that they appear in a Part 21 exchange file.
The EXPRESS language allows explicit attribute to be redeclared as DERIVED. In this case, the attribute, even though it is a derived attribute, it is also included in the table of explicit attributes. It is indicated as such with a * and a footnote. In Part 21 files these attributes are encoded as "*".
The second column of the attribute table identifies the attribute's type. The type is specified as the EXPRESS type that it is actually declared as, and if that type is a named type, the underlying type (e.g. BOOLEAN, STRING, ENTITY, ARRAY, etc.), is also given in parenthesis. This feature makes it easy to determine the underlying type of defined types.
Both entity and defined type pages include a report identifying the other types that reference the current type. This section allows you to see where in the information model an entity or type is used, and effectively provides a back link for the hypertext links in the formatted EXPRESS.
3.4 Splitting Files
When generating multiple output files, each definition is placed into its own file. This means that the tool needs to determine where one definition ends and another begins. Such splitting can be performed anywhere between the end of the preceding definition and the beginning of the next one. The splitting strategy must handle comments that lexically occur between definitions, but actually document either the following, or the preceding definition in the information model. The tool provides the -comment-before , -comment-after , and -comment-global options to control how comments are split between definitions.
Given the following information model:
SCHEMA flying_monkeys;
(*
The census entity is used to hold a count of how many flying monkeys have passed a point, and the time at which the last one was observed.
*)
ENTITY census;
monkey_count : integer;
last : time;
END_ENTITY; --census
(*
The bite entity is used to keep track of when a flying monkey bites a
person, and, whether or not the person was infected with rabies by the
monkey. If known, the ID tag from the collar of the monkey is also
recorded.
*)
ENTITY bite;
victim : STRING;
infected : LOGICAL; (*Logical because the status may not be known*)
monkey : OPTIONAL id;
END_ENTITY; --bite
END_SCHEMA;
There are comments in the schema scope that come before the definition they document. In this case, use the -comment-before option to keep the comments with the associated definition. (This is the default operation of the tool.) The -comment-after option can be used in cases where the comments appear after the declaration.
When we use the -comment-before option, the output for the census entity includes the comment that appears before it, as well as the trailing comment on the same line as the END_ENTITY keyword. The output for the census entity thus includes the following:
(*
The census entity is used to hold a count of how many flying monkeys have passed a point, and the time at which the last one was observed.
*)
ENTITY census;
monkey_count : integer;
last : time;
END_ENTITY; --census
The EXPRESS is always split between lines, when possible. Thus trailing comments after the entity remain with the entity regardless of the splitting mode selected. In the above example, the trailing comment " --census " has been kept with the definition it belongs to.
In addition to the -comment-before and -comment-after , there is a -comment-global option, which places all global scope comments onto the schema summary page, and not with either the preceding or following definition.
As an example of how the comment splitting options work, we will consider the following simple EXPRESS schema, and show how it gets split in each case.
(*A schema for demonstrating how splitting is done*)
SCHEMA test;
(* Comment at beginning*)
ENTITY A;
(*Comment inside A*)
END_ENTITY; --A
(*Comment between A and B*)
ENTITY B;
(*Comment inside B *)
END_ENTITY; --B
(*Comment at end*)
END_SCHEMA;
(*After the schema*)
With the -comment-after option, the summary file contains the following:
(*A schema for demonstrating how splitting is done*)
SCHEMA test;
(* Comment at beginning*)
ENTITY A;
ENTITY B;
END_SCHEMA;
(*After the schema*)
The page for ENTITY A contains the following text:
ENTITY A;
(*Comment inside A*)
END_ENTITY; --A
(*Comment between A and B*)
The page for ENTITY B contains the following text:
ENTITY B;
(*Comment inside B*)
END_ENTITY; --B
(*Comment at end*)
For the -comment-global option, the summary file contains the comments.
(*A schema for demonstrating how splitting is done*)
SCHEMA test;
(* Comment at beginning*)
ENTITY A;
(*Comment between A and B*)
ENTITY B;
(*Comment at end*)
END_SCHEMA;
(*After the schema*)
In this case, the HTML for entity A, contains the following:
ENTITY A;
(*Comment inside A*)
END_ENTITY; --A
Note that the trailing comment " --A " is still kept with the entity because it appears on the same line as the END_ENTITY keyword.
3.5 Examples
Generate a set of HTML pages for the AP203 schema. The output is placed into a directory named express_html :
% express2html ap203.exp
Generate a single HTML file. This will contain a the EXPRESS schema with hyperlinks for each symbol usage, but will not have the summary tables for each definition. The output is placed into a file named express.html :
% express2html -onefile ap203.exp
Create a set of pages in the directory ap214 with the page titles set to AP 214 . We must quote the title to insure that the whitespace is correctly interpreted.
% express2html -o ap214 -title "AP 214" ap214.exp
Generate a set of pages for the STEP integrated resources. The output is written to a directory named IRs .
% express2html -o IRs p41.exp p42.exp p42.exp p43.exp p44.exp p45.exp p46.exp