* src/io.c:

+ Added caca_wait_event(), a blocking caca_get_event().
  * src/ examples/:
    + More documentation.
  * doc/doxygen.cfg.in:
    + doc/doxygen.cfg is now generated by configure, so that we can use
      @top_srcdir@ and we no longer need to hardcode PROJECT_NUMBER.
    + Create manpages.

configure.ac

@@ -116,6 +116,7 @@ AC_CONFIG_FILES([
   src/Makefile
   examples/Makefile
   doc/Makefile
+  doc/doxygen.cfg
   autotools/Makefile
   debian/Makefile
 ])

doc/Makefile.am

@@ -1,4 +1,4 @@
-EXTRA_DIST = doxygen.cfg footer.html header.html $(man_MANS)
+EXTRA_DIST = doxygen.cfg.in footer.html header.html $(man_MANS)
 
 man_MANS = caca-config.1 cacademo.1 caca-spritedit.1 cacaview.1
 
@@ -20,6 +20,6 @@ endif
 
 clean: clean-local
 clean-local:
-	-rm -Rf html latex
+	-rm -Rf html latex man
 	-rm -f stamp-latex stamp-doxygen
 

doc/doxygen.cfg → doc/doxygen.cfg.in

@@ -3,8 +3,8 @@
 #---------------------------------------------------------------------------
 # Project related configuration options
 #---------------------------------------------------------------------------
-PROJECT_NAME           = libcaca
-PROJECT_NUMBER         = 0.3
+PROJECT_NAME           = @PACKAGE@
+PROJECT_NUMBER         = @VERSION@
 OUTPUT_DIRECTORY       = .
 OUTPUT_LANGUAGE        = English
 USE_WINDOWS_ENCODING   = NO
@@ -61,7 +61,7 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = ../src
+INPUT                  = @top_srcdir@/src
 FILE_PATTERNS          = *.c \
                          *.h
 RECURSIVE              = YES
@@ -95,8 +95,8 @@ IGNORE_PREFIX          =
 GENERATE_HTML          = YES
 HTML_OUTPUT            = html
 HTML_FILE_EXTENSION    = .html
-HTML_HEADER            = header.html
-HTML_FOOTER            = footer.html
+HTML_HEADER            = @srcdir@/header.html
+HTML_FOOTER            = @srcdir@/footer.html
 HTML_STYLESHEET        = 
 HTML_ALIGN_MEMBERS     = YES
 GENERATE_HTMLHELP      = NO
@@ -139,7 +139,7 @@ RTF_EXTENSIONS_FILE    =
 GENERATE_MAN           = YES
 MAN_OUTPUT             = man
 MAN_EXTENSION          = .3caca
-MAN_LINKS              = NO
+MAN_LINKS              = YES
 #---------------------------------------------------------------------------
 # configuration options related to the XML output
 #---------------------------------------------------------------------------

examples/aafire.c

@@ -1,28 +1,28 @@
 /*
- *   cacafire      fire demo using libcaca
- *   Copyright (c) 2003 Sam Hocevar <sam@zoy.org>
- *                 Jan Hubicka (hubicka@freesoft.cz)
- *                 Thomas A. K. Kjaer (takjaer@daimi.aau.dk)
- *                 Tim Newsome (nuisance@cmu.edu)
- *                 Kamil Toman (toman@artax.karlin.mff.cuni.cz)
- *                 All Rights Reserved
+ *  cacafire      fire demo for libcaca
+ *  Copyright (c) 2003 Sam Hocevar <sam@zoy.org>
+ *                Jan Hubicka (hubicka@freesoft.cz)
+ *                Thomas A. K. Kjaer (takjaer@daimi.aau.dk)
+ *                Tim Newsome (nuisance@cmu.edu)
+ *                Kamil Toman (toman@artax.karlin.mff.cuni.cz)
+ *                All Rights Reserved
  *
- *   $Id$
+ *  $Id$
  *
- *   This program is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This program is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This program is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this program; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this program; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
 #ifdef LIBCACA

examples/demo.c

@@ -1,24 +1,24 @@
 /*
- *   demo          demo using libcaca
- *   Copyright (c) 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  demo          demo for libcaca
+ *  Copyright (c) 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   $Id$
+ *  $Id$
  *
- *   This program is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This program is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This program is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this program; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this program; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
 #include "config.h"

examples/spritedit.c

@@ -1,24 +1,24 @@
 /*
- *   spritedit     sprite editor using libcaca
- *   Copyright (c) 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  spritedit     sprite editor for libcaca
+ *  Copyright (c) 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   $Id$
+ *  $Id$
  *
- *   This program is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This program is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This program is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this program; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this program; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
 #include "config.h"

examples/view.c

@@ -1,24 +1,24 @@
 /*
- *   view          image viewer for libcaca
- *   Copyright (c) 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  view          image viewer for libcaca
+ *  Copyright (c) 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   $Id$
+ *  $Id$
  *
- *   This program is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This program is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This program is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this program; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this program; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
 #include "config.h"

src/bitmap.c

@@ -1,30 +1,30 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file bitmap.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Bitmap functions
+/** \file bitmap.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Bitmap functions
  *
- *   This file contains bitmap blitting functions.
+ *  This file contains bitmap blitting functions.
  */
 
 #include "config.h"

