Re: [AD] Doc perusing

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

On 2004-10-03, Michal Molhanec <michal@xxxxxxxxxx> wrote:
> Grzegorz Adam Hankiewicz wrote:
> >Ah, very interesting indeed. And I think we can't go with calling
> >install_allegro(SYSTEM_NONE, ...) inside allegro_message because
> >of the errno/atexit variables. Suggestions?
> 
> document it. i think it's correct behaviour because it follows
> the rule "any allegro function could be called only after prior
> calling to allegro_init"

Your patched missed a few things. How do you like the attached
version?

Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.264
diff -u -r1.264 allegro._tx
--- docs/src/allegro._tx	6 Oct 2004 21:25:21 -0000	1.264
+++ docs/src/allegro._tx	7 Oct 2004 08:00:55 -0000
@@ -214,17 +214,21 @@
    Operating System is multitasking or not.
 
 @@void @allegro_message(const char *text_format, ...);
-@domain.hid set_uformat
+@xref allegro_init, install_allegro, set_uformat
 @eref Available Allegro examples
    Outputs a message, using a printf() format string. Usually you want to
    use this to report messages to the user in an OS independant way when some
-   Allegro subsystem (or allegro itself) cannot be initialised. But you must
-   not use this function if you are in a graphic mode, only before calling
-   set_gfx_mode(), or after a set_gfx_mode(GFX_TEXT). On platforms that have
-   a text console (DOS and Unix) it will print the string to that console,
-   attempting to work around codepage differences by reducing any accented
-   characters to 7-bit ASCII approximations, and on platforms featuring a
-   windowing system it will bring up a blocking GUI message box. Example:
+   Allegro subsystem cannot be initialised. But you must not use this function
+   if you are in a graphic mode, only before calling set_gfx_mode(), or after
+   a set_gfx_mode(GFX_TEXT). Also, this function depends on a system driver
+   being installed, which means that it won't display any message at all on
+   some platforms if you call it before initialising Allegro itself.
+
+   On platforms that have a text console (DOS and Unix) it will print the
+   string to that console, attempting to work around codepage differences by
+   reducing any accented characters to 7-bit ASCII approximations, and on
+   platforms featuring a windowing system it will bring up a blocking GUI
+   message box. Example:
 <codeblock>
       ret = allegro_init();
       if (ret != 0) {
Index: examples/exbitmap.c
===================================================================
RCS file: /cvsroot/alleg/allegro/examples/exbitmap.c,v
retrieving revision 1.5
diff -u -r1.5 exbitmap.c
--- examples/exbitmap.c	2 Aug 2004 11:33:09 -0000	1.5
+++ examples/exbitmap.c	7 Oct 2004 08:00:55 -0000
@@ -14,13 +14,14 @@
    BITMAP *the_image;
    PALETTE the_palette;
 
+   if (allegro_init() != 0)
+      return 1;
+
    if (argc != 2) {
       allegro_message("Usage: 'exbitmap filename.[bmp|lbm|pcx|tga]'\n");
       return 1;
    }
 
-   if (allegro_init() != 0)
-      return 1;
    install_keyboard();
 
    if (set_gfx_mode(GFX_AUTODETECT, 320, 200, 0, 0) != 0) {
Index: examples/exconfig.c
===================================================================
RCS file: /cvsroot/alleg/allegro/examples/exconfig.c,v
retrieving revision 1.3
diff -u -r1.3 exconfig.c
--- examples/exconfig.c	14 May 2003 18:46:11 -0000	1.3
+++ examples/exconfig.c	7 Oct 2004 08:00:55 -0000
@@ -29,7 +29,8 @@
 
 
    /* you should always do this at the start of Allegro programs */
-   allegro_init();
+   if (allegro_init() != 0)
+      return 1;
    /* set up the keyboard handler */
    install_keyboard();