Re: [AD] Doc perusing

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

On 2004-10-07, Michal Molhanec <michal@xxxxxxxxxx> wrote:
> heh, are you paid by some data-mining company :-) ?

Maybe I should try that kind of job. Do they pay well?

> [...] What is worse, you wording is a little bit incorrect because
> it should be "...before trying to initialize Allegro itself."

My bad, too sleepy in the morning. See 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 18:40:14 -0000
@@ -214,22 +214,28 @@
    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:
-<codeblock>
-      ret = allegro_init();
-      if (ret != 0) {
-	 allegro_message("Sorry, couldn't init Allegro (%d).\n", ret);
-	 exit(ret);
+   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 the message at all on
+   some platforms if Allegro has not been initialised correctly.
+
+   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>
+      if (allegro_init() != 0)
+	 exit(1);
+
+      if (init_my_data() != 0) {
+	 allegro_message("Sorry, missing game data!\n");
+	 exit(2);
       }<endblock>
 
 @@void @set_window_title(const char *name);
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 18:40:14 -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 18:40:14 -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();