Move documentation to metadata files and convert it to Markdown

2 files changed, 497 insertions, 416 deletions

diff --git a/lv2/atom/atom.meta.ttl b/lv2/atom/atom.meta.ttl
index 4f6e69b..7b04180 100644
--- a/lv2/atom/atom.meta.ttl
+++ b/lv2/atom/atom.meta.ttl
@@ -1,6 +1,8 @@
+@prefix atom: <http://lv2plug.in/ns/ext/atom#> .
 @prefix dcs: <http://ontologi.es/doap-changeset#> .
 @prefix doap: <http://usefulinc.com/ns/doap#> .
 @prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 
 <http://lv2plug.in/ns/ext/atom>
@@ -100,5 +102,441 @@
 				rdfs:label "Initial release."
 			]
 		]
-	] .
+	] ;
+	lv2:documentation """
+
+An atom:Atom is a simple generic data container for holding any type of Plain
+Old Data (POD).  An Atom can contain simple primitive types like integers,
+floating point numbers, and strings; as well as structured data like lists and
+dictionary-like <q>Objects</q>.  Since Atoms are POD, they can be easily copied
+(for example, with `memcpy()`) anywhere and are suitable for use in real-time
+code.
+
+Every atom starts with an LV2_Atom header, followed by the contents.  This
+allows code to process atoms without requiring special code for every type of
+data.  For example, plugins that mutually understand a type can be used
+together in a host that does not understand that type, because the host is only
+required to copy atoms, not interpret their contents.  Similarly, plugins (such
+as routers, delays, or data structures) can meaningfully process atoms of a
+type unknown to them.
+
+Atoms should be used anywhere values of various types must be stored or
+transmitted.  An atom:AtomPort can be used to transmit atoms via ports.  An
+atom:AtomPort that contains a atom:Sequence can be used for sample accurate
+communication of events, such as MIDI.
+
+### Serialisation
+
+Each Atom type defines a binary format for use at runtime, but also a
+serialisation that is natural to express in Turtle format.  Thus, this
+specification defines a powerful real-time appropriate data model, as well as a
+portable way to serialise any data in that model.  This is particularly useful
+for inter-process communication, saving/restoring state, and describing values
+in plugin data files.
+
+### Custom Atom Types
+
+While it is possible to define new Atom types for any binary format, the
+standard types defined here are powerful enough to describe almost anything.
+Implementations SHOULD build structures out of the types provided here, rather
+than define new binary formats (for example, using atom:Object rather than a
+new C `struct` type).  Host and tool implementations have support for
+serialising all standard types, so new binary formats are an implementation
+burden which harms interoperabilty.  In particular, plugins SHOULD NOT expect
+UI communication or state saving with custom binary types to work.  In general,
+new Atom types should only be defined where absolutely necessary due to
+performance reasons and serialisation is not a concern.
+
+"""^^lv2:Markdown .
+
+atom:Atom
+	lv2:documentation """
+
+An LV2_Atom has a 32-bit `size` and `type`, followed by a body of `size` bytes.
+Atoms MUST be 64-bit aligned.
+
+All concrete Atom types (subclasses of this class) MUST define a precise binary
+layout for their body.
+
+The `type` field is the URI of an Atom type mapped to an integer.
+Implementations SHOULD gracefully pass through, or ignore, atoms with unknown
+types.
+
+All atoms are POD by definition except references, which as a special case have
+`type` 0.  An Atom MUST NOT contain a Reference.  It is safe to copy any
+non-reference Atom with a simple `memcpy`, even if the implementation does not
+understand `type`.  Though this extension reserves the type 0 for references,
+the details of reference handling are currently unspecified.  A future revision
+of this extension, or a different extension, may define how to use non-POD data
+and references.  Implementations MUST NOT send references to another
+implementation unless the receiver is explicitly known to support references
+(e.g. by supporting a feature).
+
+The special case of a null atom with both `type` and `size` 0 is not considered
+a reference.
+
+"""^^lv2:Markdown .
+
+atom:Chunk
+	lv2:documentation """
+
+This type is used to indicate a certain amount of space is available.  For
+example, output ports with a variably sized type are connected to a Chunk so
+the plugin knows the size of the buffer available for writing.
+
+The use of a Chunk should be constrained to a local scope, since
+interpreting it is impossible without context.  However, if serialised to RDF,
+a Chunk may be represented directly as an xsd:base64Binary string, for example:
+
+    :::turtle
+    [] eg:someChunk "vu/erQ=="^^xsd:base64Binary .
+
+"""^^lv2:Markdown .
+
+atom:String
+	lv2:documentation """
+
+The body of an LV2_Atom_String is a C string in UTF-8 encoding, i.e. an array
+of bytes (`uint8_t`) terminated with a NULL byte (`'\\0'`).
+
+This type is for free-form strings, but SHOULD NOT be used for typed data or
+text in any language.  Use atom:Literal unless translating the string does not
+make sense and the string has no meaningful datatype.
+
+"""^^lv2:Markdown .
+
+atom:Literal
+	lv2:documentation """
+
+This type is compatible with rdfs:Literal and is capable of expressing a
+string in any language or a value of any type.  A Literal has a
+`datatype` and `lang` followed by string data in UTF-8
+encoding.  The length of the string data in bytes is `size -
+sizeof(LV2_Atom_Literal)`, including the terminating NULL character.  The
+`lang` field SHOULD be a URI of the form
+&lt;http://lexvo.org/id/iso639-3/LANG&gt; or
+&lt;http://lexvo.org/id/iso639-1/LANG&gt; where LANG is a 3-character ISO 693-3
+language code, or a 2-character ISO 693-1 language code, respectively.
+
+A Literal may have a `datatype` or a `lang`, but never both.
+
+For example, a Literal can be <q>Hello</q> in English:
+
+    :::c
+    void set_to_hello_in_english(LV2_Atom_Literal* lit) {
+         lit->atom.type     = map(expand("atom:Literal"));
+         lit->atom.size     = 14;
+         lit->body.datatype = 0;
+         lit->body.lang     = map("http://lexvo.org/id/iso639-1/en");
+         memcpy(LV2_ATOM_CONTENTS(LV2_Atom_Literal, lit),
+                "Hello",
+                sizeof("Hello"));  // Assumes enough space
+    }
+
+or a Turtle string:
+
+    :::c
+    void set_to_turtle_string(LV2_Atom_Literal* lit, const char* ttl) {
+         lit->atom.type     = map(expand("atom:Literal"));
+         lit->atom.size     = 64;
+         lit->body.datatype = map("http://www.w3.org/2008/turtle#turtle");
+         lit->body.lang     = 0;
+         memcpy(LV2_ATOM_CONTENTS(LV2_Atom_Literal, lit),
+                ttl,
+                strlen(ttl) + 1);  // Assumes enough space
+    }
+
+"""^^lv2:Markdown .
+
+atom:Path
+	lv2:documentation """
+
+A Path is a URI reference with only a path component: no scheme, authority,
+query, or fragment.  In particular, paths to files in the same bundle may be
+cleanly written in Turtle files as a relative URI.  However, implementations
+may assume any binary Path (e.g. in an event payload) is a valid file path
+which can passed to system functions like fopen() directly, without any
+character encoding or escape expansion required.
+
+Any implemenation that creates a Path atom to transmit to another is
+responsible for ensuring it is valid.  A Path SHOULD always be absolute, unless
+there is some mechanism in place that defines a base path.  Since this is not
+the case for plugin instances, effectively any Path sent to or received from a
+plugin instance MUST be absolute.
+
+"""^^lv2:Markdown .
+
+atom:URI
+	lv2:documentation """
+
+This is useful when a URI is needed but mapping is inappropriate, for example
+with temporary or relative URIs.  Since the ability to distinguish URIs from
+plain strings is often necessary, URIs MUST NOT be transmitted as atom:String.
+
+This is not strictly a URI, since UTF-8 is allowed.  Escaping and related
+issues are the host's responsibility.
+
+"""^^lv2:Markdown .
+
+atom:URID
+	lv2:documentation """
+
+A URID is typically generated with the LV2_URID_Map provided by the host .
+
+"""^^lv2:Markdown .
+
+atom:Vector
+	lv2:documentation """
+
+A homogeneous series of atom bodies with equivalent type and size.
+
+An LV2_Atom_Vector is a 32-bit `child_size` and `child_type` followed by `size
+/ child_size` atom bodies.
+
+For example, an atom:Vector containing 42 elements of type atom:Float:
+
+    :::c
+    struct VectorOf42Floats {
+        uint32_t size;        // sizeof(LV2_Atom_Vector_Body) + (42 * sizeof(float);
+        uint32_t type;        // map(expand("atom:Vector"))
+        uint32_t child_size;  // sizeof(float)
+        uint32_t child_type;  // map(expand("atom:Float"))
+        float    elems[42];
+    };
+
+Note that it is possible to construct a valid Atom for each element of the
+vector, even by an implementation which does not understand `child_type`.
+
+If serialised to RDF, a Vector SHOULD have the form:
+
+    :::turtle
+    eg:someVector
+         a atom:Vector ;
+         atom:childType atom:Int ;
+         rdf:value (
+             "1"^^xsd:int
+             "2"^^xsd:int
+             "3"^^xsd:int
+             "4"^^xsd:int
+         ) .
+
+"""^^lv2:Markdown .
+
+atom:Tuple
+	lv2:documentation """
+
+The body of a Tuple is simply a series of complete atoms, each aligned to
+64 bits.
+
+If serialised to RDF, a Tuple SHOULD have the form:
+
+    :::turtle
+    eg:someVector
+         a atom:Tuple ;
+         rdf:value (
+             "1"^^xsd:int
+             "3.5"^^xsd:float
+             "etc"
+         ) .
+
+"""^^lv2:Markdown .
+
+atom:Property
+	lv2:documentation """
+
+An LV2_Atom_Property has a URID `key` and `context`, and an Atom `value`.  This
+corresponds to an RDF Property, where the <q>key</q> is the <q>predicate</q>
+and the <q>value</q> is the object.
+
+The `context` field can be used to specify a different context for each
+property, where this is useful.  Otherwise, it may be 0.
+
+Properties generally only exist as part of an atom:Object.  Accordingly,
+they will typically be represented directly as properties in RDF (see
+atom:Object).  If this is not possible, they may be expressed as partial
+reified statements, for example:
+
+    :::turtle
+    eg:someProperty
+        rdf:predicate eg:theKey ;
+        rdf:object eg:theValue .
+
+"""^^lv2:Markdown .
+
+atom:Object
+	lv2:documentation """
+
+An <q>Object</q> is an atom with a set of properties.  This corresponds to an
+RDF Resource, and can be thought of as a dictionary with URID keys.
+
+An LV2_Atom_Object body has a uint32_t `id` and `type`, followed by a series of
+atom:Property bodies (LV2_Atom_Property_Body).  The LV2_Atom_Object_Body::otype
+field is equivalent to a property with key rdf:type, but is included in the
+structure to allow for fast dispatching.
+
+Code SHOULD check for objects using lv2_atom_forge_is_object() or
+lv2_atom_forge_is_blank() if a forge is available, rather than checking the
+atom type directly.  This will correctly handle the deprecated atom:Resource
+and atom:Blank types.
+
+When serialised to RDF, an Object is represented as a resource, for example:
+
+    :::turtle
+    eg:someObject
+        eg:firstPropertyKey "first property value" ;
+        eg:secondPropertyKey "first loser" ;
+        eg:andSoOn "and so on" .
+
+"""^^lv2:Markdown .
+
+atom:Resource
+	lv2:documentation """
+
+This class is deprecated.  Use atom:Object directly instead.
+
+An atom:Object where the <code>id</code> field is a URID, that is, an Object
+with a URI.
+
+"""^^lv2:Markdown .
+
+atom:Blank
+	lv2:documentation """
+
+This class is deprecated.  Use atom:Object with ID 0 instead.
+
+An atom:Object where the LV2_Atom_Object::id is a blank node ID (NOT a URI).
+The ID of a Blank is valid only within the context the Blank appears in.  For
+ports this is the context of the associated run() call, i.e. all ports share
+the same context so outputs can contain IDs that correspond to IDs of blanks in
+the input.
+
+"""^^lv2:Markdown .
+
+atom:Sound
+	lv2:documentation """
+
+The format of a atom:Sound is the same as the buffer format for lv2:AudioPort
+(except the size may be arbitrary).  An atom:Sound inherently depends on the
+sample rate, which is assumed to be known from context.  Because of this,
+directly serialising an atom:Sound is probably a bad idea, use a standard
+format like WAV instead.
+
+"""^^lv2:Markdown .
+
+atom:Event
+	lv2:documentation """
+
+An Event is typically an element of an atom:Sequence.  Note that this is not an Atom type since it begins with a timestamp, not an atom header.
+
+"""^^lv2:Markdown .
+
+atom:Sequence
+	lv2:documentation """
+
+A flat sequence of atom:Event, that is, a series of time-stamped Atoms.
+
+LV2_Atom_Sequence_Body.unit describes the time unit for the contained atoms.
+If the unit is known from context (e.g. run() stamps are always audio frames),
+this field may be zero.  Otherwise, it SHOULD be either units:frame or
+units:beat, in which case ev.time.frames or ev.time.beats is valid,
+respectively.
+
+If serialised to RDF, a Sequence has a similar form to atom:Vector, but for
+brevity the elements may be assumed to be atom:Event, for example:
+
+    :::turtle
+    eg:someSequence
+        a atom:Sequence ;
+        rdf:value (
+            [
+                atom:frameTime 1 ;
+                rdf:value "901A01"^^midi:MidiEvent
+            ] [
+                atom:frameTime 3 ;
+                rdf:value "902B02"^^midi:MidiEvent
+            ]
+        ) .
+
+"""^^lv2:Markdown .
+
+atom:AtomPort
+	lv2:documentation """
+
+Ports of this type are connected to an LV2_Atom with a type specified by
+atom:bufferType.
+
+Output ports with a variably sized type MUST be initialised by the host before
+every run() to an atom:Chunk with size set to the available space.  The plugin
+reads this size to know how much space is available for writing.  In all cases,
+the plugin MUST write a complete atom (including header) to outputs.  However,
+to be robust, hosts SHOULD initialise output ports to a safe sentinel (e.g. the
+null Atom) before calling run().
+
+"""^^lv2:Markdown .
+
+atom:bufferType
+	lv2:documentation """
+
+Indicates that an AtomPort may be connected to a certain Atom type.  A port MAY
+support several buffer types.  The host MUST NOT connect a port to an Atom with
+a type not explicitly listed with this property.  The value of this property
+MUST be a sub-class of atom:Atom.  For example, an input port that is connected
+directly to an LV2_Atom_Double value is described like so:
+
+    :::turtle
+    &lt;plugin&gt;
+        lv2:port [
+            a lv2:InputPort , atom:AtomPort ;
+            atom:bufferType atom:Double ;
+        ] .
+
+This property only describes the types a port may be directly connected to.  It
+says nothing about the expected contents of containers.  For that, use
+atom:supports.
+
+"""^^lv2:Markdown .
+
+atom:supports
+	lv2:documentation """
+
+This property is defined loosely, it may be used to indicate that anything
+<q>supports</q> an Atom type, wherever that may be useful.  It applies
+<q>recursively</q> where collections are involved.
+
+In particular, this property can be used to describe which event types are
+expected by a port.  For example, a port that receives MIDI events is described
+like so:
+
+    :::turtle
+    &lt;plugin&gt;
+        lv2:port [
+            a lv2:InputPort , atom:AtomPort ;
+            atom:bufferType atom:Sequence ;
+            atom:supports midi:MidiEvent ;
+        ] .
+
+"""^^lv2:Markdown .
+
+atom:eventTransfer
+	lv2:documentation """
+
+Transfer of individual events in a port buffer.  Useful as the `format` for a
+LV2UI_Write_Function.
+
+This protocol applies to ports which contain events, usually in an
+atom:Sequence.  The host must transfer each individual event to the recipient.
+The format of the received data is an LV2_Atom, there is no timestamp header.
+
+"""^^lv2:Markdown .
+
+atom:atomTransfer
+	lv2:documentation """
+
+Transfer of the complete atom in a port buffer.  Useful as the `format` for a
+LV2UI_Write_Function.
+
+This protocol applies to atom ports.  The host must transfer the complete atom
+contained in the port, including header.
+
+"""^^lv2:Markdown .
 
