Update documentation.

5 files changed, 87 insertions, 81 deletions

diff --git a/lv2/ns/ext/atom/atom.h b/lv2/ns/ext/atom/atom.h
index 39d721c..569ab49 100644
--- a/lv2/ns/ext/atom/atom.h
+++ b/lv2/ns/ext/atom/atom.h
@@ -55,7 +55,7 @@ typedef struct {
 
 /**
    An atom:String.
-   This type may safely be cast to LV2_Atom.
+   May be cast to LV2_Atom.
 */
 typedef struct {
 	uint32_t type;   /**< Type of this atom (mapped URI). */
@@ -65,7 +65,7 @@ typedef struct {
 
 /**
    An atom:Literal.
-   This type may safely be cast to LV2_Atom.
+   May be cast to LV2_Atom.
 */
 typedef struct {
 	uint32_t type;      /**< Type of this atom (mapped URI). */
@@ -77,17 +77,17 @@ typedef struct {
 
 /**
    An atom:URID or atom:BlankID.
-   This type may safely be cast to LV2_Atom.
+   May be cast to LV2_Atom.
 */
 typedef struct {
 	uint32_t type;  /**< Type of this atom (mapped URI). */
 	uint32_t size;  /**< Size in bytes, not including type and size. */
 	uint32_t id;    /**< URID (integer mapped URI) or blank node ID. */
-} LV2_Atom_ID;
+} LV2_Atom_URID;
 
 /**
    An atom:Vector.
-   This type may safely be cast to LV2_Atom.
+   May be cast to LV2_Atom.
 */
 typedef struct {
 	uint32_t type;        /**< Type of this atom (mapped URI). */
@@ -108,7 +108,7 @@ typedef struct _LV2_Atom_Property {
 
 /**
    An atom:Thing (Resource, Blank, or Message).
-   This type may safely be cast to LV2_Atom.
+   May be cast to LV2_Atom.
 */
 typedef struct {
 	uint32_t type;          /**< Type of this atom (mapped URI). */
@@ -130,7 +130,7 @@ typedef struct {
 
 /**
    An atom:Int32, a signed 32-bit integer.
-   This type may safely be cast to LV2_Atom.
+   May be cast to LV2_Atom.
 */
 typedef struct {
 	uint32_t type;
@@ -140,17 +140,17 @@ typedef struct {
 
 /**
    An atom:Int64, a signed 64-bit integer.
-   This type may safely be cast to LV2_Atom.
+   May be cast to LV2_Atom.
 */
 typedef struct {
 	uint32_t type;
 	uint32_t size;
-	int64_t value;
+	int64_t  value;
 } LV2_Atom_Int64;
 
 /**
    An atom:Float, a 32-bit IEEE-754 floating point number.
-   This type may safely be cast to LV2_Atom.
+   May be cast to LV2_Atom.
 */
 typedef struct {
 	uint32_t type;
@@ -160,7 +160,7 @@ typedef struct {
 
 /**
    An atom:Double, a 64-bit IEEE-754 floating point number.
-   This type may safely be cast to LV2_Atom.
+   May be cast to LV2_Atom.
 */
 typedef struct {
 	uint32_t type;
diff --git a/lv2/ns/ext/atom/atom.ttl b/lv2/ns/ext/atom/atom.ttl
index 2556776..c28b610 100644
--- a/lv2/ns/ext/atom/atom.ttl
+++ b/lv2/ns/ext/atom/atom.ttl
@@ -1,5 +1,5 @@
 # LV2 Atom Extension
-# Copyright 2007-2011 David Robillard <d@drobilla.net>
+# Copyright 2007-2012 David Robillard <d@drobilla.net>
 #
 # Permission to use, copy, modify, and/or distribute this software for any
 # purpose with or without fee is hereby granted, provided that the above
@@ -16,11 +16,11 @@
 @prefix atom: <http://lv2plug.in/ns/ext/atom#> .
 @prefix doap: <http://usefulinc.com/ns/doap#> .
 @prefix foaf: <http://xmlns.com/foaf/0.1/> .
-@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
-@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix lv2:  <http://lv2plug.in/ns/lv2core#> .
+@prefix owl:  <http://www.w3.org/2002/07/owl#> .
+@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
 
 <http://lv2plug.in/ns/ext/atom>
 	a lv2:Specification ;
@@ -29,8 +29,8 @@
 	doap:license <http://opensource.org/licenses/isc> ;
 	rdfs:seeAlso <atom-buffer.h> ;
 	doap:release [
-		doap:revision "0.2" ;
-		doap:created "2011-11-05"
+		doap:revision "0.3" ;
+		doap:created "2012-01-28"
 	] ;
 	doap:maintainer [
 		a foaf:Person ;
@@ -137,8 +137,8 @@ sizeof(LV2_Atom_Literal)</code>, including the terminating NULL character.  The
 href="http://www.loc.gov/standards/iso639-2/">ISO 693-2</a> or <a
 href="http://www.loc.gov/standards/iso639-2/">ISO 693-3</a> language code.</p>
 
-<p>For compatibility, a Literal MUST have either a <code>datatype</code>
-or a <code>lang</code>, but never both.</p>
+<p>A Literal may have a <code>datatype</code> OR a <code>lang</code>, but never
+both.</p>
 
 <p>For example, a Literal can be "Hello" in English:</p>
 <pre class="c-code">
diff --git a/lv2/ns/ext/atom/manifest.ttl b/lv2/ns/ext/atom/manifest.ttl
index adb10e5..20c974d 100644
--- a/lv2/ns/ext/atom/manifest.ttl
+++ b/lv2/ns/ext/atom/manifest.ttl
@@ -4,6 +4,6 @@
 <http://lv2plug.in/ns/ext/atom>
 	a lv2:Specification ;
 	lv2:minorVersion 0 ;
-	lv2:microVersion 2 ;
+	lv2:microVersion 3 ;
 	rdfs:seeAlso <atom.ttl> .
 
diff --git a/lv2/ns/ext/state/state.h b/lv2/ns/ext/state/state.h
index bbb8fad..15510e7 100644
--- a/lv2/ns/ext/state/state.h
+++ b/lv2/ns/ext/state/state.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2010-2011 David Robillard <http://drobilla.net>
+  Copyright 2010-2012 David Robillard <http://drobilla.net>
   Copyright 2010 Leonard Ritter <paniq@paniq.org>
 
   Permission to use, copy, modify, and/or distribute this software for any
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