# NAME

mdc − Mapping Definition File (MDF) compiler

# SYNOPSIS

mdc [−help] [−c] [−m] [−n] [−q] filename

# DESCRIPTION

mdc takes the specified mapping definition file (MDF) and generates a manual page, include file, or quick reference card depending on the options selected. The manual page contains tbl and troff commands for use with the man macro package. The include file contains calls to map_DefineMapping and/or map_DefineMappingList. The quick reference card contains troff commands for use with the me macro package. Any combination of these can be produced with a single invocation of mdc .

MDFs provide a method for defining and documenting mappings in a single file. Using MDFs is optional, see the map_intro manual page for additional information on mappings and the map subsystem.

mdc is written in perl and requires that the perl interpreter be available. On UNIX systems, perl is assumed to be located in /usr/local/bin/perl. If this is not correct, the mdc script may be invoked with "perl -s mdc ..." or the first line in mdc can be changed to reference the correct path for perl. On DOS and Windows NT systems, mdc must be invoked as "perl -s mdc ...". Contact PDElib customer support if you need assistance in locating and installing perl.

# OPTIONS

−help

Displays a summary of the available options.

−c

Specifies that an include file containing calls to map_DefineMapping and map_DefineMappingList should be generated. The include file will have the name xxx_mdf.h where xxx is the root portion of the file being compiled. For example, a file named cad.mdf will generate an include file named cad_mdf.h .

−m

Output the tbl and troff commands to generate a manual page for the mappings. The output is written to stdout and must be piped to the tbl command (see the examples section).

−n

Suppresses the .TH entry when the −m option is used.

−q

Output the troff commands to generate a quick reference card of the mappings. The quick reference card will contain the mapping names listed by input DTF and output DTF in a two column format. The output is written to stdout and must be piped to the troff command (see the examples section).

# MDF FORMAT

The MDF uses a simple block oriented structured so that items are delimited by @begin_xxxx/@end_xxxx keyword pairs. Keywords start with '@' and can be in any column. Only one keyword may appear per line. Comments start with '#' and must start in the first column. The introduction section must be first in the file. The parameter and mapping entries can be mixed in any order. The MDF files for GDX and the PDElib interface are included in the mdf subdirectory of PDElib.

Introduction Section

The first item in an MDF is an introduction consisting of troff commands. This introduction is only used when the −m option is used and is written unchanged to stdout. The introduction is enclosed in @begin_intro/@end_intro keywords as shown below:

@begin_intro

This is the introduction portion of an MDF. It can be arbitrarily long and may contain tbl or troff commands.

@end_intro

Mapping Entries

A mapping entry is enclosed in @begin_mapping/@end_mapping keywords and defines a mapping or mapping list. The entry consists of keywords followed by a value. Unless noted otherwise, the keyword and value must appear on the same line. Fields may be specified in any order. Each entry contains the following fields:

@name:

Specifies the mapping name. This name will be used when referencing the mapping using the map subsystem. The name may contain spaces.

@description:

Specifies a multi-line description of the mapping. The description may contain tbl/troff formatting codes. The description should completely describe the behaviour of the mapping including how mapping parameters, if any, are used in the mapping.

@input_dtf:

Specifies the input DTF for the mapping. The format can be either "ddf_name:entity_name" where name is the entity name or "ddf_name:type:*" where type is the numeric type of the entity. When the −c option is used, this value will be passed to map_DefineMapping as the input_ddf and input_tf arguments. The ddf_name portion will be prepended to "_ddf" to form the variable name passed for the input_ddf argument. For example, given an @input_dtf: entry of "cad:conic", the parameters "cad_ddf" and "conic" would be passed to map_DefineMapping. Given an @input_dtf: entry of "cad:10:*", the parameters "cad_ddf and ddf_MakeTF(10, DDF_ANY_FORM)" would be passed to map_DefineMapping.

@output_dtf:

Specifies the output DTF of the mapping. All possible output DTFs must be listed. The list can span multiple lines and each entry must be delimited with a comma. The format of each entry is the same as that described for the @input_dtf: field.