diff --git a/lv2/atom/atom.ttl b/lv2/atom/atom.ttl
index dc9fa1e..96e9326 100644
--- a/lv2/atom/atom.ttl
+++ b/lv2/atom/atom.ttl
@@ -14,121 +14,44 @@
 		<util.h> ,
 		<forge.h> ,
 		<atom.meta.ttl> ;
-	lv2:documentation """
-
-<p>An #Atom is a simple generic data container for holding any type of Plain
-Old Data (POD).  An #Atom can contain simple primitive types like integers,
-floating point numbers, and strings; as well as structured data like lists and
-dictionary-like <q>Objects</q>.  Since Atoms are POD, they can be easily copied
-(e.g. using <code>memcpy</code>) anywhere and are suitable for use in real-time
-code.</p>
-
-<p>Every atom starts with an LV2_Atom header, followed by the contents.  This
-allows code to process atoms without requiring special code for every type of
-data.  For example, plugins that mutually understand a type can be used
-together in a host that does not understand that type, because the host is only
-required to copy atoms, not interpret their contents.  Similarly, plugins (such
-as routers, delays, or data structures) can meaningfully process atoms of a
-type unknown to them.</p>
-
-<p>Atoms should be used anywhere values of various types must be stored or
-transmitted.  The port type #AtomPort can be used to transmit atoms via ports.
-An #AtomPort that contains an #Sequence can be used for sample accurate event
-communication, such as MIDI, and replaces the earlier event extension.</p>
-
-<h3>Serialisation</h3>
-
-<p>Each Atom type defines a binary format for use at runtime, but also a
-serialisation that is natural to express in Turtle format.  Thus, this
-specification defines a powerful real-time appropriate data model, as well as a
-portable way to serialise any data in that model.  This is particularly useful
-for inter-process communication, saving/restoring state, and describing values
-in plugin data files.</p>
-
-<h3>Custom Atom Types</h3>
-
-<p>While it is possible to define new Atom types for any binary format, the
-standard types defined here are powerful enough to describe almost anything.
-Implementations SHOULD build structures out of the types provided here, rather
-than define new binary formats (e.g. use #Tuple or #Object rather than
-a new C <code>struct</code> type).  Current implementations have support for
-serialising all standard types, so new binary formats are an implementation
-burden which harms interoperabilty.  In particular, plugins SHOULD NOT expect
-UI communication or state saving with custom Atom types to work.  In general,
-new Atom types should only be defined where absolutely necessary due to
-performance reasons and serialisation is not a concern.</p>
-""" .
+	rdfs:label "LV2 Atom" ;
+	rdfs:comment "A generic value container and several data types." .
 
 atom:cType
 	a rdf:Property ,
 		owl:DatatypeProperty ,
 		owl:FunctionalProperty ;
 	rdfs:label "C type" ;
