From e0c4fb1bc1c66e5655a41ddcbfaafb07e32b93a2 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 26 Nov 2010 20:25:02 +0000 Subject: Mark up documentation with lv2:documentation as per discussion on lv2-dev. Use unified lv2plug.in style for ontology documentation. --- ext/persist.lv2/persist.ttl | 68 ++++++++++++++++++++++----------------------- 1 file changed, 34 insertions(+), 34 deletions(-) (limited to 'ext/persist.lv2') diff --git a/ext/persist.lv2/persist.ttl b/ext/persist.lv2/persist.ttl index 490e2c1..7ec0e0e 100644 --- a/ext/persist.lv2/persist.ttl +++ b/ext/persist.lv2/persist.ttl @@ -42,49 +42,49 @@ foaf:homepage ; rdfs:seeAlso ] ; - rdfs:comment """ -This extension provides a mechanism for plugins to save and restore state + lv2:documentation """ +

This extension provides a mechanism for plugins to save and restore state across instances, allowing hosts to save configuration/state/data with a -project or fully clone a plugin instance (including internal state). +project or fully clone a plugin instance (including internal state).

-Unlike ports, this extension allows plugins to save private state data. +

Unlike ports, this extension allows plugins to save private state data. The motivating ideal behind this extension is for the state of a plugin instance to be entirely described by port values (as with all LV2 plugins) and a key/value dictionary as defined by this extension. This mechanism is simple, -yet sufficiently powerful to describe the state of very advanced plugins. +yet sufficiently powerful to describe the state of very advanced plugins.

-The "state" described by this extension is conceptually a single key/value +

The "state" described by this extension is conceptually a single key/value dictionary. Keys are URIs, and values are typed-tagged blobs of any type. The plugin provides a save and restore method for saving and restoring state. To initiate a save or restore, the host calls these methods, passing a callback -to be used for saving or restoring a single key/value pair. In this way, the -actual mechanism of saving and restoring state is completely abstract from the -plugin's perspective. - -Because the state is a simple dictionary, hosts and plugins can work with state -easily (virtually all programming languages have an appropriate dictionary -type available). Additionally, this format is simple and terse to serialise -in many formats (e.g. any RDF syntax, JSON, XML, key/value databases such as -BDB, etc.). In particular, state can be elegantly described in a plugin's -Turtle description, which is useful for presets (among other things). +to be used for saving or restoring a single key/value pair. In this way, +the actual mechanism of saving and restoring state is completely abstract +from the plugin's perspective.

+ +

Because the state is a simple dictionary, hosts and plugins can work +with state easily (virtually all programming languages have an appropriate +dictionary type available). Additionally, this format is simple and terse to +serialise in many formats (e.g. any RDF syntax, JSON, XML, key/value databases +such as BDB, etc.). In particular, state can be elegantly described in a +plugin's Turtle description, which is useful for presets (among other things). Note that these are all simply possibilities enabled by this simple data model. This extension defines only a few function prototypes and does not impose any requirement to use a particular syntax, data structure, library, or other implementation detail. Hosts are free to work with plugin state -in whatever way is most appropriate for that host. - -This extension makes it possible for plugins to save private data, but state is -not necessarily private, e.g. a plugin could have a public interface via ports -for manipulating internal state, which would be saved using this extension. -Plugins are strongly encouraged to represent all state change as modifications -of such key/value variables, to minimize implementation burden and enable -the many benefits of having a universal model for describing plugin state. -The use of URI keys prevents conflict and allows unrelated plugins to -meaningfully describe state changes. Future extensions will describe a -dynamic mechanism for manipulating plugin state, as well as define various -keys likely to be useful to a wide range of plugins. - -In pseudo code, a typical use case in a plugin is: +in whatever way is most appropriate for that host.

+ +

This extension makes it possible for plugins to save private data, but +state is not necessarily private, e.g. a plugin could have a public interface +via ports for manipulating internal state, which would be saved using this +extension. Plugins are strongly encouraged to represent all state change as +modifications of such key/value variables, to minimize implementation burden +and enable the many benefits of having a universal model for describing +plugin state. The use of URI keys prevents conflict and allows unrelated +plugins to meaningfully describe state changes. Future extensions will +describe a dynamic mechanism for manipulating plugin state, as well as define +various keys likely to be useful to a wide range of plugins.

+ +

In pseudo code, a typical use case in a plugin is:

 static const char* const KEY_GREETING = "http://example.org/greeting";
 
@@ -108,7 +108,7 @@ void my_restore(LV2_Handle                    instance,
 
     size_t      size;
     uint32_t    type;
-    const char* greeting = retrieve(callback_data, KEY_GREETING, &size, &type);
+    const char* greeting = retrieve(callback_data, KEY_GREETING, &size, &type);
 
     if (greeting)
         plugin->state->greeting = greeting;
@@ -118,7 +118,7 @@ void my_restore(LV2_Handle                    instance,
 }
-Similarly, a typical use case in a host is: +

Similarly, a typical use case in a host is:

 void store_callback(void*       callback_data,
                     const char* key,
@@ -134,7 +134,7 @@ Map get_plugin_state(LV2_Handle instance)
 {
     LV2_Persist* persist = instance.extension_data("http://lv2plug.in/ns/ext/persist");
     Map state_map;
-    persist.save(instance, store_callback, &state_map);
+    persist.save(instance, store_callback, &state_map);
     return state_map;
 }
@@ -158,7 +158,7 @@ but its use is not required to support the LV2 Persist extension. persist:instanceState a rdf:Property ; rdfs:range persist:InstanceState ; - rdfs:comment """ + lv2:documentation """ Predicate to relate a plugin instance to an InstanceState. This may be used wherever the state of a particular plugin instance needs to be represented. Note that the domain of this property is unspecified, since LV2 does not -- cgit v1.2.1