[Devel] Amp Example

Gabriel M. Beddingfield gabrbedd at gmail.com
Thu Jul 7 16:58:26 PDT 2011


On Thursday, July 07, 2011 03:15:47 pm David Robillard wrote:
> However, for examples like this, I think more extensive
> documentation in the example itself (ala literate
> programming) would be much more useful anyway.

As a first step... please look over the following patch for the amp example.  If this is the right track I'll 
continue it for the other files.

Note that the documentation is pretty verbose for manifest.ttl since Turtle and RDF will (likely) both be new to 
the reader.

-gabriel

--- 
Date: Thu, 7 Jul 2011 18:52:07 -0500
Subject: [PATCH] Add top-level annotations for plugin authoring.

README.txt: Tells the user which file to open first.

manifest.ttl: Added detailed annotations about the purpose of this
file, its syntax, and pointers to other files.
---
 README.txt   |    3 ++
 manifest.ttl |   81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 83 insertions(+), 1 deletions(-)
 create mode 100644 README.txt

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..2877e89
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,3 @@
+Where do I start?
+
+Read manifest.ttl.  It'll point you to the right places.
diff --git a/manifest.ttl b/manifest.ttl
index f75460b..7db7fd3 100644
--- a/manifest.ttl
+++ b/manifest.ttl
@@ -1,9 +1,88 @@
 # LV2 Plugin Manifest
-# Lists where plugins' data files and shared objects reside.
+#
+# Everything in the plugin's folder is called a "bundle."
+# The idea is that you can simply do a file archive of the
+# folder (tar, zip) and distribute the plugin that way.
+#
+# Inside the folder, the ENTRY POINT is a file called
+# `manifest.ttl`.  This file lists what plugins are in this
+# bundle, and which files are (.so, .ttl, etc.)  are
+# associated with those plugins.
+#
+# The syntax for this file is a language called Turtle
+# ("Turse RDF Triple Language").[1]  RDF[3] is a concept
+# for metadata that expresses the relationship between
+# things as triples (subject, predicate, object).
+
+# MACROS/PREFIXES
 
 @prefix lv2:  <http://lv2plug.in/ns/lv2core#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 
+# THE MAIN THING
+#
+# This is the main part of the manifest.ttl file:
+
 <http://lv2plug.in/plugins/example_amp> a lv2:Plugin ;
                                         lv2:binary   <amp.so>  ;
                                         rdfs:seeAlso <amp.ttl> .
+
+# What does it mean?
+#
+# Simplified, this declares a plugin (called
+# "http://lv2plug.in/plugins/example_amp") is an LV2 plugin.
+# The executable code is in the file 'amp.so' and there's
+# more information about the plugin (ports, etc.) in the
+# file 'amp.ttl'.  Both of these files are located in the
+# bundle.
+#
+# For a line-by-line explaination, see below.
+# See also the files amp.c and amp.ttl for documentation on
+# those files.
+#
+# <http://lv2plug.in/plugins/example_amp>
+#
+#     this is the URN[3] of a plugin.  This does NOT need to
+#     be an actual web address, it's just a name to uniquely
+#     identify your plugin.  Applications and users will
+#     always refer to your plugin using this string.
+#
+# a lv2:Plugin
+#
+#     The "a" is a Turtle shortcut for rdf:type and more or
+#     less means means "is a."  lv2:Plugin expands to
+#     <http://lv2plug.in/ns/lv2core#Plugin> (using the
+#     "lv2:" macro above) and is the established URN for the
+#     type "LV2 Plugin."  It literally means "this plugin is
+#     an LV2 plugin."
+#
+# ;
+#
+#     The semicolon means, "I'm going to say something else
+#     about this subject (the plugins URN).
+#
+# lv2:binary <amp.so>
+#
+#     Because of the semicolon, this is saying, "this plugin
+#     has executable code ("binary") in the file named
+#     "amp.so", which is located in this bundle.
+#
+#
+# rdfs:seeAlso <amp.ttl>
+#
+#     This is saying, "there is more RDF info about this
+#     plugin located in the file named 'amp.ttl', and it is
+#     considered part of this document.
+#
+# .
+#
+#     The period completes this list of statements.
+#
+# ---
+# Footnotes:
+# [1] http://www.w3.org/TeamSubmission/turtle/
+# [2] http://www.w3.org/RDF/
+#     http://www.w3.org/TR/2004/REC-rdf-primer-20040210/
+# [3] Uniform Resource Name,
+#     see http://en.wikipedia.org/wiki/Uniform_Resource_Name
+#
-- 
1.7.0.4






More information about the Devel mailing list