Merge pull request #1326 from matthiasbeyer/doc

Doc

.travis.yml

@@ -23,6 +23,7 @@ addons:
 
 script:
   - |
+    bash ./scripts/find-dead-symlinks || exit 1
     bash ./scripts/license-headers-updated || exit 1
     cargo build --all --all-features -j 1 || exit 1
     cargo test  --all --all-features -j 1 || exit 1

doc/src/02010-linking.md

@@ -1,29 +0,0 @@
-## Linking from an store entry {#sec:thestore:linking}
-
-As described in @sec:intro:problem the purpose of imag is to _link_ content
-together. The following section describes, from a technical view, how this is
-done in imag.
-
-There are two ways of linking in imag. You can either link internally or
-externally. The following sections describe the differences.
-
-### Linking to internal content {#sec:thestore:linking:internal}
-
-Internal links are links between store entries themselfes. This means that one
-store entry can link to another. Actually, links are not pointers but rather
-tries between entries, meaning that an link is not directed, but always a
-two-way pointer.
-
-How linking works from the user interface is described in @sec:modules:link.
-
-### Linking to external content {#sec:thestore:linking:external}
-
-Linking to external content means linking to files or directories which do not
-live inside the store itself but outside of it.
-
-Each store entry can store _one link to external content at most_.
-
-External linking should not be used from the user interface but rather the
-`ref` feature (@sec:modules:ref) should be used.
-@sec:modules:ref describes why that is.
-

doc/src/03010-conventions.md

@@ -1,6 +1,6 @@
 # Conventions, best practices
 
-This section goes about best practices in the imag codebase. It is mainly
+This section explains conventions used in the imag codebase. It is mainly
 focused on developers, but a user may read it for getting to know how imag
 works.
 
@@ -54,24 +54,25 @@ will not write such a library but rather a "libimagentrything" library.
 
 A library should never introduce utility functionality which could be useful for
 other libraries as well. If there is no such functionality available, the
-"libimagutil" might be a place where such a function would be put, or, if not
+"libimagutil" or "libimagentryutil" might be a place where such a function
-yet available, a "libimagentryutil" could be created.
+would be put.
 
 If a library has to introduce free functions in its public interface, one should
 think hard whether this is really necessary.
 
 ### Library error types/kinds
 
-Libraries must use the "libimagerror" tools to create error types and kinds.
+Libraries must use "error-chain" to create error types and kinds.
 Most likely, a library needs some kinds for wrapping the errors from underlying
 libraries, such as the store itself.
 
 A library must _never_ introduce multiple error types, but is free to introduce
-as many error kinds as required. Indeed, more kinds is better than fewer.
+as many error kinds as required.
 
 ### Libraries with commandline frontends
 
-Libraries with commandline frontends provide end-user functionality. Normally,
+Libraries with commandline frontends provide end-user functionality.
+Normally,
 they depend on one or more "libimagentrything" libraries. They should be named
 "libimagthing", though. For example: "libimagdiary", "libimagtimetrack" or
 "libimagwiki", whereas the commandline frontends would be "imag-diary",
@@ -80,7 +81,7 @@ they depend on one or more "libimagentrything" libraries. They should be named
 If such a library needs to depend on another "libimagthing", for example if
 "libimagdiary" needs to depend on "libimagnote", one should think about this and
 whether the functionality could be outsourced to a more general
-"libimagentrything". It is not forbidden, though.
+"libimagentrything".
 
 A library which implements a functionality for imag may contain helper functions
 for commandline stuff, but that is discouraged.
@@ -92,15 +93,9 @@ possible without a lot of effort, but still: more tests = better!
 
 ## Commandline tools
 
-The next few sections describe how the commandline frontends are implemented.
+The commandline tools are the CLI-frontends for their respective libraries.
-Each imag functionality (or module) has its own library and a commandline
+So `libimagdiary` has a CLI frontend `imag-diary`.
-frontend for it.
 
-The commandline frontends do contain little to no functionality. They simply
+Those CLI frontends use functionality from `libimagrt` to build a consistent
-translate the commandline parameters and options to calls to the appropriate
+commandline interface.
-library functions.
-
-## Commandline tool testing
-
-## Commandline interface
 

doc/src/04000-modules.md

@@ -3,8 +3,7 @@
 A module is a functionality of the program.
 There is a huge list of modules available in the imag core distribution.
 
