Move documentation to metadata files and convert it to Markdown

2 files changed, 97 insertions, 71 deletions

diff --git a/lv2/options/options.meta.ttl b/lv2/options/options.meta.ttl
index c0f598d..d545f95 100644
--- a/lv2/options/options.meta.ttl
+++ b/lv2/options/options.meta.ttl
@@ -1,12 +1,15 @@
 @prefix dcs: <http://ontologi.es/doap-changeset#> .
 @prefix doap: <http://usefulinc.com/ns/doap#> .
 @prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix opts: <http://lv2plug.in/ns/ext/options#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 
 <http://lv2plug.in/ns/ext/options>
 	a doap:Project ;
 	doap:name "LV2 Options" ;
-	doap:shortdesc "Instantiation time options." ;
+	doap:shortdesc "Runtime options for LV2 plugins and UIs." ;
 	doap:created "2012-08-20" ;
 	doap:developer <http://drobilla.net/drobilla#me> ;
 	doap:release [
@@ -39,5 +42,88 @@
 				rdfs:label "Initial release."
 			]
 		]
-	] .
+	] ;
+	lv2:documentation """
+
+This extension defines a facility for <q>options</q>, which are values the host
+passes to a plugin or UI at run time.
+
+There are two facilities for passing options to an instance: opts:options
+allows passing options at instantiation time, and the opts:interface interface
+allows options to be dynamically set and retrieved after instantiation.
+
+Note that this extension is only for allowing hosts to configure plugins, and
+is not a <q>live</q> control mechanism.  For real-time control, use event-based
+control via an atom:AtomPort with an atom:Sequence buffer.
+
+Instances may indicate they require an option with the opts:requiredOption
+property, or that they optionally support an option with the
+opts:supportedOption property.
+
+"""^^lv2:Markdown .
+
+opts:Option
+	lv2:documentation """
+
+It is not required for a property to explicitly be an Option in order to be
+used as such.  However, properties which are primarily intended for use as
+options, or are at least particularly useful as options, should be explicitly
+given this type for documentation purposes, and to assist hosts in discovering
+option definitions.
+
+"""^^lv2:Markdown .
+
+opts:interface
+	lv2:documentation """
+
+An interface (LV2_Options_Interface) for dynamically setting and getting
+options.  Note that this is intended for use by the host for configuring
+plugins only, and is not a <q>live</q> plugin control mechanism.
+
+The plugin data file should advertise this interface like so:
+
+    :::turtle
+    @prefix opts: &lt;http://lv2plug.in/ns/ext/options#&gt; .
+
+    &lt;plugin&gt;
+        a lv2:Plugin ;
+        lv2:extensionData opts:interface .
+
+"""^^lv2:Markdown .
+
+opts:options
+	lv2:documentation """
+
+To implement this feature, hosts MUST pass an LV2_Feature to the appropriate
+instantiate method with this URI and data pointed to an array of
+LV2_Options_Option terminated by an element with both key and value set to
+zero.  The instance should cast this data pointer to `const
+LV2_Options_Option*` and scan the array for any options of interest.  The
+instance MUST NOT modify the options array in any way.
+
+Note that requiring this feature may reduce the number of compatible hosts.
+Unless some options are strictly required by the instance, this feature SHOULD
+be listed as an lv2:optionalFeature.
+
+"""^^lv2:Markdown .
+
+opts:requiredOption
+	lv2:documentation """
+
+The host MUST pass a value for the specified option via opts:options during
+instantiation.
+
+Note that use of this property may reduce the number of compatible hosts.
+Wherever possible, it is better to list options with opts:supportedOption and
+fall back to a reasonable default value if it is not provided.
+
+"""^^lv2:Markdown .
+
+opts:supportedOption
+	lv2:documentation """
+
+The host SHOULD provide a value for the specified option if one is known, or
+provide the user an opportunity to specify one if possible.
+
+"""^^lv2:Markdown .
 
diff --git a/lv2/options/options.ttl b/lv2/options/options.ttl
index 7f9ed44..c7fe77e 100644
--- a/lv2/options/options.ttl
+++ b/lv2/options/options.ttl
@@ -8,98 +8,38 @@
 <http://lv2plug.in/ns/ext/options>
 	a owl:Ontology ,
 		lv2:Specification ;