@function:

Specifies the function which performs the mapping operation.

@parameters:

Specifies the mapping parameters which this mapping uses. The list can span multiple lines and is optional.

@options:

Specifies an optional list of additional options for the mapping. Available options are:

•

general

•

transient

•

1:1

The general and transient options are equivalent to the MAP_GENERAL and MAP_TRANSIENT options described in the map_DefineMapping manual page. The 1:1 option indicates that the mapping generates a single output entity for each input entity. The options must be listed on the same line as the @options: keyword and the options must be seperated with commas. An example mapping entry is shown below:

@begin_mapping

    @name: cad_conic -> gdx_arc or gdx_conic
    @description: Converts a CAD conic into a GDX_ARC or GDX_CONIC
                  depending on the form of the CAD conic.  If the CAD
                  conic defines an arc or circle, a GDX_ARC will be
                  generated, otherwise an appropriate GDX_CONIC entity
                  will be generated.
    @input_dtf: CAD:CONIC
    @output_dtf: GDX:GDX_ARC, GDX:GDX_CONIC
    @options: GENERAL, TRANSIENT, 1:1
    @function: amap__CadConicToGDX

@end_mapping

Mapping List Entries

Like regular mappings, mapping lists are enclosed in @begin_mapping/@end_mapping keywords. When defining a mapping list, only three fields are required: @name:, @description:, and @mappings:. The @name: and @description: fields are the same as described under regular mappings. The @mappings: field specifies the list of mapping names which make up the mapping list. The list can span lines and must be delimited with commas. The order in which the mappings are specified determines the order of the mapping list. In most cases mdc can determine the input DTF and output DTF for a mapping list by examining the input and output DTFs for the mappings in the list. If the list references a mapping not defined in the current MDF as the first or last mapping in the list, the input and/or output DTFs must be explicitly specified using the @input_dtf:/@output_dtf: fields.

An example mapping list entry is shown below:

@begin_mapping

    @name: cad_parm_spline -> cad_nurb_curve
    @description: Converts a CAD parametric spline into a CAD NURBS curve.
    @mappings: cad_spline -> gdx_spline_curve,
               gdx_spline_curve -> gdx_nurb_curve,
               gdx_nurb_curve -> cad_nurb_curve

@end_mapping

Parameter Tables

Parameter tables are used to describe the parameters used by mappings. Parameters can be grouped together so that a mapping may reference the group of parameter rather than each individual parameter. A parameter table is enclosed in @begin_param_table/@end_param_table keywords. Within these keywords is an @name: keyword which names the parameter table. Following that is a list of parameter descriptions. Each parameter block is enclosed within @begin_param/@end_param keywords and contains the following fields:

@name:

The name of the parameter.

@type:

The data type of the parameter. Must be one of "boolean", "integer", "float", or "string".

@default:

The default value for the parameter if one is not explicitly specified for it.

@description:

A multi-line description of the parameter. The description may contain tbl/troff formatting codes.

An example parameter table is shown below:

    @begin_param_table

    @name: CAD Parameters
    @begin_param

    @name:    CAD_TOLER
    @type:    float
    @default: .001
    @description:  Specifies the tolerance to be used when performing
                   floating point comparisons.

    @end_param
    @begin_param
       .
       .
       .
    @end_param

    @end_param_table

# EXAMPLES

To generate an include file with calls to map_DefineMapping and map_DefineMappingList:

       mdc -c cad.mdf

To generate a manual page listing the available mappings:

       mdc -m cad.mdf | tbl | nroff -man | col -b | more

To generate a quick reference summary on a PostScript printer:

       mdc -q cad.mdf | troff -me -t | lpr

# SEE ALSO

map_intro(3), map_DefineMapping(3), map_DefineMappingList(3), troff(1), tbl(1)

# DIAGNOSTICS

Assorted diagnostic messages will be issue when errors are encountered in the input file. Most diagnostics display the source line in error and halt the compilation.