matthiasbeyer/imag
1
0
Fork 0
Code Releases Activity

Auto merge of #90 - matthiasbeyer:doc-define-store-format, r=matthiasbeyer

Browse source 
Define file format

Related to #76.

@TheNeikos , @neithernut Would like to hear suggestions.
This commit is contained in:
Homu 2016-01-13 01:52:52 +09:00
commit ec6ac7794f
1 changed files with 75 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -2,5 +2,80 @@
## File Format {#sec:thestore:fileformat}
The content in the store MUST BE encoded in either Unicode UTF-8 or ASCII.
Each "Entry" (File) MUST HAVE a "Header" component as well as a "Content"
component.
Each "Entry" in the store MUST start with three single dashes ("-") followed
by a newline character, named "initial marker" in the following chapter.
The Header follows the initial marker (@sec:thestore:fileformat:header).
The Header MUST BE followed by a line which contains three single dashes ("-")
and a newline character, called "header-close marker" in the following
chapter.
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.
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.
### Content Format {#sec:thestore:fileformat:content}
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.
### Example {#sec:thestore:fileformat:example}
An example for a file in the store follows.
```
---
[imag]
nothing = here
[imag.examplemodule]
and_nothing = here_as_well
---
This is an example text, written by the user.
```
## File organization {#sec:thestore:fileorganization}
The "Entries" are stored as files in the "Store", which is a directory the
user has access to.
The store MAY exist in the users Home-directory or any other directory the
user has Read-Write-Access to.
The Path of each File is shown as absolute path in this paper, while the root
is always the store directory.
This Path is named "Storepath".
So if the store exists in `/home/user/store/`, a file with the Storepath
`/example.file` is (on the filesystem) located at
`/home/user/store/example.file`.
A Storepath contains one predefined part: The module name of the Module the
Entry belongs to, in lowercase letters.
So if a Module named "ExampleModule" stores a file in the Store, the Storepath
for a file with the name "example.file" is "/examplemodule/example.file".
Any number of subdirectories MAY BE used, so creating folder hierarchies is
possible and valid.