+	rdfs:comment "The C type that describes the binary representation of an Atom type." ;
 	rdfs:domain rdfs:Class ;
-	rdfs:range lv2:Symbol ;
-	rdfs:comment "The identifier for a C type describing the binary representation of an Atom of this type." .
+	rdfs:range lv2:Symbol .
 
 atom:Atom
 	a rdfs:Class ;
 	rdfs:label "Atom" ;
-	atom:cType "LV2_Atom" ;
-	lv2:documentation """
-<p>Abstract base class for all atoms.  An LV2_Atom has a 32-bit
-<code>size</code> and <code>type</code> followed by a body of <code>size</code>
-bytes.  Atoms MUST be 64-bit aligned.</p>
-
-<p>All concrete Atom types (subclasses of this class) MUST define a precise
-binary layout for their body.</p>
-
-<p>The <code>type</code> field is the URI of an Atom type mapped to an integer.
-Implementations SHOULD gracefully pass through, or ignore, atoms with unknown
-types.</p>
-
-<p>All atoms are POD by definition except references, which as a special case
-have <code>type = 0</code>.  An Atom MUST NOT contain a Reference.  It is safe
-to copy any non-reference Atom with a simple <code>memcpy</code>, even if the
-implementation does not understand <code>type</code>.  Though this extension
-reserves the type 0 for references, the details of reference handling are
-currently unspecified.  A future revision of this extension, or a different
-extension, may define how to use non-POD data and references.  Implementations
-MUST NOT send references to another implementation unless the receiver is
-explicitly known to support references (e.g. by supporting a feature).</p>
-
-<p>The atom with both <code>type</code> <em>and</em> <code>size</code> 0 is
-<q>null</q>, which is not considered a Reference.</p>
-""" .
+	rdfs:comment "Abstract base class for all atoms." ;
+	atom:cType "LV2_Atom" .
 
 atom:Chunk
 	a rdfs:Class ,
 		rdfs:Datatype ;
 	rdfs:subClassOf atom:Atom ;
