Changed the documentation structure

docs/technical/.gitignore

@@ -0,0 +1,2 @@
+*.html
+index.txt

docs/technical/api-notify.txt

@@ -0,0 +1,106 @@
+Notify API
+----------
+
+This API is here to provide an abstraction to the underlaying low-level filesystem notification mechanism
+to try to make applications portable but also throw away detail from client-code.
+
+IMPORTANT: The design is only tested with inotify and the API may
+need to change in the future to support more subsystems that may have some limitations. 
+
+Data structures
+~~~~~~~~~~~~~~~
+
+* `notify_event`
+
+Holds information about one perticular event
+
+`type`::
+    The type of event, can hold one and only one of these flags
+
+NOTIFY_UNKNOWN;;
+    Events that do occur but can't be mapped to a more relevant type ends up being marked as
+    an unknown event, you can most likely only tell that "something" happened on
+    the given path (so unless your application wants to know that "something" happened, ignore this)
+
+NOTIFY_CREATE;;
+    A file/directory was created on the filesystem.
+
+NOTIFY_DELETE;;
+    A file/directory was deleted from the filesystem
++
+IMPORTANT: It is possible to get just one event for a directory that has files/subdirectorys,
+    so when getting this event you should always make sure your actions does handle the possible recursion.
+
+NOTIFY_MOVE_FROM;;
+NOTIFY_MOVE_TO;;
+    As of the time of writing no implementation support these types and uses create/delete types instead.
+    A drastic design change to the `notify_event` structure should be made before this type of events
+    will be usefull.
+
+`dir`::
+    non zero if event is triggered on a directory
+    
+`path`::
+    path of the triggered event
+    
+`filename`::
+    the filename the event was triggered on
+
+Functions
+~~~~~~~~~
+
+`notify_init()`::
+
+    instantiate notify. making it ready for further `notify_*` calls. +
+    returns a positive number if everything went OK. +
+    returns zero if notify has already been instantiated. +
+    And returns -1 and sets `errno` if an error occur.
+
+`notify_add_watch()`::
+
+    tells notify to start listening on 'path'. +
+    one create event will be genereted for every file under 'path' +
+    and all subdirectorys will be watched. +
+    returns 1 if everything went ok and returns -1 and sets `errno` if an error occure.
+
+`notify_rm_watch()`::
+
+    'path' will be removed from notify and all events triggered on this path
+    will be ignored from now on.
+
+`notify_read()`::
+
+    fetches and returns one event from the subsystem. A `NULL` pointer is returned if no events
+    is available at the given moment.
++
+NOTE: The implementation may read and process the data from whatever source it has
+in this function, the only requirement is that the function never blocks.
+
+`notify_exit()`::
+
+    free's all memory associated with notify and other cleanup routines.
+
+`notify_event_new()`::
+
+    allocates memory and initilize values for a new `notify_event` structure
+
+`notify_event_clear()`::
+
+    free's all the memory and sets values back to default.
+
+`notify_event_set_*()`::
+
+    use these functions to set members of the `notify_event` structure.
+    
+`notify_event_del()`::
+
+    free's all the memory from the `notify_event` structure.
+
+`notify_event_typetostr()`::
+
+returns a string representation of a event's type. the pointer should +
+not be free'ed, so its safe to be used like this:
++
+----
+printf("type: %s\n", notify_event_typetostr(event));
+----

docs/technical/fscrawl.txt

@@ -0,0 +1,48 @@
+fscrawl - Filesystem traversal
+------------------------------
+
+API for traversing a filesystem tree/subtree.
+
+Data Structures
+~~~~~~~~~~~~~~~
+
+* `fscrawl_t`
+
+An abstract datatype, holds information about where in the filesystem you currently are etc.
+
+* `fs_entry`
+
+Holds information about a node on the filesystem
+
+`name`::
+    name of the entry (filename, directory name)
+    
+`base`::
+    The base directory where `name` exists in.
+    
+`dir`::
+    zero if the entry is a file, non zero otherwise
+
+Functions
+~~~~~~~~~
+
+`fsc_open()`::
+
+    Tries to open 'path' for traversal. +
+    Returns `NULL` if 'path' can't be open, otherwise a valid pointer to a `fscrawl_t` that can be passed to other fsc_* functions.
+
+`fsc_close()`::
+
+    Closes a `fscrawl_t` and free's all memory used by the structure.
+
+`fsc_cpy()`::
+
+    Returns a copy of 'ent'.
+
+`fsc_read()`::
+
+Reads one entry from `fscrawl_t` and returns it. +
+If the traversal is completed `NULL` is returned.
++
+NOTE: if you need to safe the `fs_entry` structure this function returns, make a call to `fsc_cpy()` +
+      otherwise you data will be overwritten by further calls to `fsc_read()`.

