Public SiteDocumentation
 

Nomad - Module Definition DTD

Module Definition DTD v1.0

Purpose

This DTD was developed to define the modules of the Nord Modular synthesizer and their hierarchie.

Note

Any information represented in the XML file is independend of the language you chose for programming. The definitions of substitutions are not directly included into this DTD as the may contain language dependend information like class-names.

Structuring Modules

Along with defining the attributes of a single module this DTD supports adding information about how they relate to each other and how they are grouped.

Example: (contained elements: structure, group, section insert ) 

<structure>
  <group name="In/Out">
    <section>
      <insert module-id="1" />
      <insert module-id="63" />
      <insert module-id="65" />
    </section>
    <section>
      <insert module-id="2" />
      <insert module-id="127" />
    </section>
    ...
  </group>
  ...
</structure>

The provided structure can be used to generate the following tabbed pane.

[figure:tabbedpane - groups and sections]
  • Each 'group'-element is mapped to a tab-group in the same order found in the xml file.
  • The 'section'-element groups modules inside a tab. Two sections should be separated by a space.
  • Modules inside a section should appear in the tab in the same order found in the xml file.

Proposal for new versions

The substitutions have to be better integrated. For example on an oscillator-module the frequency value (and with that it's substitution) depends on the states of frequency-display, coarse and fine. In this version of the DTD supports no substitutions that have more than one variable.

All possible names for a substitution should be defined in this DTD.

Language-independend substitutions for the values of a parameter should be defined in this DTD. (for example simple string-substitutions like: 0='Off',1='On')

Substitutions now threaded as language-depended, such that have to be calculated (for example the Oscillator's frequency) might be represented in the xml file as well. This could be realized as shown in the next example. (a similar substitution can be found in the substitutions DTD) 

<substitution name="example-transformation">
    <transform
      offset         = "0"      <!-- default:0  , shortcut:o -->
      factor         = "1.0"    <!-- default:1.0, shortcut:f -->
      prefix-string  = "x"      <!-- default:"" , shortcut:p -->
      suffix-string  = "[UNIT]" <!-- default:"" , shortcut:s -->
    />
</substitution>

represents the transformation:

[figure:example transformation]

There could be an 'optional'-element containing optional information about a module. For example it could contain layout related definitions such as how elements should be grouped. For example

  • coarse - fine - frequency-display belong together
  • in- or outputs often belong to an additional level-knob

This would definately increase the development time required to generate custom themes. Simply because

  • grouped elements can automatically be positioned together
  • more user interface components can be generated automatically for example grouped elements could be put into a groupbox. Also text/icon-labels (where reasonable).

Object Model

[figure:mapping]

modules-definition-v10.dtd - Reference

Top-level element(s)

List of elements

Element declarations

group
Content model: ( section + )
Used insidestructure
Attributes:
name type: CDATArequired attribute
short-name type: CDATA implied attribute
implicit value: 'name'
Optional attribute which must contain a shortcut for attribute 'name'. A shortcut should be given if 'name' contains more than eight characters.
input
Content model: EMPTY
Used insidemodule
Attributes:
id type: NMTOKENrequired attribute
The id's value is equivalent to the index of an element defined by the protocol. For example two inputs with indices 0 and 1 must have an id with the same values 0 and 1.
name type: CDATArequired attribute
type possible values: audio, control, logic, slaverequired attribute
insert
Content model: EMPTY
Used insidesection
Attributes:
module-id type: NMTOKENrequired attribute
The id of a module. A module with same id must be defined inside the 'modules'-element.
module
Content model: ( custom | input | output | parameter ) *
Used insidemodules
Attributes:
id type: NMTOKENrequired attribute
The id's value is equivalent to the index of an element defined by the protocol. For example two inputs with indices 0 and 1 must have an id with the same values 0 and 1.
short-name type: CDATArequired attribute
cva-only possible values: true, false default value: 'false'
This attribute is only used in the PolyAreaIn module. Its value is false by default. The attribute has only to be specified if it should have 'true' as value.
limit type: NMTOKEN implied attribute
implicit value: 'infinity'
Defines a limit of how many times a module is available in one patch. Not specifying this attribute means that the number of this module is not limited.
cycles type: NMTOKENrequired attribute
dyn-mem type: NMTOKENrequired attribute
height type: NMTOKENrequired attribute
prog-mem type: NMTOKENrequired attribute
x-mem type: NMTOKENrequired attribute
y-mem type: NMTOKENrequired attribute
zero-page type: NMTOKENrequired attribute
modules
Content model: ( module +)
Used insidemodules-definition
Attributes:- none -
modules-definition (top-level element)
Content model: ( structure, modules )
Used inside- none -
Attributes:- none -
output
Content model: EMPTY
Used insidemodule
Attributes:
id type: NMTOKENrequired attribute
The id's value is equivalent to the index of an element defined by the protocol. For example two inputs with indices 0 and 1 must have an id with the same values 0 and 1.
name type: CDATArequired attribute
type possible values: audio, control, logic, slaverequired attribute
parameter
Content model: EMPTY
Used insidemodule
Attributes:
id type: NMTOKENrequired attribute
The id's value is equivalent to the index of an element defined by the protocol. For example two inputs with indices 0 and 1 must have an id with the same values 0 and 1.
name type: CDATArequired attribute
min type: NMTOKEN implied attribute
implicit value: '0'
The smallest possible value. If the attribute is missing it implies a zero value.
max type: NMTOKENrequired attribute
The largest possible value.
default type: NMTOKEN implied attribute
implicit value: '0'
The default value. This should be used to set the state of a parameter when a module is instantiated.
bit-count type: NMTOKENrequired attribute
Number of bits reserved for the value. (expected by the protocol)
use-substitution type: CDATAimplied attribute
Contains an identifier for the substitution that should be used to give the formatted representation of the parameter's raw value. A missing 'use-substitution' attribute implies that the value itself is equal to it's substitution. This simply means that for example the number 5 is substituted by the string "5". (Find out more about substitutions.)
section
Content model: ( insert + )
Used insidegroup
Attributes:- none -
structure
Content model: ( group + )
Used insidemodules-definition
Attributes:- none -
true
Substitutions are not supported in this DTD version for element 'custom'.
Content model: EMPTY
Used inside- none -
Attributes:
id type: NMTOKENrequired attribute
min type: NMTOKEN implied attribute
implicit value: '0'
The smallest possible value. If the attribute is missing it implies a zero value.
max type: NMTOKENrequired attribute
The largest possible value.
default type: NMTOKEN implied attribute
implicit value: '0'
The default value. This should be used to set the state of a parameter when a module is instantiated.
bit-count type: NMTOKENrequired attribute
Number of bits reserved for the value. (expected by the protocol)

Substitution DTD v1.0

Purpose

The idea behind substitutions is to XMLize the transformation from a parameter's numeric representation to its string-representation. This has several convenient advantages:

  • less information must be included in source code
  • automated linking of substitutions and parameters

Proposal for new versions

See the "Proposal for new versions"-section.

substitutions-v10.dtd - Reference

Top-level element(s)

List of elements

Element declarations

if
If a parameter's value is equal to attribute 'value-is', 'replace-with' supersedes the superior substitution.
Content model: EMPTY
Used insidetransform
Attributes:
replace-width type: CDATArequired attribute
value-is type: NMTOKENrequired attribute
item
Content model:( #PCDATA )
Used insidelist
Attributes:- none -
list
Contains a list of strings. The parameters value is used as index to an 'item' element where the 0 is the index for the first item, 1 is the index for the second item, ... .
Content model:item +
Used insidesubstitutions
Attributes:
id type: IDrequired attribute
Name of the substitution
substitutions (top-level element)
Content model: ( transform + , use-implementation + , list + )
Used inside- none -
Attributes:
id type: IDrequired attribute
Name of the substitution
transform
This element defines the transformation
t(value) := concatenate(prefix, (value+offset)·factor, suffix) .
If element 'if' matches value, it supercedes the transformation t(value).
Content model:if ?
Used insidesubstitutions
Attributes:
id type: IDrequired attribute
Name of the substitution
factor type: NMTOKEN implied attribute
implicit value: '1.0'
offset type: NMTOKEN implied attribute
implicit value: '0.0'
prefix type: CDATA implied attribute
implicit value: '-empty string-'
suffix type: CDATA implied attribute
implicit value: '-empty string-'
use-implementation
This element links a custom implementation with a parameter.
Content model: EMPTY
Used insidesubstitutions
Attributes:
id type: IDrequired attribute
Name of the substitution
class type: IDrequired attribute
Identifier for the custom implementation.

by Christian Schneider