Add basic descriptions for as many modules as possible

doc/src/01000-intro.md

@@ -1,7 +1,10 @@
 # Introduction {#sec:introduction}
 
 This document aims to be the user documentation for imag, the personal
-information management suite for the commandline.
+information management suite for the commandline. Besides beeing a documentation,
+it servey also as "roadmap" where this project should go. Parts which are not
+yet implemented might be documented already, therefore. A list on what is 
+implemented and what is not can be found at the end of this document.
 
 If you have any objections, suggestions for improvements, bugs, etc, please file
 them in the github repository you got this documentation from.

doc/src/04020-module-bookmarks.md

@@ -1,4 +1,6 @@
 ## Bookmarks {#sec:modules:bookmarks}
 
-The Bookmarks module.
+The Bookmarks module is for keeping URLs as bookmarks, tagging and categorizing them and
+finally also open them in the browser.
+
 

doc/src/04020-module-calendar.md

@@ -1,4 +1,11 @@
 ## Calendar {#sec:modules:calendar}
 
-The Calendar module.
+The calendar module implements a commandline calendar like khal. The calendar data itself is retrieved from icalendar files which should be located outside of the imag store. imag does not handle syncing of these files. `vdirsyncer` may be your tool of choise here. 
 
+imag can show events from the calendar(s) like any other commandline calendar tool and of course can also add, delete or edit entries  (interactively or via commandline parameters).
+
+### Internals
+
+What imag does internally is described in this section.
+
+imag creates one entry in the store for one `icalendar` file. These entries are basically references to the real data. If an  `icalendar` file is removed from the filesystem, imag does not delete it from the sfore if not told explicitely.

doc/src/04020-module-category.md

@@ -1,4 +1,6 @@
 ## Category {#sec:modules:category}
 
-The Category module.
+The Category module is a plumbing command for setting an entrys category. A category must exist before it can be set for an entry. That, and that each entry may have one or no category is the difference from tags.
+
+Also: Categories may have sub-categories.
 

doc/src/04020-module-contacts.md

@@ -1,4 +1,7 @@
 ## Contacts {#sec:modules:contacts}
 
-The Contacts module.
+The Contacts module serves as a vcard viewer which is also able to alter, vcard files (either interactively or via commandline parameters).
+
+The contacts module can also call other programs and pass contact information to them, for example `mutt`.
+
 

doc/src/04020-module-cuecards.md

@@ -1,4 +1,5 @@
 ## Cuecards {#sec:modules:cuecards}
 
-The Cuecards module.
+The Cuecards module implements "cuacards-learning" like you probably did it in school.
+
 

doc/src/04020-module-diary.md

@@ -1,21 +1,12 @@
 ## Diary {#sec:modules:diary}
 
-The Diary module.
+The diary module is for keeping your diary notes.
 
-The diary module is for keeping your diary notes. It offers a self-implemented
+The diary module giv3s you the possibility to write your diary in imag.
-diary which creates the entries in the store.
+It offers daily, hourly and minutely entries (the latter beeing more like
+a private tumble-blog).
 
