/* $XConsortium: README /main/4 1996/07/15 14:38:42 drk $ */
This memo documents the Widget MetaLanguage (WML) facility which generates
the Uil compiler language description.

1. Introduction

The Uil compiler's language definition has the following components:
	- Invariant parts of the language grammar. This consists of the
	  basic syntax and keywords, for example, the 'arguments' directive.
	- Dynamic parts of the language. This consists of the widget/gadget
	  classes supported by the language, including all resources
	  (arguments and reasons), and the definitions of legal relationships
	  among these parts (which classes are legal controls (children)
	  of any given class, default values, and so on).
	- The data types supported by the compiler. The code which supports
	  the data types is invariant, but the data types must also be
	  declared and made known in WML in order to provide a clean
	  specification.

The dynamic parts of the language definition in the compiler are represented
as follows. The representation falls into two classes:
	- Definitions of the language used for validity checking and
	  reporting:
		o A set of #define literals name all data types, classes,
		  arguments, and reasons in the language.
		o A set of statically compiled tables defines the names and
		  legal relationships among these entities.
	- All data types, classes, arguments, and reasons are treated as
	  keywords in the Uil grammar. This is supported by:
		o A set of #define literals which names all the tokens in
		  the language. Some of these tokens receive identical
		  values to the literals mentioned above (this identity is
		  crucial to the compiler's correct functioning).
		o A set of statically compiled tables used by lexical
		  analysis to detect and classify the language keywords.
		o A yacc grammar including these token definitions which
		  generates a compilable Uil language parser.

These representations are all contained in .h files except for the parser,
which is contained in a .y file and its resulting .c file.

The WML system's task is to generate all these literals and tables based on
a specification of the dynamic parts of the Uil language - the data types,
widget/gadget classes, arguments, and reasons. The components of the system
are:
	- A specification of the of set of widgets to be supported. This
	  specification is an ASCII file containing a WML language
	  specification as described below. The WML language is a simple
	  declarative language whose syntax is similar to Uil itself.
	- A process named wml, which parses the WML specification and
	  produces the following output:
		o The .h files which define the first class of language
		  representations - the validity checking and reporting
		  information.
		o A set of .dat files which are used by succeeding processes
		  to produce the Uil grammar.
		o A report file which describes the toolkit being supported.
		o A .mm file to be incorporated in the Uil language
		  documentation, which tabulates the built-in language
		  tables for Uil user reference.
	- A process named wmluily which generates the Uil grammar.
	- A process named wmltokens which generates token data
	- A process named wmlkeyword which generates the token and lexical
	  analysis tables.

A shell script is provided which runs the system. The individual processes
and inputs can usually be ignored.


2. Environment

The generation and use of the WML system requires the following:
	- The C language compiler and runtime system (cc).
	- The lexical generator facility (lex)
	- the compiler compiler facility (yacc)

The WML facility is found in directory /wmlsrc. It assumes the following
directories also exist:
	/uilsrc - the directory to which the output files are to be moved
	/mrmsrc/Mrm - contains MrmCmpr.h and other .h files required to
		compile the uil compiler.

The tables produced by WML must be consistent with the Mrm compression
code tables emboded in /mrmsrc/Mrm/MrmCmpr.h and /mrmsrc/Mrm/MrmCmprTbl.h.
If in doubt, refer to /mrmsrc/Mrm/urmc.README for details.


3. WML input

Input to WML consists of:
	- A description of the widget set (toolkit) to be suppported in
	  the WML specification language.
	- Data files supplied with WML facility, and which you will
	  usually not need to modify. These are:
		o grammar.y	- specifies the invariant part of the
				  Uil grammar
		o charset.dat	- specifies the character sets supported by
				  the compiler when handling compound strings
	  Any other .dat files found in /wmlsrc are the result of running
	  the facility, and may be ignored.

3.A. WML specification language

The WML specification is a simple declarative language whose syntax is
similar to that of Uil itself. It models the widget set to be suppored in
a way that is very similar to the Uil language. It differs in having class
inheritance similar to Xt widget classes, which minimizes the amount of
specification and reduces errors. The properties of the model are:
	- Class properties
		o Classes are differentiated into two types - metaclasses
		  and classes. Metaclasses cannot instantiate widgets.
		  Typically, a WML metaclass is generated for each metaclass
		  in the widget set to be supported.
		o A regular class is defined for every low-level create
		  routine in the widget set. There are typically more WML
		  classes that widget set classes. For instance, there
		  is one XmRowColumn class, with six WML classes (XmRowColumn
		  XmMenuBar, XmOptionMenu, XmPopupMenu, XmPulldownMenu,
		  XmRadioBox).
		o Gadgets are modelled as variants of a corresponding
		  widget class.
		o A class may have zero or one superclasses. A class
		  inherits all the resources and controls of its superclass
		  (recursively). An inherited resource may have some of
		  its properties overridden.
		o A class is given a name which becomes its Uil language
		  keyword (for regular classes). Metaclass names do
		  not appear in Uil.
		o A class is identified to Mrm by its creation
		  convenience function (low-level create function). Examples
		  are XmCreateLabel, XmCreatePushButtonGadget.
	- Resource properties
		o Resources are divided into two classes - arguments and
		  and reasons. This models the Uil language distinction
		  between callbacks and all other resources.
		o A resource is considered to have universal scope. Once
		  defined, it may be used in any class. Its name and datatype
		  are invariant, but its default value may be overridden.
		o A resource is included in a class by referencing it.
		  Resources are inherited. Inherited resources may be
		  excluded, which meancs they are not available in the
		  class which provides this override (and its subclasses).
		  This corresponds to the Motif toolkit N/A access value.
		o A resource is given a name which becomes its Uil language
		  keyword.
		o A resource is identified to Mrm by the toolkit literal
		  used to name it in arglists. Examples are
		  XmNheight, XmNancestorSensitive, XmNhelpCallback. The
		  resource literal defaults to the resource name, and need
		  not be explicitly specified where they are identical.
	- Control properties
		o A control is a class which is permitted as the child
		  of some other class.
		o Naming the controls of a class is a WML feature which
		  supports validity checking. There is no coresponding
		  explicit feature in any Xt widget set.

3.A.1 WML syntax and semantics

The WML syntax can be quickly inferred from the standard input file
provided with WML - motif-tables.wml. A quick BNF is provided in section 7.


WML semantics are:
	- '!' introduces a comment. Comments run from '!' to EOL.
	- A string value may be quoted by enclosing in double quotes '"'.
	  Names as well as values may be quoted. Keywords may not.
	- All names are case-sensitive. Forward and backward references
	  are allowed. All references to be resolved are to items defined
	  in WML. These are:
		o Type = <an item defined in a DataType statement>
		o SuperClass =
		  WidgetClass = <an item defined in a Class statement>
		o Resources { <items defined in Resource statement> };
		o Controls { <items defined in Class or ControlList>
				statements> };
	- A convenience function name is required for all classes except
	  Metaclasses.
	- Datatypes are required for all Arguments, Constraints, and
	  SubResources.
	- Arguments and SubResources are functionally identical, and
	  are distinguished only because they are different kinds of
	  resources in Xt widget sets. Constraints apply only to the
	  referencing class's children. The same name may not be
	  used for both an Argument and a Constraint (once a Constraint,
	  always a Constraint).
	- If a resource occurs in the widget set with more than one
	  datatype, the Uil datatype 'any' must be used.
	- The ResourceLiteral attribute for resources is optional, and
	  need only be specified when the name is not identical to the literal.
	- The DocName and Default attributes are only used for documentation.
	  They are arbitrary strings.
	- The WidgetClass attribute identifies the Widget class
	  associated with a Gadget class, and is required.
	- The DialogClass attribute is optional.
	- The ControlList statement is a simply macro for lists of
	  controls. It avoids tedious repetition of identical lists.
	  A Controls block in a Class statement allows Class and
	  ControlList names to be freely mixed.


4. WML output
	- The .h files and parser required by the compiler. These
	  are automatically moved to /uilsrc by the runwml script.
	- A report describing the supported widget set, always named
	  wml.report. This report is intended to aid in validating
	  the WML source. The report is organized in a way which makes
	  if fairly easy to compare the Uil langauge against widget
	  set documentation as exemplified by the Motif Programmer's
	  Reference Manual. The reported is sorted as follows:
		- alphabetically by class name
		- Resources ordered by ancestor (top of tree first).
		  Resources are listed alphabetically, with datatype
		  and default always shown.
		- Reasons ordered by ancestor (top of tree first),
		  then alphabetically.
		- Controls listed alphabetically.
	- A file which provides documentation for the language, intended
	  to be an appendix to a Uil manual as exemplified by the
	  Guide to the Motif User Interface Language Compiler. This file
	  is named wml-uil.mm


5. Generating and running WML

The script file /wmlsrc/genwml will build WML. The script file /wmlsrc/runwml
will run WML with motif-tables.src as input.


6. Gotchas and problems in current WML implementation

The script files genwml and runwml should be replaced by Makefiles.

The documentation file ?.mm is relatively untested. The tables should
probably be modified, as they are currently too big to print cleanly.
The handling of the DocName attribute is incorrect.

The specification of the Motif toolkit in motif-tables.wml has not been
fully validated against the latest toolkit documentation. We believe there
are no or very few errors in the actual resources and the classes which
use them. There may be errors in the default values, which will appear
in the documentation.


7. WML BNF

WML-specification : statement_block_list

statement_block_list:
	<empty>
	statement_block_list statement_block

statement_block:
	class_statement_block
	| resource_statement_block
	| datatype_statement_block
	| control_list_statement_block

class_statement_block:
	'Class' class_statement_list

resource_statement_block:
	'Resource' resource_statement_list

datatype_statement_block:
	'Datatype' datatype_statement_list

control_list_statement_block:
	'ControlList' control_list_statement_list

class_statement_list:
	class_statement ';'
	| class_statement_list class_statement ';'

resource_statement_list:
	resource_statement ';'
	| resource_statement_list resource_statement ';'

datatype_statement_list:
	datatype_statement ';'
	| datatype_statement_list datatype_statement ';'

control_list_statement_list:
	control_list_statement ';'
	| control_list_statement_list control_list_statement ';'

class_statement:
	<name> ':' class_type class_definition

class_type:
	'MetaClass' | 'Widget' | 'Gadget'

class_definition:
	<empty>
	| '{' '}'
	| '{' class_attribute_list '}'

class_attribute_list:
	class_attribute_name '=' <string> ';'
	| class_boolean_attribute_name '=' boolean_attribute_value ';'
	| class_resources ';'
	| class_controls ';'

class_attribute_name:
	'SuperClass' | 'Alias' | 'ConvenienceFunction' | 'WidgetClass' |
	'DocName'

class_boolean_attribute_name:
	'DialogClass'

boolean_attribute_value:
	'True' | 'False'

class_resources:
	'Resources' class_resources_block

class_resources_block:
	<empty>
	'{' '}'
	'{' class_resource_list '}'

class_resource_list:
	class_resource_element
	| class_resource_list class_resource_element

class_resource_element:
	<name> class_resource_attributes ';'

class_resource_attributes:
	<empty>
	'{' '}' ';'
	'{' class_resource_attribute_list '}'

class_resource_attribute_list:
	class_resource_attribute_element
	| class_resource_attribute_list class_resource_attribute_element

class_attribute_element
	class_resource_attribute_name '=' <string> ';'
	| boolean_class_resource_attribute_name '=' boolean_attribute_value ';'

class_resource_attribute_name:
	'Default'

boolean_class_resource_attribute_name:
	'Exclude'

class_controls:
	'Controls' class_controls_block

class_controls_block:
	<empty>
	| '{' '}' ';'
	| '{' class_controls_list '}'

class_controls_list:
	class_controls_element
	class_controls_list class_controls_element

class_controls_element:
	<name> ;

resource_statement:
	<name> ':' resource_type resource_definition

resource_type:
	'Argument' | 'Reason' | 'Constraint' | 'SubResource'

resource_definition:
	<empty>
	'{' '}'
	'{' resource_attribute_list '}'

resource_attribute_list:
	resource_attribute
	resource_attribute_list resource_attribute

resource_attribute:
	resource_attribute_name '=' <string> ';'

resource_attribute_name:
	'Type' | 'ResourceLiteral' | 'Alias' | 'Related' | 'Default' |
	'DocName'

datatype_statement:
	<name> datatype_definition

datatype_definition:
	<empty>
	| '{' '}'
	| '{' datatype_attribute_list '}'

datatype_attribute_list:
	datatype_attribuute
	datatype_attribute_list datatype_attribute

datatype_attribute:
	datatype-attribute_name '=' <string> ';'

datatype_attribute_name:
	'Alias' | 'DocName'

control_list_statement:
	<name> control_list_definition

control_list_definition:
	<empty>
	'{' '}'
	'{' control_list_controls_list '}'

control_list_controls_list:
	control_list_control
	control_list_controls_list control_list_control

control_list_control:
	<name> ';'