diff options
author | Matthias Beyer <mail@beyermatthias.de> | 2016-07-08 18:43:46 +0200 |
---|---|---|
committer | Matthias Beyer <mail@beyermatthias.de> | 2016-07-08 20:43:20 +0200 |
commit | f81e47ceb2f36760b41ae29c5b58decff75ce87d (patch) | |
tree | 182456bd39f07355bb1d5810d431b8dafdd9669d | |
parent | 7a8432123bd05894b28e286308fbcb8e51fa0d7f (diff) |
doc: Rewrite linking chapter
-rw-r--r-- | doc/src/02010-linking.md | 42 |
1 files changed, 18 insertions, 24 deletions
diff --git a/doc/src/02010-linking.md b/doc/src/02010-linking.md index 7ad09cb4..ba62ec0c 100644 --- a/doc/src/02010-linking.md +++ b/doc/src/02010-linking.md @@ -1,35 +1,29 @@ ## 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. +As described in @sec:intro:problem the purpose of imag is to _link_ content +together. The following section describes, from a technical view, how this is +done in imag. + +There are two ways of linking in imag. You can either link internally or +externally. The following sections describe the differences. ### 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). +Internal links are links between store entries themselfes. This means that one +store entry can link to another. Actually, links are not pointers but rather +tries between entries, meaning that an link is not directed, but always a +two-way pointer. -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. +How linking works from the user interface is described in @sec:modules:link. ### Linking to external content {#sec:thestore:linking:external} -Each Entry can store _one link to external content at most_. +Linking to external content means linking to files or directories which do not +live inside the store itself but outside of it. + +Each store 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". +External linking should not be used from the user interface but rather the +`ref` feature (@sec:modules:ref) should be used. +@sec:modules:ref describes why that is. |