From b5c67bb00c8575d27cbfc3100e0d9c13a385e6aa Mon Sep 17 00:00:00 2001 From: David Robillard Date: Mon, 3 Oct 2016 22:46:16 -0400 Subject: Improve documentation --- plugins/eg-amp.lv2/manifest.ttl.in | 115 +++++++++++++------------------------ 1 file changed, 41 insertions(+), 74 deletions(-) diff --git a/plugins/eg-amp.lv2/manifest.ttl.in b/plugins/eg-amp.lv2/manifest.ttl.in index da8a2c4..4a22f95 100644 --- a/plugins/eg-amp.lv2/manifest.ttl.in +++ b/plugins/eg-amp.lv2/manifest.ttl.in @@ -1,46 +1,33 @@ -# ==== Bundles ==== +# LV2 plugins are installed in a ``bundle'', a directory with a standard +# structure. Each bundle has a Turtle file named `manifest.ttl` which lists +# the contents of the bundle. # -# LV2 plugins are installed in ``bundles'', a directory with a particular -# format. Inside the bundle, the entry point is a file called `manifest.ttl`. -# The manifest lists the plugins (or other resources) that are in this bundle, -# and the files that contain further information. +# Hosts typically read the manifest of every installed bundle to discover +# plugins on start-up, so it should be as small as possible for performance +# reasons. Details that are only useful if the host chooses to load the plugin +# are stored in other files and linked to from `manifest.ttl`. # -# Hosts typically read the `manifest.ttl` of every bundle when starting up to -# discover what LV2 plugins and other resources are present. Accordingly, -# manifest files should be as small as possible for performance reasons. +# ==== URIs ==== # +# LV2 makes use of URIs as globally-unique identifiers for resources. For +# example, the ID of the plugin described here is +# ``. Note that URIs are only used as +# identifiers and don't necessarily imply that something can be accessed at +# that address on the web (though that may be the case). # # ==== Namespace Prefixes ==== # -# Turtle files contain many URIs. To make this more readable, prefixes can be -# defined. For example, with the `lv2:` prefix below, instead of -# the shorter form `lv2:Plugin` can be -# used. This is just a shorthand for URIs within one file, the prefixes are -# not significant otherwise. +# Turtle files contain many URIs, but prefixes can be defined to improve +# readability. For example, with the `lv2:` prefix below, `lv2:Plugin` can be +# written instead of ``. @prefix lv2: . @prefix rdfs: . -# ==== A Plugin Entry ==== +# ==== Describing a Plugin ==== - - a lv2:Plugin ; - lv2:binary ; - rdfs:seeAlso . - -# 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 following 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 -# 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: +# Turtle files contain a set of ``statements'' which describe resources. +# This file contains 3 statements: # [options="header"] # |================================================================ # | Subject | Predicate | Object @@ -48,54 +35,34 @@ # | | lv2:binary | # | | rdfs:seeAlso | # |================================================================ -# -# The semicolon is used to continue the previous subject; an equivalent -# but more verbose syntax for the same data is: - - a lv2:Plugin . - lv2:binary . - rdfs:seeAlso . - -# (Since this data is equivalent, it is safe, if pointless, to list it twice) -# -# 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 -# . All standard LV2 classes and -# properties are documented in this way, so if you encounter a URI in some data -# which you do not understand, try this first. -# -# The URI of a plugin does not need to be a resolvable web address, it just -# serves as a global identifier. However, it is a good idea to use an actual -# web address if possible for easy access documentation, downloads, and so on, -# even if no documents are currently hosted there. There are compatibility -# rules about when the URI of a plugin must be changed, see the -# http://lv2plug.in/ns/lv2core[LV2 specification] for details. Note that this -# does not require authors to control a top-level domain; for example, URIs in -# project directories at shared hosting sites are fine. It is not required to -# use HTTP URIs, but use of other schemes is strongly discouraged. -# -# AUTHORS MUST NOT CREATE URIS AT DOMAINS THEY DO NOT CONTROL WITHOUT -# PERMISSION, AND *ESPECIALLY* MUST NOT CREATE INVALID URIS, E.G. WHERE THE -# PORTION FOLLOWING ``http://'' IS NOT A DOMAIN NAME. If you need an example -# URI, the domain http://example.org/ is reserved for this purpose. -# -# A detailed explanation of each statement follows. +# Firstly, `` is an LV2 plugin: a lv2:Plugin . -# The `a`, as in ``is a'', is a Turtle shortcut for `rdf:type`. -# `lv2:Plugin` expands to (using the -# `lv2:` prefix above) which is the type of all LV2 plugins. -# This statement means `` is an LV2 plugin''. +# The predicate ```a`'' is a Turtle shorthand for `rdf:type`. +# The binary of that plugin can be found at ``: lv2:binary . -# This says ```eg-amp` has executable code in the file `amp.so`''. -# 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. +# This file is a template; the token `@LIB_EXT@` is replaced by the build +# system with the appropriate extension for the current platform before +# installation. For example, in the output `manifest.ttl`, the binary would be +# listed as ``. Relative URIs in manifests are relative to the bundle +# directory, so this refers to a binary with the given name in the same +# directory as this manifest. +# Finally, more information about this plugin can be found in ``: rdfs:seeAlso . -# This says ``there is more information about `eg-amp` in the file `amp.ttl`''. -# The host will look at all such files when it needs to actually use or -# investigate the plugin. +# ==== Abbreviation ==== +# +# This file shows these statements individually for instructive purposes, but +# the subject `` is repetitive. Turtle +# allows the semicolon to be used as a delimiter that repeats the previous +# subject. For example, this manifest would more realistically be written like +# so: + + + a lv2:Plugin ; + lv2:binary ; + rdfs:seeAlso . -- cgit v1.2.1