From 1fe8a8702a57767db4d017b6652924dcb51f52af Mon Sep 17 00:00:00 2001 From: Sam Hocevar Date: Tue, 19 May 2009 00:52:10 +0000 Subject: [PATCH] A lot of documentation updates here and there, including bugfixes dating back to the libcucul merge. --- caca/event.c | 3 +++ doc/doxygen.cfg.in | 2 ++ doc/migrating.dox | 39 ++++++++++++++++++++------------------- doc/style.dox | 7 +++++++ doc/tutorial.dox | 10 +++++----- doc/user.dox | 2 +- ruby/ruby-caca.dox | 8 ++++---- 7 files changed, 42 insertions(+), 29 deletions(-) diff --git a/caca/event.c b/caca/event.c index 127a2d3..792d7d3 100644 --- a/caca/event.c +++ b/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) diff --git a/doc/doxygen.cfg.in b/doc/doxygen.cfg.in index c2cd980..b28b6c8 100644 --- a/doc/doxygen.cfg.in +++ b/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 diff --git a/doc/migrating.dox b/doc/migrating.dox index 9846b62..3f6c76d 100644 --- a/doc/migrating.dox +++ b/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 + 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. diff --git a/doc/style.dox b/doc/style.dox index 5da16dd..35d80b4 100644 --- a/doc/style.dox +++ b/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: diff --git a/doc/tutorial.dox b/doc/tutorial.dox index 6c38023..871dcd2 100644 --- a/doc/tutorial.dox +++ b/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 diff --git a/doc/user.dox b/doc/user.dox index c1c8ff9..7882268 100644 --- a/doc/user.dox +++ b/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: diff --git a/ruby/ruby-caca.dox b/ruby/ruby-caca.dox index 99b1202..34d0153 100644 --- a/ruby/ruby-caca.dox +++ b/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