Improve documentation.

8 files changed, 88 insertions, 123 deletions

diff --git a/lv2/lv2plug.in/ns/ext/midi/midi.ttl b/lv2/lv2plug.in/ns/ext/midi/midi.ttl
index 3e57437..2cb5415 100644
--- a/lv2/lv2plug.in/ns/ext/midi/midi.ttl
+++ b/lv2/lv2plug.in/ns/ext/midi/midi.ttl
@@ -68,8 +68,8 @@
 		]
 	] ;
 	lv2:documentation """
-<p>This extension defines a data type for a MIDI message, midi:MidiEvent, which
-is normalised for fast and convenient real-time processing.  MIDI is the
+<p>This specification defines a data type for a MIDI message, midi:MidiEvent,
+which is normalised for fast and convenient real-time processing.  MIDI is the
 <q>Musical Instrument Digital Interface</q>, a ubiquitous binary standard for
 controlling digital music devices.</p>
 
@@ -79,12 +79,10 @@ an integer and used as the type of an LV2 <a
 href="http://lv2plug.in/ns/ext/atom#Atom">Atom</a> or <a
 href="http://lv2plug.in/ns/ext/event#Event">Event</a>.</p>
 
-<p>This specification also defines a complete machine readable description of
-the MIDI standard (except for standard controller numbers).  These descriptions
-are detailed enough to express any MIDI message in RDF.  Message types are
-described down to the byte level, so all the information required to convert
-between binary MIDI and RDF MIDI is present.  This specification thus serves as
-both a human and machine readable description of the MIDI specification.</p>
+<p>This specification also defines a complete human and machine readable
+description of the MIDI standard (except for standard controller numbers).
+These descriptions are detailed enough to express any MIDI message as
+properties.</p>
 """ .
 
 midi:ActiveSense
diff --git a/lv2/lv2plug.in/ns/ext/parameters/parameters.ttl b/lv2/lv2plug.in/ns/ext/parameters/parameters.ttl
index d42c2f9..9642c32 100644
--- a/lv2/lv2plug.in/ns/ext/parameters/parameters.ttl
+++ b/lv2/lv2plug.in/ns/ext/parameters/parameters.ttl
@@ -20,10 +20,11 @@
 	doap:maintainer <http://drobilla.net/drobilla#me> ;
 	doap:developer <http://lv2plug.in/ns/meta#larsl> ;
 	lv2:documentation """
-<p>This extension defines parameters common in audio processing software.  A
+<p>This vocabulary describes parameters common in audio processing software.  A
 <q>parameter</q> is purely a metadata concept, unrelated to any particular code
-mechanism.  Parameters are used to assign meaning to controls so they can be
-used more intelligently or presented to the user more efficiently.</p>
+mechanism.  Parameters are used to assign meaning to controls (e.g. using <a
+href="http://lv2plug.in/ns/lv2core#designation">lv2:designation</a>) so they
+can be used more intelligently or presented to the user more efficiently.</p>
 """ .
 
 param:ControlGroup
diff --git a/lv2/lv2plug.in/ns/ext/patch/patch.ttl b/lv2/lv2plug.in/ns/ext/patch/patch.ttl
index b5f5df2..8db1dae 100644
--- a/lv2/lv2plug.in/ns/ext/patch/patch.ttl
+++ b/lv2/lv2plug.in/ns/ext/patch/patch.ttl
@@ -21,40 +21,35 @@
 	] ;
 	doap:shortdesc "Messages for accessing and manipulating properties." ;
 	lv2:documentation """
-<p>This extension defines messages which can be used to access and manipulate
-property-based data.  It is designed to provide a powerful dynamic control
-interface for LV2 plugins, but is useful for RDF-like systems in general.</p>
-
-<p>The main feature of this design is that requests and responses are
-themselves completely described in RDF.  Thus, the complete <q>protocol</q> can
-be expressed wherever RDF can without imposing additional implementation
-burdens like a new syntax or binary formats.  In particular, messages can be
-serialised in Turtle, or as an <a
-href="http://lv2plug.in/ns/ext/atom#Object">LV2 Object</a>.</p>
-
-<p>This set of patch types is deliberately small to avoid an explosion of
-messages that all implementations would have to explicitly support.  Instead,
-the idea is to achieve control via manipulating properties rather than defining
-custom commands.  However, this is conceptual; there is no requirement that the
-receiver actually implement a store of resources with properties.</p>
+<p>This vocabulary defines messages which can be used to access and manipulate
+properties.  It is designed to provide a dynamic control interface for LV2
+plugins, but is useful in many contexts.</p>
+
+<p>The main feature of this design is that the messages themselves are
+described in the same format as the data they work with.  In particular,
+messages can be serialised as an <a
+href="http://lv2plug.in/ns/ext/atom#Object">LV2 Object</a> or in Turtle (or any
+other RDF serialisation).</p>
+
+<p>The idea behind using a property-based interface for control is to prevent
+an an explosion of message types.  Instead of a custom message for each action,
+control is achieved via manipulating properties (which are likely already
+defined for other reasons).  Note, however, that this is purely conceptual;
+there is no requirement that the receiver actually implement a store of
+resources with properties.</p>
 
 <p>For example, consider an object that can blink.  Rather than define a
 specific interface to control this (e.g. <code>obj.start_blinking();
-obj.stop_blinking()</code>), set a <q>blinking</q> property to true or false to
-achieve the desired behaviour.  One benefit of this approach is that a
-persistent state model is available <q>for free</q>: simply serialise the
-<q>blinking</q> property.</p>
-
-<p>Because changes are described in terms of properties, important
-functionality like undo stacks or revision control are simple to implement
-generically.  Accordingly, plugins are strongly encouraged to use these
-property-based messages rather than defining custom methods for every action
-they require (or worse, defining entirely new formats for messages).</p>
-
-<p>These methods are deliberately very similar to HTTP methods, but defined
-specifically for property-based resources.  The <q>properties</q> used here are
-RDF properties, thus predicates from any of the countless pre-existing
-vocabularies may be used.</p>
+obj.stop_blinking()</code>), set a <q>blinking</q> property to true or false
+(e.g. <code>obj.set(blinking, true)</code>) to achieve the desired behaviour.
+One benefit of this approach is that a persistent state model is available
+<q>for free</q>: simply serialise the <q>blinking</q> property.</p>
+
+<p>This specification is strictly metadata and does not define any binary
+mechanism, though it can be completely expressed by standard types in the <a
+href="http://lv2plug.in/ns/ext/atom">LV2 Atom</a> extension.  Thus, hosts can
+be expected to be capable of transmitting it between plugins, or between a
+plugin and its UI, making it a good choice for advanced plugin control.</p>
 """ .
 
 patch:Ack
@@ -141,7 +136,7 @@ patch:Insert
 	rdfs:label "Insert" ;
 	rdfs:subClassOf [
 		a owl:Restriction ;
-		owl:maxCardinality 1 ;
+		owl:cardinality 1 ;
 		owl:onProperty patch:subject
 	] ;
 	lv2:documentation """
@@ -161,7 +156,7 @@ patch:Move
 	rdfs:label "Move" ;
 	rdfs:subClassOf [
 		a owl:Restriction ;
-		owl:maxCardinality 1 ;
+		owl:cardinality 1 ;
 		owl:onProperty patch:subject
 	] , [
 		a owl:Restriction ;
@@ -182,14 +177,6 @@ patch:Patch
 		a owl:Restriction ;
 		owl:minCardinality 1 ;
 		owl:onProperty patch:subject
-	] , [
-		a owl:Restriction ;
-		owl:maxCardinality 1 ;
-		owl:onProperty patch:add
-	] , [
-		a owl:Restriction ;
-		owl:maxCardinality 1 ;
-		owl:onProperty patch:remove
 	] ;
 	lv2:documentation """
 <p>A method for modifying the properties of an object.</p>
@@ -221,7 +208,7 @@ patch:Put
 	rdfs:label "Put" ;
 	rdfs:subClassOf [
 		a owl:Restriction ;
-		owl:maxCardinality 1 ;
+		owl:cardinality 1 ;
 		owl:onProperty patch:subject
 	] ;
 	lv2:documentation """
diff --git a/lv2/lv2plug.in/ns/ext/port-groups/port-groups.ttl b/lv2/lv2plug.in/ns/ext/port-groups/port-groups.ttl
index 01687f6..f9f9700 100644
--- a/lv2/lv2plug.in/ns/ext/port-groups/port-groups.ttl
+++ b/lv2/lv2plug.in/ns/ext/port-groups/port-groups.ttl
@@ -34,12 +34,11 @@ on a plugin with a single identifier and no context.
 """
 	] ;
 	rdfs:comment """
-A grouping of ports (or any other means of signal transmission) that should
-logically be considered a single "stream", e.g. two audio ports in a group may
-form a stereo stream.  In order to avoid the need to define large numbers of
-identical group definitions, a group definition may be shared.  For example, a
-plugin collection may define a single URI for a pg:StereoGroup with the symbol
-"input" and use it in many plugins.
+A set of ports/channels/controls/etc that are are logically grouped together,
+e.g. two audio ports in a group may form a stereo stream.  In order to avoid
+the need to define large numbers of identical group definitions, a group
+definition may be shared.  For example, a plugin collection may define a single
+URI for a pg:StereoGroup with the symbol "input" and use it in many plugins.
 """ .
 
 pg:InputGroup