-From a naming perspective, we do not differ between low-level and high-level
+Some of the modules shipped with imag cover core functionality such as
-modules. Some of the modules shipped with imag cover core functionality such as
 linking, tagging or references to files outside of the store or even the store
 interface itself.
 Others cover things like diary, notes, wiki or bookmarks.

doc/src/04020-module-bibliography.md

@@ -1,4 +0,0 @@
-## Bibliography {#sec:modules:bibliography}
-
-The Bibliography module.
-

doc/src/04020-module-borrow.md

@@ -1,3 +0,0 @@
-## Borrow {#sec:modules:borrow}
-
-The Borrow module.

doc/src/04020-module-calendar.md

@@ -1,11 +0,0 @@
-## Calendar {#sec:modules:calendar}
-
-The calendar module implements a commandline calendar like khal. The calendar data itself is retrieved from icalendar files which should be located outside of the imag store. imag does not handle syncing of these files. `vdirsyncer` may be your tool of choise here. 
-
-imag can show events from the calendar(s) like any other commandline calendar tool and of course can also add, delete or edit entries  (interactively or via commandline parameters).
-
-### Internals
-
-What imag does internally is described in this section.
-
-imag creates one entry in the store for one `icalendar` file. These entries are basically references to the real data. If an  `icalendar` file is removed from the filesystem, imag does not delete it from the sfore if not told explicitely.

doc/src/04020-module-category.md

@@ -1,6 +0,0 @@
-## Category {#sec:modules:category}
-
-The Category module is a plumbing command for setting an entrys category. A category must exist before it can be set for an entry. That, and that each entry may have one or no category is the difference from tags.
-
-Also: Categories may have sub-categories.
-

doc/src/04020-module-contacts.md

@@ -1,7 +0,0 @@
-## Contacts {#sec:modules:contacts}
-
-The Contacts module serves as a vcard viewer which is also able to alter, vcard files (either interactively or via commandline parameters).
-
-The contacts module can also call other programs and pass contact information to them, for example `mutt`.
-
-

doc/src/04020-module-counter.md

@@ -1,27 +0,0 @@
-## Counter {#sec:modules:counter}
-
-The Counter module helps you counting things.
-
-In its current state the counter module is capable of simple counting. You can
-create, list and delete counters which are simply numbers and incremet,
-decrement, set and reset them.
-
-Future plans include counting functionality which is able to save date and
-possibly timestamp of your increments/decrements, so you can export this and use
-(for example) R to visualize this data.
-
-Filters for selecting only certain time ranges when listing/exporting your
-counters will be added as well.
-
-### Examples
-
-Here are some examples how to use the counter module:
-
-```bash
-
-imag counter create --name example --initval 42 # or: -n example -i 42
-imag counter --inc example # or -i example
-imag counter --reset example
-imag counter --dec example # or -d example
-```
-

doc/src/04020-module-cuecards.md

@@ -1,5 +0,0 @@
-## Cuecards {#sec:modules:cuecards}
-
-The Cuecards module implements "cuacards-learning" like you probably did it in school.
-
-

doc/src/04020-module-filter.md

@@ -1,4 +0,0 @@
-## Filter {#sec:modules:filter}
-
-The Filter module is only of use when chaining up imag calls via bash pipes. It can be used to filter out entries based on some parameters, like for example whether a certain header field is set or not.
-

doc/src/04020-module-git.md

@@ -1,5 +0,0 @@
-## Git {#sec:modules:git}
-
-The Git module provises a convenient way to call the git executable on the imag store without having to `cd` to it first. Nothing more.
-
-

doc/src/04020-module-gps.md

@@ -1,4 +0,0 @@
-## GPS {#sec:modules:gps}
-
-The GPS module is a plumbing command for attaching a GPS coordinate to an entry.
-

doc/src/04020-module-habit.md

@@ -1,12 +0,0 @@
-## Habit {#sec:modules:habit}
-
-The Habit module is a habit tracker. One can add habits, specify how often they
-should be done and instantiate them.
-
-Example: After creating a new habit "Sunday Run", which should be done on
-Sundays, one can mark that the habit was done.
-Statistics and number-crunching can be done later on, after there is some habit
-data there.
-
-Exports to CSV are possible.
-

doc/src/04020-module-images.md

@@ -1,4 +0,0 @@
-## Images {#sec:modules:images}
-
-The Images module is for tagging, categorizing and sorting images. GPS coordinates can be attached to image references. Images can be put into collections. Image viewing programs can be called from imag. If an image gets modified (for example via darktable) and a new image file is created, the Image module can be used to group them.
-

