* Documentation improvements. Wrote a small migration guide and added the

skeleton of a tutorial for Jylam.

TODO

@@ -7,39 +7,27 @@
   - all the sprite stuff (loading, saving, blitting, transparency
      support, background colour support, thinking of a storage format,
      etc.)
-
   - Or maybe, instead of doing shit with the sprites, just allow canvases
      to have several buffers, allow to change the active buffer, and treat
      sprites like that.
-
   - ASCII/ANSI art loading functions (maybe load them as sprites)
 
-
   \subsection indep API-independent stuff
 
   - support for transparency (CUCUL_COLOR_TRANSPARENT)
-
   - Brightness, contrast support for bitmaps (the functions are here, we
      just need to fill them)
-
   - Error distribution dithering
-
   - Add a random factor to the random ditherer. No need to change the API
      for that, we can just pass "random:10" instead of "random" to the
      cucul_set_bitmap_dithering() function.
-
   - Implement the colour modes set in cucul_set_bitmap_color(). For the
      moment only "full16" and "16" are implemented.
-
   - Fix the thin ellipse rendering (currently it's only |s and -s, we
      could make them smoother by using ' ` , etc).
-
   - support for double width glyphs (also needs some libcaca changes)
-
   - better mask support in cucul_blit()
-
   - factor internal Unicode character conversions, especially UCS4 -> UTF-8
-
   - optimise exporters so that they do not allocate huge blocks of memory
      when they only need half of it.
 
@@ -51,20 +39,14 @@
   - text edit widget with cursor support (I'm unsure about this, it
      seems pretty difficult)
 
-
   \subsection indep API-independent stuff
 
   - Write a Linux console output
-
   - Better keyboard driver in an X terminal, see
      http://groups.yahoo.com/group/zepp/message/381
-
   - Unicode support for X11 (maybe through Xft)
-
   - fix Unicode support for ncurses
-
   - Unicode support for GL
-
   - and Jylam wants a framebuffer output
 
 
@@ -73,35 +55,27 @@
   \subsection needed Needed
 
   - Fix Python
-
   - Fix Perl
-
   - C# (it's the next big thing, believe me)
-
   - PHP (together with the HTML output it would allow for nice web
      applications)
 
-
   \subsection notimp Not that important
 
   - Ruby
-
   - Java
 
 
 \section kernel Kernel mode
 
   - keyboard support
-
   - printf/fprintf are missing
-
   - Improve malloc/free so that we can reuse freed memory
 
 
 \section doc Documentation
 
   - Write a tutorial.
-
   - Draw a nicer logo
 
 
@@ -110,25 +84,19 @@
   \section cacaview cacaview
 
   - File browser
-
   - open ANSI files
-
   - save in different formats
 
-
   \section cacadraw cacadraw
 
   - Does not exist yet, but I want it. A modern ANSI editor that can also
      do Unicode.
 
-
   \section cuculet CUCUlet
 
   - Does not exist yet, but I want it. A replacement for FIGlet that can
      also do Unicode
-
   - Colour support, of course: outputs to IRC, ANSI, HTML...
-
   - Can open FIGlet fonts
 
 */

caca/caca.h

@@ -143,7 +143,7 @@ enum caca_key
     CACA_KEY_F15 = 0x128  /**< The F15 key. */
 };
 
-/** \defgroup caca Basic libcaca functions
+/** \defgroup caca libcaca basic functions
  *
  *  These functions provide the basic \e libcaca routines for driver
  *  initialisation, system information retrieval and configuration.
@@ -159,7 +159,7 @@ unsigned int caca_get_display_height(caca_display_t *);
 int caca_set_display_title(caca_display_t *, char const *);
 /*  @} */
 
-/** \defgroup event Event handling
+/** \defgroup event libcaca event handling
  *
  *  These functions handle user events such as keyboard input and mouse
  *  clicks.

cucul/cucul.h

@@ -42,7 +42,7 @@ typedef struct cucul_buffer cucul_buffer_t;
 /** font structure */
 typedef struct cucul_font cucul_font_t;
 
-/** \defgroup colour Colour definitions
+/** \defgroup colour libcucul colour definitions
  *
  *  Colours that can be used with cucul_set_color().
  *
@@ -67,7 +67,7 @@ typedef struct cucul_font cucul_font_t;
 #define CUCUL_COLOR_TRANSPARENT 0x20 /**< The transparent colour. */
 /*  @} */
 