src/box.c

@@ -1,30 +1,30 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file box.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Simple box drawing functions
+/** \file box.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Simple box drawing functions
  *
- *   This file contains box drawing functions, both filled and outline.
+ *  This file contains box drawing functions, both filled and outline.
  */
 
 #include "config.h"

src/caca.c

@@ -1,32 +1,32 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file caca.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Main \e libcaca functions
+/** \file caca.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Main \e libcaca functions
  *
- *   This file contains the main functions used by \e libcaca applications to
- *   initialise the library, get the screen properties, set the framerate and
- *   so on.
+ *  This file contains the main functions used by \e libcaca applications to
+ *  initialise the library, get the screen properties, set the framerate and
+ *  so on.
  */
 
 #include "config.h"
@@ -61,10 +61,14 @@ enum caca_driver _caca_driver;
 static mmask_t oldmask;
 #endif
 
-/**
- * \brief Initialise libcaca.
+/** \brief Initialise \e libcaca.
  *
- * \return 0 upon success, a non-zero value if an error occurs.
+ *  This function initialises internal \e libcaca structures and the backend
+ *  that will be used for subsequent graphical operations. It must be the
+ *  first \e libcaca function to be called in a function. caca_end() should
+ *  be called at the end of the program to free all allocated resources.
+ *
+ *  \return 0 upon success, a non-zero value if an error occurs.
  */
 int caca_init(void)
 {
@@ -153,20 +157,22 @@ int caca_init(void)
     return 0;
 }
 
-/**
- * \brief Get the screen width.
+/** \brief Get the screen width.
+ *
+ *  This function returns the current screen width, in character cells.
  *
- * \return The screen width, in character cells.
+ *  \return The screen width.
  */
 unsigned int caca_get_width(void)
 {
     return _caca_width;
 }
 
-/**
- * \brief Get the screen height.
+/** \brief Get the screen height.
  *
- * \return The screen height, in character cells.
+ *  This function returns the current screen height, in character cells.
+ *
+ *  \return The screen height.
  */
 unsigned int caca_get_height(void)
 {
@@ -209,11 +215,14 @@ const char *caca_get_color_name(enum caca_color color)
     return color_names[color];
 }
 
-/**
- * \brief Get the current value of a feature.
+/** \brief Get the current value of a feature.
+ *
+ *  This function retrieves the value of an internal \e libcaca feature. A
+ *  generic feature value is expected, such as CACA_ANTIALIASING.
  *
- * \param feature The requested feature.
- * \return The current value of the feature.
+ *  \param feature The requested feature.
+ *  \return The current value of the feature or CACA_UNKNOWN_FEATURE if an
+ *          error occurred..
  */
 enum caca_feature caca_get_feature(enum caca_feature feature)
 {
@@ -231,11 +240,14 @@ enum caca_feature caca_get_feature(enum caca_feature feature)
     }
 }
 
-/**
- * \brief Set a feature.
+/** \brief Set a feature.
  *
- * \param feature The wanted feature.
- * \return void
+ *  This function sets an internal \e libcaca feature such as the antialiasing
+ *  or dithering modes. If a specific feature such as CACA_DITHERING_RANDOM,
+ *  caca_set_feature() will set it immediately. If a generic feature is given
+ *  instead, such as CACA_DITHERING, the default value will be used instead.
+ *
+ *  \param feature The requested feature.
  */
 void caca_set_feature(enum caca_feature feature)
 {
@@ -298,10 +310,11 @@ const char *caca_get_feature_name(enum caca_feature feature)
     }
 }
 
