Update documentation.

1 files changed, 65 insertions, 59 deletions

diff --git a/lv2/ns/ext/state/state.ttl b/lv2/ns/ext/state/state.ttl
index 9a31bfb..84cda42 100644
--- a/lv2/ns/ext/state/state.ttl
+++ b/lv2/ns/ext/state/state.ttl
@@ -1,5 +1,5 @@
 # LV2 State Extension
-# Copyright 2010-2011 David Robillard <d@drobilla.net>
+# Copyright 2010-2012 David Robillard <d@drobilla.net>
 # Copyright 2010 Leonard Ritter <paniq@paniq.org>
 #
 # Permission to use, copy, modify, and/or distribute this software for any
@@ -28,7 +28,7 @@
 	doap:license <http://opensource.org/licenses/isc> ;
 	doap:release [
 		doap:revision "0.5" ;
-		doap:created "2011-12-22"
+		doap:created "2012-01-29"
 	] ;
 	doap:developer [
 		a foaf:Person ;
@@ -42,17 +42,17 @@
 		rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
 	] ;
 	lv2:documentation """
-<p>This extension provides a mechanism for plugins to save and restore state
-across instances, allowing hosts to save, restore, clone, or take a snapshot of
-a plugin instance's state at any point in time.  The intention is for a plugin
-instance's state to be <em>completely</em> described by port values (as with all
-LV2 plugins) and a simple dictionary.</p>
+<p>This extension provides a simple mechanism for plugins to save and restore
+state across instances, allowing hosts to save and restore a plugin instance's
+state at any time.  The goal is for an instance's state to be
+<em>completely</em> described by port values (as with all LV2 plugins) and a
+dictionary.</p>
 
 <p>The <q>state</q> described by this extension is conceptually a simple
 key:value dictionary, where keys are URIDs (URIs mapped to integers) and values
 are type-tagged blobs of any type.  A single key:value pair is called a
-<q>property</q>.  The plugin provides an LV2_State_Interface for working with
-this state.  To save or restore, the host calls LV2_State_Interface::save() or
+<q>property</q>.  To implement state, the plugin provides a state:Interface to
+the host.  To save or restore, the host calls LV2_State_Interface::save() or
 LV2_State_Interface::restore(), passing a callback to be used for handling a
 single property.  The host is free to implement property storage and retrieval
 in any way.</p>
@@ -72,19 +72,15 @@ in any way.</p>
   snapshots.</li>
   <li>Easily stored in a typical <q>map</q> or <q>dictionary</q> data
   structure.</li>
-  <li>Keys may be defined by extensions, making state meaningful between
-  implementations and enabling dynamic state control.</li>
+  <li>Keys may be defined by extensions and used by several plugins,
+  making state meaningful enabling dynamic state control.</li>
 </ul>
 
-<p>This extension defines a conceptual state model and a mechanism for saving
-and restoring it, but no interface for manipulating it dynamically.  However,
-any such mechanism SHOULD work with the same properties used in this extension
-to avoid complicating the concept of plugin state.  For example, an extension
-to the example plugin below could be to support a message like
-<code>set(eg:greeting, "Bonjour")</code>, which could be sent by the host, UIs,
-or other plugins (via the host) to dynamically control the plugin's state.
-Accordingly, plugins SHOULD use meaningful and well-defined keys wherever
-possible.</p>
+<p>Implementations or further extensions which work with plugin state
+(including dynamic plugin control) SHOULD work entirely within this model.
+That is, <strong>do not complicate the state model</strong>.  <em>All</em>
+information required to express an instance's state at any given time can, and
+should, be expressed within this model.</p>
 
 <h3>Plugin Code Example</h3>
 
@@ -185,23 +181,17 @@ Map get_plugin_state(LV2_Handle instance)
 
 <h3>Referring to Existing Files</h3>
 
-<p>This extension deliberately avoids imposing any file formats or file system
-dependencies on implementations.  However, some plugins need to refer to
-files in their state.  This is done by storing the file's path as a property
-just like any other value.</p>
-
-<p>Plugins MUST use the type state:Path for all paths in their state.  This
-allows hosts to know about all such files, which is necessary for making
-session export and archival possible (among other things).  Hosts are free to
-map paths in any way, and plugins MUST NOT assume the restored path will be
-identical to the saved path.</p>
+<p>Plugins may need to refer to files (e.g. loaded samples) in their state.
+This is done by storing the file's path as a property just like any other
+value.  However, there are some rules which MUST be followed when storing
+paths, see <a href="#mapPath">state:mapPath</a> for details.</p>
 
 <h3>Creating New Files or Directories</h3>
 
-<p>New implementations and basic plugins are strongly encouraged to simply
-store all state as properties using this API.  However, some plugins have an
-existing file or directory formats for state.  Plugins MAY create new files
-or directories by using the state:newPath feature, if it is provided by the
+<p>Implementations are strongly encouraged to avoid the use of files and simply
+store all state as properties whenever possible.  However, occasionally the
+ability to create files is necessary.  The feature <a
+href="#newPath">state:newPath</a> makes this possible, if it is provided by the
 host.</p>
 """ .
 
