Merge pull request #661 from matthiasbeyer/crate-documentation

Documentation for the github pages

.imag-documentation/src/lib.rs

@@ -1,6 +1,40 @@
-#[cfg(test)]
-mod tests {
-    #[test]
-    fn it_works() {
-    }
-}
+//! # imag
+//!
+//! This is the _developer_ documentation for the imag personal information management suite for the
+//! commandline.
+//!
+//! For the user documentation, have a look
+//! [at the 'doc' subtree in the repository](http://git.imag-pim.org/imag/tree/doc)
+//! which can be compiled to HTML or PDF using [pandoc](pandoc.org) (and might be a bit outdated as
+//! imag is not yet released for use).
+//!
+//! ## General
+//!
+//! _Some_ things from the user documentation might be helpful for developers as well, so make sure
+//! to at least skim over it if you want to contribute to the imag source.
+//!
+//! Also make sure you had a look at
+//! [the CONTRIBUTING](http://git.imag-pim.org/imag/tree/CONTRIBUTING.md)
+//! file and [the developers certificate of origin](http://developercertificate.org/), which we also
+//! have in the `CONTRIBUTING` file, by the way.
+//!
+//! ## Contributing
+//!
+//! All things relevant for contributing are descripbed in
+//! [the CONTRIBUTING file](http://git.imag-pim.org/imag/tree/CONTRIBUTING.md),
+//! but here are some additional notes:
+//!
+//! * We have a `editorconfig` file in the repository. Would be nice if you'd
+//!   [use it](http://editorconfig.org/)
+//! * We have [default.nix](http://git.imag-pim.org/imag/tree/default.nix) file, which can be used
+//!   to install dependencies in `nix-shell` environments. If you have a installation of the nix
+//!   package manager, feel free to use this opportunity to be _pure_.
+//! * If you want to play around with imag, use the
+//!   [imagrc.toml](http://git.imag-pim.org/imag/tree/imagrc.toml)
+//!   file from the repository, we try to keep it up to date.
+//! * You can use [the Makefile](http://git.imag-pim.org/imag/tree/Makefile) to build things (if you
+//!   have all dependencies and cargo/rustc installed, of course).
+//! * It is a real advantage to use `cargo-check` when developing things - it speeds you up, beleive
+//!   me!
+//!
+

libimagbookmark/README.md

@@ -0,0 +1,11 @@
+# libimagbookmark
+
+This library crate implements functionality for bookmarks.
+
+It uses `libimagentrylink` to create external links and therefor deduplicates
+equivalent external links (`libimagentrylink` deduplicates - you cannot store
+two different store entries for `https://imag-pim.org` in the store).
+
+It supports bookmark collections and all basic functionality that one might
+need.
+

libimagdiary/README.md

@@ -0,0 +1,16 @@
+# libimagdiary
+
+This library crates implements a full diary.
+
+One can have one or more diaries in the store, each diary can have unlimited
+entries.
+
+## Future plans
+
+The diary should be able to provide _daily_, _hourly_ and even _minutely_
+diary entries, so one can use the diary as normal "Dear diary,
+today..."-diary, or more fine-grained and more like a journal.
+
+The internal file format as well as the store-path generation for this module is
+prepared for such functionality.
+

libimagentryselect/README.md

@@ -0,0 +1,7 @@
+# libimagentryselect
+
+Small library crate for asking the user to _select_ one or more entries out of
+a list of entries.
+
+Not much functionality, yet.
+

libimagerror/README.md

@@ -0,0 +1,21 @@
+# libimagerror
+
+In imag, we do not panic.
+
+Whatever we do, if we fail as hard as possible, the end-user should _never ever_
+see a backtrace from a `panic!()`.
+
+Anyways, the user _might_ see a error trace generated by imag.
+That is because imag is software for power-users, for nerds (I use the term
+"nerd" because for me it is a good thing - I do not want to offend anyone by
+using it).
+This target group can read backtraces without getting confused. `IO Error` and
+`Permission denied Error` are things that nerds can understand and they already
+know what to do in the most obvious cases (such as `Permission denied Error`).
+
+This library crate is for generating error types and handle them in a nice way.
+It can be seen as mini-framework inside imag which was written to work with
+error types in a specified way. All imag crates _must_ use this library if they
+can return errors in any way, except the `libimagutil` - which is for the most
+basic utilities.
+

libimaginteraction/README.md

@@ -0,0 +1,7 @@
+# libimaginteraction
+
+A crate for more general interaction with the user (interactive commandline
+interface).
+
+Offers functions for asking the user Y/N questions, for (numeric) values, etc.
+

libimagref/README.md

@@ -0,0 +1,54 @@
+# libimagref
+
+This library crate contains functionality to generate _references_ within the
+imag store.
+
+It can be used to create references to other files on the filesystem (reachable
+via a filesystem path). It differs from `libimagentrylink`/external linking as
+it is designed exclusively for filesystem references, not for URLs.
+
+A reference can have several properties, for example can a reference track the
+content of a filesystem path by hashing the content with a hashsum (SHA1) and
+one can check whether a file was changed by that.
+As files can get big (think of `debian.iso`) _partial hashing_ is supported
+(think of "hash the first 2048 bytes of a file).
+
+The library contains functionality to re-find a moved file automatically by
+checking the content hash which was stored before.
+
+Permission changes can be tracked as well.
+
+So this library helps to resemble something like a _symlink_.
+
+## Limits
+
+Please understand that this is _not_ intended to be a version control system or
+something like that.
+We also can not use _real symlinks_ as we need imag-store-objects to be able to
+link stuff.
+
+## Usecase
+
+This library offers functionality to refer to content outside of the store.
+It can be used to refer to _nearly static stuff_ pretty easily - think of a
+Maildir - you add new mails by fetching them, but you mostly do not remove mails
+and if you do you end up with a "null pointer" in the store, which can then be
+handled properly.
+
+As this library supports custom hashes (you don't have to hash the full file,
+you can also parse the file and hash only _some_ content) this is pretty
+flexible.
+For example if you want to implement a imag module which tracks a certain kind
+of files which constantly change... but the first 5 lines do never change
+after the file is created - you can write a custom hasher that only uses the
+first 5 lines for the hash.
+
+## Internals
+
+Internally, in the store, the file gets created under
+`/ref/<hash of the path to the file to refer to>`.
+If the content of the file is hashed, we can still re-find the file via the
+content hash (which is stored in the header of the store entry).
+
+The reference object can, after the path was re-found, be updated.
+