-	rdfs:label "Chunk of memory" ;
-	owl:onDatatype xsd:base64Binary ;
-	lv2:documentation """
-<p>A chunk of memory with undefined contents.  This type is used to indicate a
-certain amount of space is available.  For example, output ports with a
-variably sized type are connected to a Chunk so the plugin knows the size of
-the buffer available for writing.</p>
-
-<p>The use of a Chunk should be constrained to a local scope, since
-interpreting it is impossible without context.  However, if serialised to RDF,
-a Chunk may be represented directly as an xsd:base64Binary string, e.g.:</p>
-
-<pre class="turtle-code">
-[] eg:someChunk "vu/erQ=="^^xsd:base64Binary .
-</pre>
-""" .
+	rdfs:label "Chunk" ;
+	rdfs:comment "A chunk of memory with undefined contents." ;
+	owl:onDatatype xsd:base64Binary .
 
 atom:Number
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Atom ;
-	rdfs:label "Number" .
+	rdfs:label "Number" ;
+	rdfs:comment "Base class for numeric types." .
 
 atom:Int
 	a rdfs:Class ,
 		rdfs:Datatype ;
 	rdfs:subClassOf atom:Number ;
-	rdfs:label "Signed 32-bit integer" ;
+	rdfs:label "Int" ;
+	rdfs:comment "A native `int32_t`." ;
 	atom:cType "LV2_Atom_Int" ;
 	owl:onDatatype xsd:int .
 
