6.1 Description
The EXPRESS-G Layout tool will take syntactically correct EXPRESS text files and convert them to EXPRESS-G diagrams. The diagrams can then be viewed with expgedit or printed using either expg2ps or expg2hpgl .
6.2 Command Line (All Platforms)
express2expg [options] expfile1 [expfile2 ...]
The options recognized by the diagram layout tool are shown below:
-help- Print this list of options. The tool performs no other action and ignores all other options.
-cuttopage- Force the layout engine to break definitions into pieces small enough to fit on a single page (where possible). This is useful for printed diagrams, but for interactive viewing it is more useful to preserve the full inheritance tree structure without the extra page breaks this creates.
-diagonals- Allow the layout engine to use diagonal lines. By default, the engine uses a Manhattan layout (all lines at right angles).
-direct- Direct inter-schema links. Normally, express2expg will attempt to keep schema's independent by inserting inter-schema references. This option will force the tool to link objects directly where possible. Because the diagrams may be spread out, this tends to just replace the inter-schema references with page breaks. Use the -nobreak or -farbreak options to disable page breaks.
-farbreak- Don't insert a page break if objects are "close." When arranging a diagram, the tool inserts page breaks to avoid long crossing lines. This option forces direct connections instead of page breaks, for objects that are near one another. This is useful for smaller schemas, where it is possible to work with most of the schema at once. Note, however, that a large number of lines can slow down display with the expgedit editor.
-fontname <name>- Set the font for printing. The default is Helvetica-Bold. In order for express2expg to properly layout the boxes for printing it needs to have a description of the font. On UNIX systems we use font metrics files that are freely available from Adobe. See UNIX Technical Notes for more information about obtaining, and adding font metrics files to your installation.
-fontsize <point-size>- Set font size for printing. The default is 7 pt. text. This can be too small for some purposes, but is quite readable, and reproducible on a 300dpi printer. Due to limitations in X11, the full scale view of your document will always use a 10 pt. font. Page breaks and boxes will be scaled according to this value.
-fulltree- Keep inheritance trees full. The express2expg tool normally breaks up wide inheritance trees by inserting page breaks. You may want to use this option when preparing EXPRESS-G diagrams for printing with either expg2ps or expg2hpgl .
-i / -index- Print an index listing for every definition in the diagram. The name of each definition is printed, along with the number of the page it is defined on. The expginfo tool can also produce such a listing. See EXPRESS-G Diagram Information for an example.
-l / -landscape- Swap the x and y dimensions of the page. For example, if you had 8.5x14 (legal-sized printer) paper, and wanted landscape mode you would use: express2expg -pagewidth 7.5 -pageheight 13 -l
-nobreak- Do not insert page breaks in the diagram. This is only useful on rather small schemas.
-pagesize <std-size>- Select one of the named standard paper sizes A , B , D , or E .
-pageheight <height-in-inches>- Set the size in inches of the height of the page. The default is 10.0". See -pagewidth above for some warnings as to its use.
-pagewidth <width-in-inches>- Set the size in inches of the width of the page. The default is 7.5". If you have a printer that takes larger paper you may wish to change this. Note that you often need to leave a margin around the page where the printer is incapable of printing.
-ref <num>- Change the starting number of the page references. Page references will start at <num> and increase by 1. Note that page references are not the same as page numbers. Each page reference has a unique number within the EXPRESS-G diagram. This offers a way to have unique page references through multiple EXPRESS-G diagrams.
-v- Verbose mode will give more information about the conversion process, such as messages from the EXPRESS compiler. It is also useful for tracking the progress through large schemas.
-workingset <namefile>- Generate EXPRESS-G for the subset of entities in a working set. Reads a list of names from <namefile> and creates diagrams for just those entities and supporting types. Useful when working with a few types or entities from a large APs. See Customizing Output with a Working Set File for a description of working sets.
6.3 Control Panel (Windows Only)
The EXPRESS-G layout control panel is shown in Figure 6.1. Click EXPRESS-G Layout in the ST-Developer Control Panel window. To generate EXPRESS-G, specify an EXPRESS source file, and click the OK button. Any messages from the layout engine will be shown in the output box in the control panel. You can show or hide the output box using the Output button in the ST-Developer control panel.
To convert multiple files at once, enclose each file name in double quotes, and separate the file names with spaces. If you use the browse button and the Open File dialog this is done automatically.
The conversion process may take several minutes, but only needs to be done once per EXPRESS file. The conversion produces a .exg file which may be viewed with the EXPRESS-G Editor.
Control Panel Options
The EXPRESS-G layout File tab is shown in Figure 6.1. It has the following elements.
EXPRESS file(s)
Provides a space to type the name of the file(s) to convert. The [...] button displays the Open File dialog box that can be used to browse the file system and locate the files.
Use working set
Generates output using a working set file. Provides a space to type the working set file name. You can also use the [...] button to locate the file on the disk. For more information on working sets see the EXPRESS compiler documentation. Equivalent to the -workingset command-line option. See Customizing Output with a Working Set File for a description of working sets.
Output diagram file
Provides a space for you to type the name of the resulting EXPRESS-G diagram file. You can also use the [...] button to locate the file on the disk. If do not specify the name of the output file, the resulting diagram file will be named after the first EXPRESS file, but witht the `.exg' extension.
Verbose output
Select to make the tool display more information about the conversion process, such as messages from EXPRESS compiler. Equivalent to the -v command-line option.
Generate page index
Displays an index which lists the location of all definitions. Equivalent to the -index command-line option.
Additional diagram layout options are available under the Options tab shown in Figure 6.2. It has the following fields and controls.
No boxes at page boundary
Breaks up definitions until they are small enough to fit on a single page (where possible). Equivalent to the -cuttopage command-line option.
Use direct links for inter-schema references
Normally, the layout engine will attempt to keep schemas independent by inserting inter-schema references. This option will force the tool to link objects directly where possible. Equivalent to the -direct command-line option.
No page references between "close" entities
Forces direct connections instead of page references, for objects that are near one another. Equivalent to the -farbreak command-line option.
Do not break up large inheritance trees
Keeps inheritance trees full. Use this option to create wall-sized EXPRESS-G diagrams for printing. Equivalent to the -fulltree command-line option.
Use diagonal lines
This prevents EXPRESS-G Layout from using a Manhattan style layout. Equivalent to the -diagonal command-line option.
Landscape layout
Sets the landscape orientation of pages. Note that this will swap the values in the Page Width and Page Height boxes. Equivalent to the -landscape command-line option.
Font
Contains a sample of the font that will be used in the diagram. Click the [...] button to display the Font dialog box which will allow you to select a font and its attributes (bold, italic, color, etc.).
No page references
Does not generate any page references. This is only useful on rather small schemas. Equivalent to the -nobreak command-line option
Start page reference at
Page references start at this number and increase by 1. Each page reference has a unique number within an EXPRESS-G diagram. This offers a way to have unique page references through multiple EXPRESS-G diagrams. Equivalent to the -ref command-line option.
Page size
Provides a list of standard page sizes and two text boxes to specify a custom size.
Page width
Page width in inches (avaliable when Custom is selected in the list).
Page height
Page height in inches (avaliable when Custom is selected in the list).
Use Defaults
Resets all of the options to their default values. The default value for each option is shown below:
Use working set No
Verbose output No
Generate page index No
No boxes at page boundary No
Use direct links for interschema references No
No page breaks between "close" entities No
Do not break up large inheritance trees No
Use diagonal lines No
Landscape layout No
Font Arial Regular 8pt. Black
No page breaks No
Start page ref at No
Page size "A"
Page width 7.5"
Page height 10.0"
Option settings are saved in the system registry when you click the OK button, and will be reloaded from the registry next time you open the control panel. Settings are not saved if you click the Cancel button.
6.4 Layout Tool Operation
To convert an EXPRESS file, use the command:
% express2expg <file_name>
or click on the EXPRESS-G Layout button in the ST-Developer Control Panel. The converter uses the EXPRESS compiler to generate an intermediate form, which is processed to create EXPRESS-G diagrams. If the EXPRESS compiler is not able to compile the EXPRESS file, the converter will not generate diagrams. The name of the file that the EXPRESS-G diagram is written to is the same as the original except the .exp is replaced with .exg .
6.5 Layout Style
The layout engine considers the inheritance hierarchy first, and will arrange definitions so that references to an entity come in from the top and references to sub-types are placed at the bottom of an entity. Attributes will be placed at the sides of each entity.
On the virtual page, the largest inheritance trees are placed first. The converter proceeds from left to right, top to bottom across the virtual page. The largest tree is in the upper left hand corner and the smallest is at the bottom, as shown in Figure 6.3. The smallest objects tend to be defined types, selects, enumerations or unused entities.
The default layout style is useful for learning or comparing EXPRESS schemas. By default the tool will try to keep the inheritance trees whole. The tool inserts a page reference or an inter-schema reference when ever it is unable to put the actual entity in that location. The tool disregards page boundaries when placing entities.
You may wish to change the defaults when preparing diagrams for printed documentation. For instance, use the -cuttopage option to break the diagram into page-sized pieces.
6.6 UNIX Technical Notes
The UNIX EXPRESS-G tools use Adobe font metrics files to calculate basic information about the font sizes. Without a proper font metrics file express2expg will tend to generate a poor layout. Adobe provides font metrics files via anonymous FTP ( ftp://ftp.adobe.com/pub/adobe/type/ ). We have included files for Helvetica, Times, and Courier in normal, italic, bold and bold&italic styles. The files are installed in $ROSE/system_db/afm .
The EXPRESS-G tools will check for the desired font metrics file in the following places:
$ROSE_AFM (a list of colon separated directories to check)
$HOME
$HOME/afm
$ROSE/system_db/afm