-/**
- * \brief Uninitialise libcaca.
+/** \brief Uninitialise \e libcaca.
  *
- * \return void
+ *  This function frees all resources allocated by caca_init(). After
+ *  caca_end() has been called, no other \e libcaca functions may be used
+ *  unless a new call to caca_init() is done.
  */
 void caca_end(void)
 {
@@ -346,6 +359,10 @@ void caca_end(void)
 #endif
 }
 
+/*
+ * XXX: The following functions are local.
+ */
+
 static void caca_init_driver(void)
 {
 #if defined(HAVE_GETENV) && defined(HAVE_STRCASECMP)

src/caca.h

@@ -1,88 +1,89 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
- *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
- *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
- *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file caca.h
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief The \e libcaca public header.
+/** \file caca.h
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief The \e libcaca public header.
  *
- *   This header contains the public types and functions that applications
- *   using \e libcaca may use.
+ *  This header contains the public types and functions that applications
+ *  using \e libcaca may use.
  */
 
-/**  \mainpage libcaca developer documentation
- *
- *   \section intro Introduction
- *
- *   \e libcaca is a graphics library that outputs text instead of pixels,
- *   so that it can work on older video cards or text terminals. It is not
- *   unlike the famous AAlib library. libcaca needs a terminal to work,
- *   thus it should work on all Unix systems (including Mac OS X) using
- *   either the slang library or the ncurses library, on DOS using the conio
- *   library, and on Windows systems using either slang or ncurses (through
- *   Cygwin emulation) or conio.
- *
- *   \e libcaca is free software, released under the GNU Lesser General
- *   Public License. This ensures that \e libcaca will always remain free
- *   software.
- *
- *   \section api The libcaca API
- *
- *   The complete \e libcaca programming interface is available from the
- *   caca.h header.
- *
- *   \section env Environment variables
- *
- *   Some environment variables can be used to change the behaviour of
- *   \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:
- *       - \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.
- *
- *   \li \b CACA_BACKGROUND: set the background type.
- *       - \c solid uses solid coloured backgrounds for all characters. This
- *         feature does not work with all terminal emulators. This is the
- *         default choice.
- *       - \c black uses only black backgrounds to render characters.
- *
- *   \li \b CACA_ANTIALIASING: set the antialiasing mode. Antialiasing
- *       smoothens the rendered image and avoids the commonly seen staircase
- *       effect.
- *       - \c none disables antialiasing.
- *       - \c prefilter uses a simple prefilter antialiasing method. This is
- *         the default choice.
- *
- *   \li \b CACA_DITHERING: set the dithering mode. Dithering is necessary
- *       when rendering a picture that has more colours than the usually
- *       available palette.
- *       - \c none disables dithering.
- *       - \c ordered2 uses a 2x2 Bayer matrix for dithering.
- *       - \c ordered4 uses a 4x4 Bayer matrix for dithering. This is the
- *         default choice.
- *       - \c ordered8 uses a 8x8 Bayer matrix for dithering.
- *       - \c random uses random dithering.
+/** \mainpage libcaca developer documentation
+ *
+ *  \section intro Introduction
+ *
+ *  \e libcaca is a graphics library that outputs text instead of pixels,
+ *  so that it can work on older video cards or text terminals. It is not
+ *  unlike the famous AAlib library. \e libcaca can use almost any virtual
+ *  terminal to work, thus it should work on all Unix systems (including
+ *  Mac OS X) using either the slang library or the ncurses library, on DOS
+ *  using the conio library, and on Windows systems using either slang or
+ *  ncurses (through Cygwin emulation) or conio. There is also a native X11
+ *  driver that does not require a text terminal.
+ *
+ *  \e libcaca is free software, released under the GNU Lesser General
+ *  Public License. This ensures that \e libcaca will always remain free
+ *  software.
+ *
+ *  \section api The libcaca API
+ *
+ *  The complete \e libcaca programming interface is available from the
+ *  caca.h header.
+ *
+ *  \section env Environment variables
+ *
+ *  Some environment variables can be used to change the behaviour of
+ *  \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:
+ *      - \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.
+ *
+ *  \li \b CACA_BACKGROUND: set the background type.
+ *      - \c solid uses solid coloured backgrounds for all characters. This
+ *        feature does not work with all terminal emulators. This is the
+ *        default choice.
+ *      - \c black uses only black backgrounds to render characters.
+ *
+ *  \li \b CACA_ANTIALIASING: set the antialiasing mode. Antialiasing
+ *      smoothens the rendered image and avoids the commonly seen staircase
+ *      effect.
+ *      - \c none disables antialiasing.
+ *      - \c prefilter uses a simple prefilter antialiasing method. This is
+ *        the default choice.
+ *
+ *  \li \b CACA_DITHERING: set the dithering mode. Dithering is necessary
+ *      when rendering a picture that has more colours than the usually
+ *      available palette.
+ *      - \c none disables dithering.
+ *      - \c ordered2 uses a 2x2 Bayer matrix for dithering.
+ *      - \c ordered4 uses a 4x4 Bayer matrix for dithering. This is the
+ *        default choice.
+ *      - \c ordered8 uses a 8x8 Bayer matrix for dithering.
+ *      - \c random uses random dithering.
  */
 
 #ifndef __CACA_H__
@@ -117,9 +118,6 @@ enum caca_color
     CACA_COLOR_WHITE = 15 /**< The colour index for white. */
 };
 