@@ -136,7 +59,8 @@ atom:Long
 	a rdfs:Class ,
 		rdfs:Datatype ;
 	rdfs:subClassOf atom:Number ;
-	rdfs:label "Signed 64-bit integer" ;
+	rdfs:label "Long" ;
+	rdfs:comment "A native `int64_t`." ;
 	atom:cType "LV2_Atom_Long" ;
 	owl:onDatatype xsd:long .
 
@@ -144,7 +68,8 @@ atom:Float
 	a rdfs:Class ,
 		rdfs:Datatype ;
 	rdfs:subClassOf atom:Number ;
-	rdfs:label "32-bit floating point number" ;
+	rdfs:label "Float" ;
+	rdfs:comment "A native `float`." ;
 	atom:cType "LV2_Atom_Float" ;
 	owl:onDatatype xsd:float .
 
@@ -152,7 +77,8 @@ atom:Double
 	a rdfs:Class ,
 		rdfs:Datatype ;
 	rdfs:subClassOf atom:Number ;
-	rdfs:label "64-bit floating point number" ;
+	rdfs:label "Double" ;
+	rdfs:comment "A native `double`." ;
 	atom:cType "LV2_Atom_Double" ;
 	owl:onDatatype xsd:double .
 
@@ -160,289 +86,99 @@ atom:Bool
 	a rdfs:Class ,
 		rdfs:Datatype ;
 	rdfs:subClassOf atom:Atom ;
-	rdfs:label "Boolean" ;
+	rdfs:label "Bool" ;
+	rdfs:comment "An atom:Int where 0 is false and any other value is true." ;
 	atom:cType "LV2_Atom_Bool" ;
-	owl:onDatatype xsd:boolean ;
-	rdfs:comment "An Int where 0 is false and any other value is true." .
+	owl:onDatatype xsd:boolean .
 
 atom:String
 	a rdfs:Class ,
 		rdfs:Datatype ;
 	rdfs:subClassOf atom:Atom ;
 	rdfs:label "String" ;
+	rdfs:comment "A UTF-8 string." ;
 	atom:cType "LV2_Atom_String" ;
-	owl:onDatatype xsd:string ;
-	lv2:documentation """
-<p>A UTF-8 encoded string.</p>
-
-<p>The body of an LV2_Atom_String is a C string in UTF-8 encoding, i.e. an
-array of bytes (<code>uint8_t</code>) terminated with a NULL byte
-(<code>'\\0'</code>).</p>
-
-<p>This type is for free-form strings, but SHOULD NOT be used for typed data or
-text in any language.  Use atom:Literal unless translating the string does not
-make sense and the string has no meaningful datatype.</p>
-""" .
+	owl:onDatatype xsd:string .
 
 atom:Literal
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Atom ;
-	rdfs:label "String Literal" ;
-	atom:cType "LV2_Atom_Literal" ;
-	lv2:documentation """
-<p>A UTF-8 encoded string literal, with an optional datatype or language.</p>
-
-<p>This type is compatible with rdfs:Literal and is capable of expressing a
-string in any language or a value of any type.  A Literal has a
-<code>datatype</code> and <code>lang</code> followed by string data in UTF-8
-encoding.  The length of the string data in bytes is <code>size -
-sizeof(LV2_Atom_Literal)</code>, including the terminating NULL character.  The
-<code>lang</code> field SHOULD be a URI of the form
-&lt;http://lexvo.org/id/iso639-3/LANG&gt; or
-&lt;http://lexvo.org/id/iso639-1/LANG&gt; where LANG is a 3-character ISO 693-3
-language code, or a 2-character ISO 693-1 language code, respectively.</p>
-
-<p>A Literal may have a <code>datatype</code> OR a <code>lang</code>, but never
-both.</p>
-
-<p>For example, a Literal can be "Hello" in English:</p>
-<pre class="c-code">
-void set_to_hello_in_english(LV2_Atom_Literal* lit) {
-     lit->atom.type     = map(expand("atom:Literal"));
-     lit->atom.size     = 14;
-     lit->body.datatype = 0;
-     lit->body.lang     = map("http://lexvo.org/id/iso639-1/en");
-     memcpy(LV2_ATOM_CONTENTS(LV2_Atom_Literal, lit),
-            "Hello",
-            sizeof("Hello"));  // Assumes enough space
-}
-</pre>
-
-<p>or a Turtle string:</p>
-<pre class="c-code">
-void set_to_turtle_string(LV2_Atom_Literal* lit, const char* ttl) {
-     lit->atom.type     = map(expand("atom:Literal"));
-     lit->atom.size     = 64;
-     lit->body.datatype = map("http://www.w3.org/2008/turtle#turtle");
-     lit->body.lang     = 0;
-     memcpy(LV2_ATOM_CONTENTS(LV2_Atom_Literal, lit),
-            ttl,
-            strlen(ttl) + 1);  // Assumes enough space
-}
-</pre>
-""" .
+	rdfs:label "Literal" ;
+	rdfs:comment "A UTF-8 string literal with optional datatype or language." ;
+	atom:cType "LV2_Atom_Literal" .
 
 atom:Path
 	a rdfs:Class ,
 		rdfs:Datatype ;
 	rdfs:subClassOf atom:URI ;
 	owl:onDatatype atom:URI ;
