summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthias Beyer <mail@beyermatthias.de>2018-02-07 10:07:27 +0100
committerGitHub <noreply@github.com>2018-02-07 10:07:27 +0100
commit4d026131a1a8b18b4eb8cb25e165dbc645ab9af0 (patch)
treed0ae43bda994c7e6b92974c65c7e654fa1975c46
parent73c1dbbbe8707c2287f90259b3921c0ed57b5683 (diff)
parent979a25c4d6b703cdac14915baa079ac7f796e438 (diff)
downloadimag-4d026131a1a8b18b4eb8cb25e165dbc645ab9af0.zip
imag-4d026131a1a8b18b4eb8cb25e165dbc645ab9af0.tar.gz
Merge pull request #1232 from matthiasbeyer/doc-overhaul
Doc overhaul
-rw-r--r--doc/src/01000-intro.md58
-rw-r--r--doc/src/01010-architecture.md3
2 files changed, 34 insertions, 27 deletions
diff --git a/doc/src/01000-intro.md b/doc/src/01000-intro.md
index 7c562bb..76a67b1 100644
--- a/doc/src/01000-intro.md
+++ b/doc/src/01000-intro.md
@@ -1,14 +1,8 @@
# Introduction {#sec:introduction}
This document is the user documentation for imag, the personal
-information management suite for the commandline. Besides beeing a documentation,
-it serves also as "roadmap" where this project should go. Parts which are not
-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.
+information management suite for the commandline. Besides being a documentation,
+it serves also as "roadmap" where this project should go.
**Basically: This is Hobby stuff. Expect incompleteness, false statements and
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
them.
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.
## The Problem {#sec:intro:problem}
-The problem imag wants to solve is rather simple. When the project was
-initiated, there was no PIM-Suite available which
+The problem this project tries to solve is to provide a modular commandline
+application for personal information management.
-* was for this domain of users ("power-users", "commandline users")
-* uses plain text as storage format
-* was scriptable
-* was modular
-* contained functionality to link content
+It targets "power users" or "commandline users", uses plain text as a storage
+format and tries to be scriptable.
+imag offers the ability to link data from different "PIM aspects" (such as
+"diary" and "bookmark" for example).
-The latter point is the bigger one: "imag" wants to offer the ability for users
-to link content. This means not only that a contact may be linked to a
-date, but that _all things_ can be linked together. For example that a wiki
-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.
+One major goal of imag is to make the PIM data traverseable and queryable.
+For example: a wiki article can be linked to an appointment 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
-management suite seemed nice at the time and still does.
+imag wants to offer an all-in-one scriptable modular commandline personal
+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 "imag" takes on solving this problem is to store content in a
"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.
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.
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
-store.
+movies to the store, but creates references to the actual files and stores
+meta-information in the store.
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
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.
+
diff --git a/doc/src/01010-architecture.md b/doc/src/01010-architecture.md
index 2ad3268..f3d98a9 100644
--- a/doc/src/01010-architecture.md
+++ b/doc/src/01010-architecture.md
@@ -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
and access to the `Store` object.
Cross-cutting, there is the error library (and possibly