matthiasbeyer/imag
1
0
Fork 0
Code Releases Activity

Auto merge of #122 - matthiasbeyer:doc/redefine-header, r=matthiasbeyer

Browse source 
Doc/redefine header

As proposed in personal discussion with @TheNeikos
This commit is contained in:
Homu 2016-01-19 09:08:50 -08:00
commit 705ad884bc
1 changed files with 48 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
doc/src/02000-store.md
View file

@ -16,21 +16,41 @@ The content follows the header-close marker (@sec:thestore:fileformat:content).
### Header Format {#sec:thestore:fileformat:header} ### Header Format {#sec:thestore:fileformat:header}
The header format MUST BE "TOML". 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 #### Header section: "imag" {#sec:thestore:fileformat:header:imag}
data goes to.
The contents of these sections are edited via commandline calls or by the 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. 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 This "imag" section MUST contain the following keys
dedicated section, as TOML supports it.
The name of the section MUST BE the name of the module in lowercase 1. A "version" Key. The version stored here is the version of the Store, the
letters. Entry was created with.
The section MAY BE empty.
1. Other OPTIONAL sections which are named and edited by the user. The program The "imag" section MAY contain
MUST NOT touch the contents of these sections, except explicitely asked by
the user to do so. 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} ### 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. textual content.
The content MAY BE rendered as Markdown or other markup format for the users The content MAY BE rendered as Markdown or other markup format for the users
convenience. convenience.
The program SHOULD NOT expect any particular markup format, except explicitely The Store library MUST NOT expect any particular markup format.
configured in the header of the file.
### Example {#sec:thestore:fileformat:example} ### Example {#sec:thestore:fileformat:example}
@ -48,9 +67,19 @@ An example for a file in the store follows.
``` ```
--- ---
[imag] [imag]
nothing = here version = "0.1.0"
[imag.examplemodule]
and_nothing = here_as_well [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. This is an example text, written by the user.