A lot of documentation updates here and there, including bugfixes dating

back to the libcucul merge.

caca/event.c

@@ -229,6 +229,9 @@ uint32_t caca_get_event_key_utf32(caca_event_t const *ev)
  *  will be undefined. See caca_get_event_type() for more information.
  *
  *  \param ev The libcaca event.
+ *  \param utf8 A string buffer with enough bytes to hold the pressed
+ *              key value in UTF-8. Though fewer bytes may be written to
+ *              it, 7 bytes is the minimum safe size.
  *  \return This function always returns 0.
  */
 int caca_get_event_key_utf8(caca_event_t const *ev, char *utf8)

doc/doxygen.cfg.in

@@ -567,6 +567,8 @@ WARN_LOGFILE           =
 INPUT                  = @top_srcdir@ \
                          @top_srcdir@/doc \
                          @top_srcdir@/caca \
+                         @top_srcdir@/caca/codec \
+                         @top_srcdir@/caca/driver \
                          @top_srcdir@/ruby
 
 # This tag can be used to specify the character encoding of the source files 

doc/migrating.dox

@@ -47,7 +47,7 @@ int main(void)
     /* Initialise libcaca */
     caca_canvas_t *cv;
     caca_display_t *dp;
-    dp = caca_create_display(cv);
+    dp = caca_create_display(NULL);
     cv = caca_get_canvas(dp);
     /* Set window title */
     caca_set_display_title(dp, "Window");
@@ -71,9 +71,7 @@ int main(void)
 
  Note the following important things:
 
- - Functions now take an object handle as their first argument.
- - All input/output functions start with \b caca_ and all
-   drawing and text handling functions start with \b caca_ .
+ - Most functions now take an object handle as their first argument.
 
  \section foo2 Migration strategy
 
@@ -105,6 +103,9 @@ int main(void)
 \endcode
 </td></tr></table>
 
+ The modified code is guaranteed to build both with \e libcaca 0.x and
+ \e libcaca 1.0.
+
  \section foo3 Function equivalence list
 
  \subsection bar1 Basic functions
@@ -146,7 +147,7 @@ int main(void)
    uselessness.
  - \b caca_putchar(): use caca_put_char().
  - \b caca_putstr(): use caca_put_str().
- - \b caca_printf(): use caca_printf().
+ - \b caca_printf(): unchanged.
  - \b caca_clear(): use caca_clear_canvas().
 
  \subsection bar4 Primitives drawing
@@ -154,27 +155,27 @@ int main(void)
  These functions are almost unchanged, except for Unicode support and the
  fact that they now act on a given canvas.
 
- - \b caca_draw_line(): use caca_draw_line().
- - \b caca_draw_polyline(): use caca_draw_polyline().
- - \b caca_draw_thin_line(): use caca_draw_thin_line().
- - \b caca_draw_thin_polyline(): use caca_draw_thin_polyline().
+ - \b caca_draw_line(): unchanged.
+ - \b caca_draw_polyline(): unchanged.
+ - \b caca_draw_thin_line(): unchanged.
+ - \b caca_draw_thin_polyline(): unchanged.
 
- - \b caca_draw_circle(): use caca_draw_circle().
- - \b caca_draw_ellipse(): use caca_draw_ellipse().
- - \b caca_draw_thin_ellipse(): use caca_draw_thin_ellipse().
- - \b caca_fill_ellipse(): use caca_fill_ellipse().
+ - \b caca_draw_circle(): unchanged.
+ - \b caca_draw_ellipse(): unchanged.
+ - \b caca_draw_thin_ellipse(): unchanged.
+ - \b caca_fill_ellipse(): unchanged.
 
- - \b caca_draw_box(): use caca_draw_box().
+ - \b caca_draw_box(): unchanged.
  - \b caca_draw_thin_box(): use caca_draw_thin_box() or caca_draw_cp437_box().