@@ -60,11 +59,6 @@ pg:Element
 	rdfs:comment "An ordered element of a group." ;
 	rdfs:subClassOf [
 		a owl:Restriction ;
-		owl:onProperty lv2:index ;
-		owl:maxCardinality 1 ;
-		rdfs:comment "An element has at most one lv2:index."
-	] , [
-		a owl:Restriction ;
 		owl:onProperty lv2:designation ;
 		owl:cardinality 1 ;
 		rdfs:comment "An element MUST have exactly one lv2:designation."
@@ -106,7 +100,7 @@ Indicates that this group is a child of another group.  This property has no
 meaning with respect to plugin execution, but the host may find this
 information useful (e.g. to provide a compact user interface).  Note that being
 a sub-group does not relax the restriction that the group MUST have a unique
-symbol.
+symbol with respect to the plugin.
 """ .
 
 pg:source
diff --git a/lv2/lv2plug.in/ns/ext/port-props/port-props.ttl b/lv2/lv2plug.in/ns/ext/port-props/port-props.ttl
index 8111821..00b5ff3 100644
--- a/lv2/lv2plug.in/ns/ext/port-props/port-props.ttl
+++ b/lv2/lv2plug.in/ns/ext/port-props/port-props.ttl
@@ -19,7 +19,7 @@
 	doap:maintainer <http://drobilla.net/drobilla#me> ;
 	doap:developer <http://lv2plug.in/ns/meta#kfoltman> ;
 	lv2:documentation """
-<p>This extension defines various properties for plugin ports, which can be
+<p>This vocabulary defines various properties for plugin ports, which can be
 used to better describe how a plugin can be controlled.  Using this metadata,
 hosts can build better UIs for plugins, and provide more advanced automatic
 functionality.</p>
diff --git a/lv2/lv2plug.in/ns/ext/presets/presets.ttl b/lv2/lv2plug.in/ns/ext/presets/presets.ttl
index 24dafc9..756590f 100644
--- a/lv2/lv2plug.in/ns/ext/presets/presets.ttl
+++ b/lv2/lv2plug.in/ns/ext/presets/presets.ttl
@@ -51,26 +51,10 @@
 		]
 	] ;
 	lv2:documentation """
-<p>This extension describes a format for presets (i.e. named sets of control
+<p>This vocabulary describes a format for presets (i.e. named sets of control
 values and possibly other state) for LV2 plugins.  The structure of a
 pset:Preset is deliberately identical to that of an lv2:Plugin, and can be
-thought of as a plugin template or overlay.  For example:</p>
-
-<pre class="turtle-code">
-@prefix eg: &lt;http://example.org/&gt; .
-
-eg:mypreset
-    a pset:Preset ;
-    rdfs:label "One louder" ;
-    lv2:appliesTo eg:myplugin ;
-    lv2:port [
-        lv2:symbol "volume1" ;
-        pset:value 11.0
-    ] , [
-        lv2:symbol "volume2" ;
-        pset:value 11.0
-    ] .
-</pre>
+thought of as a plugin template or overlay.</p>
 
 <p>Presets may be defined in any bundle, including the plugin's bundle,
 separate third party preset bundles, or user preset bundles saved by hosts.
@@ -97,12 +81,25 @@ pset:Preset
 		rdfs:comment "A Preset MUST have at least one string rdfs:label."
 	] ;
 	lv2:documentation """
-<p>A Preset for an LV2 Plugin.  A preset can be considered an "overlay" on a
-Plugin.  Rather than attempting to define all valid predicates for a Preset
-(which is not possible since presets may need to specify values for things
-defined in other extensions), the presets extension simply provides this class
-which can be augmented with any data in the exact same fashion as the
-definition of a Plugin.</p>
+<p>A Preset for an LV2 Plugin.  The structure of a Preset deliberately mirrors that
+of a plugin, so existing predicates can be used to describe any data associated with
+the preset.  For example:</p>
+
+<pre class="turtle-code">
+@prefix eg: &lt;http://example.org/&gt; .
+
+eg:mypreset
+    a pset:Preset ;
+    rdfs:label "One louder" ;
+    lv2:appliesTo eg:myplugin ;
+    lv2:port [
+        lv2:symbol "volume1" ;
+        pset:value 11.0
+    ] , [
+        lv2:symbol "volume2" ;
+        pset:value 11.0
+    ] .
+</pre>
 
 <p>A Preset SHOULD have at least one lv2:appliesTo property.  Each Port on a
 Preset MUST have at least a lv2:symbol property and a pset:value property.</p>
