DTD for Modular Vocabulary (mv) files

This software is part of the GLOSS system, http://gloss.bham.ac.uk. Author: Richard Kaye, May 2006, copyright reserved. Licence: This software may be used under the conditions of the latest version of the GPL. No warranty.

The GLOSS system takes a text file and transforms it to xml by means of a modular vocabulary (MV) written in xml and somewhat similar to XSL stylesheets. This document describes the main features of modular vocabularies and the DTD (available online at http://gloss.bham.ac.uk/dtd/mv/modularvocab.dtd) for such modular vocabularies. It is meant as a definitive (but not necessarily easy) guide to the way MV files are read and in particular the MV elements you may use in modular vocabularies. Other tools and documentation in the gloss system may help, but are not described here.

Throughout this document we use the prefixes "mv:" for elements in the modular vocabulary namespace, and "xr:" for elements in the xml representation namespace. These prefixes can be altered by setting parameter entities as explained in the appropriate section, but for simplicity they are describes as elements with their default prefixes as if fixed.

A Modular Vocabulary (mv) file consists of a root mv:modularvocab element containing modes defined by mv:mode elements. (There are other top-level elements allowed for initialization of parameters and definition of namespaces, these are also explained below.) When the gloss processor is in a particular mode, it parses its input into tokens and processes these tokens according to the instructions in the mode. The mode therefore contains a mixture of executable instructions (these are the mv:... elements) and other XML data which is placed on an output tree, in a manner similar to XSLT.

Gloss produces output which is an XML description in a simplified XML vocabulary of an output XML document. The relationship between the XML and the output document is defined by elements in the xml representation namespace, with default prefix (as used here) of xr:. See that section of the Gloss documentation for further details.

This documentation is generated from the DTD itself. Sections of DTD occuring here are from the DTD and are definitive, and all of the DTD is presented in this way. The rest is additional description and links for human readers.

We provide some support for top-level xi:include elements.

At any moment of execution, there is a set of active parameters containing additional data other than the current token being processed and the current mode of execution. These parameters have a name (normally consisting of a URI or prefix followed by a string of letters, underscores, hyphens and digits) and value which is a string of characters. Certain commands manipulate these parameters, as you would expect. Parameter values are used to modify textual data, such as attribute values etc.

Almost every attribute value and text in the mv input files is modified or evaluated using interpolation. This means that prefixes are resolved to their corresponding URI namespaces, parameter references in the text are replaced by the corresponding parameter values, and certain built-in parameters are repaced by their values from the current token or mode. The rules by which this happens are explained in a separate page on parameters.

Text nodes in the MV file are ignored except when executing commands. (The code for execution is in java class gloss.GlossExecution.) When executing text, the following is performed.

First leading and trailing whitespace is removed, and if the result is empty nothing more is done. (See also , mv:cr and mv:literal if you want to add whitespace or other literal text to the output.) The remaining text is interpolated using the standard rules.

If the current output mode is a CharacterData node (Comment, CDATA, Text) then the resulting text is added to that. Otherwise a new Text node is created and the text placed in that.

See also mv:text.

CDATA nodes in the MV file are ignored except when executing commands. (The code for execution is in java class gloss.GlossExecution.) CDATA is executed as text, except that the text is not interpolated, whitespace is not stripped, and an empty string is treated like any other.

As for text, if the current output mode is a CharacterData node (Comment, CDATA, Text) then the resulting text is added to that. Otherwise a new CDATA node is created and the text placed in that.

See also mv:cdata.

The mv source document may contain comments where-ever they are allowed by XML. There is no action or output associated with such comments. See also mv:comment.

Processing-instruction nodes in the MV file are ignored except when executing commands. (The code for execution is in java class gloss.GlossExecution.) When executing Processing-instruction nodes, they are copied verbatim to the output document in the current place without any interpolation. See also mv:processing-instruction.

The following lists and describes the parameter entities defined in this DTD, modularvocab.dtd, to do with defining or changing the XML namespace prefix (default mv:) and the namespace for such elements.

%mv.prefix; defines the prefix used for mv elements. (There are no attributes specific to the mv namespace.) Redefine this to some other prefix that you prefer to use. (Note: you must use some prefix. There is no provision to use the default (i.e., prefix-less) namespace.) The default value is mv.

%mv.namespace; defines the namespace URI for mv elements. You probably won't need to modify this.

%mv.nsattr; defines the attribute name xmlns:mv defining the mv namespace according to the XML namespaces rules. You probably won't need to modify this either. This attribute may be added to mv:declare-prefix, mv:modularvocab, mv:mode, mv:init-parameter, mv:set-parameter elements.

The following is an alphabetical list of additional parameters that simply define the full qualified name of the element they name. In all cases %mv.XXXX; expands to mv:XXXX (where mv: is the current prefix and XXXX is the local name). These will not need to be changed. Each of these elements is described in detail below, and the code for their execution is in java class gloss.GlossExecution.

abort

append-parameter

attribute

cdata

character-reference

comment

cr

declare-prefix

default

document

document-fragment

doctype

dtd

element

element-declaration

else

entity-reference

error

execute

export-parameter

get-text

hook

if

if-not

include

incr-parameter

init-parameter

infix

literal

match

message

mode

modularvocab

processing-instruction

process-tokens

return

set-parameter

group

text

xr-element

Synopsis:

The "mv:abort" element pushes the current token back on to the input stream (which may possibly be re-read as a different token depending on the mode it is next read in), and ends the current mode (started with mv:execute or mv:process-tokens or was the main root mode "main") passing control to the previous mode.

Synopsis:

This appends data to a parameter value. <mv:append-parameter name="xxx" value="yyy"/> is equivalent to <mv:set-parameter name="xxx" value="${xxx}yyy" /> but is more convenient and may be faster. Both attributes are interpolated as usual first. Default for name is $q and for value is $v.

Synopsis:

Attributes name and ns are interpolated. Name has default value $q; ns has default value ${{XMLNS}$p}, where XMLNS is a URI mapping gloss parameter values to XML namespace prefixes. (Note that XML does not allow attributes to have a default namespace so $p must be non-null.) The output is an attribute node with namespace given either by the ns value or by ${{XMLNS}$p} and value being the content of the element. It is an error to give the name a prefix if the namespace is undefined. Note that it is the first of a group of attributes with the same name and namespace that are significant.

Synopsis:

Inserts a cdata node into the output tree with the content given.

Synopsis:

Inserts an xr:character-reference element into the output tree. with reference name (default value $q).

Synopsis:

Inserts a comment node into the output tree, with textual content that of the node.

Synopsis:

mv:cr elements signify that a carriage return should be placed on the output. TO-DO: need to think about any better way of controlling whitespace in the output.

Synopsis:

Defines a mapping of prefix to uri for a set of modes, or set/init-parameter commands. The content of a mv:declare-prefix command consists of a number of mv:set-parameter mv:init-parameter mv:declare-prefix or mv:modes. Neither attrubute is interpolated.

Synopsis:

These elements are children of mv:mode elements and denote action to take when a token has been accepted but no earlier match has been found. There are no attributes and the allowed content (the "..." above) is exactly as for mv:match.

Synopsis:

Creates a root xr:document node to contain data, and identifies which XML declaration to use.

Synopsis:

Creates a root xr:document-fragment node to contain data, and identifies which XML encoding declaration to use.

Synopsis:

Creates a root xr:doctype node to contain a suitable DOCTYPE declaration. The root attribute is optional and will be inferred from other data if necessary. Content may be an internal DTD. (DTDs are TO DO.)

Synopsis:

Creates a DTD document. Everything to do with DTDs and their content is TO DO.

Synopsis:

The "mv:element" command starts a new element node with the name and namespace given. If the name is "prefix:local" and the attribute ns is not given explicitly, the namespace is obtained from a parameter value. It is an error to give the name a prefix if the namespace is undefined.

The content of this node defines the content of the element.

Synopsis:

Part of the DTD description which is still TO DO.

Synopsis:

If immediately following <mv:if ...></mv:if> or <mv:if-not ...></mv:if-not> the content is executed if the test in <mv:if ...> (or <mv:if-not ...>) is false (true, respectively). Otherwise the content is ignored.

Synopsis:

Inserts an xr:entity-reference element into the output tree.

Synopsis:

The content of the error command is text that is interpolated in the usual way. It becomes the message of a parse exception that is thrown immediately, usually stopping the computation.

Synopsis:

The execute command executes the named mode as if a token of the given type (with data as given, and depth, linenumber, columnnumber taken from the current token) had been read. It finds the appropriate match and performs the content of this match element and then returns to the calling mode. It is an error if there is no mode with the given name. The attribute parameters="[no]share" behaves as for mv:process-tokens and has default value "noshare".

Synopsis:

This sets the value of the parameter to the value given, if present, and then exports the parameter's value to the first ancestor node with the same prefix.

Synopsis:

The last node placed is removed and its text value is stored in the parameter with the given name.

Synopsis:

Synopsis:

Here, the expression at "test" is evaluated using usual rules. If value="..." is omitted the test is true iff this expression is non-null and non-empty. Otherwise the test is true if the expression evaluates to the same one that value does. If the test comes out true, then the children of the node are executed. name and value are interpolated as usual.

Synopsis:

Here, the expression at "test" is evaluated using usual rules. If value="..." is omitted the test is true iff this expression is null or empty. Otherwise the test is true if the expression evaluates to the a different one that value does. If the test comes out true, then the children of the node are executed. name and value are interpolated as usual.

Synopsis:

"mv:include" tags signify that the matches from one mode should be considered as included at that point in another. They do not affect the "accept" or other attributes of the parent mv:mode element.

Synopsis:

This numerically adds data to an existing parameter value. <mv:incr-parameter name="xxx" value="yyy"/> is equivalent to xxx=xxx+yyy except when xxx does not resolve to an integer then xxx is left unchanged. value="1" is the default.

Synopsis:

The result of this command is that the parameter specified by "name" is initialized to value specified by "value", unless it has already been set or initialized, in which case no changes are made.

Synopsis:

The "mv:infix" command starts a new element node with the name and namespace given. This node replaces the last node put onto the output tree at the current position, and this replaced node becomes the first child of the new element. It is an error if there is no such node to replace.

In other respects, it behaves just like mv:element So if the name is "prefix:local" and the attribute ns is not given explicitly, the namespace is obtained from a parameter value. It is an error to give the name a prefix if the namespace is undefined.

The content of this node defines additional content of the element.

Attributes to this element may be added using <mv:attribute> or <xr:attribute>. The fact that the element already has children will not affect this.

Synopsis:

The contents of the element (usually a CDATA block) are put on the output in literal fashion.

Synopsis:

"mv:match" tags signify possible matches in a mode against a new token. The type must be given and must match. The other data should match if given.

The data, localname, prefix, fullname, value attributes specify data that must match. All of the attributes from this list that are presented must match for a match to have deemed to occur. Simple matches just specify the string that these datamust equal. (Such strings must not start with a $ character). A more complex matching syntax exists when one of these attributes is given and starts with a $.

The children-XXX attributes change the expected number of children tokens of the mode this <mv:match> is being interpreted in. You can make absolute changes to the total (children-total) or to the number of remaining children (children-remainaing), or relative changes to either (children-adjust). If more than one of these three attributes is given, total takes precidence over remaining which takes precedence over adjust.

Synopsis:

A message is printed to standard error on the console, perhaps indicating a possible problem. The content of the element is text which is interpolated in the usual way and printed as the message.

Synopsis:

An mv:mode is a mode of operation or module for this vocabulary, and consists of a list of possible matches for tokens.

The "accept" attribute lists all possible types of token that will be allowed together with all possible allowed punctuation symbols. The default for "main" is "accept=''"; therwise there is no default and "accept" must be given.

The possible types for accept, other than literal punctuation, are

Attribute "children" (default = +infinity, except when name="main" when children="1" is the default) allows the user to specify a maximum number of tokens received by this mode.

Setting "use-indentation='false'" stops the default mechanism that exits a mode when a lower-or-same indented token is found amongst sub-tokens of a node. The default value for use-indentation is normally true (except when name="main" when it is false) but this default can be reset by changing the %mv.use-indentation-default; parameter.

NONE of the attributes here are interpolated.

Synopsis:

"mv:modularvocab" is the root element and its content consists of a number of mv:set-parameter mv:init-parameter mv:declare-prefix or mv:modes.

Synopsis:

Inserts a processing instruction node into the output tree, with target as given and textual content that of the node.

Synopsis:

The "mv:process-tokens" command pushes to start a new mode (as named, or if this name is not given, with the same name as the current node). The new mode name is interpolated in the usual way.

Unless parameters="share" is present, "mv:process-tokens" uses a different clone of the parameter list so any set-parameter executed within the process-tokens will not affect the current parameter list. (N.B., subsequent "mv:process-tokens" commands will also need parameters="share" to export their parameters, i.e., parameter changes made after a subsequently executed "mv:process-tokens" without parameters="share" will not be exported.) See also export-parameter.

The "children" and "use-indentation" attributes can be used here to override any declared in the mode.

Synopsis:

<mv:return/> ends the current mode passing control to the previous mode.

Synopsis:

The result of this command is that the parameter specified by "name" is set to value specified by "value". Both name and value are interpolated as usual. Parameters can be used in text modes, many attributes, and to define namespaces.

Synopsis:

This generates an xr:group element for adding additional grouping structure to the output.

Synopsis:

Inserts a text node into the output tree, with textual content that of the node. Note that this element is converted to a genuine text node, not an intermediate xr:text representation.

Synopsis:

Inserts an element in the XR namespace directly into the output tree. This element will be processed by the printer.

We read in here the DTD for gloss tokens. This is useful for mvs that receive an unexpected tokens and don't know what to do with it, or for post-processing using XSLT. This DTD for gloss tokens is very straightforward. You should find it described elsewhere.

See the documentation elsewhere for this DTD.