-	rdfs:label "File path string" ;
-	lv2:documentation """
-<p>A local file path.</p>
-
-<p>A Path is a URI reference with only a path component: no scheme, authority,
-query, or fragment.  In particular, paths to files in the same bundle may be
-cleanly written in Turtle files as a relative URI.  However, implementations
-may assume any binary Path (e.g. in an event payload) is a valid file path
-which can passed to system functions like fopen() directly, without any
-character encoding or escape expansion required.</p>
-
-<p>Any implemenation that creates a Path atom to transmit to another is
-responsible for ensuring it is valid.  A Path SHOULD always be absolute, unless
-there is some mechanism in place that defines a base path.  Since this is not
-the case for plugin instances, effectively any Path sent to or received from a
-plugin instance MUST be absolute.</p>
-""" .
+	rdfs:label "Path" ;
+	rdfs:comment "A local file path." .
 
 atom:URI
 	a rdfs:Class ,
 		rdfs:Datatype ;
 	rdfs:subClassOf atom:String ;
 	owl:onDatatype xsd:anyURI ;
-	rdfs:label "URI string" ;
-	lv2:documentation """
-<p>A URI string.  This is useful when a URI is needed but mapping is
-inappropriate, for example with temporary or relative URIs.  Since the ability
-to distinguish URIs from plain strings is often necessary, URIs MUST NOT be
-transmitted as atom:String.</p>
-
-<p>This is not strictly a URI, since UTF-8 is allowed.  Escaping and related
-issues are the host's responsibility.</p>
-""" .
+	rdfs:label "URI" ;
+	rdfs:comment "A URI string." .
 
 atom:URID
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Atom ;
-	rdfs:label "Integer URID" ;
-	atom:cType "LV2_Atom_URID" ;
-	lv2:documentation """
-<p>An unsigned 32-bit integer mapped from a URI (e.g. with LV2_URID_Map).</p>
-""" .
+	rdfs:label "URID" ;
+	rdfs:comment "An unsigned 32-bit integer ID for a URI." ;
+	atom:cType "LV2_Atom_URID" .
 
 atom:Vector
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Atom ;
 	rdfs:label "Vector" ;
-	atom:cType "LV2_Atom_Vector" ;
-	lv2:documentation """
-<p>A homogeneous series of atom bodies with equivalent type and size.</p>
-
-<p>An LV2_Atom_Vector is a 32-bit <code>child_size</code> and
-<code>child_type</code> followed by <code>size / child_size</code> atom
-bodies.</p>
-
-<p>For example, an atom:Vector containing 42 elements of type atom:Float:</p>
-<pre class="c-code">
-struct VectorOf42Floats {
-    uint32_t size;        // sizeof(LV2_Atom_Vector_Body) + (42 * sizeof(float);
-    uint32_t type;        // map(expand("atom:Vector"))
-    uint32_t child_size;  // sizeof(float)
-    uint32_t child_type;  // map(expand("atom:Float"))
-    float    elems[42];
-};
-</pre>
-
-<p>Note that it is possible to construct a valid Atom for each element
-of the vector, even by an implementation which does not understand
-<code>child_type</code>.</p>
-
-<p>If serialised to RDF, a Vector SHOULD have the form:</p>
-
-<pre class="turtle-code">
-eg:someVector
-     a atom:Vector ;
-     atom:childType atom:Int ;
-     rdf:value (
-         "1"^^xsd:int
-         "2"^^xsd:int
-         "3"^^xsd:int
-         "4"^^xsd:int
-     ) .
-</pre>
-""" .
+	rdfs:comment "A homogeneous sequence of atom bodies with equivalent type and size." ;
+	atom:cType "LV2_Atom_Vector" .
 
 atom:Tuple
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Atom ;
 	rdfs:label "Tuple" ;
-	lv2:documentation """
-<p>A series of Atoms with varying <code>type</code> and <code>size</code>.</p>
-
-<p>The body of a Tuple is simply a series of complete atoms, each aligned to
-64 bits.</p>
-
-<p>If serialised to RDF, a Tuple SHOULD have the form:</p>
-
-<pre class="turtle-code">
-eg:someVector
-     a atom:Tuple ;
-     rdf:value (
-         "1"^^xsd:int
-         "3.5"^^xsd:float
-         "etc"
-     ) .
-</pre>
-
-""" .
+	rdfs:comment "A sequence of atoms with varying type and size." .
 
 atom:Property
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Atom ;
 	rdfs:label "Property" ;