diff --git a/lv2/lv2plug.in/ns/extensions/ui/ui.ttl b/lv2/lv2plug.in/ns/extensions/ui/ui.ttl
index 3aa48ee..32934d6 100644
--- a/lv2/lv2plug.in/ns/extensions/ui/ui.ttl
+++ b/lv2/lv2plug.in/ns/extensions/ui/ui.ttl
@@ -44,20 +44,15 @@ the original plugin bundle.</p>
 <p>Note that the process that loads the shared object file containing the UI
 code and the process that loads the shared object file containing the actual
 plugin implementation are not necessarily the same process (and not even
-necessarily on the same machine).  This means that plugin and UI code can
-<strong>not</strong> use singletons and global variables and expect them to
-refer to the same objects in the UI and the actual plugin. The function
-callback interface defined in this header is the only method of communication
-between UIs and plugin instances (extensions may define more, though this is
-discouraged unless absolutely necessary since the significant benefits of
-network transparency and serialisability are lost).</p>
-
-<p>Since the LV2 specification itself allows for extensions that may add new
-functionality that could be useful to control with a UI, this extension allows
-for meta-extensions that can extend the interface between the UI and the
-host. These extensions mirror the extensions used for plugins - there are
-required and optional "features" that you declare in the RDF data for the
-UI:</p>
+necessarily on the same machine).  This means that plugin and UI code MUST NOT
+use singletons and global variables and expect them to refer to the same
+objects in the UI and the actual plugin. The function callback interface
+defined in this header is the only method of communication between UIs and
+plugin instances (extensions may define more, though this is discouraged unless
+absolutely necessary since the significant benefits of network transparency and
+serialisability are lost).</p>
+
+<p>UI functionality may be extended via features, much like plugins:</p>
 
 <pre class="turtle-code">
 &lt;http://my.pluginui&gt; lv2:requiredFeature &lt;http://my.feature&gt; .
@@ -68,24 +63,17 @@ UI:</p>
 those of lv2:Plugin instances: if a UI declares a feature as required, the host
 is NOT allowed to load it unless it supports that feature; and if it does
 support a feature, it MUST pass an appropriate LV2_Feature struct to the UI's
-instantiate() method.  These features may be used to specify how to pass
-specific types of data between the UI and the plugin port buffers (see
-LV2UI_Write_Function for details).</p>
-
-<p>UIs written to this specification do not need to be threadsafe - the
-functions defined below may only be called in the same thread the UI main loop
-is running in.</p>
-
-<p>Note that this UI extension is NOT a lv2:Feature. There is no way for a
-plugin to know whether the host that loads it supports UIs or not, and the
-plugin must always work without the UI (although it may be rather useless
-unless it has been configured using the UI in a previous session).  From the
-plugin perspective, control from a UI is the same as control from anywhere else
-(e.g. the host, the user): via ports.</p>
-
-<p>A UI does not have to be a graphical widget, it could just as well be a
-server listening for OSC input or an interface to some sort of hardware device,
-depending on the RDF class of the UI.</p>
+instantiate() method.  This extension defines several standard features for
+common functionality.</p>
+
+<p>UIs written to this specification do not need to be thread-safe.  All
+functions may only be called in the <q>UI thread</q>.  There is only one UI
+thread (for toolkits, the one the UI main loop runs in).  There is no
+requirement that a <q>UI</q> actually be a graphical widget.</p>
+
+<p>Note that UIs are completely separate from plugins.  From the plugin's
+perspective, control from a UI is indistinguishable from any other control, as
+it all occcurs via ports.</p>
 """ .
 
 ui:UI
diff --git a/lv2/lv2plug.in/ns/extensions/units/units.ttl b/lv2/lv2plug.in/ns/extensions/units/units.ttl
index d55ebc6..4b058c4 100644
--- a/lv2/lv2plug.in/ns/extensions/units/units.ttl
+++ b/lv2/lv2plug.in/ns/extensions/units/units.ttl
@@ -9,7 +9,7 @@
 	a owl:Ontology ;
 	owl:imports <http://lv2plug.in/ns/lv2core> ;
 	lv2:documentation """
-<p>This extension defines a number of units for use in audio processing.</p>
+<p>This vocabulary defines a number of units for use in audio processing.</p>
 
 <p>For example, to say that a gain port's value is in decibels (units:db)</p>
 <pre class="turtle-code">