Mark up documentation with lv2:documentation as per discussion on lv2-dev.

Use unified lv2plug.in style for ontology documentation.

1 files changed, 52 insertions, 56 deletions

diff --git a/core.lv2/lv2.ttl b/core.lv2/lv2.ttl
index c3abdbf..68c8891 100644
--- a/core.lv2/lv2.ttl
+++ b/core.lv2/lv2.ttl
@@ -1,5 +1,5 @@
 # RDF Schema for LV2 plugins
-# PROVISIONAL Revision 4
+# PROVISIONAL Revision 4.0pre1
 #
 # This document describes the classes and properties that are defined by the
 # core LV2 specification.  See <http://lv2plug.in> for more information.
@@ -70,8 +70,8 @@ more details.
     doap:shortdesc "An audio plugin interface specification" ;
     doap:programming-language "C" ;
     doap:release [
-        doap:revision "4" ;
-        doap:created "2009-08-16"
+        doap:revision "4.0pre2" ;
+        doap:created "2010-11-05"
     ] ;
     doap:maintainer [
         a foaf:Person ;
@@ -83,27 +83,29 @@ more details.
         foaf:name "David Robillard" ;
         foaf:homepage <http://drobilla.net/> ;
         rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
-    ] ; rdfs:comment """
+    ] ;
+    lv2:documentation """
 <h4>Overview</h4>
+<p>
 There are a large number of open source and free software synthesis packages in
 use or development at this time. This API ("LV2") attempts to give programmers
 the ability to write simple "plugin" audio processors in C/C++ and link
 them dynamically ("plug" them) into a range of these packages ("hosts").
 It should be possible for any host and any plugin to communicate completely
 through this interface.
-
+</p><p>
 This API is deliberately as short and simple as possible.  The information
 required to use a plugin is in a companion data (RDF) file.  The shared
 library portion of the API does not contain enough information to make use
 of the plugin possible; the data file is mandatory.
-
+</p><p>
 Plugins can operate on any type of data.  Plugins have "ports" that are
 inputs or outputs and each plugin is "run" for a "block" corresponding to
 a short time interval measured in samples.  The plugin may assume that all
 its input and output ports have been connected to the relevant data location
 (using the connect_port() function) before it is asked to run, unless the
 port has been set "connection optional" in the plugin's data file.
-
+</p><p>
 This "core" specification defines two types of port data, equivalent to those
 in LADSPA: control rate and audio rate.  Audio rate data is communicated using
 arrays with one <code>float</code> element per sample processed, allowing
@@ -112,20 +114,22 @@ rate data is communicated using single <code>float</code> values. Control
 rate data has a single value at the start of a call to the run() function
 which is considered valid for the duration of the call to run().  Thus the
 "control rate" is determined by the block size, controlled by the host.
-
+</p><p>
 Plugins reside in shared object files suitable for dynamic linking (e.g. by
-dlopen() and family). This file provides one or many plugins via the
+dlopen() and family). This object provides one or more <a
+href="urn:struct:LV2_Descriptor">plugin descriptors</a> via the
 lv2_descriptor() function.  These plugins can be instantiated to create
 "plugin instances", which can be connected together to perform tasks.
-
+</p><p>
 This API contains very limited error-handling.
-
-<h4>Threading Rules</h4> Certain hosts may need to call the functions
+</p>
+<h4>Threading Rules</h4>
+<p>Certain hosts may need to call the functions
 provided by a plugin from multiple threads. For this to be safe, the plugin
 must be written so that those functions can be executed simultaneously
 without problems.  To facilitate this, the functions provided by a plugin
 are divided into classes:
-
+</p>
 <dl>
 <dt>Discovery Class</dt>
 <dd>lv2_descriptor(), extension_data()</dd>
@@ -134,11 +138,11 @@ are divided into classes:
 <dt>Audio Class</dt>
 <dd>run(), connect_port()</dd>
 </dl>
-
+<p>
 Extensions to this specification which add new functions MUST declare in
 which of these classes the functions belong, or define new classes for them.
 The rules that hosts MUST follow are:
-
+</p>
 <ul>
 <li>When a function is running for a plugin instance, no other
    function in the same class may run for that instance.</li>
@@ -147,9 +151,10 @@ The rules that hosts MUST follow are:
 <li>When a function from the Instantiation class is running for a plugin
    instance, no other functions for that instance may run.</li>
 </ul>
+<p>
 Any simultaneous calls that are not explicitly forbidden by these rules
 are allowed. For example, a host may call run() for two different plugin