-/** \defgroup cucul Basic libcucul functions
+/** \defgroup cucul libcucul basic functions
  *
  *  These functions provide the basic \e libcaca routines for library
  *  initialisation, system information retrieval and configuration.
@@ -82,7 +82,7 @@ void cucul_free_canvas(cucul_canvas_t *);
 int cucul_rand(int, int);
 /*  @} */
 
-/** \defgroup buffer Buffer handling
+/** \defgroup buffer libcucul buffer handling
  *
  *  These functions provide methods to handle libcucul buffers.
  *
@@ -92,7 +92,7 @@ void * cucul_get_buffer_data(cucul_buffer_t *);
 void cucul_free_buffer(cucul_buffer_t *);
 /*  @} */
 
-/** \defgroup canvas Canvas drawing
+/** \defgroup canvas libcucul canvas drawing
  *
  *  These functions provide low-level character printing routines and
  *  higher level graphics functions.
@@ -108,7 +108,7 @@ void cucul_clear_canvas(cucul_canvas_t *, unsigned char);
 void cucul_blit(cucul_canvas_t *, int, int, cucul_canvas_t const *, cucul_canvas_t const *);
 /*  @} */
 
-/** \defgroup transform Canvas transformation
+/** \defgroup transform libcucul canvas transformation
  *
  *  These functions perform horizontal and vertical canvas flipping.
  *
@@ -119,7 +119,7 @@ void cucul_flop(cucul_canvas_t *);
 void cucul_rotate(cucul_canvas_t *);
 /*  @} */
 
-/** \defgroup prim Primitives drawing
+/** \defgroup prim libcucul primitives drawing
  *
  *  These functions provide routines for primitive drawing, such as lines,
  *  boxes, triangles and ellipses.
@@ -144,7 +144,7 @@ void cucul_draw_thin_triangle(cucul_canvas_t *, int, int, int, int, int, int);
 void cucul_fill_triangle(cucul_canvas_t *, int, int, int, int, int, int, char const *);
 /*  @} */
 
-/** \defgroup sprite Sprite handling
+/** \defgroup sprite libcucul sprite handling
  *
  *  These functions provide high level routines for sprite loading, animation
  *  and rendering.
@@ -160,7 +160,7 @@ void cucul_draw_sprite(cucul_canvas_t *, int, int, cucul_sprite_t const *, int);
 void cucul_free_sprite(cucul_sprite_t *);
 /*  @} */
 
-/** \defgroup dither Bitmap dithering
+/** \defgroup dither libcucul bitmap dithering
  *
  *  These functions provide high level routines for dither allocation and
  *  rendering.
@@ -190,7 +190,7 @@ void cucul_dither_bitmap(cucul_canvas_t *, int, int, int, int,
 void cucul_free_dither(cucul_dither_t *);
 /*  @} */
 
-/** \defgroup font Font handling
+/** \defgroup font libcucul font handling
  *
  *  These functions provide font handling routines and high quality
  *  canvas to bitmap rendering.
@@ -205,7 +205,7 @@ void cucul_render_canvas(cucul_canvas_t *, cucul_font_t *, void *,
 void cucul_free_font(cucul_font_t *);
 /*  @} */
 
