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

67
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}
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.