How to Use this Document
If you are new to the OrganSpec standard, you should start by
reading all of this Overview.
After that, you should probably start with the
Organ element and work downward from there.
If you'd rather just dive in headfirst, take a look at the
example.
To learn about how to deal with specific organ features,
try the Index, Glossary and How-To.
Prerequisites
A familiarity with XML is helpful in understanding
this document, but it is not required.
You may want to look at the XML Overview.
Some familiarity with pipe organs is required,
or very little of this will make sense.
General Structure of an OrganSpec
An OrganSpec consists of elements which represent major features
of a pipe organ, such as stops, ranks, couplers, consoles, keyboards,
chambers, etc.
The topmost or outermost element is the
Organ, which represents one entire organ.
The OrganSpec standard provides a fair amount of flexibility
in how a specification is formatted.
This flexibility allows simple specifications to avoid unnecessary
complexity, while providing enough power to represent large and
complex specifications.
It's possible to get overwhelmed by the level of detail allowed
by the various elements; look at the example
to see how simple an OrganSpec can be.
In a simple specification, the Organ
specification might contain a Location
element to describe where the organ is located,
a Builder element to describe the organ builder,
a Source element to describe where
the specification was copied from, and one
Keyboard element for each manual
or pedal keyboard.
The Keyboard elements would contain some number of
Stop elements, and perhaps some
Coupler elements.
In a more complex specification, the Organ element might contain
Chamber elements to describe
the chambers and the Console elements
to describe multiple consoles. The Chamber element might
contain one Rank element for each
rank of pipes. The Console element would contain the
Keyboard and Coupler elements, and perhaps a
Division element to describe
a floating division.
Element Descriptions
Each element is described on its own page, which has the following sections:
- A description of what the element is for and how it is used.
- A list of the "parent" elements; that is, the elements which
may contain the element being described.
- A list of the "child" elements; that is, the elements which may
appear within the body of element being described.
This list includes how many times the child element may appear
within the parent.
- A list of the element's attributes, with their meanings and usage.
The word "required" appears in italics to indicate an attribute which
must appear in every instance of the element.
- One or more examples of how the element can be used.
- A fragment of the XML DTD that defines the element.
If you don't understand what this is for, don't worry about it.
Order of Elements
In general, the order in which elements occur does not convey any
information, is not significant, and is not guaranteed to be maintained.
Ordering information may be specified through the use of the "order" attribute
which is allowed in many elements.
Histories
Many elements within an OrganSpec may optionally have installation and/or
removal dates associated with them.
This allows one OrganSpec to record not just a single snapshot in
time of an instrument, but how it was altered over time.
Interesting historical events regarding an organ, which do not
fit into some other element, can be stored in a History element.
Remarks
The OrganSpec standard is designed to capture a great deal
of interesting information about an organ in a way which can easily
be processed by software.
A Remark element is available for
storing information which doesn't fit anywhere else.
Language Independence
The OrganSpec standard is designed to allow OrganSpecs to be independent
of any language, and to allow rendering in human-readable form in any
language. Free-form narrative text is allowed only in the
Remark element, which contains a required
"language" attribute for specifying the language of the remark,
and allows the simultaneous inclusion of the same remark in multiple
languages.
Character Set
The XML standard provides for a specification of the character set being used.
To maximize compatability, only the "UTF-8" character set should be used.
To maximize transmittability over the internet, only ASCII (7-bit) characters
should be used. (ASCII is a subset of UTF-8).
If a NON-ASCII character is needed,
then it should be encoded as one of the character entities,
which are intentionally compatible with HTML.
Accents should not be dropped, nor should they be approximated
using ASCII characters. For example:
| Original
| Correct
| Incorrect
|
| Baßflöte
| Baßflöte
| Bassflote, Baßflöte, BaBflo"te
|
| Flûte à Bec
| Flûte à Bec
| Flute a Bec, Flûte à Bec, Flu^te a' Bec
|
Outstanding Issues
- How should "second touch" (on theatre organs) be represented?
As an attribute of the Stop element?
As an attribute of the Division element?
As a new element?
- Should History, Source and Builder be allowed anywhere?
- Should the "type" attribute in the KeyAction and StopAction
elements be restricted to a limited set choices?
If so, what should the choices be?
- There is no good way to represent a mixture which is unified.
Add a new element called RankSet?
- Should the Rank element have a "compass" attribute?
- How should we represent scale data?
This will almost certainly not be addressed in version 1.0,
but it needs to be thought about.
- What aboue ventils?
Copyright © Institute for Pipe Organ Research And Education, Inc. 2002