diff options
authorDavid Robillard <d@drobilla.net>2012-02-19 03:05:47 +0000
committerDavid Robillard <d@drobilla.net>2012-02-19 03:05:47 +0000
commitb8e06a4495b2d39a8a82ec9647d7a87916caca56 (patch)
parenta085d55c5b45ebfa126511aaec0aa307b0893e53 (diff)
Improve atom introduction.
1 files changed, 8 insertions, 9 deletions
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
index 2e82e32..c3249ec 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
@@ -42,24 +42,23 @@
lv2:documentation """
<p>This extension defines a generic container for data, called an <q>Atom</q>,
and several basic Atom types which can be used to express structured data.
-Atoms allow LV2 plugins and hosts to communicate, process, serialise, and store
-values of any type via a generic mechanism (e.g. ports, files, networks,
-ringbuffers, etc.). Atoms are, with one exception, Plain Old Data (POD) which
-may safely be copied (e.g. with a simple call to <code>memcpy</code>).</p>
+Atoms are (with one exception) Plain Old Data (POD), which means they can be
+easily copied generically (e.g. using <code>memcpy</code>), and are suitable
+for use in high-performance and real-time code.</p>
<p>Since Atom communication can be implemented generically, plugins that
understand some type can be used together in a host that does not understand
-that type, and plugins (e.g. routers, delays) can process atoms of unknown
+that type. Similarly, plugins (such as routers, delays, or data stores) 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. This extension defines port types, atom:ValuePort and
-atom:MessagePort, which are connected to an Atom. The atom:Sequence type in
-conjunction with atom:MessagePort is intended to replace the <a
+atom:MessagePort, which contain Atoms. The atom:Sequence type in conjunction
+with atom:MessagePort is intended to replace the <a
href="http://lv2plug.in/ns/ext/event">LV2 event</a> extension.</p>
<p>The types defined in this extension should be powerful enough to express
-almost any structure. Implementers SHOULD build structures out of the types
+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