diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md index 8290f915..6d09db0c 100644 --- a/doc/src/02000-store.md +++ b/doc/src/02000-store.md @@ -16,21 +16,41 @@ The content follows the header-close marker (@sec:thestore:fileformat:content). ### Header Format {#sec:thestore:fileformat:header} The header format MUST BE "TOML". -The contents of the header contain +The sections which MAY or MUST be in the header are defined in the following +chapters. -1. A section called "imag", where the automatically by the program generated - data goes to. - The contents of these sections are edited via commandline calls or by the - program implicitely and SHOULD NOT be edited by the user. - Modules of the program are free to store arbitrary data here. - If a module stores data in the header of a file it MUST do that in a - dedicated section, as TOML supports it. - The name of the section MUST BE the name of the module in lowercase - letters. - The section MAY BE empty. -1. Other OPTIONAL sections which are named and edited by the user. The program - MUST NOT touch the contents of these sections, except explicitely asked by - the user to do so. +#### Header section: "imag" {#sec:thestore:fileformat:header:imag} + +The header MUST contain a section called "imag", where the automatically by the +program generated data is stored in. +The contents of this section is edited via commandline calls or by the +program implicitely and SHOULD NOT be edited by the user. + +This "imag" section MUST contain the following keys + +1. A "version" Key. The version stored here is the version of the Store, the + Entry was created with. + +The "imag" section MAY contain + +1. A section "imag.links" where a module is allowed to store URIs in a flat + list +1. A section "imag.content", used for referring to external content. + The key "uri" is the only one which is required, it refers to external + content. + An explicitely suggested key is "file" for referring to a _local Mirror_ of + the content. + +#### Header section: "custom" {#sec:thestore:fileformat:header:custom} + +The header MAY contain a section named "custom". +The user is free to store arbitrary data here. +The user is also free to edit this section by either commandline or editor. + +#### Module Header section {#sec:thestore:fileformat:header:module} + +The header MAY contain a section named after a module. +The corrosponding module is allowed to store arbitrary data in this section. ### Content Format {#sec:thestore:fileformat:content} @@ -38,8 +58,7 @@ The content is the part of the file where the user is free to enter any textual content. The content MAY BE rendered as Markdown or other markup format for the users convenience. -The program SHOULD NOT expect any particular markup format, except explicitely -configured in the header of the file. +The Store library MUST NOT expect any particular markup format. ### Example {#sec:thestore:fileformat:example} @@ -48,9 +67,19 @@ An example for a file in the store follows. ``` --- [imag] -nothing = here -[imag.examplemodule] -and_nothing = here_as_well +version = "0.1.0" + +[imag.content] +url = "file://home/user/kittens.mpeg" + +imag.links = [ + "imag://home/user/more_kittens.mpeg" +] + +[examplemodule] +arbitrary = data +[custom] +truth = 42 --- This is an example text, written by the user.