doc/src/04020-module-item.md

@@ -1,7 +0,0 @@
-## Item {#sec:modules:item}
-
-The Item module is a plumbing command to create entries for items in the imag store.
-
-Items can be anything. For example, one could create a Tomato and a Bread as item to add them later in the shopping list (as in imag-shoppinglist), but also a computer and a printer can be created to use them later in a project (as in imag-project).
-
-

doc/src/04020-module-ledger.md

@@ -1,4 +0,0 @@
-## Ledger {#sec:modules:ledger}
-
-The Ledger module implements a ledger like `beancount`.
-

doc/src/04020-module-movies.md

@@ -1,4 +0,0 @@
-## Movies {#sec:modules:movies}
-
-The Movies module is for categorizing, rating and tagging movies.
-

doc/src/04020-module-music.md

@@ -1,6 +0,0 @@
-## Music {#sec:modules:music}
-
-The Music module is for rating, categorizing, tagging and enjoying music. It offers functionality to fetch lyrics, create automatically linkings from genre entries to music files (music files are represented as a entry jn imag), combining songs in albums and albums in artists, etc.
-
-A scrobble server may be implemented at some point to provide more ways to retrieving data over ones music taste. Suggested songs (from the own library of music or via external tools like musicbrainz) may be a feature that comes aith the scrobble server.
-

doc/src/04020-module-news.md

@@ -1,4 +0,0 @@
-## News {#sec:modules:news}
-
-The News module is an RSS reader.
-

doc/src/04020-module-password.md

@@ -1,4 +0,0 @@
-## Password {#sec:modules:password}
-
-The Password module.
-

doc/src/04020-module-project.md

@@ -1,8 +0,0 @@
-## Project {#sec:modules:project}
-
-The Project module can be used to plan and organize projects, though does not offer ways to share these plans with others. If that is desired, a new store should be created, put under version controll (possibly git) and shared via this mechanism.
-
-The project tool integrates the timetracking module as well as the todo module.
-
-A project is represented by a single imag entry. Notes, subprojects, todos, timetrackings and other things are linked to the project. A project does not necessarily have to be a programming project, but could be a project for building a house or losing weight for example.
-

doc/src/04020-module-rate.md

@@ -1,6 +0,0 @@
-## Rate {#sec:modules:rate}
-
-The Rate module is another plumbing command. It simply offers rating functionality, whereas allowed values are 0-10 (0 beeing equal to no rating).
-
-
-

doc/src/04020-module-read.md

@@ -1,5 +0,0 @@
-## Read {#sec:modules:read}
-
-The Read module is a plumbing command for reading entries from the store and writing them to stdout for further processing.
-
-

doc/src/04020-module-receipt.md

@@ -1,5 +0,0 @@
-## Receipt {#sec:modules:receipt}
-
-The Receipt module is for tracking, categorizing, tagging, quering and managing receipts.
-
-

doc/src/04020-module-shoppinglists.md

@@ -1,4 +0,0 @@
-## Shoppinglists {#sec:modules:shoppinglists}
-
-The Shoppinglists module provides functionality for creating shopping lists and organizing them. A shoppinglist can be printed and them be used to go shopping, of course.
-

doc/src/04020-module-summary.md

@@ -1,5 +0,0 @@
-## Summary {#sec:modules:summary}
-
-The Summary module is a wrapper to call a list (specified in the config file) of imag commands and viewing their outputs.
-
-

doc/src/04020-module-url.md