-/** \ingroup convenience */
-const char *caca_get_color_name(enum caca_color);
-
 /** \brief Internal features.
  *
  *  This enum lists all possible internal libcaca features such as the
@@ -151,9 +149,6 @@ enum caca_feature
     CACA_UNKNOWN_FEATURE = 0xffff /**< Unknown feature. */
 };
 
-/** \ingroup convenience */
-const char *caca_get_feature_name(enum caca_feature);
-
 /*
  * Backwards compatibility macros
  */
@@ -208,36 +203,54 @@ enum caca_key
 };
 
 /** \defgroup basic Basic functions
- *  \@{ */
+ *
+ *  These functions provide the basic \e libcaca routines for library
+ *  initialisation, system information retrieval and configuration.
+ *
+ *  @{ */
 int caca_init(void);
 void caca_set_delay(unsigned int);
 enum caca_feature caca_get_feature(enum caca_feature);
 void caca_set_feature(enum caca_feature);
+const char *caca_get_feature_name(enum caca_feature);
 unsigned int caca_get_rendertime(void);
 unsigned int caca_get_width(void);
 unsigned int caca_get_height(void);
 void caca_refresh(void);
 void caca_end(void);
-/** \@} */
+/*  @} */
 
 /** \defgroup event Event handling functions
- *  \@{ */
+ *
+ *  These functions handle user events such as keyboard input and mouse
+ *  clicks.
+ *
+ *  @{ */
 unsigned int caca_get_event(void);
-/** \@} */
+unsigned int caca_wait_event(void);
+/*  @} */
 
 /** \defgroup char Character printing functions
- *  \@{ */
+ *
+ *  These functions provide low-level character printing routines.
+ *
+ *  @{ */
 void caca_set_color(enum caca_color, enum caca_color);
 enum caca_color caca_get_fg_color(void);
 enum caca_color caca_get_bg_color(void);
+const char *caca_get_color_name(enum caca_color);
 void caca_putchar(int, int, char);
 void caca_putstr(int, int, const char *);
 void caca_printf(int, int, const char *, ...);
 void caca_clear(void);
-/** \@} */
+/*  @} */
 
 /** \defgroup prim Primitives drawing functions
- *  \@{ */
+ *
+ *  These functions provide routines for primitive drawing, such as lines,
+ *  boxes, triangles and ellipses.
+ *
+ *  @{ */
 void caca_draw_line(int, int, int, int, char);
 void caca_draw_polyline(const int x[], const int y[], int, char);
 void caca_draw_thin_line(int, int, int, int);
@@ -255,16 +268,23 @@ void caca_fill_box(int, int, int, int, char);
 void caca_draw_triangle(int, int, int, int, int, int, char);
 void caca_draw_thin_triangle(int, int, int, int, int, int);
 void caca_fill_triangle(int, int, int, int, int, int, char);
-/** \@} */
+/*  @} */
 
 /** \defgroup math Mathematical functions
- *  \@{ */
+ *
+ *  These functions provide a few useful math-related routines.
+ *
+ *  @{ */
 int caca_rand(int, int);
 unsigned int caca_sqrt(unsigned int);
-/** \@} */
+/*  @} */
 
 /** \defgroup sprite Sprite handling functions
- *  \@{ */
+ *
+ *  These functions provide high level routines for sprite loading, animation
+ *  and rendering.
+ *
+ *  @{ */
 struct caca_sprite;
 struct caca_sprite * caca_load_sprite(const char *);
 int caca_get_sprite_frames(const struct caca_sprite *);
@@ -274,10 +294,14 @@ int caca_get_sprite_dx(const struct caca_sprite *, int);
 int caca_get_sprite_dy(const struct caca_sprite *, int);
 void caca_draw_sprite(int, int, const struct caca_sprite *, int);
 void caca_free_sprite(struct caca_sprite *);
-/** \@} */
+/*  @} */
 
 /** \defgroup bitmap Bitmap handling functions
- *  \@{ */
+ *
+ *  These functions provide high level routines for bitmap allocation and
+ *  rendering.
+ *
+ *  @{ */
 struct caca_bitmap;
 struct caca_bitmap *caca_create_bitmap(unsigned int, unsigned int,
                                        unsigned int, unsigned int,
@@ -288,9 +312,7 @@ void caca_set_bitmap_palette(struct caca_bitmap *,
                              unsigned int b[], unsigned int a[]);
 void caca_draw_bitmap(int, int, int, int, const struct caca_bitmap *, void *);
 void caca_free_bitmap(struct caca_bitmap *);
-/** \@} */
-
-/** \defgroup convenience Convenience functions */
+/*  @} */
 
 #ifdef __cplusplus
 }

src/caca_internals.h

@@ -1,30 +1,30 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file caca_internals.h
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief The \e libcaca private header.
+/** \file caca_internals.h
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief The \e libcaca private header.
  *
- *   This header contains the private types and functions used by \e libcaca.
+ *  This header contains the private types and functions used by \e libcaca.
  */
 
 #ifndef __CACA_INTERNALS_H__

src/conic.c

@@ -1,31 +1,31 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file conic.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Ellipse and circle drawing functions
+/** \file conic.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Ellipse and circle drawing functions
  *
- *   This file contains ellipse and circle drawing functions, both filled
- *   and outline.
+ *  This file contains ellipse and circle drawing functions, both filled
+ *  and outline.
  */
 
 #include "config.h"

src/graphics.c

@@ -1,30 +1,30 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file graphics.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Character drawing functions
+/** \file graphics.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Character drawing functions
  *
- *   This file contains character and string drawing functions.
+ *  This file contains character and string drawing functions.
  */
 
 #include "config.h"
@@ -99,12 +99,14 @@ static unsigned int _caca_rendertime;
 static enum caca_color _caca_fgcolor = CACA_COLOR_LIGHTGRAY;
 static enum caca_color _caca_bgcolor = CACA_COLOR_BLACK;
 
-/**
- * \brief Set the default colour pair.
+/** \brief Set the default colour pair.
  *
- * \param fgcolor The desired foreground colour.
- * \param bgcolor The desired background colour.
- * \return void
+ *  This function sets the default colour pair. String functions such as
+ *  caca_printf() and graphical primitive functions such as caca_draw_line()
+ *  will use these colour pairs.
+ *
+ *  \param fgcolor The requested foreground colour.
+ *  \param bgcolor The requested background colour.
  */
 void caca_set_color(enum caca_color fgcolor, enum caca_color bgcolor)
 {
@@ -141,33 +143,39 @@ void caca_set_color(enum caca_color fgcolor, enum caca_color bgcolor)
     }
 }
 
-/**
- * \brief Get the current foreground colour.
+/** \brief Get the current foreground colour.
+ *
+ *  This function returns the current foreground colour that was set with
+ *  caca_set_color().
  *
- * \return The current foreground colour.
+ *  \return The current foreground colour.
  */
 enum caca_color caca_get_fg_color(void)
 {
     return _caca_fgcolor;
 }
 
-/**
- * \brief Get the current background colour.
+/** \brief Get the current background colour.
+ *
+ *  This function returns the current background colour that was set with
+ *  caca_set_color().
  *
- * \return The current background colour.
+ *  \return The current background colour.
  */
 enum caca_color caca_get_bg_color(void)
 {
     return _caca_bgcolor;
 }
 
-/**
- * \brief Print a character at given coordinates.
+/** \brief Print a character.
  *
- * \param x The X coordinate of the character.
- * \param y The Y coordinate of the character.
- * \param c The character to print.
- * \return void
+ *  This function prints a character at the given coordinates, using the
+ *  default foreground and background values. If the coordinates are outside
+ *  the screen boundaries, nothing is printed.
+ *
+ *  \param x X coordinate.
+ *  \param y Y coordinate.
+ *  \param c The character to print.
  */
 void caca_putchar(int x, int y, char c)
 {
@@ -212,13 +220,16 @@ void caca_putchar(int x, int y, char c)
     }
 }
 
-/**
- * \brief Print a string at given coordinates.
+/** \brief Print a string.
+ *
+ *  This function prints a string at the given coordinates, using the
+ *  default foreground and background values. The coordinates may be outside
+ *  the screen boundaries (eg. a negative Y coordinate) and the string will
+ *  be cropped accordingly if it is too long.
  *
- * \param x The X coordinate of the string.
- * \param y The Y coordinate of the string.
- * \param s The string to print.
- * \return void
+ *  \param x X coordinate.
+ *  \param y Y coordinate.
+ *  \param s The string to print.
  */
 void caca_putstr(int x, int y, const char *s)
 {
@@ -290,14 +301,18 @@ void caca_putstr(int x, int y, const char *s)
     }
 }
 
-/**
- * \brief Format a string at given coordinates.
+/** \brief Format a string.
  *
- * \param x The X coordinate of the string.
- * \param y The Y coordinate of the string.
- * \param format The format string to print.
- * \param ... Arguments to the format string.
- * \return void
+ *  This function formats a string at the given coordinates, using the
+ *  default foreground and background values. The coordinates may be outside
+ *  the screen boundaries (eg. a negative Y coordinate) and the string will
+ *  be cropped accordingly if it is too long. The syntax of the format
+ *  string is the same as for the C printf() function.
+ *
+ *  \param x X coordinate.
+ *  \param y Y coordinate.
+ *  \param format The format string to print.
+ *  \param ... Arguments to the format string.
  */
 void caca_printf(int x, int y, const char *format, ...)
 {
@@ -326,10 +341,9 @@ void caca_printf(int x, int y, const char *format, ...)
         free(buf);
 }
 
-/**
- * \brief Clear the screen.
+/** \brief Clear the screen.
  *
- * \return void
+ *  This function clears the screen using a black background.
  */
 void caca_clear(void)
 {
@@ -637,21 +651,31 @@ int _caca_end_graphics(void)
     return 0;
 }
 
-/**
- * \brief Set the refresh delay.
+/** \brief Set the refresh delay.
+ *
+ *  This function sets the refresh delay in microseconds. The refresh delay
+ *  is used by caca_refresh() to achieve constant framerate. See the
+ *  caca_refresh() documentation for more details.
+ *
+ *  If the argument is zero, constant framerate is disabled. This is the
+ *  default behaviour.
  *
- * \param usec The refresh delay in microseconds.
- * \return void
+ *  \param usec The refresh delay in microseconds.
  */
 void caca_set_delay(unsigned int usec)
 {
     _caca_delay = usec;
 }
 
-/**
- * \brief Get the average rendering time.
+/** \brief Get the average rendering time.
  *
- * \return The render time in microseconds.
+ *  This function returns the average rendering time, which is the average
+ *  measured time between two caca_refresh() calls, in microseconds. If
+ *  constant framerate was activated by calling caca_set_delay(), the average
+ *  rendering time will not be considerably shorter than the requested delay
+ *  even if the real rendering time was shorter.
+ *
+ *  \return The render time in microseconds.
  */
 unsigned int caca_get_rendertime(void)
 {
@@ -678,10 +702,16 @@ static unsigned int _caca_getticks(void)
     return ticks;
 }
 
-/**
- * \brief Flush pending changes and redraw the screen.
+/** \brief Flush pending changes and redraw the screen.
+ *
+ *  This function flushes all graphical operations and prints them to the
+ *  screen. Nothing will show on the screen caca_refresh() is not called.
  *
- * \return void
+ *  If caca_set_delay() was called with a non-zero value, caca_refresh()
+ *  will use that value to achieve constant framerate: if two consecutive
+ *  calls to caca_refresh() are within a time range shorter than the value
+ *  set with caca_set_delay(), the second call will wait a bit before
+ *  performing the screen refresh.
  */
 void caca_refresh(void)
 {

src/io.c

@@ -1,30 +1,30 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file io.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Event handling functions
+/** \file io.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Event handling functions
  *
- *   This file contains event handling functions for keyboard and mouse input.
+ *  This file contains event handling functions for keyboard and mouse input.
  */
 
 #include "config.h"
@@ -54,8 +54,12 @@ static unsigned int _read_key(void);
 static unsigned int keybuf[KEY_BUFLEN + 1]; /* zero-terminated */
 static int keys = 0;
 
-/**
- * \brief Get the next mouse or keyboard input event.
+/** \brief Get the next mouse or keyboard input event.
+ *
+ *  This function polls the event queue for mouse or keyboard events and
+ *  returns the event. It is non-blocking and returns zero if no event is
+ *  pending in the queue. See also caca_wait_event() for a blocking version
+ *  of this function.
  *
  * \return The next event in the queue, or 0 if no event is pending.
  */
@@ -186,6 +190,31 @@ unsigned int caca_get_event(void)
     return CACA_EVENT_KEY_PRESS | '\x1b';
 }
 
+/** \brief Wait for the next mouse or keyboard input event.
+ *
+ *  This function returns the first mouse or keyboard event in the queue. If
+ *  no event is pending, it blocks until an event is received. See also
+ *  caca_get_event() for a non-blocking version of this function.
+ *
+ *  \return The next event in the queue.
+ */
+unsigned int caca_wait_event(void)
+{
+    for( ; ; )
+    {
+        unsigned int event = caca_get_event();
+
+        if(event)
+            return event;
+
+        usleep(1000);
+    }
+}
+
+/*
+ * XXX: The following functions are local.
+ */
+
 static void _push_key(unsigned int key)
 {
     if(keys == KEY_BUFLEN)

src/line.c

@@ -1,31 +1,31 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file line.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Line drawing functions
+/** \file line.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Line drawing functions
  *
- *   This file contains line and polyline drawing functions, with both thin
- *   and thick styles.
+ *  This file contains line and polyline drawing functions, with both thin
+ *  and thick styles.
  */
 
 #include "config.h"
@@ -78,9 +78,9 @@ void caca_draw_line(int x1, int y1, int x2, int y2, char c)
 
 /**
  * \brief Draw a polyline on the screen using the given character and
- *        coordinate arrays. The first and last points are not connected,
- *        so in order to draw a polygon you need to specify the starting
- *        point at the end of the list as well.
+ *       coordinate arrays. The first and last points are not connected,
+ *       so in order to draw a polygon you need to specify the starting
+ *       point at the end of the list as well.
  *
  * \param x Array of X coordinates. Must have \p n + 1 elements.
  * \param y Array of Y coordinates. Must have \p n + 1 elements.
@@ -127,9 +127,9 @@ void caca_draw_thin_line(int x1, int y1, int x2, int y2)
 
 /**
  * \brief Draw a thin polyline on the screen using the given coordinate
- *        arrays and with ASCII art. The first and last points are not
- *        connected, so in order to draw a polygon you need to specify the
- *        starting point at the end of the list as well.
+ *       arrays and with ASCII art. The first and last points are not
+ *       connected, so in order to draw a polygon you need to specify the
+ *       starting point at the end of the list as well.
  *
  * \param x Array of X coordinates. Must have \p n + 1 elements.
  * \param y Array of Y coordinates. Must have \p n + 1 elements.
@@ -239,7 +239,7 @@ static uint8_t clip_bits(int x, int y)
 
 /**
  * \brief Solid line drawing function, using Bresenham's mid-point line
- *        scan-conversion algorithm.
+ *       scan-conversion algorithm.
  *
  * \param s a line structure
  * \return void

src/math.c

@@ -1,30 +1,30 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file math.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Math functions
+/** \file math.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Math functions
  *
- *   This file contains simple mathematical routines.
+ *  This file contains simple mathematical routines.
  */
 
 #include "config.h"

src/sprite.c

@@ -1,30 +1,30 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file sprite.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Sprite loading and blitting
+/** \file sprite.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Sprite loading and blitting
  *
- *   This file contains a small framework for sprite loading and blitting.
+ *  This file contains a small framework for sprite loading and blitting.
  */
 
 #include "config.h"

src/triangle.c

@@ -1,30 +1,30 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
  *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
  *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
  *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
  */
 
-/**  \file triangle.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Triangle drawing functions
+/** \file triangle.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Triangle drawing functions
  *
- *   This file contains triangle drawing functions, both filled and outline.
+ *  This file contains triangle drawing functions, both filled and outline.
  */
 
 #include "config.h"