From a2871d7ad8553dcc2d4a232d5103dcf234477e5a Mon Sep 17 00:00:00 2001 From: David Robillard <d@drobilla.net> Date: Mon, 16 Apr 2012 22:46:02 +0000 Subject: Improve documentation. --- lv2/lv2plug.in/ns/ext/midi/midi.ttl | 14 ++--- lv2/lv2plug.in/ns/ext/parameters/parameters.ttl | 7 ++- lv2/lv2plug.in/ns/ext/patch/patch.ttl | 71 +++++++++-------------- lv2/lv2plug.in/ns/ext/port-groups/port-groups.ttl | 18 ++---- lv2/lv2plug.in/ns/ext/port-props/port-props.ttl | 2 +- lv2/lv2plug.in/ns/ext/presets/presets.ttl | 45 +++++++------- 6 files changed, 67 insertions(+), 90 deletions(-) (limited to 'lv2/lv2plug.in/ns/ext') 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 @@ -59,11 +58,6 @@ pg:Element rdfs:label "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 ; @@ -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: <http://example.org/> . - -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: <http://example.org/> . + +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> -- cgit v1.2.1