Still making the docs
This commit is contained in:
parent
e4074fedae
commit
6014c57ce0
|
|
@ -2,14 +2,21 @@
|
|||
#*****************************************************************************#
|
||||
# Target for the end user #
|
||||
#*****************************************************************************#
|
||||
# Make it.
|
||||
all: -all
|
||||
|
||||
# Preview in local how it will render.
|
||||
preview prev: -all-watch
|
||||
|
||||
# Upload it to production (only for maintainers).
|
||||
show: -all -install
|
||||
|
||||
.PHONY: preview prev
|
||||
#*****************************************************************************#
|
||||
# Internal #
|
||||
#*****************************************************************************#
|
||||
JEK := bundle exec jekyll
|
||||
ROOT := cake@p7.planet-casio.com:libcasio_doc
|
||||
|
||||
# Prepare the bundle.
|
||||
-prepare:
|
||||
|
|
@ -23,5 +30,10 @@ preview prev: -all-watch
|
|||
-all-watch: -prepare
|
||||
$(JEK) serve --watch $(JEKYLL_OPT)
|
||||
|
||||
.PHONY: -prepare -all -all-watch
|
||||
# Upload.
|
||||
-install:
|
||||
find _site -type f -exec chmod 644 {} \;
|
||||
rsync -Prlt --delete _site/ "$(ROOT)"
|
||||
|
||||
.PHONY: -prepare -all -all-watch -install
|
||||
# End of file.
|
||||
|
|
|
|||
|
|
@ -1,12 +1,39 @@
|
|||
-
|
||||
name: Introduction
|
||||
uri: /
|
||||
name: Introduction
|
||||
uri: /
|
||||
-
|
||||
name: Getting started
|
||||
uri: /getting-started.html
|
||||
name: Getting started
|
||||
uri: /getting-started.html
|
||||
-
|
||||
sname: User documentation
|
||||
docs:
|
||||
-
|
||||
name: Logging
|
||||
uri: /logging.html
|
||||
-
|
||||
-
|
||||
name: Error management
|
||||
uri: /errors.html
|
||||
-
|
||||
name: Chararacter encoding
|
||||
uri: /char.html
|
||||
-
|
||||
name: Streams
|
||||
uri: /streams.html
|
||||
-
|
||||
name: Filesystems
|
||||
uri: /filesystems.html
|
||||
-
|
||||
name: Main filesystems
|
||||
uri: /mcs.html
|
||||
-
|
||||
name: Links and protocols
|
||||
uri: /link.html
|
||||
-
|
||||
name: Decoding files
|
||||
uri: /file.html
|
||||
-
|
||||
sname: Developer documentation
|
||||
docs:
|
||||
-
|
||||
name: Logging internals
|
||||
uri: /logging-internals.html
|
||||
|
|
|
|||
|
|
@ -6,10 +6,14 @@
|
|||
|
||||
<title>{{ site.title }}{% if page.title %} : {{ page.title }}{% endif %}</title>
|
||||
<meta name="description" content="{{ site.subtitle }}">
|
||||
<link rel="icon" href="favicon.png">
|
||||
<!--[if IE]>
|
||||
<link rel="shortcut icon" href="favicon.ico">
|
||||
<[endif]-->
|
||||
|
||||
<link rel="stylesheet" href="{{ site.baseurl }}/assets/bootstrap.min.css">
|
||||
<link rel="stylesheet" href="{{ site.baseurl }}/assets/syntax.css">
|
||||
<link rel="stylesheet" href="{{ site.baseurl }}/assets/main.css">
|
||||
<link rel="stylesheet" href="assets/bootstrap.min.css?upd">
|
||||
<link rel="stylesheet" href="assets/syntax.css?upd">
|
||||
<link rel="stylesheet" href="assets/main.css?upd">
|
||||
</head><body>
|
||||
<div class="container">
|
||||
|
||||
|
|
@ -21,8 +25,15 @@
|
|||
|
||||
<div class="row">
|
||||
<div id="navigation" class="col-sm-2"><ul class="nav nav-list">
|
||||
{% for section in site.data.sections %}
|
||||
<li><a href="{{ site.baseurl }}{{ section.uri }}">{{ section.name }}</a></li>
|
||||
{% for element in site.data.sections %}
|
||||
{% if element.name %}
|
||||
<li><a href="{{ site.baseurl }}{{ element.uri }}">{{ element.name }}</a></li>
|
||||
{% else %}
|
||||
<li><p>{{ element.sname }}</p></li>
|
||||
{% for document in element.docs %}
|
||||
<li><a href="{{ site.baseurl }}{{ document.uri }}">{{ document.name }}</a></li>
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
</ul></div>
|
||||
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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 `<libcasio/char.h>`,
|
||||
but as usual, including `<libcasio.h>` 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 <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <stdint.h>
|
||||
#include <libcasio.h>
|
||||
|
||||
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 %}
|
||||
|
|
@ -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 `<libcasio/error.h>`,
|
||||
although as usual, you should include `<libcasio.h>` 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.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 66 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 592 B |
|
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
layout: page
|
||||
title: decoding files
|
||||
---
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
layout: page
|
||||
title: filesystems
|
||||
---
|
||||
|
|
@ -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>`. 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/
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
layout: page
|
||||
title: links and protocols
|
||||
---
|
||||
|
|
@ -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_<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 %}
|
||||
|
|
@ -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_<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 %}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
layout: page
|
||||
title: main filesystems
|
||||
---
|
||||
|
|
@ -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 `<libcasio.h>`, or
|
||||
the stream-specific header, `<libcasio/stream.h>`.
|
||||
|
||||
### 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 <libcasio.h>
|
||||
{% 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 <libcasio.h>
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue