diff options
authorDavid Robillard <d@drobilla.net>2013-01-27 21:18:10 +0000
committerDavid Robillard <d@drobilla.net>2013-01-27 21:18:10 +0000
commit21d16ed2e53601f8a26f378b3274a207a9426b12 (patch)
parent322105561fa73239fae9d1f4215b250682a02564 (diff)
Improve atom documentation.
2 files changed, 47 insertions, 35 deletions
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
index 725d9ff..c222ebf 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
@@ -14,43 +14,53 @@
<forge.h> ,
<lv2-atom.doap.ttl> ;
lv2:documentation """
-<p>This specification defines a generic container for data, called an
-<q>Atom</q>, and several basic Atom types which can be used to express
-structured data. An atom:Atom is (with one exception) Plain Old Data (POD),
-which means it can be copied generically (e.g. using a simple
-<code>memcpy</code>), and is suitable for use in real-time code.</p>
-<p>The purpose of Atoms is to allow implementations that process and/or
-transmit data to be independent of that data's type. For example, plugins that
-mutually understand a type can be used together in a host that does not
-understand that type, because the host's required facilities are generic.
-Similarly, plugins (such as routers, delays, or data structures) can
-meaningfully process atoms of a type unknown to them.</p>
+<p>This specification defines a simple generic data container, called an
+<q>Atom</q>. An atom:Atom can contain simple primitive types like integers,
+floating point numbers, and strings; as well as structured data like lists and
+dictionary-like <q>Objects</q>. An Atom is, with one exception, Plain Old Data
+(POD), meaning it can be easily copied (e.g. using <code>memcpy</code>) and is
+suitable for use in real-time code.</p>
+<p>Atoms are not limited to the types defined here, but allow implementations
+to work with any type of POD data at all. This is possible because Atom types
+are URIs, but mapped to integers using the <a href="../urid/urid.html">LV2
+URID</a> extension for performance reasons.</p>
+<p>Since atoms are simple to copy,
+communication of any atom is simple to implement without requiring special code
+for every type of data. For example, plugins that mutually understand a type
+can be used together in a host that does not understand that type, because the
+host is only required to copy atoms, not interpret their contents. Similarly,
+plugins (such as routers, delays, or data structures) can meaningfully process
+atoms of a type unknown to them.</p>
<p>Atoms can and should be used anywhere values of various types must be stored
or transmitted. The port type atom:AtomPort can be used to transmit atoms via
-ports. The atom:Sequence type in an atom:AtomPort replaces the <a
+ports. An atom:AtomPort that contains an atom:Sequence can be used for sample
+accurate event communication, such as MIDI, and replaces the earlier <a
href="../event/event.html">LV2 event</a> extension.</p>
-<p>The types defined in this extension should be powerful enough to express
-almost any structure. Implementations SHOULD build structures out of the types
-provided here, rather than define new binary formats (e.g. use atom:Object
-rather than a new C <code>struct</code> type). New binary formats are an
-implementation burden which harms interoperabilty, and should only be defined
-where absolutely necessary.</p>
-<p>Implementing this extension requires a facility for mapping URIs to
-integers, such as the <a href="../urid/urid.html">LV2 URID</a> extension.</p>
-<p>An Atom type primarily defines a binary format (i.e. a C data type) for use
-at runtime. However, each Atom type also has a standard serialisation format
-which SHOULD be used wherever an atom needs to be expressed as a string or in
-Turtle. Thus, this specification not only defines binary data types for
-plugins to use, but a complete data model with a portable RDF-compatible
-serialisation. This is useful for inter-process communication as well as
-saving state.</p>
+<p>Each Atom type defines a binary format for use at runtime, but also a
+serialisation that is natural to express in Turtle format. Thus, this
+specification defines a powerful real-time appropriate data model, as well as a
+portable way to serialise any data in that model. This is particularly useful
+for inter-process communication, saving/restoring state, and describing values
+in plugin data files.</p>
+<h3>Custom Atom Types</h3>
+<p>While it is possible to define new Atom types for any binary format, the
+standard types defined here are powerful enough to describe almost anything.
+Implementations SHOULD build structures out of the types provided here, rather
+than define new binary formats (e.g. use atom:Tuple or atom:Object rather than
+a new C <code>struct</code> type). Current implementations have support for
+serialising all standard types, so new binary formats are an implementation
+burden which harms interoperabilty. In particular, plugins SHOULD NOT expect
+UI communication or state saving with custom Atom types to work. In general,
+new Atom types should only be defined where absolutely necessary due to
+performance reasons and serialisation is not a concern.</p>
""" .
@@ -239,11 +249,11 @@ atom:Path
<p>A local file path.</p>
<p>A Path is a URI reference with only a path component: no scheme, authority,
-query, or fragment. Thus, paths to files in the same bundle may be cleanly
-written in Turtle files as a relative URI. However, implementations may assume
-any binary Path (e.g. in an event payload) is a valid file path which can
-passed to system functions like fopen() directly, without any character
-encoding or escape expansion required.</p>
+query, or fragment. In particular, paths to files in the same bundle may be
+cleanly written in Turtle files as a relative URI. However, implementations
+may assume any binary Path (e.g. in an event payload) is a valid file path
+which can passed to system functions like fopen() directly, without any
+character encoding or escape expansion required.</p>
<p>Any implemenation that creates a Path atom to transmit to another is
responsible for ensuring it is valid. A Path SHOULD always be absolute, unless
diff --git a/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl b/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl
index ca33803..db52e54 100644
--- a/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl
@@ -19,6 +19,8 @@
rdfs:label "Fix lv2_atom_sequence_end()."
] , [
rdfs:label "Remove atom:stringType in favour of owl:onDatatype so generic tools can understand and validate atom literals."
+ ] , [
+ rdfs:label "Improve atom documentation."
] , [