-instances simultaneously.
+instances simultaneously.</p>
 """ .
 
 
@@ -242,36 +247,38 @@ language tag.
          rdfs:comment """
 A port MUST have at least one lv2:name which is of type xsd:string.
 """ ] ;
-    rdfs:comment """
-The class which represents an LV2 port.
+    lv2:documentation """
+<p>The class which represents an LV2 port.</p>
 
-In order for it to be used by a host it MUST have at least 
-the following properties:
-    rdf:type (with object one of lv2:Port, lv2:InputPort, lv2:OutputPort)
-    rdf:type (more specific port class, see below)
-    lv2:index
-    lv2:symbol
-    lv2:name
+<p>In order for it to be used by a host it MUST have at least 
+the following properties:</p>
+<ul>
+<li>rdf:type (with object one of lv2:Port, lv2:InputPort, lv2:OutputPort)</li>
+<li>rdf:type (more specific port class, see below)</li>
+<li>lv2:index</li>
+<li>lv2:symbol</li>
+<li>lv2:name</li>
+</ul>
 
-All LV2 port descriptions MUST have a property rdf:type where the object is
+<p>All LV2 port descriptions MUST have a property rdf:type where the object is
 one of lv2:Port lv2:InputPort or lv2:OutputPort.  Additionally there MUST
 be at least one other rdf:type property which more specifically describes
-type of the port (e.g. lv2:AudioPort).
+type of the port (e.g. lv2:AudioPort).</p>
 
-Hosts that do not support a specific port class MUST NOT instantiate the
+<p>Hosts that do not support a specific port class MUST NOT instantiate the
 plugin, unless that port has the connectionOptional property set (in which case
 the host can simply "connect" that port to NULL).  If a host is interested
 in plugins to insert in a certain signal path (e.g. stereo audio), it SHOULD
 consider all the classes of a port to determine which ports are most suitable
 for connection (e.g. by ignoring ports with additional classes the host does
-not recognize).
+not recognize).</p>
 
-A port has two identifiers - a (numeric) index, and a (textual) symbol.
+<p>A port has two identifiers - a (numeric) index, and a (textual) symbol.
 The index can be used as an identifier at run-time, but persistent references
 to ports (e.g. in a saved preset) MUST use the symbol.  A symbol is guaranteed
 to refer to the same port on all plugins with a given URI.  An index does NOT
 necessarily refer to the same port on all plugins with a given URI (i.e. the
-index for a port may differ between plugin binaries).
+index for a port may differ between plugin binaries).</p>
 """ .
 
 lv2:InputPort a rdfs:Class ;
@@ -340,39 +347,28 @@ version to distinguish incompatible objects (use the URI for that).
 
 
 ####################################
-## Optional Plugin RDF Properties ##
+## Documentation                  ##
 ####################################
 
-lv2:basicXHTML a rdfs:Class ;
-    rdfs:seeAlso <http://www.w3.org/TR/xhtml1/> ;
-    rdfs:seeAlso <http://www.w3.org/TR/xhtml-modularization/> ;
-    rdfs:comment """
-A very basic subset of XHTML for use with lv2:documentation, intended to be
-reasonable for hosts to support for styled inline documentation.
-
-A literal with this data type is an XHTML 1.0 fragment containing only
-tags from the following XHTML modules: text, hypertext, list, basic tables,
-image, presentation.  See the XHTML and XHTML Modularization specifications
-for details.  A literal with this data type must be legal to insert as the
-body of a &lt;div&gt; tag (free text is allowed).
-
-If only basicXHTML documentation is given but a host has no facilities for
-handling tags, simply stripping tags and inserting newlines after appropriate
-tags will yield a somewhat readable plain text version of the documentation.
-""" .
-
 lv2:documentation a rdf:Property ;
     rdfs:domain  lv2:Resource ;
+    rdfs:range   rdfs:Literal ;
     rdfs:label   "documentation" ;
-    rdfs:comment """
-Relates a Plugin to some text/audio/video documentation either online or
-included with the plugin package.  The value of this property may be either a
-URL, or a literal of any type.  Literal documentation SHOULD be either plain
-text, or lv2:basicXHTML.  More advanced documentation should be linked to instead.
+    rdfs:seeAlso <http://www.w3.org/TR/xhtml-basic/> ;
+    lv2:documentation """
+<p>Relates a Resource to documentation markup.  The value of this property
+MUST be a string literal which is a valid XHTML Basic 1.1 fragment suitable
+for use as the content of a &lt;div&gt; element.  This can be used by
+hosts to provide rich online documentation or by tools to generate external
+documentation pages.  The standard language tagging facility of RDF can be
+used to provide multi-lingual documentation.</p>
+<p>XHTML Basic is a W3C Recommendation which defines a basic subset of XHTML
+intended to be reasonable to implement with limited resources (e.g. on embedded
+devices).  See <a href="http://www.w3.org/TR/xhtml-basic/#s_xhtmlmodules"
+>XHTML Basic, Section 3</a> for a list of legal tags.</p>
 """ .
 
 
-
 ###################################
 ## Mandatory Port RDF Properties ##
 ###################################