docs/technical/genindex.sh

@@ -0,0 +1,21 @@
+
+#!/bin/sh
+
+if [ $# -lt 1 ]; then
+    exit 1
+fi
+
+(
+    echo "Archived API Documentation"
+    echo "--------------------------"
+
+    for DOC in `ls *.txt`; do
+        if [ "$DOC" = "$1" ]; then
+            continue
+        fi
+        display=$(sed -e 1q "${DOC}")
+        link=${DOC%.txt}.html
+        echo "* link:${link}[${display}]"
+    done
+
+) > $1

docs/technical/log.txt

@@ -0,0 +1,59 @@
+Log - Message logging API
+-------------------------
+
+This interface is designed in such way that code that wants to logg a massage can do so with one call and don't worry
+about where it may turn up and what format it should use etc. +
+All this is setup trough one function call idealy in the beginning of a process.
+
+Macros
+~~~~~~
+
+`LOG_INFO`::
+    Information, Someone thinks you may find this important.
+    
+`LOG_WARN`::
+    Warning, just a warning. can be ignored if you simply just don't care about it.
+    
+`LOG_CRIT`::
+    Critical condition, some things may not work as supposed to.
+    
+`LOG_DEBUG`::
+    Debug level, messages that is usefull when debugging.
+    
+`LOG_ALL`::
+    All of the above.
+
+Functions
+~~~~~~~~~
+
+`init_log()`::
+Initialize the logging functionality, 'level' is a bitmask of the LOG_* contansts defining what types of messages should be logged. +
+if 'path' is a writeable directory, output will be written to files in that directory otherwise `stderr` is used.
++
+----
+init_log(LOG_INFO | LOG_WARN, NULL);
+----
++
+Will log info and warning messages to `stderr`.
+
+`logstrtolvl()`::
+    returns the LOG_* equivalent of a string representation.
+
+`loglvltostr()`::
+    returns the string representation of a LOG_* constant.
+
+`logmsg()`::
+logs a message, 'level' should be a LOG_* constant for what level the message is for. +
+the rest of the arguments is a variable argument list and behaves like `printf()`
++
+----
+logmsg(LOG_INFO, "this is an integer: %i", 12);
+logmsg(LOG_INFO, "this is just a message");
+----
++
+
+NOTE: No newline at the end of the message is needed.
+
+`logerrno`::
+like `perror()`, logs an message by the 'errno' number. +
+if 'prefix' is not `NULL` and points to a string that is not zero length, the message will be prepended whit 'prefix' followed by a colon and a space.

docs/technical/path.txt

@@ -0,0 +1,35 @@
+Path - Path handling routines
+-----------------------------
+
+This module implements common routines for dealing with paths.
+
+Functions
+~~~~~~~~~
+
+`is_abspath()`::
+
+    Returns a non zero value if 'path' is an absolute path. zero otherwise.
+
+`is_file()`::
+
+    Returns a non zero value if 'path' is a regular file. zero otherwise.
+
+`is_dir()`::
+
+    Returns a non zero value if 'path' is a directory. zero otherwise.
+    
+`path_normalize`::
+
+Returns a string that contains the normalized full path specified by 'base', 'name' and 'dir'. +
+The function performs this type of checks/manipulation:
++
+--
+    * If the first character in 'base' is "~" it is expanded to the users home directory.
+    * Sequences of delimiters are replaced with one delimiter.
+    * Makes sure 'base' is an absolute path.
+    * 'name' must not contain an delimiter.
+    * terminates the string with an delimiter if 'dir' is non-zero.
+--
++
+Returns `NULL` if 'base' is not an absolute path or 'name' contains a delimiter.
+

docs/technical/queue.txt

@@ -0,0 +1,57 @@
+Queue
+-----
+
+Simple FIFO queue allowing enqueueing and dequeing from the start and end. +
+This implementation only stores generic pointers to objects.
+So you must take care of the objects lifetime, size etc by yourself.
+
+Data structures
+~~~~~~~~~~~~~~~
+
+* `queue_t`
+    An abstract datatype holding the queue, used by queue_* functions.
+
+Functions
+~~~~~~~~~
+
+`queue_init()`::
+
+    Initalize the queue and returns a pointer to it.
+
+`queue_enqueue()`::
+
+    Places the pointer 'obj' at the end of the queue.
++
+NOTE: no data is copied, only the address 'obj' is stored in the queue.
+
+`queue_dequeue()`::
+
+    Removes and returns a item from the start of the queue.
+
+`queue_isempty()`::
+
+    Returns non zero if 'q' is empty. zero otherwise.
+    
+`queue_num_items`::
+
+    Returns the number of items in 'q' at this given moment.
+
+`queue_destroy()`::
+
+    Free's the metadata from `queue_t`.
++
+[IMPORTANT]
+===========
+This function does not take care of the objects in the queue, to avoid memory leaks
+be sure to clear out the queue before destroying. +
+
+[blue]#The example below assumes malloc:ed pointers is stored in the queue:#
+--------------------------------------
+while(!queue_isempty(queue)) {
+    void *item = queue_dequeue(queue);
+    if (item)
+        free(item);
+}
+queue_destroy(queue);
+--------------------------------------
+===========

docs/technical/rbtree.txt

@@ -0,0 +1,74 @@
+Red-Black Tree
+--------------
+
+Macros
+~~~~~~
+
+`RBTREE_INIT`::
+Initialize a `rbtree` structure. +
+should only be used with the declaration like:
++
+----
+rbtree tree = RBTREE_INIT(...);
+----
++
+the arguments are pointers to callback functions, in order: `delete_fn`, `update_fn`, `cmp_fn`
+
+Data structures
+~~~~~~~~~~~~~~~
+
+* `rbtree`
++
+--
+Structure that holds a tree of nodes
+
+`root`::
+    Pointer to the node that is the root of the tree.
+
+`delete_fn`::
+    Pointer to the function that should handle the delete routines for the `key` pointer.
+
+`update_fn`::
+    Pointer to the function that is called when the implementation performs an update of an `key` pointer. +
+    The function gets the following information passed in order: old pointer, new pointer.
+
+NOTE: You may only need this if you store the data in another structure and has to keep it synchronized with the RB-tree.
+
+`cmp_fn`::
+    Pointer to the function that is used to compare two `key` pointers. +
+    Shall return a value greater than zero if 'ptr1' > 'ptr2', a value less than zero if 'ptr1' < 'ptr2' and zero if 'ptr1' == 'ptr2'.
+--
+
+Functions
+~~~~~~~~~
+
+`rbtree_insert()`::
+
+    Creates and inserts a new node in the tree. +
+    If provided, calls `rbtree->update_fn` and `rbtree->delete_fn` if a node should be updated. +
+    Returns nonzero if a new node was inserted or updated, zero otherwise.
+
+NOTE: The memory pointed to by the 'key' pointer is *not* copied so you must ensure that it has a infinite lifetime.
+
+`rbtree_delete()`::
+
+    Deletes a node from the tree. if provided, calls `rbtree->delete_fn` for the node. +
+    Returns nonzero if a node was removed, zero otherwise.
+    
+`rbtree_free()`::
+
+    Deletes the whole tree. if provided, calls `rbtree->delete_fn` for every node.
+    
+`rbtree_walk()`::
+
+    Walks the tree in-order and passes a pointer to `key`
+    for the given node to the 'action' callback function.
+
+`rbtree_search()`::
+
+    Searches the tree for 'key'. +
+    Returns a pointer to the node if found else `NULL`.
+
+`rbtree_is_empty()`::
+
+    Checks if a tree is empty, retruns zero if the tree is empty, nonzero otherwise. 

docs/technical/strbuf.txt

@@ -0,0 +1,93 @@
+String buffer API
+-----------------
+
+First off, the major design choices. the most important thing to keep in mind
+when using the API is that it is designed for low-level usage, The basic error checking
+is removed (like checking if the input strbuf pointer is null). +
+This is not done to gain speed, but because this is a buffer API, you should in almost every case allocate
+the structure on the stack or have it passed from a function that has it allocated on the stack. +
+Other types of skipped error checking is for example if the ->len member is in range of
+the allocated block. (obviously this is checked in functions that may need to expand the memory)
+
+Data structures
+~~~~~~~~~~~~~~~
+
+* `strbuf_t`
+
+The ->buf member is yours to mess with if you want, but you should never go beyond ->len. +
+A `NULL` terminating character is located at ->len+1 at all times so it is safe to use the ->buf member
+on any function that relies on the input being a valid C string. The API will never rely on this
+and it's possible to have embedded `NULL`'s because of that.
+
+NOTE: ->alloc_size and ->len should *not* be messed with, only `strbuf_*` functions will know how to handle those properly.
+
+Functions
+~~~~~~~~~
+
+`strbuf_append()`::
+
+    This function will append the buffer with the contents of 'ptr'
+    and will always copy exactly 'len' bytes. (if memory can be obtained ofcourse)
+
+`strbuf_append_str()`::
+
+    Will add the 'str' C-string to the end of ->buf
+
+`strbuf_append_ch()`::
+
+    Adds one character 'ch' to the end of ->buf
+
+`strbuf_append_repeat()`::
+
+    Adds 'len' characters of 'ch' to the end of ->buf
+
+`strbuf_reduce()`::
+
+Will reduce ->buf by 'len' bytes from the end.
++
+NOTE: This doesn't shrink the memory block
+    just changes the size and properly `NULL` terminates the now reduced space.
+
+`strbuf_trim()`::
+`strbuf_rtrim()`::
+`strbuf_ltrim()`::
+
+    Removes space characters from the beginning (ltrim) of the ->buf string, the end (rtrim) or both (trim).
+
+`strbuf_rchop()`::
+
+    Chops off everything to the right of the rightmost 'ch' encountered in the string.
+
+`strbuf_rev()`::
+
+    Reverses the ->buf string.
+
+`strbuf_squeeze()`::
+
+    Squeezes "together" sequences of 'ch' into one character.
+
+`strbuf_term()`::
+
+    ensure that ->buf is terminated with 'ch'. Will not change ->buf if it is already terminated.
+
+`strbuf_explode()`::
+
+Returns a NULL terminated list of string buffers, each containing a substring of 'str' splitted by delimiter'. +
+Returns `NULL` if 'delimiter' does not exists in 'str'.
++
+TIP: use `strbuf_free_list()` to free the entire list.
++
+NOTE: 'delimiter' is not included in the list.
+
+`strbuf_release()`::
+
+    This function should be used to detach the ->buf member from the `strbuf_t` structure. +
+    A `malloc()`'ed C string of size `strlen()+1` is returned that you are now responsible for.
+
+`strbuf_free()`::
+
+    Free's all the memory (allocated on the heap) associted with the `strbuf_t` structure.
+
+`strbuf_free_list()`::
+
+    Free's all the memory from an NULL terminated list of string buffers.

docs/technical/xalloc.txt

@@ -0,0 +1,42 @@
+xalloc - safe memory allocation
+-------------------------------
+
+This module implements malloc and friends + some extensions.
+If `__DEBUG__` symbol is defined. The functions will provide extended
+debug logic and kills the program (passing 0 as size to malloc for example).
+
+The funtions will at all times kill the program if memory can't be allocated for
+some reason, this makes the need for client-code to check for `NULL` pointers returned
+by these functions redundant.
+
+Functions
+~~~~~~~~~
+
+`xmalloc()`::
+
+    Just like malloc, this function allocates a block of memory of 'size' bytes. +
+    If compiled with the `__DEBUG__` symbol, the function will not allow zero size
+
+`xmallocz()`::
+
+    Exactly like xmalloc but will initialize the block with zero's.
+
+`xrealloc()`::
+
+    Reallocates a previous allocated block of memory to 'size' bytes. +
+    If compiled with the `__DEBUG__` symbol, the function will not allow zero size
+
+`xstrdup()`::
+
+    Allocates and copies the string 's' to a new memory location and returns it to the user. +
+    If compiled with the `__DEBUG__` symbol, the function will not allow 's' to be a `NULL` pointer
+
+`xmemdup()`::
+
+    Allocates and copies `len` bytes from `ptr` to a new memory location and returns it to the user. +
+    If compiled with the `__DEBUG__` symbol, the function will not allow 'ptr' to be a `NULL` pointer
+
+`xfree()`::
+
+    Free's a previous allocated block (pointed to by 'ptr') that is allocated by xmalloc/malloc. +
+    If compiled with the `__DEBUG__` symbol, the function will not allow 'ptr' to be a NULL pointer