@@ -231,12 +221,13 @@ state:State
 	lv2:documentation """
 <p>This class is used to express a plugin instance's state in RDF. The
 key/value properties of the instance form the predicate/object (respectively)
-of triples with a state:State as the subject (see state:state for an
-example). This may be used wherever it is useful to express a plugin instance's
-state in RDF (e.g. for serialisation, storing in a model, or transmitting over
-a network). Note that this class is provided because it may be useful for
-hosts, plugins, or extensions that work with instance state, but its use is not
-required to support the LV2 State extension.</p>
+of triples with a state:State as the subject (see <a
+href="#state">state:state</a> for an example). This may be used wherever it is
+useful to express a plugin instance's state in RDF (e.g. for serialisation,
+storing in a model, or transmitting over a network). Note that this class is
+provided because it may be useful for hosts, plugins, or extensions that work
+with instance state, but its use is not required to support the LV2 State
+extension.</p>
 """ .
 
 state:state
@@ -267,16 +258,15 @@ state:mapPath
 	a lv2:Feature ;
 	rdfs:label "Support for storing paths in files" ;
 	lv2:documentation """
-<p>This feature allows plugins to store paths inside files stored in its state
-(if, for example, a plugin saves to an existing file format which contains
-paths).  To support this feature a host must pass an LV2_Feature with URI
-LV2_STATE_MAP_PATH_URI and data pointed to an LV2_State_Map_Path to the
+
+<p>This feature maps absolute paths to/from <q>abstract paths</q> which are
+stored in state.  To support this feature a host must pass an LV2_Feature with
+URI LV2_STATE_MAP_PATH_URI and data pointed to an LV2_State_Map_Path to the
 plugin's LV2_State_Interface methods.</p>
 
-<p>The plugin MUST use the provided functions to map <em>all</em> paths stored
-in any files it creates (using state:makePath) and stores in the state.  This
-is necessary to enable host to handle file system references correctly, e.g.
-for session export or archival.</p>
+<p>The plugin MUST map <em>all</em> paths stored in its state (including in any
+files in its state).  This is necessary to enable host to handle file system
+references correctly, e.g. for distribution or archival.</p>
 
 <p>For example, a plugin may write a path to a state file like so:</p>
 
@@ -307,21 +297,37 @@ state:makePath
 	rdfs:label "Support for creating new files and directories" ;
 	lv2:documentation """
 
-<p>This feature allows plugins to create new files or directories.  To support
-this feature the host passes an LV2_Feature with URI LV2_STATE_MAKE_PATH_URI
-and data pointed to an LV2_State_Make_Path to the plugin.  The host may provide
-this feature during state saving only or at any time, by passing the feature to
-LV2_State_Interface::save() or LV2_Descriptor::instantiate(), respectively.</p>
+<p>This feature allows plugins to create new files and/or directories.  To
+support this feature the host passes an LV2_Feature with URI
+LV2_STATE_MAKE_PATH_URI and data pointed to an LV2_State_Make_Path to the
+plugin.  The host may make this feature available only during save by passing
+it to LV2_State_Interface::save(), or available any time by passing it to
+LV2_Descriptor::instantiate().  If passed to LV2_State_Interface::save(), the
+feature MUST NOT be used beyond the scope of that call.</p>
+
+<p>The plugin is guaranteed a hierarchial namespace unique to that plugin
+instance, and may expect the returned path to have the requested path as a
+suffix.  There is <em>one</em> such namespace, even if the feature is passed to
+both LV2_Descriptor::instantiate() <em>and</em>
+LV2_State_Interface::save().  Beyond this, the plugin MUST NOT make any
+assumptions about the returned paths.</p>
+
+<p>Like any other paths, the plugin MUST map these paths using <a
+href="#mapPath">state:mapPath</a> before storing them in state.  The plugin
+MUST NOT assume these paths will be available across a save/restore otherwise,
+i.e.  only mapped paths saved to state are persistent, any other created paths
+are temporary.</p>
 
 <p>For example, a plugin may create a file in a subdirectory like so:</p>
 
 <pre class="c-code">
-void save_myfile(LV2_State_Make_Path* make_path)
+char* save_myfile(LV2_State_Make_Path* make_path)
 {
     char* path   = make_path->path(make_path->handle, "foo/bar/myfile.txt");
     FILE* myfile = fopen(path, 'w');
     fprintf(myfile, "Hello");
     fclose(myfile);
+    return path;
 }
 </pre>
 """ .
@@ -332,11 +338,11 @@ state:Path
 	lv2:documentation """
 <p>A path to a file or directory.</p>
 
-<p>The format of a state:Path is a C string escaped or otherwise restricted in
-a system-specific manner.  This URI (LV2_STATE_PATH_URI), mapped to an integer,
-MUST be used as the <code>type</code> parameter for any files passed to the
-LV2_State_Store_Function; and will likewise be returned by the corresponding
-call to the LV2_State_Retrieve_Function.</p>
+<p>The format of a state:Path is a C string, possibly escaped or otherwise
+restricted in a system-specific manner.  This URI (LV2_STATE_PATH_URI), mapped
+to an integer, MUST be used as the <code>type</code> parameter for any files
+passed to the LV2_State_Store_Function; and will likewise be returned by the
+corresponding call to the LV2_State_Retrieve_Function.</p>
 
 <p>When storing and retrieving a path, the plugin MUST NOT assume the same path
 will be restored.  However, the restored path will refer to a file with