From 78d25ebad70f0e446f9d7d6692f0ce6a354d39b4 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jan 2016 14:34:58 +0100 Subject: [PATCH 1/2] Rewrite part on store path format --- doc/src/02000-store.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md index cbe22037..482facbb 100644 --- a/doc/src/02000-store.md +++ b/doc/src/02000-store.md @@ -71,11 +71,30 @@ So if the store exists in `/home/user/store/`, a file with the Storepath `/example.file` is (on the filesystem) located at `/home/user/store/example.file`. -A Storepath contains one predefined part: The module name of the Module the -Entry belongs to, in lowercase letters. -So if a Module named "ExampleModule" stores a file in the Store, the Storepath -for a file with the name "example.file" is "/examplemodule/example.file". +A Storepath contains predefined parts: + +* The module name of the Module the Entry belongs to. + This part is a directory. +* The version (semantic versioning applies) of the module storing the Entry + This part is a postfix to the filename + +The pattern for the storepath is + +``` +///~ +``` + +So if a Module named "ExampleModule" with version "0.1" stores a file in the +Store, the Storepath for a file with the name "example" is +"/ExampleModule/example~0.1". Any number of subdirectories MAY BE used, so creating folder hierarchies is possible and valid. +A file "example" for a module "module" in version "0.1" would be stored in +sub-folders like this: + +``` +/module/some/sub/folder/example~0.1 +``` + From 4ce693c05f29fd6d3a6fd058a3d6dc1a29ef669e Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jan 2016 14:35:13 +0100 Subject: [PATCH 2/2] Add paragraph on store path links --- doc/src/02000-store.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md index 482facbb..8290f915 100644 --- a/doc/src/02000-store.md +++ b/doc/src/02000-store.md @@ -97,4 +97,32 @@ sub-folders like this: /module/some/sub/folder/example~0.1 ``` +## Store path links {#sec:thestore:links} + +Linking entries MUST BE version independent. + +This means if an entry "a" from a module "A" gets written to the store, it may +link to an entry "b" from a module "B", which is in version "0.1" at the moment. +If the module "B" gets updated, it might update its entries in the store as +well. +The link from the "a" MUST NOT get invalid in this case. + +This is accomplished by linking without the version number: So a link for the +entry + +``` +/module/some/sub/folder/example~0.1 +``` + +is + +``` +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. +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.