-/** \defgroup exporter Exporters to various formats
+/** \defgroup exporter libcucul exporters to various formats
  *
  *  These functions export the current canvas to various text formats. It
  *  is necessary to call cucul_free_buffer() to dispose of the data.

doc/Makefile.am

@@ -1,6 +1,7 @@
 # $Id$
 
-EXTRA_DIST = doxygen.cfg.in footer.html header.html libcaca.dox $(man_MANS)
+EXTRA_DIST = doxygen.cfg.in footer.html header.html $(man_MANS) \
+             libcaca.dox user.dox migrating.dox tutorial.dox
 
 man_MANS = caca-config.1 cacafire.1 cacaview.1
 

doc/libcaca.dox

@@ -21,7 +21,7 @@
  software. It used to be licensed under the GNU Lesser General Public
  License, but that was not free enough.
 
- \section api The libcaca API
+ \section devel Developer's documentation
 
  \e libcaca relies on a low-level, device independent library, called
  \e libcucul. \e libcucul can be used alone as a simple ASCII and/or
@@ -30,34 +30,26 @@
  The complete \e libcucul and \e libcaca programming interface is
  available from the cucul.h and caca.h headers.
 
- \section env Environment variables
+ Some other topics are covered by specific sections:
 
- Some environment variables can be used to change the behaviour of
- \e libcaca without having to modify the program which uses them. These
- variables are:
+ - \subpage tutorial
+ - \subpage migrating
 
- \li \b CACA_DRIVER: set the backend video driver. In order of preference:
-     - \c conio uses the DOS conio.h interface.
-     - \c ncurses uses the ncurses library.
-     - \c slang uses the S-Lang library.
-     - \c x11 uses the native X11 driver.
-     - \c gl uses freeglut and opengl libraries.
-     - \c raw outputs to the standard output instead of rendering the
-       canvas. This is can be used together with cacaserver.
+ \section user User's documentation
 
- \li \b CACA_GEOMETRY: set the video display size. The format of this
-     variable must be XxY, with X and Y being integer values. This option
-     currently works with the network, X11 and GL drivers.
+ - \subpage env
 
- \li \b CACA_FONT: set the rendered font. The format of this variable is
-     implementation dependent, but since it currently only works with the
-     X11 driver, an X11 font name such as "fixed" or "5x7" is expected.
-
- \section Misc
+ \section misc Misc
 
  - \subpage news
  - \subpage authors
  - \subpage thanks
  - \subpage todo
 
+ \section license License
+
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the Do What The Fuck You Want To Public License, version
+ 2 as published by Sam Hocevar. For details see http://sam.zoy.org/wtfpl/ .
+
 */

doc/migrating.dox