@@ -1,13 +0,0 @@
-## Url {#sec:modules:url}
-
-The Url module is a plumbing module to put URLs into the imag store.
-
-### Implementation
-
-The implementation of the URL module saves URLs on a per-entry basis. This means that each URL is hashed (with something like SHA512) and the hash is used as filename. The scheme is as follows:
-
-    /url/<hash of the domain>/<hash of the full URL>
-
-This scheme results in grouping URLs of the same domain (for example https://imag-pim.org) but distinction of the actual full URL, while still deduplicating URLs. Entering the same URL twice results in the same entry.
-
-This module does nothing more on its own. Its functionality may be used elsewhere (for example a bookmark module).

doc/src/04020-module-weather.md

@@ -1,4 +0,0 @@
-## Weather {#sec:modules:weather}
-
-The Weather module.
-

doc/src/04020-module-wiki.md

@@ -1,4 +0,0 @@
-## Wiki {#sec:modules:wiki}
-
-The Wiki module provides a personal wiki implementation.
-

doc/src/04020-module-workout.md

@@ -1,11 +0,0 @@
-## Workout {#sec:modules:workout}
-
-The Workout module is for tracking workouts. Burned calories, walked kilometers, lifting sets and all the things can be entered.
-
-### Submodules
-
-Each type of workout can be handled with one subcommand of the module, whereas training seasions can be used to group types of workouts (for example swimming and running).
-
-A step-counter functionality is implemented as first submodule.
-Import functionality for the step-counter submodule is available for importing from (for example) an Android step-counter App.
-

doc/src/04020-module-write.md

@@ -1,5 +0,0 @@
-## Write {#sec:modules:write}
-
-The Write module is a plumbing command for reading a store feom stdin and writing it to the filesystem.
-
-

doc/src/05100-lib-bibliography.md

@@ -1,2 +0,0 @@
-## libimagbibliography
-

doc/src/05100-lib-borrow.md

@@ -1,2 +0,0 @@
-## libimagborrow
-

doc/src/05100-lib-calendar.md

@@ -1,2 +0,0 @@
-## libimagcalendar
-

doc/src/05100-lib-cuecards.md

@@ -1,2 +0,0 @@
-## libimagcuecards
-

doc/src/05100-lib-images.md

@@ -1,2 +0,0 @@
-## libimagimages
-

doc/src/05100-lib-ledger.md

@@ -1,2 +0,0 @@
-## libimagledger
-

doc/src/05100-lib-movies.md

@@ -1,2 +0,0 @@
-## libimagmovies
-

doc/src/05100-lib-music.md

@@ -1,2 +0,0 @@
-## libimagmusic
-

doc/src/05100-lib-news.md

@@ -1,7 +0,0 @@
-## libimagnews
-
-The library for the news module implements a RSS reader.
-
-Details, for example where the feeds are stored (inside or outside the imag store) have to be evaluated.
-
-

doc/src/05100-lib-password.md

@@ -1,2 +0,0 @@
-## libimagpassword
-

doc/src/05100-lib-project.md

@@ -1,2 +0,0 @@
-## libimagproject
-

doc/src/05100-lib-read.md

@@ -1,10 +0,0 @@
-## libimagread
-
-This library is for the plumbing command `imag-read`.
-
-It extends the `Runtime` object and adds a `write_store_to(writer)` function (amongst others). After calling this function, the calling program cannot continue to do things, so this consumes the `Runtime` object and the calling program is expected to exit with the returned error code.
-
-The calling program is expected to _not_ print anything to stdout before or after calling this function.
-
-This library is intended for use with the `imag-read` command only.
-

doc/src/05100-lib-receipt.md

@@ -1,2 +0,0 @@
-## libimagreceipt
-

doc/src/05100-lib-shoppinglists.md

@@ -1,2 +0,0 @@
-## libimagshoppinglists
-

doc/src/05100-lib-weather.md

@@ -1,2 +0,0 @@
-## libimagweather
-

doc/src/05100-lib-wiki.md

@@ -1,7 +0,0 @@
-## libimagwiki
-
-The wiki library implements a complete wiki for personal use.
-
-This basically is a note-taking functionality combined with linking.
-
-

doc/src/05100-lib-workout.md

@@ -1,2 +0,0 @@
-## libimagworkout
-

doc/src/05100-lib-write.md

@@ -1,11 +0,0 @@
-## libimagwrite
-
-This library is for the plumbing command `imag-write`.
-
-It extends the `Runtime` object and adds a `read_store_from(reader)` function (amongst others). After calling this function, the calling program cannot continue to do things, so this consumes the `Runtime` object and the calling program is expected to exit with the returned error code.
-
-The calling program is expected to _not_ print or read anything to/from stdout/stdin before or after calling this function.
-
-This library is intended for use with the `imag-write` command only.
-
-

doc/templates/default.latex

@@ -45,6 +45,8 @@ $endfor$
 \renewcommand{\headrulewidth}{0.4pt}
 \renewcommand{\footrulewidth}{0.4pt}
 
+\newcommand{\passthrough}[1]{#1}
+
 \begin{document}
 
     \thispagestyle{empty}

scripts/find-dead-symlinks

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+[[ 0 == "$(find . -xtype l | wc -l)" ]] || {
+    echo >2 "DEAD SYMLINKS FOUND"
+    exit 1
+}
+