|author||Matthias Beyer <firstname.lastname@example.org>||2016-10-27 18:43:29 +0200|
|committer||GitHub <email@example.com>||2016-10-27 18:43:29 +0200|
Merge pull request #825 from matthiasbeyer/readme-rewrite
1 files changed, 63 insertions, 88 deletions
@@ -2,16 +2,16 @@
`imag` is a commandline personal information management suite.
-**This application is in early development. There are _some_ things that work,
-but we do not consider anything stable or usable at this moment. Feel free to
-play around anyways.**
-## What is this / Goal and Functionality
+**This application is in early development. There are _some_ things that work,
+but we do not consider anything stable or usable at this moment. Feel free to
+play around anyways.**
+## Goal / What is imag?
Our (long-term) goal is to
@@ -20,35 +20,23 @@ Our (long-term) goal is to
> management, consists of reusable parts and integrates well with known
> commandline tools.
-We try to implement as many aspects of personal information management (PIM),
-but re-use existing commandline tools.
-We do this by tracking/referring to the data the tools create.
-A user can now link pieces of data (from different tools), tag this data and
-query/search this data using imag.
-So `imag` is more like a data-mining helper than an actual PIM tool, but we
-implement some of the PIM aspects directly in `imag`.
-Parts of PIM (we call them "modules") that are already implemented and basically
-* todo (via taskwarrior, we track the tasks one creates in taskwarrior)
-* counter (just an example, nothing that usable)
-Helper modules that come with `imag` but are not "PIM aspects":
-* linking entries
-* viewing entries
-* tagging entries
-* creating misc entries
-* creating entries that refer to files/directories
+imag is a PIM _helper_. We do not actually implement the PIM functionality, but
+try to interface with existing PIM tools (via their API or via some standard
+format they use, e.g. vcard) to make the data they manage _linkable_
+and _queryable_ in an uniform way.
+imag consists of _modules_ (e.g. `imag-notes`, `imag-diary`), where each module
+covers one PIM aspect.
+The initial approach is to use one PIM tool for one module.
+So you can use `imag-todo` with [taskwarrior](https://taskwarrior.org/)
+but `imag-calendar` with [icalendar](https://en.wikipedia.org/wiki/ICalendar)
-Here goes how to try `imag` out.
+Here is how to try `imag` out.
-`imag` is a _suite_ of tools and you can build them individually.
+`imag` is a _suite/collection_ of tools and you can build them individually.
All subdirectories prefixed with "`libimag"` are libraries for the respective
All subdirectories prefixed with `"imag-"` are binaries and compiling them will
@@ -56,79 +44,69 @@ give you a commandline application.
-By now, there are several targets in the Makefile, fulfilling following roles:
-* `all` is the default and builds every crate in debug mode.
- To build a single module, call `make <module>`, for example `make imag-store`.
-* `release`, as the name implies, builds every module in release mode.
- E.G.: `make imag-store-release` to build "imag-store" in release mode.
-* `install` will install all commandline modules to the default installation
- root (see `man cargo-install`).
- To install a single module, run `make <module>-install`,
- E.G.: `make imag-store-install`
-* `bin`/`lib` are separate targets for either building all binaries or
-* `lib-test` runs `cargo test` for all libraries.
- For testing a single library, E.G.: `make test-libimagstore`.
-* `clean` will run `cargo clean` in every crate.
- For cleaning a single crate, use `make imag-store-clean` for example.
-* to build _only_ the `imag` binary, use the target `imag-bin`
- (`imag-bin-release` for release build, `imag-bin-clean` for `cargo clean`ing).
+We use `make` to automate the build process (as `cargo` is not (yet?) able to
+build several applications at once).
+Make sure to _not_ include some `-j 8` arguments, as cargo parallelizes the
+build process on its own. If you parallelize it with make, you end up with a
+really high load on your system.
+There are several targets for each of the sub-crates in the Makefile:
+| Target | Multi | Purpose | Example |
+| :--- | ----- | :--- | :--- |
+| all | | Build everything, debug mode | `make all` |
+| bin | | Build all binaries, debug mode | `make bin` |
+| lib | | Build all libraries, debug mode | `make lib` |
+| lib-test | | Test all libraries | `make lib-test` |
+| imag-bin | | Build only the `imag` binary, debug mode | `make imag-bin` |
+| check | * | Run `cargo check` | `make check` |
+| clean | * | Remove build artifacts | `make clean` |
+| install | * | Build everything, release mode, install | `make install` |
+| release | * | Build everything, release mode | `make release` |
+| update | * | Run `cargo update` | `make update` |
+The `Multi` targets are callable for each sub-crate. For example you can call
+`make imag-bookmark-check` to run `cargo check` on the `imag-bookmark` subcrate.
-To test out a single module, simply using `cargo run -- <options>` in the
-respective directory will do the trick.
-But you can also `make <module>` and call the binary on the commandline.
-For using it "normally", install the
-binaries as described above, as well as the imag-binary:
+After you build the module you want to play with, you can simply call the binary
+itself with the `--help` flag, to get some help what the module is capable of.
-$> make install
-The installation root of the binaries may not yet be in your $PATH.
-To see where this installation root is check out `man cargo-install`.
-To change the $PATH in bash:
-$> imag --help
-To test, simply add `--help` to one of the above commands:
-$> imag counter --help
+If you installed the module, you can either call `imag-<modulename>` (if the
+install-directory is in your `$PATH`), or install the `imag` binary to call `imag
+<modulename>` (also if everything is in your `$PATH`).
## Staying up-to-date
-Despite we have a [official site for imag](http://imag-pim.org), I do not push
-updates to this site, yet. Anyways, I post a blog articles about what happened
-in the last two weeks every other week.
+We have a [official website for imag](http://imag-pim.org), where I post
+There is no RSS feed, though.
+We also have a [mailinglist](http://imag-pim.org/mailinglist/) where I post
+updates and where discussion and questions are encouraged.
-You can find them
-[on my personal blog, tagged "imag"](http://beyermatthias.de/tags/imag.html)
+There is a blog series which gets a update every other week
+on my blog, where
+[entries are tagged "imag"](http://beyermatthias.de/tags/imag.html).
+I also post non-regular posts about imag things there.
I also post these blog posts
and submit them to [this-week-in-rust](https://this-week-in-rust.org/).
-From time to time I publish an article about imag which does not focus on some
-things that are happening, but rather about something more general.
-For detailed information, please read [the documentation](./doc/).
-You can either read the Markdown files or compile it to HTML/PDF using
+This is a hobby project, so sometimes things are not optimal and might go
+unrecognized and slip through. Feel free to open issues about things you notice!
+Though, we have some documentation in [the ./doc subtree](./doc/)
+which can be compiled to PDF or a website.
+These docs are not published anywhere and are not even integrated into our CI,
+so it might be broken (though it's unlikely).
Developer documentation is also available
[online on github.io](https://matthiasbeyer.github.io/imag/imag_documentation/index.html).
-Please note that the documentation is work in progress as well and may be
## Please contribute!
We are looking for contributors!
@@ -154,6 +132,3 @@ or our [mailinglist](http://imag-pim.org/mailinglist/).
We chose to distribute this software under terms of GNU LGPLv2.1.
-This decision was made to ensure everyone can write applications which use the
-imag core functionality which is distributed with the imag source distribution.