@@ -0,0 +1,165 @@
+/* $Id$ */
+
+/** \page migrating Migrating from libcaca 0.9 to the 1.0 API
+
+ This section will guide you through the migration of a \e libcaca 0.9
+ application to the latest API version.
+
+ \section foo1 Overview
+
+ The most important changes in the 1.0 API of \e libcaca are the
+ \e libcaca / \e libcucul split and the object-oriented design. Where
+ you used to do:
+
+\code
+#include <caca.h>
+
+int main(void)
+{
+    /* Initialise libcaca */
+    caca_init();
+    /* Set window title */
+    caca_set_window_title("Hello!");
+    /* Choose drawing colours */
+    caca_set_color(CACA_COLOR_BLACK, CACA_COLOR_WHITE);
+    /* Draw a string at coordinates (0, 0) */
+    caca_putstr(0, 0, "This is a message");
+    /* Refresh display */
+    caca_refresh();
+    /* Wait for a key press event */
+    caca_wait_event(CACA_EVENT_KEY_PRESS);
+    /* Clean up library */
+    caca_end();
+
+    return 0;
+}
+\endcode
+
+ You now do:
+
+\code
+#include <cucul.h>
+#include <caca.h>
+
+int main(void)
+{
+    /* Initialise libcaca */
+    cucul_canvas_t *cv; caca_display_t *dp; caca_event_t ev;
+    cv = cucul_create_canvas(0, 0);
+    dp = caca_create_display(cv);
+    /* Set window title */
+    caca_set_display_title(dp, "Hello!");
+    /* Choose drawing colours */
+    cucul_set_color(cv, CUCUL_COLOR_BLACK, CUCUL_COLOR_WHITE);
+    /* Draw a string at coordinates (0, 0) */
+    cucul_putstr(cv, 0, 0, "This is a message");
+    /* Refresh display */
+    caca_refresh_display();
+    /* Wait for a key press event */
+    caca_get_event(dp, CACA_EVENT_KEY_PRESS, &ev, -1);
+    /* Clean up library */
+    caca_free_display(dp);
+    cucul_free_canvas(cv);
+
+    return 0;
+}
+\endcode
+
+ 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 cucul_ .
+
+ \section foo2 Function equivalence list
+
+ \subsection bar1 Basic functions
+
+ - \b caca_init(): use cucul_create_canvas() to create a \e libcucul canvas,
+   followed by caca_create_display() to attach a \e libcaca display to it.
+ - \b caca_set_delay(): unchanged.
+ - \b caca_get_feature(): deprecated.
+ - \b caca_set_feature(): deprecated, see cucul_set_dither_antialias(),
+   cucul_set_dither_color() and cucul_set_dither_mode() instead.
+ - \b caca_get_feature_name(): deprecated, see cucul_get_dither_mode_list(),
+   cucul_get_dither_antialias_list() and cucul_get_dither_color_list()
+   instead.
+ - \b caca_get_rendertime(): unchanged.
+ - \b caca_get_width(): use cucul_get_canvas_width().
+ - \b caca_get_height(): use cucul_get_canvas_height().
+ - \b caca_set_window_title(): use caca_set_display_title().
+ - \b caca_get_window_width(): use caca_get_display_width().
+ - \b caca_get_window_height(): use caca_get_display_height().
+ - \b caca_refresh(): use caca_refresh_display().
+ - \b caca_end(): use caca_free_display() to detach the \e libcaca display,
+   followed by cucul_free_canvas() to free the underlying \e libcucul canvas.
+
+ \subsection bar2 Event handling
+
+ - \b caca_get_event(): unchanged.
+ - \b caca_wait_event(): use caca_get_event() with a \c timeout argument
+   of \b -1.
+ - \b caca_get_mouse_x(): unchanged.
+ - \b caca_get_mouse_y(): unchanged.
+
+ \subsection bar3 Character printing
+
+ - \b caca_set_color(): use cucul_set_color() or cucul_set_truecolor().
+ - \b caca_get_fg_color(): deprecated.
+ - \b caca_get_bg_color(): deprecated.
+ - \b caca_get_color_name(): use cucul_get_color_name().
+ - \b caca_putchar(): use cucul_putchar().
+ - \b caca_putstr(): use cucul_putstr().
+ - \b caca_printf(): use cucul_printf().
+ - \b caca_clear(): use cucul_clear_canvas().
+
+ \subsection bar4 Primitives drawing
+
+ - \b caca_draw_line(): use cucul_draw_line().
+ - \b caca_draw_polyline(): use cucul_draw_polyline().
+ - \b caca_draw_thin_line(): use cucul_draw_thin_line().
+ - \b caca_draw_thin_polyline(): use cucul_draw_thin_polyline().
+
+ - \b caca_draw_circle(): use cucul_draw_circle().
+ - \b caca_draw_ellipse(): use cucul_draw_ellipse().
+ - \b caca_draw_thin_ellipse(): use cucul_draw_thin_ellipse().
+ - \b caca_fill_ellipse(): use cucul_fill_ellipse().
+
+ - \b caca_draw_box(): use cucul_draw_box().
+ - \b caca_draw_thin_box(): use cucul_draw_thin_box().
+ - \b caca_fill_box(): use cucul_fill_box().
+
+ - \b caca_draw_triangle(): use cucul_draw_triangle().
+ - \b caca_draw_thin_triangle(): use cucul_draw_thin_triangle().
+ - \b caca_fill_triangle(): use cucul_fill_triangle().
+
+ \subsection bar5 Mathematical functions
+
+ - \b caca_rand(): use cucul_rand()
+ - \b caca_sqrt(): this function is now deprecated
+
+ \subsection bar6 Sprite handling
+
+ The sprite handling functions are currently being reworked.
+
+ \subsection bar7 Bitmap handling
+
+ - \b caca_create_bitmap(): use cucul_create_dither().
+ - \b caca_set_bitmap_palette(): use cucul_set_dither_palette().
+ - \b caca_draw_bitmap(): use cucul_dither_bitmap().
+ - \b caca_free_bitmap(): use cucul_free_dither().
+
+ \section foo3 Compilation
+
+ The \c caca-config utility is deprecated in favour of the standard
+ \c pkg-config interface:
+
+\code
+gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
+gcc foobar.o -o foobar `pkg-config --libs caca`
+\endcode
+
+ \c caca-config is still provided as a convenience tool but will be removed
+ in the future.
+
+*/

doc/user.dox

@@ -0,0 +1,26 @@
+/* $Id$ */
+
+/** \page env 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
+ variables are:
+
+ \li \b CACA_DRIVER: set the backend video driver. In order of preference:
+     - \c conio uses the DOS conio.h interface.
+     - \c ncurses uses the ncurses library.
+     - \c slang uses the S-Lang library.
+     - \c x11 uses the native X11 driver.
+     - \c gl uses freeglut and opengl libraries.
+     - \c raw outputs to the standard output instead of rendering the
+       canvas. This is can be used together with cacaserver.
+
+ \li \b CACA_GEOMETRY: set the video display size. The format of this
+     variable must be \c XxY, with \c X and \c Y being integer values. This
+     option currently works with the X11 and GL drivers.
+
+ \li \b CACA_FONT: set the rendered font. The format of this variable is
+     implementation dependent, but since it currently only works with the
+     X11 driver, an X11 font name such as \c fixed or \c 5x7 is expected.
+
+*/