+	rdfs:label "LV2 Options" ;
+	rdfs:comment "Runtime options for LV2 plugins and UIs." ;
 	rdfs:seeAlso <options.h> ,
-		<options.meta.ttl> ;
-	lv2:documentation """
-<p>This extension defines a facility for <q>options</q>, which are dynamic
-properties that may be changed at run time.</p>
-
-<p>There are two facilities for passing options to an instance: opts:options
-allows passing options at instantiation time, and the opts:interface interface
-allows options to be dynamically set and retrieved after instantiation.</p>
-
-<p>Note that this extension is only for allowing hosts to configure plugins,
-and is not a <q>live</q> control mechanism.  For real-time control, use
-event-based control via an atom:AtomPort with an atom:Sequence buffer.</p>
-
-<p>Instances may indicate they <q>require</q> an option with the
-opts:requiredOption property, or that they optionally <q>support</q> an option
-with the opts:supportedOption property.</p>
-""" .
+		<options.meta.ttl> .
 
 opts:Option
 	a rdfs:Class ;
 	rdfs:label "Option" ;
 	rdfs:subClassOf rdf:Property ;
-	lv2:documentation """
-<p>A property intended to be used as a static option for an instance.</p>
-
-<p>It is not required for a property to explicitly be an Option in order to be
-used as such.  However, properties which are primarily intended for use as
-options, or are at least particularly useful as options, should be explicitly
-given this type for documentation purposes, and to assist hosts in discovering
-option definitions.</p>
-""" .
+	rdfs:comment "A value for a static option passed to an instance." .
 
 opts:interface
 	a lv2:ExtensionData ;
-	lv2:documentation """
-<p>An interface (LV2_Options_Interface) for dynamically setting and getting
-options.  Note this is intended for use by the host for configuring plugins
-only, and and is <em>not</em> a <q>live</q> plugin control mechanism.</p>
-
-<p>The plugin data file should describe this like so:</p>
-<pre class="turtle-code">
-@prefix opts: &lt;http://lv2plug.in/ns/ext/options#&gt; .
-
-&lt;plugin&gt;
-    a lv2:Plugin ;
-    lv2:extensionData opts:interface .
-</pre>
-""" .
+	rdfs:label "interface" ;
+	rdfs:comment "An interface for dynamically setting and getting options." .
 
 opts:options
 	a lv2:Feature ;
 	rdfs:label "options" ;
-	lv2:documentation """
-<p>The feature used to provide options to an instance.</p>
-
-<p>To implement this feature, hosts MUST pass an LV2_Feature to the appropriate
-instantiate method with this URI and data pointed to an array of
-LV2_Options_Option terminated by an element with both key and value set to
-zero.  The instance should cast this data pointer to <code>const
-LV2_Options_Option*</code> and scan the array for any options of interest.  The
-instance MUST NOT modify the options array in any way.</p>
-
-<p>Note that requiring this feature may reduce the number of compatible hosts.
-Unless some options are strictly required by the instance, this feature SHOULD
-be listed as a lv2:optionalFeature.</p>
-""" .
+	rdfs:comment "The feature used to provide options to an instance." .
 
 opts:requiredOption
 	a rdf:Property ,
 		owl:ObjectProperty ;
 	rdfs:range rdf:Property ;
 	rdfs:label "required option" ;
-	lv2:documentation """
-<p>An option required by the instance to function at all.  The host MUST pass a
-value for the specified option via opts:options in order to create an
-instance.</p>
-
-<p>Note that use of this property may reduce the number of compatible hosts.
-Wherever possible, it is better to list options with opts:supportedOption and
-fall back to a reasonable default value if it is not provided.</p>
-""" .
+	rdfs:comment "An option required by the instance to function at all." .
 
 opts:supportedOption
 	a rdf:Property ,
 		owl:ObjectProperty ;
 	rdfs:range rdf:Property ;
 	rdfs:label "supported option" ;
-	lv2:documentation """
-<p>An option supported or <q>understood</q> by the instance.  The host SHOULD
-provide a value for the specified option if one is known, or provide the user
-an opportunity to specify one if one is Indicates that the instance host MUST
-pass a value for the specified option in order to instantiate the instance.</p>
-""" .
+	rdfs:comment "An option supported or by the instance." .