Generate book from example plugin source.

1 files changed, 41 insertions, 51 deletions

diff --git a/plugins/eg-amp.lv2/manifest.ttl.in b/plugins/eg-amp.lv2/manifest.ttl.in
index 2813473..51f4a79 100644
--- a/plugins/eg-amp.lv2/manifest.ttl.in
+++ b/plugins/eg-amp.lv2/manifest.ttl.in
@@ -9,34 +9,31 @@
 # 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
+#
+# ==== Namespace Prefixes ====
 #
 # Turtle files often contain many URIs.  To make this more readable, prefixes
-# can be defined.  For example, with the lv2 prefix below, instead of
-# <http://lv2plug.in/ns/lv2core#Plugin> the shorter form lv2:Plugin can be
-# used.  This is just a shorthand for URIs, the prefixes are not significant.
+# can be defined.  For example, with the `lv2:` prefix below, instead of
+# <http://lv2plug.in/ns/lv2core#Plugin> the shorter form `lv2:Plugin` can be
+# used.  This is just a shorthand for URIs within a file, the prefixes are not
+# significant otherwise.
 
 @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")
+# ==== Data ====
 
 <http://lv2plug.in/plugins/eg-amp>
 	a lv2:Plugin ;
 	lv2:binary <amp@LIB_EXT@>  ;
 	rdfs:seeAlso <amp.ttl> .
 
-# Explanation
-#
-# The token @LIB_EXT@ above is replaced by the build system (waf) by the
-# appropriate extension for the current platform (e.g. .so, .dylib, .dll),
-# which is why this file is called manifest.ttl.in and not manifest.ttl.  This
-# documentation assumes .so for simplicity.
+# The token `@LIB_EXT@` above is replaced by the build system with the
+# appropriate extension for the current platform (e.g. .so, .dylib, .dll).
+# This file is called called `manifest.ttl.in` rather than `manifest.ttl`
+# to indicate that it is not the final file to be installed.
+# This is not necessary, but is a good idea for portable plugins.
+# For reability, the text will assume `.so` is the extension used.
 #
 # In short, this declares that the resource with URI
 # "http://lv2plug.in/plugins/eg-amp" is an LV2 plugin, with executable code in
@@ -44,12 +41,12 @@
 # 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>
+# |================================================================
+# | Subject                             | Predicate    | Object
+# | <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>
+# |================================================================
 #
 # The semicolon is used to continue the previous subject; an equivalent
 # but more verbose syntax for the same data is:
@@ -69,7 +66,8 @@
 # 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.
+# plugin must be changed, see the http://lv2plug.in/ns/lv2core[LV2 specification]
+# for details.
 #
 # AUTHORS MUST NOT CREATE URIS AT DOMAINS THEY DO NOT CONTROL WITHOUT
 # PERMISSION, AND *ESPECIALLY* MUST NOT CREATE SYNTACTICALLY INVALID URIS,
@@ -80,32 +78,24 @@
 # If this is truly impossible, use a URN, e.g. urn:myplugs:superamp.
 #
 # 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
+<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) which is the type of all LV2 plugins.
+# This statement means ``<http://lv2plug.in/plugins/eg-amp> is an LV2 plugin''.
+
+<http://lv2plug.in/plugins/eg-amp> lv2:binary <amp@LIB_EXT@> .
+
+# 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.
+
+<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.