-	atom:cType "LV2_Atom_Property" ;
-	lv2:documentation """
-<p>A property of an atom:Object.  An LV2_Atom_Property has a URID
-<code>key</code> and <code>context</code>, and an Atom <code>value</code>.
-This corresponds to an RDF Property, where the <q>key</q> is the <q>predicate</q>
-and the <q>value</q> is the object.</p>
-
-<p>The <code>context</code> field can be used to specify a different context
-for each property, where this is useful.  Otherwise, it may be 0.</p>
-
-<p>Properties generally only exist as part of an atom:Object.  Accordingly,
-they will typically be represented directly as properties in RDF (see
-atom:Object).  If this is not possible, they may be expressed as partial
-reified statements, e.g.:</p>
-
-<pre class="turtle-code">
-eg:someProperty
-    rdf:predicate eg:theKey ;
-    rdf:object eg:theValue .
-</pre>
-""" .
+	rdfs:comment "A property of an atom:Object." ;
+	atom:cType "LV2_Atom_Property" .
 
 atom:Object
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Atom ;
 	rdfs:label "Object" ;
-	atom:cType "LV2_Atom_Object" ;
-	lv2:documentation """
-<p>An <q>Object</q> is an atom with a set of properties.  This corresponds to
-an RDF Resource, and can be thought of as a dictionary with URID keys.</p>
-
-<p>An LV2_Atom_Object body has a uint32_t <code>id</code> and
-<code>type</code>, followed by a series of atom:Property bodies
-(LV2_Atom_Property_Body).  The LV2_Atom_Object_Body::otype field is equivalent
-to a property with key rdf:type, but is included in the structure to allow for
-fast dispatching.</p>
-
-<p>Code SHOULD check for objects using lv2_atom_forge_is_object() or
-lv2_atom_forge_is_blank() if a forge is available, rather than checking the
-atom type directly.  This will correctly handle the deprecated atom:Resource
-and atom:Blank types.</p>
-
-<p>When serialised to RDF, an Object is represented as a resource, e.g.:</p>
-
-<pre class="turtle-code">
-eg:someObject
-    eg:firstPropertyKey "first property value" ;
-    eg:secondPropertyKey "first loser" ;
-    eg:andSoOn "and so on" .
-</pre>
-""" .
+	rdfs:comment "A collection of properties." ;
+	atom:cType "LV2_Atom_Object" .
 
 atom:Resource
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Object ;
 	rdfs:label "Resource" ;
+	rdfs:comment "A named collection of properties with a URI." ;
 	owl:deprecated "true"^^xsd:boolean ;
-	atom:cType "LV2_Atom_Object" ;
-	lv2:documentation """
-<p>This class is deprecated.  Use atom:Object instead.</p>
-
-<p>An atom:Object where the <code>id</code> field is a URID, i.e. an Object
-with a URI.</p>
-""" .
+	atom:cType "LV2_Atom_Object" .
 
 atom:Blank
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Object ;
 	rdfs:label "Blank" ;
+	rdfs:comment "An anonymous collection of properties without a URI." ;
 	owl:deprecated "true"^^xsd:boolean ;
-	atom:cType "LV2_Atom_Object" ;
-	lv2:documentation """
-<p>This class is deprecated.  Use atom:Object with ID 0 instead.</p>
-
-<p>An atom:Object where the LV2_Atom_Object::id is a blank node ID (NOT a URI).
-The ID of a Blank is valid only within the context the Blank appears in.  For
-ports this is the context of the associated run() call, i.e. all ports share
-the same context so outputs can contain IDs that correspond to IDs of blanks in
-the input.</p>
-""" .
+	atom:cType "LV2_Atom_Object" .
 
 atom:Sound
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Vector ;
 	rdfs:label "Sound" ;
-	atom:cType "LV2_Atom_Sound" ;
-	lv2:documentation """
-<p>An atom:Vector of atom:Float which represents an audio waveform.  The format
-is the same as the buffer format for lv2:AudioPort (except the size may be
-arbitrary).  An atom:Sound inherently depends on the sample rate, which is
-assumed to be known from context.  Because of this, directly serialising an
-atom:Sound is probably a bad idea, use a standard format like WAV instead.</p>
-""" .
+	rdfs:comment "A atom:Vector of atom:Float which represents an audio waveform." ;
+	atom:cType "LV2_Atom_Sound" .
 
 atom:frameTime
 	a rdf:Property ,
@@ -450,9 +186,7 @@ atom:frameTime
 		owl:FunctionalProperty ;
 	rdfs:range xsd:decimal ;
 	rdfs:label "frame time" ;
-	lv2:documentation """
-<p>Time stamp in audio frames.  Typically used for events.</p>
-""" .
+	rdfs:comment "A time stamp in audio frames." .
 
 atom:beatTime
 	a rdf:Property ,
@@ -460,66 +194,26 @@ atom:beatTime
 		owl:FunctionalProperty ;
 	rdfs:range xsd:decimal ;
 	rdfs:label "beat time" ;
-	lv2:documentation """
-<p>Time stamp in beats.  Typically used for events.</p>
-""" .
+	rdfs:comment "A time stamp in beats." .
 
 atom:Event
 	a rdfs:Class ;
 	rdfs:label "Event" ;
 	atom:cType "LV2_Atom_Event" ;
