Improve documentation.

1 files changed, 35 insertions, 37 deletions

diff --git a/ext/persist.lv2/persist.ttl b/ext/persist.lv2/persist.ttl
index 7ec0e0e..64e217e 100644
--- a/ext/persist.lv2/persist.ttl
+++ b/ext/persist.lv2/persist.ttl
@@ -45,44 +45,42 @@
 	lv2:documentation """
 <p>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).</p>
-
-<p>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.</p>
-
-<p>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.</p>
-
-<p>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
+project or fully clone (i.e. make a deep copy of) a plugin instance.</p>
+
+<p>This extension allows plugins to save private state data, i.e. data that is
+not contained in input ports. The motivating ideal is for the state of a plugin
+instance to be <em>entirely</em> 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 arbitrarily advanced
+state.</p>
+
+<p>The <q>state</q> 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 key/value pair. This data is available
+to the host, allowing state to be easily used in many different way. The
+actual mechanism of saving and restoring state is completely abstract from the
+plugin's perspective.</p>
+
+<p>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.</p>
-
-<p>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.</p>
+such as BDB, etc.). In particular, state can be elegantly described in a
+plugin's Turtle description, which is useful for e.g. presets or default
+state. Note that these are simply possibilities; this extension defines only a
+few function prototypes and does not require the use of any particular syntax,
+data structure, file system, or other implementation detail. Hosts are free to
+work with plugin state in whatever way is most appropriate for that host.</p>
+
+<p>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 for
+inspecting and manipulating internal state, which would be saved using this
+extension. Plugins and extensions SHOULD express state changes as modifications
+to this key/value dictionary, and use meaningful types wherever
+possible. Extensions may define a dynamic mechanism for accessing plugin state,
+or conventional state keys likely to be useful to several implementations.</p>
 
 <p>In pseudo code, a typical use case in a plugin is:</p>
 <pre>