Add (modified) documentation from Gabriel M. Beddingfield

1 files changed, 84 insertions, 0 deletions

diff --git a/plugins/eg-amp.lv2/manifest.ttl b/plugins/eg-amp.lv2/manifest.ttl
index f45e23d..821c977 100644
--- a/plugins/eg-amp.lv2/manifest.ttl
+++ b/plugins/eg-amp.lv2/manifest.ttl
@@ -1,7 +1,91 @@
+# LV2 Bundle Manifest
+#
+# All LV2 plugins are installed as "bundles", a directory with a particular
+# format.  Inside the bundle, 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.
+#
+# Hosts read bundles' manifest.ttl to discover what plugins (and other
+# resources) are available.  Manifest files should be as small as possible for
+# performance reasons.
+#
+# The syntax of this file (and most other LV2 data files) is a language called
+# Turtle ("Turse RDF Triple Language").[1]  RDF[3] is a data model that
+# expresses the relationship between things as (subject, predicate, object)
+# triples.  Turtle is a simple, terse, abbreviated syntax for RDF.
+
+# Namespace Prefixes
+
 @prefix lv2:  <http://lv2plug.in/ns/lv2core#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 
+# Data (list of resources in this bundle, hence "manifest")
+
 <http://lv2plug.in/plugins/eg-amp>
 	a lv2:Plugin ;
 	lv2:binary <amp.so>  ;
 	rdfs:seeAlso <amp.ttl> .
+
+# Explanation
+#
+# In short, this declares that the resource with URI
+# "http://lv2plug.in/plugins/eg-amp") is an LV2 plugin, with executable code in
+# the file "amp.so" and a full description in "amp.ttl".  These paths are
+# relative to the bundle directory.
+#
+# There are 3 statements in this description:
+#
+# # | Subject                             | Predicate    | Object
+# -------------------------------------------------------------------
+# 1 | <http://lv2plug.in/plugins/eg-amp>  | a            | lv2:Plugin
+# 2 | <http://lv2plug.in/plugins/eg-amp>  | lv2:binary   | <amp.so>
+# 3 | <http://lv2plug.in/plugins/eg-amp>  | rdfs:seeAlso | <amp.ttl>
+#
+# The semicolon is used to continue the previous subject, an equivalent
+# but more verbose syntax for the same data is:
+#
+# <http://lv2plug.in/plugins/eg-amp> a lv2:Plugin .
+# <http://lv2plug.in/plugins/eg-amp> lv2:binary <amp.so> ;
+# <http://lv2plug.in/plugins/eg-amp> rdfs:seeAlso <amp.ttl> .
+#
+# Note that the documentation for a URI can often be found by visiting that URI
+# in a web browser, e.g. the documentation for lv2:binary can be found at
+# <http://lv2plug.in/ns/lv2core#binary>.  If you encounter a predicate in some
+# data which you do not understand, try this first.
+#
+# Note the URI of a plugin does NOT need to be an actual web address, it's just
+# a global identifier.  It is, however, a good idea to use an actual web
+# address if possible, since it can be used to easily access documentation,
+# downloads, etc.  Note there are compatibility rules for when the URI of a
+# plugin must be changed, see the LV2 specification[4] for details.
+#
+# A detailed explanation of each statement follows.
+#
+# 1: <http://lv2plug.in/plugins/eg-amp> a lv2:Plugin
+#
+#    The "a" is a Turtle shortcut for rdf:type and more or less means "is a".
+#    lv2:Plugin expands to <http://lv2plug.in/ns/lv2core#Plugin> (using the
+#    "lv2:" prefix above) and is the established URI for the type "LV2 Plugin".
+#    This statement literally means "this resource is an LV2 plugin".
+#
+# 2: <http://lv2plug.in/plugins/eg-amp> lv2:binary <amp.so>
+#
+#    This says "this plugin has executable code ("binary") in the file
+#    named "amp.so", which is located in this bundle.  The LV2 specification
+#    defines that all relative URIs in manifest files are relative to the bundle
+#    directory, so this refers to the file amp.so in the same directory as this
+#    manifest.ttl file.
+#
+# 3: <http://lv2plug.in/plugins/eg-amp> rdfs:seeAlso <amp.ttl>
+#
+#    This says "there is more information about this plugin located in the file
+#    "amp.ttl".  The host will look at all such files when it needs to actually
+# use or investigate the plugin.
+
+# 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] http://tools.ietf.org/html/rfc3986
+# [4] http://lv2plug.in/ns/lv2core
\ No newline at end of file