From 2ce4d334b4c1317a2eb03331f748d7fdf8ca5173 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 24 Aug 2016 13:29:53 +0200 Subject: [PATCH 1/7] Add module-documentation for the documentation crate --- .imag-documentation/src/lib.rs | 46 +++++++++++++++++++++++++++++----- 1 file changed, 40 insertions(+), 6 deletions(-) diff --git a/.imag-documentation/src/lib.rs b/.imag-documentation/src/lib.rs index cdfbe1aa..2f50c33f 100644 --- a/.imag-documentation/src/lib.rs +++ b/.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! +//! + From eafd8c1ae593dba31f5bfbd6618b89918f6f68a4 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 24 Aug 2016 13:49:53 +0200 Subject: [PATCH 2/7] Add README.md for libimagerror --- libimagerror/README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 libimagerror/README.md diff --git a/libimagerror/README.md b/libimagerror/README.md new file mode 100644 index 00000000..f61724cf --- /dev/null +++ b/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. + From fc53d9a4019f77eaa1c98670ad333611edaab534 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 24 Aug 2016 14:12:05 +0200 Subject: [PATCH 3/7] Add README.md for libimagref --- libimagref/README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 libimagref/README.md diff --git a/libimagref/README.md b/libimagref/README.md new file mode 100644 index 00000000..146059f1 --- /dev/null +++ b/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/`. +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. + From 62a7e75230effca3c050cb4d3121d336587dd62a Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 24 Aug 2016 14:15:28 +0200 Subject: [PATCH 4/7] Add README.md for libimagbookmark --- libimagbookmark/README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 libimagbookmark/README.md diff --git a/libimagbookmark/README.md b/libimagbookmark/README.md new file mode 100644 index 00000000..1a77f92e --- /dev/null +++ b/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. + From 47588dc2f3a1c1b89910d83fe7ae6303d8543e01 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 24 Aug 2016 14:22:01 +0200 Subject: [PATCH 5/7] Add README.md for libimagdiary --- libimagdiary/README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 libimagdiary/README.md diff --git a/libimagdiary/README.md b/libimagdiary/README.md new file mode 100644 index 00000000..0c2df2cd --- /dev/null +++ b/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. + From a148af6ce8152c7ec5d9eae55bfd8eca1179fdab Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 24 Aug 2016 14:23:31 +0200 Subject: [PATCH 6/7] Add README.md for libimagentryselect --- libimagentryselect/README.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 libimagentryselect/README.md diff --git a/libimagentryselect/README.md b/libimagentryselect/README.md new file mode 100644 index 00000000..de6c4825 --- /dev/null +++ b/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. + From 2e627a57210b671ac30985135c6b850023251b26 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 24 Aug 2016 14:25:57 +0200 Subject: [PATCH 7/7] Add README.md for libimaginteraction --- libimaginteraction/README.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 libimaginteraction/README.md diff --git a/libimaginteraction/README.md b/libimaginteraction/README.md new file mode 100644 index 00000000..b8939feb --- /dev/null +++ b/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. +