-{% for section in site.data.sections %}
- - {{ section.name }}
+{% for element in site.data.sections %}
+{% if element.name %}
+ - {{ element.name }}
+{% else %}
+ {{ element.sname }}
- {{ document.name }}
+{% endfor %}
+{% endif %}
{% endfor %}
diff --git a/docs/assets/main.css b/docs/assets/main.css
index cfd1c60..39df95d 100755
--- a/docs/assets/main.css
+++ b/docs/assets/main.css
@@ -9,10 +9,28 @@ pre, code, pre code {
border-radius: 0;
background-color: #f9f9f9;
font-size: 0.85em;
+ tab-size: 4;
+ -moz-tab-size: 4;
+ -o-tab-size: 4;
}
-
.highlight {
- background-color: #f9f9f9;
+ margin: 20px 0 10px;
+}
+.highlight > pre, .highlight > pre > code {
+ background-color: transparent;
+ padding: 0;
+}
+.highlight table {
+ width: 100%;
+}
+.highlight table td.gl {
+ width: 0;
+}
+.highlight table td {
+ padding: 0;
+}
+.highlight table pre {
+ margin: 0;
}
pre {
@@ -52,9 +70,17 @@ code {
font-size: 0.9em;
}
-#navigation li a {
- padding-left: 10px;
- padding-right: 10px;
+#navigation li {
+ padding-left: 0;
+}
+
+#navigation li p {
+ font-weight: bold;
+}
+
+#navigation li a, #navigation li p {
+ padding: 10px;
+ margin: 0;
}
#navigation .nav-header {
diff --git a/docs/char.md b/docs/char.md
new file mode 100644
index 0000000..1b9ccd6
--- /dev/null
+++ b/docs/char.md
@@ -0,0 +1,92 @@
+---
+layout: page
+title: character encoding and conversions
+---
+libcasio has its own portable character encoding conversion, resembling
+iconv. It supports Unicode transformation formats (UTF-8, UTF-16, UTF-32)
+and CASIO's proprietary character encoding named FONTCHARACTER according to
+the SDK it published in 2006 for the fx-9860G.
+
+The character conversion utilities are defined in `
`,
+but as usual, including `` for everything is recommended.
+
+### Opening and closing a conversion descriptor
+The conversion descriptor is the main object that will keep track of
+the conversion steps and status. Here are the main functions to manage it:
+
+{% highlight c linenos %}
+int casio_open_conv(casio_conv_t *cd, const char *to, const char *from);
+int casio_close_conv(casio_conv_t cd);
+{% endhighlight %}
+
+The `to` and `from` parameters of the `casio_open_conv()` function are the
+string identifiers of the source and destination encodings for the conversion.
+For example, use `casio_open_conv(&cd, "utf-8", "utf-32")` to open a descriptor
+that will be able to convert UTF-32 encoded data into UTF-8 encoded data.
+
+### Converting formats
+Once the conversion descriptor is opened, you can use the `casio_conv()`
+function, defined this way:
+
+{% highlight c linenos %}
+int casio_conv(casio_conv_t cd,
+ const char **in_buffer, size_t *in_left,
+ const char **out_buffer, size_t *out_left);
+{% endhighlight %}
+
+In the same fashion than iconv, this function is made for being called
+several times, usually because you read from a stream and write to another
+stream — although you can use it to convert data all at once.
+
+Here is a simple example using two buffers:
+
+{% highlight c linenos %}
+#include
+#include
+#include
+#include
+
+int main(void)
+{
+ int err = 0; casio_conv_t cd = NULL;
+ uint32_t buf0[] = {'H', 'e', 'l', 'l', 'o'};
+ size_t buf0_size = 5 * sizeof(uint32_t);
+ uint32_t buf1[] = {' ', 'w', 'o', 'r', 'l', 'd', '!'};
+ size_t buf1_size = 7 * sizeof(uint32_t);
+ char bufdata[30], *buf = &bufdata;
+ size_t outsize = 29; /* let space for the end zero */
+
+ /* Open the conversion descriptor. */
+ err = casio_open_conv(&cd, "utf-8", "utf-32");
+ if (err) {
+ fprintf(stderr, "Could not open the conversion desc.: %s",
+ casio_strerror(err));
+ goto fail;
+ }
+
+ /* Convert the first buffer. */
+ err = casio_conv(cd, &buf0, &buf0_size, &buf, &outsize);
+ if (err) {
+ fprintf(stderr, "Could not convert the first buffer: %s",
+ casio_strerror(err));
+ goto fail;
+ }
+
+ /* Convert the second buffer. */
+ err = casio_conv(cd, &buf1, &buf1_size, &buf, &outsize);
+ if (err) {
+ fprintf(stderr, "Could not convert the second buffer: %s",
+ casio_strerror(err));
+ goto fail;
+ }
+
+ /* Print the buffer. */
+ *buf = '\0';
+ fputs(bufdata, stdout);
+
+fail:
+ /* Close the conversion descriptor. */
+ casio_close_conv(cd);
+ return (err != 0);
+}
+{% endhighlight %}
diff --git a/docs/errors.md b/docs/errors.md
new file mode 100644
index 0000000..57cbce1
--- /dev/null
+++ b/docs/errors.md
@@ -0,0 +1,30 @@
+---
+layout: page
+title: error management
+---
+Almost all functions that can fail in libcasio return an `int`, even if
+they open a handle or descriptor of some kind (which is usually passed by
+using a pointer to it as a first argument). This integer corresponds to the
+error that occured in the function, or zero, representing the "everything
+went fine" error.
+
+The errors that can happen in libcasio are defined in ``,
+although as usual, you should include `` to access the code
+and utilities.
+
+Some errors are "relative", which means their significance depends on the
+function that returned it, when others are not. For example, `casio_error_op`
+means the function has received arguments that it doesn't manage (sometimes,
+yet), and it should not be transmitted as is, while `casio_error_read` can
+be transmitted without any risk.
+
+To get the full list of errors, you should read the header directly.
+If you simply want to get the error string, you can use the `casio_strerror()`
+function, which has the following prototype:
+
+{% highlight c linenos %}
+const char *casio_strerror(int err);
+{% endhighlight %}
+
+This string should only be used for displaying the error, as it could be
+translated in future versions of the library.
diff --git a/docs/favicon.ico b/docs/favicon.ico
new file mode 100644
index 0000000..88dc4c9
Binary files /dev/null and b/docs/favicon.ico differ
diff --git a/docs/favicon.png b/docs/favicon.png
new file mode 100644
index 0000000..6a828fe
Binary files /dev/null and b/docs/favicon.png differ
diff --git a/docs/file.md b/docs/file.md
new file mode 100644
index 0000000..bd0a045
--- /dev/null
+++ b/docs/file.md
@@ -0,0 +1,4 @@
+---
+layout: page
+title: decoding files
+---
diff --git a/docs/filesystems.md b/docs/filesystems.md
new file mode 100644
index 0000000..02804ff
--- /dev/null
+++ b/docs/filesystems.md
@@ -0,0 +1,4 @@
+---
+layout: page
+title: filesystems
+---
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 2927de7..8646cb3 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -4,8 +4,7 @@ title: getting started
---
The libcasio development happens [on Github][gh].
There is currently no mailing-list.
-The release source codes are available [here][pub] (all P7 projects are
-in the same folder).
+The release tarballs are available [here][pub].
libcasio is a development library, either shared or static.
There are many configuration options for adapting the library to your
@@ -31,4 +30,4 @@ To configure, use `./configure `. Options are used as
Other options are packaging options (todo: add info about them here).
[gh]: https://github.com/PlaneteCasio/libcasio
-[pub]: https://p7.planet-casio.com/pub/
+[pub]: https://libcasio.planet-casio.com/pub/
diff --git a/docs/index.md b/docs/index.md
index a4e37c1..2543857 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,7 +2,8 @@
layout: page
title: introduction
---
-This is the libcasio developer documentation.
+This is the libcasio documentation. It targets library users and library
+developers.
libcasio ought to become the _de facto_ standard when it comes to manipulating
protocols and file formats used with CASIO calculators. Most of it is
diff --git a/docs/link.md b/docs/link.md
new file mode 100644
index 0000000..54f74ed
--- /dev/null
+++ b/docs/link.md
@@ -0,0 +1,4 @@
+---
+layout: page
+title: links and protocols
+---
diff --git a/docs/logging-internals.md b/docs/logging-internals.md
new file mode 100644
index 0000000..c5cc461
--- /dev/null
+++ b/docs/logging-internals.md
@@ -0,0 +1,40 @@
+---
+layout: page
+title: logging internals
+---
+To use the libcasio logging interface, 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_`, 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 %}
diff --git a/docs/logging.md b/docs/logging.md
index 55b3b71..e7a78c7 100644
--- a/docs/logging.md
+++ b/docs/logging.md
@@ -2,6 +2,9 @@
layout: page
title: logging
---
+**This document only describes the library user control interface, which**
+**doesn't cover the actual logging, aimed at library developers.**
+
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):
@@ -14,7 +17,6 @@ different levels (plus a special one):
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).
@@ -54,6 +56,7 @@ An example log level listing is the following:
void callback(void *cookie, const char *str)
{
+ (void)cookie; /* no cookie, we don't want to use you */
printf("- %s\n", str);
}
@@ -64,41 +67,3 @@ int main(void)
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_`, 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 %}
diff --git a/docs/mcs.md b/docs/mcs.md
new file mode 100644
index 0000000..053350f
--- /dev/null
+++ b/docs/mcs.md
@@ -0,0 +1,4 @@
+---
+layout: page
+title: main filesystems
+---
diff --git a/docs/streams.md b/docs/streams.md
index 9f6dcf2..39d32dc 100644
--- a/docs/streams.md
+++ b/docs/streams.md
@@ -2,6 +2,10 @@
layout: page
title: streams
---
+Streams are the abstractions for exchanging data with anything: a local or
+distant file, a device through serial or USB communications, local memory
+(usually for simulation), etc.
+
When it wasn't libcasio yet (at the time, communication-related objects were
in libp7), libusb usage used to be hardcoded in the Protocol 7.00 management
functions (sending, receiving); then, it used FILE streams from the GNU libc
@@ -18,7 +22,7 @@ This document describes how to use and make a libcasio stream. Notice that
for the examples in this document, you shall include ``, or
the stream-specific header, ``.
-### Opening and closing
+### Opening and closing a stream
There are three ways to open a stream:
- with a specialized function, such as `casio_open_stream_streams()` for
@@ -35,27 +39,41 @@ the libcasio error code that occured (or 0 if no error has occured).
Once you are done with the stream, you shall close it, so that all of the
allocated resources can be free'd properly. In order to do this,
-you can simply use `casio_close()`. So here's a simple example using the
-`casio_open_memory()` function (which makes a stream out of memory):
+you can simply use `casio_close()`.
- #include
+{% highlight c linenos %}
+int casio_open_any_stream(casio_stream_t **stream, ...);
+int casio_close(casio_stream_t *stream);
+{% endhighlight %}
+
+So here's a simple example using the `casio_open_memory()` function
+(which makes a stream out of memory), for opening a stream and directly
+closing it:
+
+{% highlight c linenos %}
+#include
+
+void do_something()
+{
+ int err;
+ casio_stream_t *stream = NULL;
+ char zone[6];
- void do_something()
- {
- int err;
- casio_stream_t *stream = NULL;
- char zone[6];
-
- err = casio_open_memory(&stream, zone, 6);
- if (err) {
- /* an error has occured! */
- return ;
- }
-
- /* do something here, if an error occurs, make sure to
- close the stream anyway, or use the 'fail' label here */
- fail:
- err = casio_close(stream);
- /* you can check the error if you want, but the stream will always
- be closed at this point, more or less properly */
+ err = casio_open_memory(&stream, zone, 6);
+ if (err) {
+ /* an error has occured! */
+ return ;
}
+
+ /* do something here, if an error occurs, make sure to
+ close the stream anyway, or use the 'fail' label here */
+
+fail:
+ err = casio_close(stream);
+ /* you can check the error if you want, but the stream will always
+ be closed at this point, more or less properly */
+}
+{% endhighlight %}
+
+### Opening modes
+In libcasio, streams are cool.