Rewrite README.md
This commit is contained in:
parent
b8916c3526
commit
73b11e4bd2
1 changed files with 107 additions and 150 deletions
257
README.md
257
README.md
|
|
@ -1,13 +1,118 @@
|
||||||
# imag - [imag-pim.org](http://imag-pim.org)
|
# imag - [imag-pim.org](http://imag-pim.org)
|
||||||
|
|
||||||
Imag is a CLI PIM suite you can
|
`imag` is a commandline personal information management suite.
|
||||||
integrate in your tools of choice (Editor, MUA, RSS reader, etc etc).
|
|
||||||
|
**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.**
|
||||||
|
|
||||||
[](https://travis-ci.org/matthiasbeyer/imag)
|
[](https://travis-ci.org/matthiasbeyer/imag)
|
||||||
[](http://www.issuestats.com/github/matthiasbeyer/imag)
|
[](http://www.issuestats.com/github/matthiasbeyer/imag)
|
||||||
[](http://www.issuestats.com/github/matthiasbeyer/imag)
|
[](http://www.issuestats.com/github/matthiasbeyer/imag)
|
||||||
[]()
|
[]()
|
||||||
|
|
||||||
|
## What is this / Goal and Functionality
|
||||||
|
|
||||||
|
Our (long-term) goal is to
|
||||||
|
|
||||||
|
> Create a fast, reliable commandline personal
|
||||||
|
> information management suite which covers all aspects of personal information
|
||||||
|
> 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
|
||||||
|
working:
|
||||||
|
|
||||||
|
* todo (via taskwarrior, we track the tasks one creates in taskwarrior)
|
||||||
|
* diary
|
||||||
|
* notes
|
||||||
|
* bookmarks
|
||||||
|
* 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
|
||||||
|
|
||||||
|
## Building/Running
|
||||||
|
|
||||||
|
Here goes how to try `imag` out.
|
||||||
|
|
||||||
|
`imag` is a _suite_ of tools and you can build them individually.
|
||||||
|
All subdirectories prefixed with "`libimag"` are libraries for the respective
|
||||||
|
binaries.
|
||||||
|
All subdirectories prefixed with `"imag-"` are binaries and compiling them will
|
||||||
|
give you a commandline application.
|
||||||
|
|
||||||
|
### Building
|
||||||
|
|
||||||
|
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
|
||||||
|
libraries.
|
||||||
|
* `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).
|
||||||
|
|
||||||
|
### Running
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```
|
||||||
|
$> 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$> PATH=$PATH:~/.cargo/bin
|
||||||
|
$> imag --help
|
||||||
|
```
|
||||||
|
|
||||||
|
To test, simply add `--help` to one of the above commands:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$> imag counter --help
|
||||||
|
```
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
For detailed information, please read [the documentation](./doc/).
|
||||||
|
You can either read the Markdown files or compile it to HTML/PDF using
|
||||||
|
[pandoc](http://pandoc.org).
|
||||||
|
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
|
||||||
|
outdated.
|
||||||
|
|
||||||
## Please contribute!
|
## Please contribute!
|
||||||
|
|
||||||
We are looking work contributors!
|
We are looking work contributors!
|
||||||
|
|
@ -21,154 +126,6 @@ things!
|
||||||
|
|
||||||
Also have a look at [the CONTRIBUTING.md file](./CONTRIBUTING.md)!
|
Also have a look at [the CONTRIBUTING.md file](./CONTRIBUTING.md)!
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
Our goal is to
|
|
||||||
|
|
||||||
> Create a fast, reliable, forwards/backwards compatible commandline personal
|
|
||||||
> information management suite which covers all aspects of personal information
|
|
||||||
> management, consists of reusable parts and integrates well with known
|
|
||||||
> commandline tools.
|
|
||||||
|
|
||||||
We try to accomplish these requirements:
|
|
||||||
|
|
||||||
* "fast": We use the awesome, fast and safe programming language "Rust"
|
|
||||||
* "reliable": We try to test every aspect of our software. Our build process
|
|
||||||
ensures that the build breaks whenever a library interface changes and the
|
|
||||||
modules which use the library are not updated.
|
|
||||||
* "forwards/backwards compatible:" Our (plain text) on-disk data format and
|
|
||||||
storage library both ensure that incompatibilities are captured and resolved
|
|
||||||
([using](https://crates.io/crates/semver) [semver](https://semver.org))
|
|
||||||
* "commandline": We ensure that everything can be done by commandline calls, for
|
|
||||||
some modules there might be a curses-like UI, but there are no graphical
|
|
||||||
clients and there never will be any within this codebase. We use
|
|
||||||
[clap](https://crates.io/crates/clap) for commandline-interface building and
|
|
||||||
we try to keep the interface easy and consistent between modules.
|
|
||||||
* "personal": We store everything as plain text in a store inside the users
|
|
||||||
`$HOME` directory. There will be a version-control (most surely `git`) hook
|
|
||||||
integrated to sync between several machines. There are no multi-user features
|
|
||||||
included or planned at the time of writing.
|
|
||||||
* "information management": We want to give the user the possibility to put
|
|
||||||
every single information about their personal lives into the store and we try
|
|
||||||
hard to provide a sane interface to query and retrieve data from this
|
|
||||||
database.
|
|
||||||
* "covers all the aspects of personal information management": We want to
|
|
||||||
provide modules for:
|
|
||||||
* contact management
|
|
||||||
* calendar
|
|
||||||
* diary
|
|
||||||
* notes
|
|
||||||
* personal wiki
|
|
||||||
* news (rss)
|
|
||||||
* passwords
|
|
||||||
* images
|
|
||||||
* music
|
|
||||||
* movies
|
|
||||||
* personal project management
|
|
||||||
* podcast management
|
|
||||||
* ledger
|
|
||||||
* mail
|
|
||||||
* bibliography management
|
|
||||||
* ... and many, many more.
|
|
||||||
* "constists of reusable parts": Every functionality is implemented as library.
|
|
||||||
The binaries we ship are just commandline-interace-to-library-interface
|
|
||||||
translators
|
|
||||||
* "integrates well with known commandline tools": We do not re-invent the wheel.
|
|
||||||
**We do not implement "yet another password manager", but use
|
|
||||||
[the standard unix password manager](https://www.passwordstore.org/), do not
|
|
||||||
implement a news reader, but use [newsbeuter](http://www.newsbeuter.org/),
|
|
||||||
do not reimplement a mail reader, etc etc.**
|
|
||||||
We do not copy images, movies or other data to the store but "link" them into
|
|
||||||
the store, so you can use imag tools to query and access this data, but still
|
|
||||||
live with your beloved commandline apps. We do not want to duplicate work but
|
|
||||||
reuse as much as possible.
|
|
||||||
You don't like one of the applications we use (for example `pass` as password
|
|
||||||
manager)? Sure, feel free to submit patches so the user is able to switch the
|
|
||||||
used tool, as long as it doesn't break the workflow. We will happily merge
|
|
||||||
them!
|
|
||||||
|
|
||||||
## Current state of development
|
|
||||||
|
|
||||||
**This application is in _really_ early development.**
|
|
||||||
|
|
||||||
We have implemented the very core of the system, though some more utility work
|
|
||||||
is to be done.
|
|
||||||
We have the store working, a hooks API and some default hooks are in
|
|
||||||
development.
|
|
||||||
Basic features like tagging and linking entries is possible as well as viewing
|
|
||||||
entries.
|
|
||||||
Some small things are implemented, like a note-taking module, a basic diary
|
|
||||||
module, a counter module and a bookmark module.
|
|
||||||
These modules contain basic features and are subject to change.
|
|
||||||
More modules are about to be implemented.
|
|
||||||
|
|
||||||
Though, the very core of the system is stable and nothing prevents _you_ from
|
|
||||||
contributing and implementing a module.
|
|
||||||
|
|
||||||
## Building/Running
|
|
||||||
|
|
||||||
Here goes how to try imag out.
|
|
||||||
|
|
||||||
### Building
|
|
||||||
|
|
||||||
By now, there are several targets in the Makefile, fulfilling following roles:
|
|
||||||
* `all` Is the default and builds every crate in debug mode. This is the same as
|
|
||||||
traversing every directory yourself and calling `cargo build` in it.
|
|
||||||
To build a single crate, call `make <crate>`, for example
|
|
||||||
`make imag-store`
|
|
||||||
* `release`, as the name implies, builds every crate in release mode. Following
|
|
||||||
the example above, to build `imag-store` in release mode, call
|
|
||||||
`make imag-store-release`.
|
|
||||||
* `install` will install all binary crates to the default installation root (see
|
|
||||||
`man cargo-install`). To install a single module, run `make <module>-install`,
|
|
||||||
again, for example: `make imag-store-install`
|
|
||||||
* `bin`/`lib` are separate targets for either building all binaries or
|
|
||||||
libraries.
|
|
||||||
* `lib-test` runs `cargo test` for all libraries. For testing a single library,
|
|
||||||
run `make test-libimagstore` for example.
|
|
||||||
* `clean` will run `cargo clean` in every crate. Again, 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-update` for
|
|
||||||
`cargo update`ing, `imag-bin-clean` for `cargo clean`ing).
|
|
||||||
|
|
||||||
### Running
|
|
||||||
|
|
||||||
To test out a single module, simply using `cargo run -- <options>` in the
|
|
||||||
respective directory will do the trick. For using it "normally", install the
|
|
||||||
binaries as described above, as well as the imag-binary:
|
|
||||||
```
|
|
||||||
$> make install
|
|
||||||
```
|
|
||||||
The installation root of the binaries (a.k.a. where they are installed to), 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
|
|
||||||
```
|
|
||||||
|
|
||||||
Please note that $PATH will be reset in a new shell. To make these changes
|
|
||||||
permanent, see the User Guide of your shell.
|
|
||||||
|
|
||||||
## Documentation
|
|
||||||
|
|
||||||
For detailed information, please read [the documentation](./doc/) (You can
|
|
||||||
either read the Markdown files or compile it to HTML/PDF using
|
|
||||||
[pandoc](http://pandoc.org)).
|
|
||||||
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
|
|
||||||
outdated.
|
|
||||||
|
|
||||||
## Contact
|
## Contact
|
||||||
|
|
||||||
Have a look at [our website](http://imag-pim.org) where you can find some
|
Have a look at [our website](http://imag-pim.org) where you can find some
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue