matthiasbeyer/imag
1
0
Fork 0
Code Releases Activity

Merge pull request #825 from matthiasbeyer/readme-rewrite

Browse source 
Readme rewrite
This commit is contained in:
Matthias Beyer 2016-10-27 18:43:29 +02:00 committed by GitHub
commit 85e95d142c
1 changed files with 61 additions and 86 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

147
README.md
View file

@ -2,16 +2,16 @@
`imag` is a commandline personal information management suite. `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.**
[![Build Status](https://travis-ci.org/matthiasbeyer/imag.svg?branch=master)](https://travis-ci.org/matthiasbeyer/imag) [![Build Status](https://travis-ci.org/matthiasbeyer/imag.svg?branch=master)](https://travis-ci.org/matthiasbeyer/imag)
[![Issue Stats](http://www.issuestats.com/github/matthiasbeyer/imag/badge/pr?style=flat-square)](http://www.issuestats.com/github/matthiasbeyer/imag) [![Issue Stats](http://www.issuestats.com/github/matthiasbeyer/imag/badge/pr?style=flat-square)](http://www.issuestats.com/github/matthiasbeyer/imag)
[![Issue Stats](http://www.issuestats.com/github/matthiasbeyer/imag/badge/issue?style=flat-square)](http://www.issuestats.com/github/matthiasbeyer/imag) [![Issue Stats](http://www.issuestats.com/github/matthiasbeyer/imag/badge/issue?style=flat-square)](http://www.issuestats.com/github/matthiasbeyer/imag)
[![license](https://img.shields.io/github/license/matthiasbeyer/imag.svg?maxAge=2592000?style=flat-square)]() [![license](https://img.shields.io/github/license/matthiasbeyer/imag.svg?maxAge=2592000?style=flat-square)]()
## 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 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 > management, consists of reusable parts and integrates well with known
> commandline tools. > commandline tools.
We try to implement as many aspects of personal information management (PIM), imag is a PIM _helper_. We do not actually implement the PIM functionality, but
but re-use existing commandline tools. try to interface with existing PIM tools (via their API or via some standard
We do this by tracking/referring to the data the tools create. format they use, e.g. vcard) to make the data they manage _linkable_
A user can now link pieces of data (from different tools), tag this data and and _queryable_ in an uniform way.
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
working:
* todo (via taskwarrior, we track the tasks one creates in taskwarrior) imag consists of _modules_ (e.g. `imag-notes`, `imag-diary`), where each module
* diary covers one PIM aspect.
* notes The initial approach is to use one PIM tool for one module.
* bookmarks So you can use `imag-todo` with [taskwarrior](https://taskwarrior.org/)
* counter (just an example, nothing that usable) but `imag-calendar` with [icalendar](https://en.wikipedia.org/wiki/ICalendar)
files.
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
## Building/Running ## Building/Running
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 "`libimag"` are libraries for the respective
binaries. binaries.
All subdirectories prefixed with `"imag-"` are binaries and compiling them will All subdirectories prefixed with `"imag-"` are binaries and compiling them will
@ -56,79 +44,69 @@ give you a commandline application.
### Building ### Building
By now, there are several targets in the Makefile, fulfilling following roles: 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.
* `all` is the default and builds every crate in debug mode. There are several targets for each of the sub-crates in the Makefile:
To build a single module, call `make <module>`, for example `make imag-store`.
* `release`, as the name implies, builds every module in release mode. | Target | Multi | Purpose | Example |
E.G.: `make imag-store-release` to build "imag-store" in release mode. | :--- | ----- | :--- | :--- |
* `install` will install all commandline modules to the default installation | all | | Build everything, debug mode | `make all` |
root (see `man cargo-install`). | bin | | Build all binaries, debug mode | `make bin` |
To install a single module, run `make <module>-install`, | lib | | Build all libraries, debug mode | `make lib` |
E.G.: `make imag-store-install` | lib-test | | Test all libraries | `make lib-test` |
* `bin`/`lib` are separate targets for either building all binaries or | imag-bin | | Build only the `imag` binary, debug mode | `make imag-bin` |
libraries. | check | * | Run `cargo check` | `make check` |
* `lib-test` runs `cargo test` for all libraries. | clean | * | Remove build artifacts | `make clean` |
For testing a single library, E.G.: `make test-libimagstore`. | install | * | Build everything, release mode, install | `make install` |
* `clean` will run `cargo clean` in every crate. | release | * | Build everything, release mode | `make release` |
For cleaning a single crate, use `make imag-store-clean` for example. | update | * | Run `cargo update` | `make update` |
* to build _only_ the `imag` binary, use the target `imag-bin`
(`imag-bin-release` for release build, `imag-bin-clean` for `cargo clean`ing). 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.
### Running ### Running
To test out a single module, simply using `cargo run -- <options>` in the After you build the module you want to play with, you can simply call the binary
respective directory will do the trick. itself with the `--help` flag, to get some help what the module is capable of.
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:
``` If you installed the module, you can either call `imag-<modulename>` (if the
$> make install install-directory is in your `$PATH`), or install the `imag` binary to call `imag
``` <modulename>` (also if everything is in your `$PATH`).
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:
```bash
$> PATH=$PATH:~/.cargo/bin
$> imag --help
```
To test, simply add `--help` to one of the above commands:
```bash
$> imag counter --help
```
## Staying up-to-date ## Staying up-to-date
Despite we have a [official site for imag](http://imag-pim.org), I do not push We have a [official website for imag](http://imag-pim.org), where I post
updates to this site, yet. Anyways, I post a blog articles about what happened [release notes](http://imag-pim.org/releases/).
in the last two weeks every other week. There is no RSS feed, though.
You can find them We also have a [mailinglist](http://imag-pim.org/mailinglist/) where I post
[on my personal blog, tagged "imag"](http://beyermatthias.de/tags/imag.html) updates and where discussion and questions are encouraged.
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 I also post these blog posts
[on reddit](https://www.reddit.com/r/rust/search?q=What%27s+coming+up+in+imag&restrict_sr=on) [on reddit](https://www.reddit.com/r/rust/search?q=What%27s+coming+up+in+imag&restrict_sr=on)
and submit them to [this-week-in-rust](https://this-week-in-rust.org/). 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.
## Documentation ## Documentation
For detailed information, please read [the documentation](./doc/). This is a hobby project, so sometimes things are not optimal and might go
You can either read the Markdown files or compile it to HTML/PDF using unrecognized and slip through. Feel free to open issues about things you notice!
[pandoc](http://pandoc.org).
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 Developer documentation is also available
[online on github.io](https://matthiasbeyer.github.io/imag/imag_documentation/index.html). [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
outdated.
## Please contribute! ## Please contribute!
We are looking for contributors! 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. 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.