From 88930da7962beabab8d7a92419b8696fd8dca107 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jan 2016 14:41:44 +0100 Subject: [PATCH 1/6] Add fields in the header section "imag" --- doc/src/02000-store.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md index 8290f915..5a72f372 100644 --- a/doc/src/02000-store.md +++ b/doc/src/02000-store.md @@ -25,9 +25,16 @@ The contents of the header contain 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. + 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. From cafc6dbadfb7ab24386385aefbce8bb4ae413bd6 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jan 2016 15:58:22 +0100 Subject: [PATCH 2/6] Rewrite chapter on header contents --- doc/src/02000-store.md | 51 ++++++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 19 deletions(-) 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 +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. - Exceptions are: +#### Header section: "imag" {#sec:thestore:fileformat:header:imag} - * 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. +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. -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. +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} From adaa6b69ec93d6768d7e86d9ca2c444e4160831c Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jan 2016 16:01:26 +0100 Subject: [PATCH 3/6] Clearify content section format (as seen by the store library) --- doc/src/02000-store.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md index 10e497e3..1ba6d65a 100644 --- a/doc/src/02000-store.md +++ b/doc/src/02000-store.md @@ -58,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} From 9d9efa76ea41cb970871c2a1565460d20606e8ef Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jan 2016 16:10:31 +0100 Subject: [PATCH 4/6] Update example --- doc/src/02000-store.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md index 1ba6d65a..79b35409 100644 --- a/doc/src/02000-store.md +++ b/doc/src/02000-store.md @@ -67,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. From 6183efedbc5a921cd3ef96cc56aab90f67e562d9 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jan 2016 16:20:05 +0100 Subject: [PATCH 5/6] Fix: Remove "mime"-key in header We don't need this one, actually. --- doc/src/02000-store.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md index 79b35409..d35cbb03 100644 --- a/doc/src/02000-store.md +++ b/doc/src/02000-store.md @@ -36,10 +36,9 @@ 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 + Valid keys in this section are "uri" and "file", 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} From e44e413b0842507ea8de0c9fd1e8399bee0e4e29 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jan 2016 17:27:23 +0100 Subject: [PATCH 6/6] Clear the "imag.content" key definition. --- doc/src/02000-store.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md index d35cbb03..6d09db0c 100644 --- a/doc/src/02000-store.md +++ b/doc/src/02000-store.md @@ -35,10 +35,11 @@ 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" and "file", whereas - - "uri" refers to the external content - - "file" refers to a local variant, this is optional +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}