From 430284545345539c9ffb31df889debac1d3888b5 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Sun, 22 Mar 2020 16:36:44 +0100
Subject: Move documentation to metadata files and convert it to Markdown

---
 lv2/log/log.meta.ttl | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 lv2/log/log.ttl      | 38 ++++++--------------------
 2 files changed, 82 insertions(+), 31 deletions(-)

(limited to 'lv2/log')

diff --git a/lv2/log/log.meta.ttl b/lv2/log/log.meta.ttl
index 1a5a56e..87cff43 100644
--- a/lv2/log/log.meta.ttl
+++ b/lv2/log/log.meta.ttl
@@ -1,6 +1,8 @@
 @prefix dcs: <http://ontologi.es/doap-changeset#> .
 @prefix doap: <http://usefulinc.com/ns/doap#> .
 @prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix log: <http://lv2plug.in/ns/ext/log#> .
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 
 <http://lv2plug.in/ns/ext/log>
@@ -49,5 +51,76 @@
 				rdfs:label "Initial release."
 			]
 		]
-	] .
+	] ;
+	lv2:documentation """
+
+This extension defines a feature, log:log, which allows plugins to print log
+messages with an API similar to the standard C `printf` function.  This allows,
+for example, plugin logs to be nicely presented to the user in a graphical user
+interface.
+
+Different log levels are defined by URI and passed as an LV2_URID.  This
+extensions defines standard levels which are expected to be understood by all
+implementations and should be sufficient in most cases, but advanced
+implementations may define and use additional levels to suit their needs.
+
+"""^^lv2:Markdown .
+
+log:Entry
+	a rdfs:Class ;
+	rdfs:label "Log Entry" ;
+	lv2:documentation """
+
+Subclasses of this are passed as the `type` parameter to LV2_Log_Log methods to
+describe the nature of the log entry.
+
+"""^^lv2:Markdown .
+
+log:Error
+	lv2:documentation """
+
+An error should only be posted when a serious unexpected error occurs, and
+should be actively shown to the user by the host.
+
+"""^^lv2:Markdown .
+
+log:Note
+	lv2:documentation """
+
+A note records some useful piece of information, but may be ignored.  The host
+should provide passive access to note entries to the user.
+
+"""^^lv2:Markdown .
+
+log:Warning
+	lv2:documentation """
+
+A warning should be posted when an unexpected, but non-critical, error occurs.
+The host should provide passive access to warnings entries to the user, but may
+also choose to actively show them.
+
+"""^^lv2:Markdown .
+
+log:Trace
+	lv2:documentation """
+
+A trace should not be displayed during normal operation, but the host may
+implement an option to display them for debugging purposes.
+
+This entry type is special in that one may be posted in a real-time thread.  It
+is assumed that if debug tracing is enabled, real-time performance is not a
+concern.  However, the host MUST guarantee that posting a trace _is_ real-time
+safe if debug tracing is not enabled (for example, by simply ignoring the call
+as early as possible).
+
+"""^^lv2:Markdown .
+
+log:log
+	lv2:documentation """
+
+A feature which plugins may use to log messages.  To support this feature,
+the host must pass an LV2_Feature to LV2_Descriptor::instantiate() with URI
+LV2_LOG__log and data pointed to an instance of LV2_Log_Log.
+
+"""^^lv2:Markdown .
 
diff --git a/lv2/log/log.ttl b/lv2/log/log.ttl
index 1f4f170..f374051 100644
--- a/lv2/log/log.ttl
+++ b/lv2/log/log.ttl
@@ -6,26 +6,15 @@
 
 <http://lv2plug.in/ns/ext/log>
 	a lv2:Specification ;
+	rdfs:label "LV2 Log" ;
+	rdfs:comment "A feature for writing log messages." ;
 	rdfs:seeAlso <log.h> ,
-		<log.meta.ttl> ;
-	lv2:documentation """
-<p>This extension defines a feature, log:log, which allows plugins to print log
-messages with an API much like the standard C printf functions.  This allows,
-for example, plugin logs to be nicely presented to the user in a graphical user
-interface.</p>
-
-<p>Different log levels (e.g. <q>error</q> or <q>information</q>) are defined
-by URI and passed as an LV2_URID.  This document defines the typical levels
-which should be sufficient, but implementations may define and use additional
-levels to suit their needs.</p>
-""" .
+		<log.meta.ttl> .
 
 log:Entry
 	a rdfs:Class ;
-	rdfs:label "Log Entry" ;
-	lv2:documentation """
-<p>A log entry.  Subclasses of this class can be passed to LV2_Log_Log methods
-to describe the nature of the log message.</p>""" .
+	rdfs:label "Entry" ;
+	rdfs:comment "A log entry." .
 
 log:Error
 	a rdfs:Class ;
@@ -49,21 +38,10 @@ log:Trace
 	a rdfs:Class ;
 	rdfs:label "Trace" ;
 	rdfs:subClassOf log:Entry ;
-	lv2:documentation """
-<p>A debugging trace.  These entries should not be displayed during normal
-operation, but the host may implement an option to display them for debugging
-purposes.</p>
-
-<p>This entry type is special in that it may be written to in a real-time
-thread.  It is assumed that if debug tracing is enabled, real-time
-considerations are not a concern.</p>
-""" .
+	rdfs:comment "A debugging trace message." .
 
 log:log
 	a lv2:Feature ;
-	lv2:documentation """
-<p>A feature which plugins may use to log messages.  To support this feature,
-the host must pass an LV2_Feature to LV2_Descriptor::instantiate() with URI
-LV2_LOG__log and data pointed to an instance of LV2_Log_Log.</p>
-""" .
+	rdfs:label "log" ;
+	rdfs:comment "Logging feature." .
 
-- 
cgit v1.2.1