- - \b caca_fill_box(): use caca_fill_box().
+ - \b caca_fill_box(): unchanged.
 
- - \b caca_draw_triangle(): use caca_draw_triangle().
- - \b caca_draw_thin_triangle(): use caca_draw_thin_triangle().
- - \b caca_fill_triangle(): use caca_fill_triangle().
+ - \b caca_draw_triangle(): unchanged.
+ - \b caca_draw_thin_triangle(): unchanged.
+ - \b caca_fill_triangle(): unchanged.
 
  \subsection bar5 Mathematical functions
 
- - \b caca_rand(): use caca_rand(). The second argument is different, make
+ - \b caca_rand(): unchanged, but the second argument is different, make
    sure you take that into account.
  - \b caca_sqrt(): this function is now deprecated, use your system's
    \b sqrt() call instead.

doc/style.dox

@@ -47,9 +47,16 @@ x = min(x1, x2, x3);
 
  \code
 int function(int);
+ \endcode
+
+ A space can be inserted after keywords such as \c for, \c while or \c if,
+ but consistency with the rest of the page is encouraged:
 
+ \code
 if(a == b)
     return;
+
+if (p == NULL)
  \endcode
 
  Do not put parentheses around return values:

doc/tutorial.dox

@@ -38,15 +38,15 @@ What does it do?
  - Set the display's window name (only available in windowed displays, does
    nothing otherwise).
  - Set the current canvas colours to black background and white foreground.
- - Write the string "This is a message" using the current colors onto the
-   canvas.
- - Refresh the display.
- - Wait for an event of type "CACA_EVENT_KEY_PRESS".
+ - Write the string \c "This is a message" onto the canvas, using the current
+   colour pair.
+ - Refresh the display, causing the text to be effectively displayed.
+ - Wait for an event of type \c CACA_EVENT_KEY_PRESS.
  - Free the display (release memory). Since it was created together with the
    display, the canvas will be automatically freed as well.
 
 You can then compile this code on an UNIX-like system using the following
-comman (requiring pkg-config and gcc):
+commans (requiring \c pkg-config and \c gcc):
 \code
 gcc `pkg-config --libs --cflags caca` example.c -o example
 \endcode

doc/user.dox

@@ -3,7 +3,7 @@
 /** \page libcaca-env Libcaca environment variables
 
  Some environment variables can be used to change the behaviour of
- \e libcaca without having to modify the program which uses them. These
+ \e libcaca without having to modify the program which uses it. These
  variables are:
 
  \li \b CACA_DRIVER: set the backend video driver. In order of preference:

ruby/ruby-caca.dox

@@ -1,6 +1,6 @@
 /*$Id$ */ /** \page libcaca-ruby-api Libcaca Ruby API
 
-Theclasses available for libcaca are :
+The classes available for libcaca are :
 
 \li\b Caca::Canvas : functions that have a caca_canvas_t* as first argument
 \li\b Caca::Dither : functions that have a caca_dither_t* as first argument
@@ -18,7 +18,7 @@ Theclasses available for libcaca are :
 \li\b Caca::Event::Resize
 \li\b Caca::Event::Quit
 
-Thecharacter set conversion functions are not available yet in the binding.
+The character set conversion functions are not available yet in the binding.
 
 \code
 $irb -rcaca
@@ -117,7 +117,7 @@ irb(main):015:0>Caca::Event::Resize.my_instance_methods
 =>["w", "h"]
 \endcode
 
-\sectionSamples
+\section Samples
 
 \code
 $ruby -rcaca -e 'c=Caca::Canvas.new(6, 3).fill_box(0,0,2,2,"#"[0]);
@@ -132,7 +132,7 @@ c.export_memory("irc")'
 $ruby -e 'puts Caca::Canvas.new(6,3).draw_thin_polyline([[0,0], [0,2],
 [5,2],[0,0]]).export_memory("irc")'
 -.
-|`.  
+| `.
 ----`-
 \endcode