aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/lv2plug.in/ns/ext
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2012-04-16 22:46:02 +0000
committerDavid Robillard <d@drobilla.net>2012-04-16 22:46:02 +0000
commita2871d7ad8553dcc2d4a232d5103dcf234477e5a (patch)
tree2e91248756f0db763e8fa84029c13958b4bb5bbf /lv2/lv2plug.in/ns/ext
parentaeebfa8cf21973833f9bd4a6191f2e95dbf87109 (diff)
downloadlv2-a2871d7ad8553dcc2d4a232d5103dcf234477e5a.tar.xz
Improve documentation.
Diffstat (limited to 'lv2/lv2plug.in/ns/ext')
-rw-r--r--lv2/lv2plug.in/ns/ext/midi/midi.ttl14
-rw-r--r--lv2/lv2plug.in/ns/ext/parameters/parameters.ttl7
-rw-r--r--lv2/lv2plug.in/ns/ext/patch/patch.ttl71
-rw-r--r--lv2/lv2plug.in/ns/ext/port-groups/port-groups.ttl18
-rw-r--r--lv2/lv2plug.in/ns/ext/port-props/port-props.ttl2
-rw-r--r--lv2/lv2plug.in/ns/ext/presets/presets.ttl45
6 files changed, 67 insertions, 90 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>