-As of now there is only the possibility to create daily entries, but the
+Exporting the diary is possible, so one can write it in markdown and 
-possibility to implement hourly or even minutely entries is there.
+later pass that to pandoc, if desired, to generate a website or book
-
+from it.
-The module offers commands to create, delete, edit and list diary entries.
-
-### Backends
-
-At this moment, only the imag store is an available backend and therefor diary
-entries are written to the imag store.
-
-There is no implementation for other diary software planned _yet_, but there
-might be a [jrnl](http://jrnl.sh/) backend some time, but not as long as `jrnl`
-does not provide a multi-file storage system.
 

doc/src/04020-module-filter.md

@@ -1,4 +1,4 @@
 ## Filter {#sec:modules:filter}
 
-The Filter module.
+The Filter module is only of use when chaining up imag calls via bash pipes. It can be used to filter out entries based on some parameters, like for example whether a certain header field is set or not.
 

doc/src/04020-module-git.md

@@ -1,4 +1,5 @@
 ## Git {#sec:modules:git}
 
-The Git module.
+The Git module provises a convenient way to call the git executable on the imag store without having to `cd` to it first. Nothing more.
+
 

doc/src/04020-module-gps.md

@@ -0,0 +1,6 @@
+## GPS {#sec:modules:gps}
+
+The GPS module is a plumbing command for attaching a GPS coordinate to an entry.
+
+
+

doc/src/04020-module-habit.md

@@ -1,4 +1,8 @@
 ## Habit {#sec:modules:habit}
 
-The Habit module.
+The Habit module is a habit tracker. One can add habits, specify how often they should be done and instantiate them.
+
+Example: After creating a new habit "Sunday Run", which should be done on sundays, one can mark (only on sundays of course) that the habit was done. Statistics and number-crunching can be done later on, after there is some habit data there.
+
+Exports to CSV are possible.
 

doc/src/04020-module-images.md

@@ -1,4 +1,4 @@
 ## Images {#sec:modules:images}
 
-The Images module.
+The Images module is for tagging, categorizing and sorting images. GPS coordinates can be attached to image references. Images can be put into collections. Image viewing programs can be called from imag. If an image gets modified (for example via darktable) and a new image file is created, the Image module can be used to group them.
 

doc/src/04020-module-item.md

@@ -0,0 +1,7 @@
+## Item {#sec:modules:item}
+
+The Item module is a plumbing command to create entries for items in the imag store.
+
+Items can be anything. For example, one could create a Tomato and a Bread as item to add them later in the shopping list (as in imag-shoppinglist), but also a computer and a printer can be created to use them later in a project (as in imag-project).
+
+

doc/src/04020-module-ledger.md

@@ -1,4 +1,4 @@
 ## Ledger {#sec:modules:ledger}
 
-The Ledger module.
+The Ledger module implements a ledger like `beancount`.
 

doc/src/04020-module-link.md

@@ -1,7 +1,5 @@
 ## Link {#sec:modules:link}
 
-The Linking module.
-
 The linking module `imag-link` is one of the plumbing modules.
 It offers the possibility to link entries in the store.
 

doc/src/04020-module-mails.md

@@ -1,4 +1,12 @@
 ## Mails {#sec:modules:mails}
 
-The Mails module.
+The Mails module implements a commandline email client. Emails can be written (via `$EDITOR`) and viewed, also in threads. Emails can be crawled for creating new contacts.
+
+A Text User Interface is not planned, but might be there at some point.
+
+The mail module implements a minimal Email client. It does not handle IMAP syncing or SMTP things, it is just a _viewer_ for emails (a MUA).
+
+The goal of the initial implementation is only a CLI, not a TUI like mutt offers, for example (but that might be implemented later). As this is an imag module, it also creates references to mails inside the imag store which can be used by other tools then (for example `imag-link` to link an entry with a mail - or the imag entry representing that mail).
+
+So this module offers functionality to read (Maildir) mailboxes, search for and list mails and mail-threads and reply to mails (by spawning the `$EDITOR`).
 

doc/src/04020-module-movies.md

@@ -1,4 +1,4 @@
 ## Movies {#sec:modules:movies}
 
-The Movies module.
+The Movies module is for categorizing, rating and tagging movies.
 

doc/src/04020-module-music.md

@@ -1,4 +1,6 @@
 ## Music {#sec:modules:music}
 
-The Music module.
+The Music module is for rating, categorizing, tagging and enjoying music. It offers functionality to fetch lyrics, create automatically linkings from genre entries to music files (music files are represented as a entry jn imag), combining songs in albums and albums in artists, etc.
+
+A scrobble server may be implemented at some point to provide more ways to retrieving data over ones music taste. Suggested songs (from the own library of music or via external tools like musicbrainz) may be a feature that comes aith the scrobble server.
 

doc/src/04020-module-news.md

@@ -1,4 +1,4 @@
 ## News {#sec:modules:news}
 
-The News module.
+The News module is an RSS reader.
 

doc/src/04020-module-project.md

@@ -1,4 +1,8 @@
 ## Project {#sec:modules:project}
 
-The Project module.
+The Project module can be used to plan and organize projects, though does not offer ways to share these plans with others. If that is desired, a new store should be created, put under version controll (possibly git) and shared via this mechanism.
+
+The project tool integrates the timetracking module as well as the todo module.
+
+A project is represented by a single imag entry. Notes, subprojects, todos, timetrackings and other things are linked to the project. A project does not necessarily have to be a programming project, but could be a project for building a house or losing weight for example.
 

doc/src/04020-module-rate.md

@@ -0,0 +1,6 @@
+## Rate {#sec:modules:rate}
+
+The Rate module is another plumbing command. It simply offers rating functionality, whereas allowed values are 0-10 (0 beeing equal to no rating).
+
+
+

doc/src/04020-module-read.md

@@ -1,4 +1,5 @@
 ## Read {#sec:modules:read}
 
-The Read module.
+The Read module is a plumbing command for reading entries from the store and writing them to stdout for further processing.
+
 

doc/src/04020-module-receipt.md

@@ -1,4 +1,5 @@
 ## Receipt {#sec:modules:receipt}
 
-The Receipt module.
+The Receipt module is for tracking, categorizing, tagging, quering and managing receipts.
+
 

doc/src/04020-module-shoppinglists.md

@@ -1,4 +1,4 @@
 ## Shoppinglists {#sec:modules:shoppinglists}
 
-The Shoppinglists module.
+The Shoppinglists module provides functionality for creating shopping lists and organizing them. A shoppinglist can be printed and them be used to go shopping, of course.
 

doc/src/04020-module-summary.md

@@ -1,4 +1,5 @@
 ## Summary {#sec:modules:summary}
 
-The Summary module.
+The Summary module is a wrapper to call a list (specified in the config file) of imag commands and viewing their outputs.
+
 

doc/src/04020-module-timetrack.md

@@ -1,4 +1,9 @@
 ## Timetrack {#sec:modules:timetrack}
 
-The Timetrack module.
+The Timetrack module implements a `timewarrior`-like timetracking functionality for imag.
+
+Each timetracking is a 'tag' which can be started and stopped. These tags are _no_ tags as in imag-tag, but timetracking-tags. 
+
+Summaries can be printed, also filtered by tags if desired.
+
 

doc/src/04020-module-todo.md

@@ -1,4 +1,7 @@
-## Todos {#sec:modules:todos}
+## Todo {#sec:modules:todo}
+
+The Todo module implements `taskwarrior` functionality by integrating taskwarrior itself into imag.
+
+Each taskwarrior task s referenced from imag and represented as imag entry, thus making it linkable by other imag entries.
 
-The Todos module.
 

doc/src/04020-module-url.md

@@ -1,4 +1,13 @@
 ## Url {#sec:modules:url}
 
-The Url module.
+The Url module is a plumbing module to put URLs into the imag store.
 
+### Implementation
+
+The implementation of the URL module saves URLs on a per-entry basis. This means that each URL is hashed (with something like SHA512) and the hash is used as filename. The scheme is as follows:
+
+    /url/<hash of the domain>/<hash of the full URL>
+
+This scheme results in grouping URLs of the same domain (for example https://imag-pim.org) but distinction of the actual full URL, while still deduplicating URLs. Entering the same URL twice results in the same entry.
+
+This module does nothing more on its own. Its functionality may be used elsewhere (for example a bookmark module).

doc/src/04020-module-wiki.md

@@ -1,4 +1,4 @@
 ## Wiki {#sec:modules:wiki}
 
-The Wiki module.
+The Wiki module provides a personal wiki implementation.
 

doc/src/04020-module-workout.md

@@ -1,4 +1,11 @@
 ## Workout {#sec:modules:workout}
 
-The Workout module.
+The Workout module is for tracking workouts. Burned calories, walked kilometers, lifting sets and all the things can be entered.
+
+### Submodules
+
+Each type of workout can be handled with one subcommand of the module, whereas training seasions can be used to group types of workouts (for example swimming and running).
+
+A step-counter functionality is implemented as first submodule.
+Import functionality for the step-counter submodule is available for importing from (for example) an Android step-counter App.
 

doc/src/04020-module-write.md

@@ -1,4 +1,5 @@
 ## Write {#sec:modules:write}
 
-The Write module.
+The Write module is a plumbing command for reading a store feom stdin and writing it to the filesystem.
+
 

libimagmail/README.md

@@ -0,0 +1 @@
+../doc/src/04020-module-mails.md