Merge pull request #167 from matthiasbeyer/doc/linking

doc: Add chapter on linking

doc/src/02000-store.md

@@ -171,6 +171,7 @@ imag://module/some/sub/folder/example
 
 As shown in the example, a link to imag-internal entries, the link is prefixed
 with a "imag://" identifier.
+This prefix is optional.
 A link to external content MUST NEVER be prefixed this way.
 The path of the internal link MUST NEVER be relative, but always absolute from
 the root directory of the store.

doc/src/02010-linking.md

@@ -0,0 +1,35 @@
+## Linking from an store entry {#sec:thestore:linking}
+
+In @sec:thestore:fileformat:header:imag it was already defined that there MUST
+BE a section "imag" in the header. This section can be used to link to
+"internal" and "external" content, whereas "internal content" refers to entries
+which are stored in the very same store as the entry which links.
+The term "external content" means content which is not stored in the
+store, but elsewhere on the filesystem or the network (thus, an URL is valid
+external content).
+
+Entries can be referenced from the content part. For example, if the content
+part is written in Markdown, the user is able to link content within the
+Markdown text.
+These links could be either links to internal content or external content.
+
+### Linking to internal content {#sec:thestore:linking:internal}
+
+Links to internal content are stored in the Array "imag.links = []".
+Each entry in this array MUST BE a String which is an absolute path to a store
+entry (@sec:thestore:links).
+
+As links from within the content part of a module is not cross-compatible over
+modules, each module SHOULD store the links which are in the content
+part also in the "imag.links" Array. This way, other modules can read the links
+without having knowledge about how to parse the content part of an entry.
+
+### Linking to external content {#sec:thestore:linking:external}
+
+Each Entry can store _one link to external content at most_.
+
+This link is stored in the header field "imag.content.uri"
+(@sec:thestore:fileformat:header:imag).
+A key "imag.content.file" COULD be used for a local mirror of the content which
+is referenced by "imag.content.uri".
+

doc/src/04100-lib-link.md

@@ -0,0 +1,42 @@
+# liblink {#sec:liblink}
+
+The "liblink" library contains functionality for linking from entries to
+internal and external content.
+
+The utilities provided by "liblink" contain functions to
+
+* Get internal links from arbitraty entries
+* Access an "EntryHeader" object to
+  * get internal links
+  * set internal links
+  * get "Entry" objects for links from a header
+
+## Linking internal content with liblink {#sec:liblink:internal}
+
+As one entry MAY contain zero or more interal links in the header section
+"imag.links", the "liblink" library provides functionality to
+
+* get the link from an EntryHeader object
+* set the links in a EntryHeader object
+* query for a specific link in a EntryHeader object
+  * by regex
+  * by module name
+  * by filename
+
+as well as functionality to get "Entry" objects for each entry in the Header.
+
+## Linking external content with liblink {#sec:liblink:external}
+
+As one "EntryHeader" MUST NOT contain more than one link to external content (as
+defined in @sec:thestore:linking:external, the following scheme for linking to
+external content MUST BE provided by "liblink":
+
+* Generate a "link" entry in the store
+  * with store path starting with "/link/"
+  * where the header field "imag.content.uri" MUST BE set
+  * with optional content which can be stored in the section of the "liblink"
+    module section (section name "link", as defined by
+    @sec:thestore:fileformat:header:module).
+* Get an external link by store path (looking up the store path entry and
+  getting the link to the external content from it)
+