Started writing a little more docs.

Makefile

@@ -216,7 +216,7 @@ $(eval $(call make-obj-rule,$(src))))
 #*****************************************************************************#
 # Make the HTML documentation.
 html:
-	@sphinx-build -b html docs docs/_build/html
+	make -C docs
 
 .PHONY: html
 # End of file

docs/_data/sections.yml

@@ -4,6 +4,9 @@
 -
   name: Getting started
   uri: /getting-started.html
+-
+  name: Logging
+  uri: /logging.html
 -
   name: Streams
   uri: /streams.html

docs/assets/main.css

@@ -1,6 +1,7 @@
 body {
     font-weight: 400;
     text-shadow: 0 1px 1px rgba(255, 255, 255, 0.7);
+    overflow-y: scroll;
 }
 
 pre, code, pre code {

docs/getting-started.md

@@ -3,6 +3,32 @@ layout: page
 title: getting started
 ---
 The libcasio development happens [on Github][gh].  
-There is currently no mailing-list.
+There is currently no mailing-list.  
+The release source codes are available [here][pub] (all P7 projects are
+in the same folder).
+
+libcasio is a development library, either shared or static.
+There are many configuration options for adapting the library to your
+platform and needs.
+
+To configure, use `./configure <options>`. Options are used as
+`--<name>=<value>`. The following are some build options:
+
+- `--target=<target>`: the target for which to produce the library (by default,
+  native);
+- `--static`: produce a static library (by default, shared);
+- `--windows`: use the Windows versions of the final formats (dll instead of
+  elf, lib instead of coff);
+- `--no-libusb`: do not use (and link against) libusb;
+- `--no-file`: do not use the standard I/O library (probably because there
+  aren't any);
+- `--no-log`, `--loglevel=<level>`: if we should include debugging content
+  (but keep the interface), and if yes, what the default library log level.
+  See [Logging](logging.html) for more information;
+- `--maintainer`: alias for `--loglevel=info`, also introduces more
+  compilation warnings.
+
+Other options are packaging options (todo: add info about them here).
 
 [gh]: https://github.com/PlaneteCasio/libcasio
+[pub]: https://p7.planet-casio.com/pub/

docs/logging.md

@@ -0,0 +1,104 @@
+---
+layout: page
+title: logging
+---
+For debugging purposes, libcasio has a debugging interface that allows
+displaying messages in the debug stream (usually `stderr`) with four
+different levels (plus a special one):
+
+- `info` (debug information);
+- `warn` (warnings);
+- `error` (non-fatal errors);
+- `fatal` (fatal errors);
+- `none` (special log level to tell not to print messages).
+
+Each level includes the message from the levels below in the list.
+
+### Control interface for the library users
+The log level used to be hardcoded into the library (with the configure
+script), but it appeared that some users wanted to be able to control it
+from the utilities using the library (with a `--log` option).
+
+This interface is declared in `<libcasio/log.h>`. For forward compatibility
+purposes, it works with strings.
+
+To set the loglevel, use `casio_setlog()`, and to get a pointer to the current
+loglevel, use `casio_getlog()`.
+
+{% highlight c linenos %}
+void casio_setlog(const char *level);
+const char *casio_getlog(void);
+{% endhighlight %}
+
+Setting an unknown log level will simply result in setting the log level
+to `none`.
+
+Before setting the log level, you should list the recognized log levels.
+For this, use the `casio_setlog()` function:
+
+{% highlight c linenos %}
+typedef void casio_log_list_t(void *cookie, const char *str);
+void casio_listlog(casio_log_list_t *callback, void *cookie);
+{% endhighlight %}
+
+The callback will be called for every recognized log level. It is possible
+for the function to call the callback only once (see the `--no-log` option
+in [Getting started](getting-started.html)).
+
+An example log level listing is the following:
+
+{% highlight c linenos %}
+#include <stdio.h>
+#include <stdlib.h>
+#include <libcasio.h>
+
+void callback(void *cookie, const char *str)
+{
+	printf("- %s\n", str);
+}
+
+int main(void)
+{
+	printf("Available log levels:\n");
+	casio_listlog(&callback, NULL);
+	return (0);
+}
+{% endhighlight %}
+
+### Main interface for the library developers
+To use it, just include `internals.h` at source root, or include something
+that ends up including it, directly or indirectly. If the interface looks
+weird to you, that may be because this has been an experiment to make
+a logging system compatible with K&R and ANSI C (which explains the double
+parenthesis).
+
+There are two different types of logging in libcasio: message logging, and
+memory logging (which end up being the same to the user).
+
+First, message logging. The main macro for this is `msg((LEVEL, FORMAT, ...))`.
+The level is of the form `ll_<level>`, so `ll_info`, `ll_warn`, `ll_error`
+or `ll_fatal`. The format and arguments are for the printf-like function
+behind, so you can use `msg((ll_info, "%d + %s", 5, "coucou"))` for example.
+
+If you are doing a condition only for a logging instruction, with no `else if`
+or `else` clause in the same state behind, you can use the `ifmsg`, `elifmsg`
+and `elsemsg` macros. `ifmsg` and `elifmsg` take the condition and the
+arguments for the `msg` function. For example:
+
+{% highlight c linenos %}
+if (something.cool > 0) {
+	/* do something because it is cool */
+}
+elifmsg(something.cool == 0, (ll_warn, "The thing is not cool."))
+elsemsg((ll_error, "The thing has NEGATIVE coolness, that's not cool."))
+{% endhighlight %}
+
+The memory logging family are organized the same, except the names are
+`mem`, `ifmem`, `elifmem` and `elsemem`, and instead of the format and
+format arguments, you have the pointer and the memory area size, e.g.:
+
+{% highlight c linenos %}
+char cooldude = "COOLDUD\x7F";
+msg((ll_info, "Cool dude magic:"));
+mem((ll_info, cooldude, 8));
+{% endhighlight %}