matthiasbeyer/imag
1
0
Fork 0
Code Releases Activity

Merge pull request #1232 from matthiasbeyer/doc-overhaul

Browse source 
Doc overhaul
This commit is contained in:
Matthias Beyer 2018-02-07 10:07:27 +01:00 committed by GitHub
commit 4d026131a1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 34 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
doc/src/01000-intro.md
View file

@ -1,14 +1,8 @@
# Introduction {#sec:introduction} # Introduction {#sec:introduction}
This document is the user documentation for imag, the personal This document is the user documentation for imag, the personal
information management suite for the commandline. Besides beeing a documentation, information management suite for the commandline. Besides being a documentation,
it serves also as "roadmap" where this project should go. Parts which are not it serves also as "roadmap" where this project should go.
yet implemented might be documented already, therefore. Also, because this is a
hobby thing, parts which are implemented might be documented falsely or not at
all.
A list on what is implemented and what is not can be found at the end of this
document.
It might be outdated though.
**Basically: This is Hobby stuff. Expect incompleteness, false statements and **Basically: This is Hobby stuff. Expect incompleteness, false statements and
generally read with big grain of salt.** generally read with big grain of salt.**
@ -16,40 +10,40 @@ generally read with big grain of salt.**
If you have any objections, suggestions for improvements, bugs, etc, please file If you have any objections, suggestions for improvements, bugs, etc, please file
them. them.
A way to reach out to the imag project maintainer(s) is described in the A way to reach out to the imag project maintainer(s) is described in the
CONTRIBUTING file of the repository or in this document, on the appropriate CONTRIBUTING file of the repository or in this document, in the appropriate
section. section.
## The Problem {#sec:intro:problem} ## The Problem {#sec:intro:problem}
The problem imag wants to solve is rather simple. When the project was The problem this project tries to solve is to provide a modular commandline
initiated, there was no PIM-Suite available which application for personal information management.
* was for this domain of users ("power-users", "commandline users") It targets "power users" or "commandline users", uses plain text as a storage
* uses plain text as storage format format and tries to be scriptable.
* was scriptable imag offers the ability to link data from different "PIM aspects" (such as
* was modular "diary" and "bookmark" for example).
* contained functionality to link content
The latter point is the bigger one: "imag" wants to offer the ability for users One major goal of imag is to make the PIM data traverseable and queryable.
to link content. This means not only that a contact may be linked to a For example: a wiki article can be linked to an appointment which is linked to a
date, but that _all things_ can be linked together. For example that a wiki todo which is linked to a note which is linked to a contact.
article can be linked to a date which is linked to a todo which is linked to a
note which is linked to a contact.
Also, having an all-in-one scriptable modular commandline personal information imag wants to offer an all-in-one scriptable modular commandline personal
management suite seemed nice at the time and still does. information management suite for all PIM aspects one can think of.
Because imag uses plain text (TOML headers for structured data and plain text
which can be rendered using markdown, for example, for continuous text)
the user is always able to access their data without the imag tools at hand.
## The Approach {#sec:intro:approach} ## The Approach {#sec:intro:approach}
The approach "imag" takes on solving this problem is to store content in a The approach "imag" takes on solving this problem is to store content in a
"store" and persisting content in a unified way. "store" and persisting content in a unified way.
Meta-Information is attached to the content which can be used to store Meta-information is attached to the content which can be used to store
structured data. structured data.
This can be used to implement a variety of "domain modules" using the store. This can be used to implement a variety of "domain modules" using the store.
While content is stored in _one_ place, imag does not duplicate content. While content is stored in _one_ place, imag does not duplicate content.
imag does not copy or move icalendar files, emails, vcard files, music or imag does not copy or move icalendar files, emails, vcard files, music or
movies to the store, but indexes them and stores the meta-information in the movies to the store, but creates references to the actual files and stores
store. meta-information in the store.
Detailed explanation on this approach follows in the chapters of this work. Detailed explanation on this approach follows in the chapters of this work.
@ -65,3 +59,15 @@ make it visible to imag this way.
This is a technical detail a user does not necessarily need to know, but as imag This is a technical detail a user does not necessarily need to know, but as imag
is intended for power-users anyways, we could say it fits here. is intended for power-users anyways, we could say it fits here.
## Alternative Projects {#sec:intro:alternatives}
imag is not the only project which tries to solve that particular problem. For
example there is
[org mode](https://orgmode.org)
for the [emacs](https://www.gnu.org/software/emacs/) text editor.
There is also [zim](http://zim-wiki.org/), a desktop wiki editor which is
intended to be used for a personal wiki.
The difference between imag and the mentioned projects is that imag is not there
yet. Some parts can be used, though it is far away from being feature-complete.

3
doc/src/01010-architecture.md
View file

@ -65,7 +65,8 @@ With the things from above, a module could have the following architecture:
+-----------------------------------+---------+ +-----------------------------------+---------+
``` ```
The foundation of all imag modules is the store, as one can see in the image. The foundation of all imag modules is the store, as one can see in the
visualization from above.
Above the store library there is the libimagrt, which provides the basic runtime Above the store library there is the libimagrt, which provides the basic runtime
and access to the `Store` object. and access to the `Store` object.
Cross-cutting, there is the error library (and possibly Cross-cutting, there is the error library (and possibly