Merge pull request #799 from matthiasbeyer/doc-libs

Doc libs

doc/src/05000-libraries.md

@@ -0,0 +1,14 @@
+# Libraries {#sec:libraries}
+
+This section of the documentation is only relevant for developers and you might
+skip it if you're only a user of the imag tool.
+
+The following sections contain a short documentation on what the several
+libraries are supposed to do.
+It is generated from the `README.md` files of each library and only gives a
+general overview what can be done with the library.
+For a more comprehensive documentation of the library, one might consult the
+appropriate documentation generated from the source of the library itself.
+
+The documentation of the libraries is sorted _alphabetically_.
+

doc/src/05100-lib-bookmark.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.
+

doc/src/05100-lib-counter.md

@@ -0,0 +1,4 @@
+## libimagcounter
+
+Library of "imag-counter", usable by other modules as well to implement counter
+functionality for entries.

doc/src/05100-lib-diary.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.
+

doc/src/05100-lib-entryfilter.md

@@ -0,0 +1,9 @@
+## libimagentryfilter
+
+Helper library to filter lists of entries by certain predicated. Offers filters
+for filtering by header values and other predicates, plus this library offers
+logical operants to combine filters.
+
+A commandline-to-filter DSL is planned for this, so commandline applications can
+use this to implement a uniform filter interface.
+

doc/src/05100-lib-entrylink.md

@@ -0,0 +1,5 @@
+## libimagentrylink
+
+Linking library for linking entries with other entries. Used for "imag-link",
+the commandline utility, but intended for use in other binaries and libraries as
+well.

doc/src/05100-lib-entrylist.md

@@ -0,0 +1,12 @@
+## libimagentrylist
+
+Library for listing entries in different manner.
+
+This includes:
+
+* Plain one-line-one-entry-path listing
+* Tree listing by submodule
+* Listing with metadata
+  * One-line-one-entry
+  * ASCII-Table
+

doc/src/05100-lib-entrymarkdown.md

@@ -0,0 +1,9 @@
+## libimagentrymarkdown
+
+Helper crate to add useful functionality in a wrapper around
+[hoedown](https://crates.io/crates/hoedown) for imag.
+
+Adds functionality to extract links, parse content into HTML and other things
+which might be useful for markdown rendering in imag.
+
+

doc/src/05100-lib-entrytag.md

@@ -0,0 +1,6 @@
+## libimagentrytag
+
+Library for tagging entries. Used in "imag-tag" but should be used in all other
+modules which contain tagging functionality, so the backend and frontend look
+the same for all modules.
+

doc/src/05100-lib-error.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.
+

doc/src/05100-lib-interaction.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.
+

doc/src/05100-lib-ref.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.
+

doc/src/05100-lib-rt.md

@@ -0,0 +1,11 @@
+## libimagrt
+
+This library provides utility functionality for the modules and the binary
+frontends, such as reading and parsing the configuration file, a builder
+helper for the commandline interface and such.
+
+It also contains the store object and creates it from configuration.
+
+the `libimagrt::runtime::Runtime` object is the first complex object that comes
+to live in a imag binary.
+

doc/src/05100-lib-store.md

@@ -0,0 +1,11 @@
+## libimagstore
+
+The store is the heart of everything. Here lives the data, the complexity and
+the performance bottleneck.
+
+The store offeres read/write access to all entries, a hook system to do
+on-the-fly modification of incoming/outgoing files and so on.
+
+The store itself does not offer functionality, but has a commandline interface
+"imag-store" which can do basic things with the store.
+

doc/src/05100-lib-util.md

@@ -0,0 +1,4 @@
+## libimagutil
+
+Utility library. Does not depend on other imag crates.
+

libimagbookmark/README.md

@@ -1,11 +0,0 @@
-# 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.
-

libimagbookmark/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-bookmark.md

libimagcounter/README.md

@@ -1,4 +0,0 @@
-# libimagcounter
-
-Library of "imag-counter", usable by other modules as well to implement counter
-functionality for entries.

libimagcounter/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-counter.md

libimagdiary/README.md

@@ -1,16 +0,0 @@
-# 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.
-

libimagdiary/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-diary.md

libimagentryfilter/README.md

@@ -1,9 +0,0 @@
-# libimagentryfilter
-
-Helper library to filter lists of entries by certain predicated. Offers filters
-for filtering by header values and other predicates, plus this library offers
-logical operants to combine filters.
-
-A commandline-to-filter DSL is planned for this, so commandline applications can
-use this to implement a uniform filter interface.
-

libimagentryfilter/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-entryfilter.md

libimagentrylink/README.md

@@ -1,5 +0,0 @@
-# libimagentrylink
-
-Linking library for linking entries with other entries. Used for "imag-link",
-the commandline utility, but intended for use in other binaries and libraries as
-well.

libimagentrylink/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-entrylink.md

libimagentrylist/README.md

@@ -1,12 +0,0 @@
-# libimagentrylist
-
-Library for listing entries in different manner.
-
-This includes:
-
-* Plain one-line-one-entry-path listing
-* Tree listing by submodule
-* Listing with metadata
-  * One-line-one-entry
-  * ASCII-Table
-

libimagentrylist/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-entrylist.md

libimagentrymarkdown/README.md

@@ -1,9 +0,0 @@
-# libimagentrymarkdown
-
-Helper crate to add useful functionality in a wrapper around
-[hoedown](https://crates.io/crates/hoedown) for imag.
-
-Adds functionality to extract links, parse content into HTML and other things
-which might be useful for markdown rendering in imag.
-
-

libimagentrymarkdown/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-entrymarkdown.md

libimagentrytag/README.md

@@ -1,6 +0,0 @@
-# libimagentrytag
-
-Library for tagging entries. Used in "imag-tag" but should be used in all other
-modules which contain tagging functionality, so the backend and frontend look
-the same for all modules.
-

libimagentrytag/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-entrytag.md

libimagerror/README.md

@@ -1,21 +0,0 @@
-# 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.
-

libimagerror/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-error.md

libimaginteraction/README.md

@@ -1,7 +0,0 @@
-# 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.
-

libimaginteraction/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-interaction.md

libimagref/README.md

@@ -1,54 +0,0 @@
-# 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.
-

libimagref/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-ref.md

libimagrt/README.md

@@ -1,11 +0,0 @@
-# libimagrt
-
-This library provides utility functionality for the modules and the binary
-frontends, such as reading and parsing the configuration file, a builder
-helper for the commandline interface and such.
-
-It also contains the store object and creates it from configuration.
-
-the `libimagrt::runtime::Runtime` object is the first complex object that comes
-to live in a imag binary.
-

libimagrt/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-rt.md

libimagstore/README.md

@@ -1,11 +0,0 @@
-# libimagstore
-
-The store is the heart of everything. Here lives the data, the complexity and
-the performance bottleneck.
-
-The store offeres read/write access to all entries, a hook system to do
-on-the-fly modification of incoming/outgoing files and so on.
-
-The store itself does not offer functionality, but has a commandline interface
-"imag-store" which can do basic things with the store.
-

libimagstore/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-store.md

libimagutil/README.md

@@ -1,4 +0,0 @@
-# libimagutil
-
-Utility library. Does not depend on other imag crates.
-

libimagutil/README.md

@@ -0,0 +1 @@
+../doc/src/05100-lib-util.md