summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthias Beyer <mail@beyermatthias.de>2017-08-11 22:12:43 +0000
committerMatthias Beyer <mail@beyermatthias.de>2017-08-11 22:20:11 +0000
commit1c98dca547cac4bff4ff2b0444b7ac0fd2c8aad9 (patch)
treeafb9eb17ea6e9fee4906f575d7333473d617f014
parent6d73dae8a5faccb5c22aef0959e1278a028e0418 (diff)
downloadimag-1c98dca547cac4bff4ff2b0444b7ac0fd2c8aad9.zip
imag-1c98dca547cac4bff4ff2b0444b7ac0fd2c8aad9.tar.gz
Add basic descriptions for as many modules as possible
-rw-r--r--doc/src/01000-intro.md5
-rw-r--r--doc/src/04020-module-bookmarks.md4
-rw-r--r--doc/src/04020-module-calendar.md9
-rw-r--r--doc/src/04020-module-category.md4
-rw-r--r--doc/src/04020-module-contacts.md5
-rw-r--r--doc/src/04020-module-cuecards.md3
-rw-r--r--doc/src/04020-module-diary.md23
-rw-r--r--doc/src/04020-module-filter.md2
-rw-r--r--doc/src/04020-module-git.md3
-rw-r--r--doc/src/04020-module-gps.md6
-rw-r--r--doc/src/04020-module-habit.md6
-rw-r--r--doc/src/04020-module-images.md2
-rw-r--r--doc/src/04020-module-item.md7
-rw-r--r--doc/src/04020-module-ledger.md2
-rw-r--r--doc/src/04020-module-link.md2
-rw-r--r--doc/src/04020-module-mails.md10
-rw-r--r--doc/src/04020-module-movies.md2
-rw-r--r--doc/src/04020-module-music.md4
-rw-r--r--doc/src/04020-module-news.md2
-rw-r--r--doc/src/04020-module-project.md6
-rw-r--r--doc/src/04020-module-rate.md6
-rw-r--r--doc/src/04020-module-read.md3
-rw-r--r--doc/src/04020-module-receipt.md3
-rw-r--r--doc/src/04020-module-shoppinglists.md2
-rw-r--r--doc/src/04020-module-summary.md3
-rw-r--r--doc/src/04020-module-timetrack.md7
-rw-r--r--doc/src/04020-module-todo.md7
-rw-r--r--doc/src/04020-module-url.md11
-rw-r--r--doc/src/04020-module-wiki.md2
-rw-r--r--doc/src/04020-module-workout.md9
-rw-r--r--doc/src/04020-module-write.md3
l---------libimagmail/README.md1
32 files changed, 119 insertions, 45 deletions
diff --git a/doc/src/01000-intro.md b/doc/src/01000-intro.md
index 37653f6..3d9bd31 100644
--- a/doc/src/01000-intro.md
+++ b/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.
diff --git a/doc/src/04020-module-bookmarks.md b/doc/src/04020-module-bookmarks.md
index d98285a..a8e874e 100644
--- a/doc/src/04020-module-bookmarks.md
+++ b/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.
+
diff --git a/doc/src/04020-module-calendar.md b/doc/src/04020-module-calendar.md
index e171437..aa2b1c3 100644
--- a/doc/src/04020-module-calendar.md
+++ b/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.
diff --git a/doc/src/04020-module-category.md b/doc/src/04020-module-category.md
index ce26fa5..7748c59 100644
--- a/doc/src/04020-module-category.md
+++ b/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.
diff --git a/doc/src/04020-module-contacts.md b/doc/src/04020-module-contacts.md
index 056b486..13e4fe9 100644
--- a/doc/src/04020-module-contacts.md
+++ b/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`.
+
diff --git a/doc/src/04020-module-cuecards.md b/doc/src/04020-module-cuecards.md
index ecfc4f8..e44b443 100644
--- a/doc/src/04020-module-cuecards.md
+++ b/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.
+
diff --git a/doc/src/04020-module-diary.md b/doc/src/04020-module-diary.md
index beac0d5..d62c2bc 100644
--- a/doc/src/04020-module-diary.md
+++ b/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
-diary which creates the entries in the store.
+The diary module giv3s you the possibility to write your diary in imag.
+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
-possibility to implement hourly or even minutely entries is there.
-
-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.
+Exporting the diary is possible, so one can write it in markdown and
+later pass that to pandoc, if desired, to generate a website or book
+from it.
diff --git a/doc/src/04020-module-filter.md b/doc/src/04020-module-filter.md
index 8daa9fe..667995e 100644
--- a/doc/src/04020-module-filter.md
+++ b/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.
diff --git a/doc/src/04020-module-git.md b/doc/src/04020-module-git.md
index 380fd37..14f44b4 100644
--- a/doc/src/04020-module-git.md
+++ b/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.
+
diff --git a/doc/src/04020-module-gps.md b/doc/src/04020-module-gps.md
new file mode 100644
index 0000000..2a2a835
--- /dev/null
+++ b/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.
+
+
+
diff --git a/doc/src/04020-module-habit.md b/doc/src/04020-module-habit.md
index fb1e2ba..1fb7160 100644
--- a/doc/src/04020-module-habit.md
+++ b/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.
diff --git a/doc/src/04020-module-images.md b/doc/src/04020-module-images.md
index df0b02b..aba1e36 100644
--- a/doc/src/04020-module-images.md
+++ b/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.
diff --git a/doc/src/04020-module-item.md b/doc/src/04020-module-item.md
new file mode 100644
index 0000000..0c0cae4
--- /dev/null
+++ b/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).
+
+
diff --git a/doc/src/04020-module-ledger.md b/doc/src/04020-module-ledger.md
index 131a7b7..d4c6b33 100644
--- a/doc/src/04020-module-ledger.md
+++ b/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`.
diff --git a/doc/src/04020-module-link.md b/doc/src/04020-module-link.md
index 8fe2a23..1e3c5e4 100644
--- a/doc/src/04020-module-link.md
+++ b/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.
diff --git a/doc/src/04020-module-mails.md b/doc/src/04020-module-mails.md
index eb6e37a..1e27fbb 100644
--- a/doc/src/04020-module-mails.md
+++ b/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`).
diff --git a/doc/src/04020-module-movies.md b/doc/src/04020-module-movies.md
index 8497cb6..c703ee1 100644
--- a/doc/src/04020-module-movies.md
+++ b/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.
diff --git a/doc/src/04020-module-music.md b/doc/src/04020-module-music.md
index a506d0b..d123f24 100644
--- a/doc/src/04020-module-music.md
+++ b/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.
diff --git a/doc/src/04020-module-news.md b/doc/src/04020-module-news.md
index bc29878..01341ca 100644
--- a/doc/src/04020-module-news.md
+++ b/doc/src/04020-module-news.md
@@ -1,4 +1,4 @@
## News {#sec:modules:news}
-The News module.
+The News module is an RSS reader.
diff --git a/doc/src/04020-module-project.md b/doc/src/04020-module-project.md
index b61fa84..fba9a8d 100644
--- a/doc/src/04020-module-project.md
+++ b/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.
diff --git a/doc/src/04020-module-rate.md b/doc/src/04020-module-rate.md
new file mode 100644
index 0000000..31fe783
--- /dev/null
+++ b/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).
+
+
+
diff --git a/doc/src/04020-module-read.md b/doc/src/04020-module-read.md
index 2bc44ef..b457000 100644
--- a/doc/src/04020-module-read.md
+++ b/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.
+
diff --git a/doc/src/04020-module-receipt.md b/doc/src/04020-module-receipt.md
index d707603..869d201 100644
--- a/doc/src/04020-module-receipt.md
+++ b/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.
+
diff --git a/doc/src/04020-module-shoppinglists.md b/doc/src/04020-module-shoppinglists.md
index 8830542..1b1c5b5 100644
--- a/doc/src/04020-module-shoppinglists.md
+++ b/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.
diff --git a/doc/src/04020-module-summary.md b/doc/src/04020-module-summary.md
index a4aeea2..98d7e0b 100644
--- a/doc/src/04020-module-summary.md
+++ b/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.
+
diff --git a/doc/src/04020-module-timetrack.md b/doc/src/04020-module-timetrack.md
index 00b9ee8..a22fca2 100644
--- a/doc/src/04020-module-timetrack.md
+++ b/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.
+
diff --git a/doc/src/04020-module-todo.md b/doc/src/04020-module-todo.md
index 1c3f539..426052c 100644
--- a/doc/src/04020-module-todo.md
+++ b/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.
diff --git a/doc/src/04020-module-url.md b/doc/src/04020-module-url.md
index cf4cfdc..aed78d9 100644
--- a/doc/src/04020-module-url.md
+++ b/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).
diff --git a/doc/src/04020-module-wiki.md b/doc/src/04020-module-wiki.md
index 5b273fb..019b316 100644
--- a/doc/src/04020-module-wiki.md
+++ b/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.
diff --git a/doc/src/04020-module-workout.md b/doc/src/04020-module-workout.md
index f7ee02b..f14cfdb 100644
--- a/doc/src/04020-module-workout.md
+++ b/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.
diff --git a/doc/src/04020-module-write.md b/doc/src/04020-module-write.md
index c81e4cc..d3438e4 100644
--- a/doc/src/04020-module-write.md
+++ b/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.
+
diff --git a/libimagmail/README.md b/libimagmail/README.md
new file mode 120000
index 0000000..d5d8fb0
--- /dev/null
+++ b/libimagmail/README.md
@@ -0,0 +1 @@
+../doc/src/04020-module-mails.md \ No newline at end of file