-	lv2:documentation """
-<p>An atom with a time stamp prefix, typically an element of an atom:Sequence.
-Note this is not an Atom type.</p>
-""" .
+	rdfs:comment "An atom with a time stamp prefix in a sequence." .
 
 atom:Sequence
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Atom ;
 	rdfs:label "Sequence" ;
 	atom:cType "LV2_Atom_Sequence" ;
-	lv2:documentation """
-<p>A sequence of atom:Event, i.e. a series of time-stamped Atoms.</p>
-
-<p>LV2_Atom_Sequence_Body.unit describes the time unit for the contained atoms.
-If the unit is known from context (e.g. run() stamps are always audio frames),
-this field may be zero.  Otherwise, it SHOULD be either units:frame or
-units:beat, in which case ev.time.frames or ev.time.beats is valid,
-respectively.</p>
-
-<p>If serialised to RDF, a Sequence has a similar form to atom:Vector, but for
-brevity the elements may be assumed to be atom:Event, e.g.:</p>
-
-<pre class="turtle-code">
-eg:someSequence
-    a atom:Sequence ;
-    rdf:value (
-        [
-            atom:frameTime 1 ;
-            rdf:value "901A01"^^midi:MidiEvent
-        ] [
-            atom:frameTime 3 ;
-            rdf:value "902B02"^^midi:MidiEvent
-        ]
-    ) .
-</pre>
-""" .
+	rdfs:comment "A sequence of events." .
 
 atom:AtomPort
 	a rdfs:Class ;
 	rdfs:subClassOf lv2:Port ;
 	rdfs:label "Atom Port" ;
-	lv2:documentation """
-<p>A port which contains an atom:Atom.  Ports of this type are connected to an
-LV2_Atom with a type specified by atom:bufferType.</p>
-
-<p>Output ports with a variably sized type MUST be initialised by the host
-before every run() to an atom:Chunk with size set to the available space.  The
-plugin reads this size to know how much space is available for writing.  In all
-cases, the plugin MUST write a complete atom (including header) to outputs.
-However, to be robust, hosts SHOULD initialise output ports to a safe sentinel
-(e.g. the null Atom) before calling run().</p>
-""" .
+	rdfs:comment "A port which contains an atom:Atom." .
 
 atom:bufferType
 	a rdf:Property ,
@@ -527,78 +221,27 @@ atom:bufferType
 	rdfs:domain atom:AtomPort ;
 	rdfs:range rdfs:Class ;
 	rdfs:label "buffer type" ;
-	lv2:documentation """
-<p>Indicates that an AtomPort may be connected to a certain Atom type.  A port
-MAY support several buffer types.  The host MUST NOT connect a port to an Atom
-with a type not explicitly listed with this property.  The value of this
-property MUST be a sub-class of atom:Atom.  For example, an input port that is
-connected directly to an LV2_Atom_Double value is described like so:</p>
-
-<pre class="turtle-code">
-&lt;plugin&gt;
-    lv2:port [
-        a lv2:InputPort , atom:AtomPort ;
-        atom:bufferType atom:Double ;
-    ] .
-</pre>
-
-<p>This property only describes the types a port may be <em>directly</em>
-connected to.  It says nothing about the expected contents of containers.  For
-that, use atom:supports.</p>
-""" .
+	rdfs:comment "An atom type that a port may be connected to." .
 
 atom:childType
 	a rdf:Property ,
 		owl:ObjectProperty ;
 	rdfs:label "child type" ;
-	rdfs:comment """The type of a container's children.""" .
+	rdfs:comment "The type of children in a container." .
 
 atom:supports
 	a rdf:Property ;
 	rdfs:label "supports" ;
-	rdfs:range rdfs:Class ;
-	lv2:documentation """
-<p>Indicates that a particular Atom type is supported.</p>
-
-<p>This property is defined loosely, it may be used to indicate that anything
-<q>supports</q> an Atom type, wherever that may be useful.  It applies
-<q>recursively</q> where collections are involved.</p>
-
-<p>In particular, this property can be used to describe which event types are
-expected by a port.  For example, a port that receives MIDI events is described
-like so:</p>
-
-<pre class="turtle-code">
-&lt;plugin&gt;
-    lv2:port [
-        a lv2:InputPort , atom:AtomPort ;
-        atom:bufferType atom:Sequence ;
-        atom:supports midi:MidiEvent ;
-    ] .
-</pre>
-""" .
+	rdfs:comment "A supported atom type." ;
+	rdfs:range rdfs:Class .
 
 atom:eventTransfer
 	a ui:PortProtocol ;
 	rdfs:label "event transfer" ;
-	lv2:documentation """
-<p>Transfer of individual events in a port buffer.  Useful as the
-<code>format</code> for a LV2UI_Write_Function.</p>
-
-<p>This protocol applies to ports which contain events, usually in an
-atom:Sequence.  The host must transfer each individual event to the recipient.
-The format of the received data is an LV2_Atom, there is no timestamp
-header.</p>
-""" .
+	rdfs:comment "A port protocol for transferring events." .
 
 atom:atomTransfer
 	a ui:PortProtocol ;
 	rdfs:label "atom transfer" ;
-	lv2:documentation """
-<p>Transfer of the complete atom in a port buffer.  Useful as the
-<code>format</code> for a LV2UI_Write_Function.</p>
-
-<p>This protocol applies to atom ports.  The host must transfer the complete
-atom contained in the port, including header.</p>
-""" .
+	rdfs:comment "A port protocol for transferring atoms." .