From cafc6dbadfb7ab24386385aefbce8bb4ae413bd6 Mon Sep 17 00:00:00 2001
From: Matthias Beyer <mail@beyermatthias.de>
Date: Tue, 19 Jan 2016 15:58:22 +0100
Subject: Rewrite chapter on header contents

---
 doc/src/02000-store.md | 57 +++++++++++++++++++++++++++++++-------------------
 1 file changed, 35 insertions(+), 22 deletions(-)

(limited to 'doc')

diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md
index 5a72f372..10e497e3 100644
--- a/doc/src/02000-store.md
+++ b/doc/src/02000-store.md
@@ -16,28 +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
-
-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.
-   Exceptions are:
-
-    * A module MAY collect URIs and put it into a flat list in the subsection
-      "imag.links".
-    * A section "imag.content" MAY BE used for refering to external content.
-      Valid keys in this section are "uri", "file" and "mime", whereas
-        - "uri" refers to the external content
-        - "file" refers to a local variant, this is optional
-        - "mime" stores the MIME-Type of the local variant, if present.
-
-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.
+The sections which MAY or MUST be in the header are defined in the following
+chapters.
+
+#### 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 refering to external content.
+   Valid keys in this section are "uri", "file" and "mime", whereas
+     - "uri" refers to the external content
+     - "file" refers to a local variant, this is optional
+     - "mime" stores the MIME-Type of the local variant, if present.
+
+#### 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}
 
-- 
cgit v1.2.3