Re: [AD] First batch of doc changes

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

On 2005-06-10, Evert Glebbeek <eglebbk@xxxxxxxxxx> wrote:
>  @shortdesc Stores the last Allegro error message.
>     Text string used by set_gfx_mode() and install_sound() to report error 
>     messages. If they fail and you want to tell the user why, this is the 
> -   place to look for a description of the problem.
> +   place to look for a description of the problem. Example:

Just noticed that description is not too correct any more, as other
functions in Allegro might want to use it too.

   Text string used by set_gfx_mode(), install_sound() and other functions to
   report error messages. If they...

Also I would like to change slightly the example I proposed:

+         allegro_message("%s.\nLast Allegro error `%s'\n",
+                         message, allegro_error);

I think the "last" bit is necessary because set_gfx_mode() has a
bad habit of garbling allegro_error while trying different graphic
modes. In fact, I remember one proposal to make some sort of
ring buffer with a few last error messages or something like that.
Hmmm... not that this really matters that much, a real abort_on_error
would possibly check that allegro_error is not empty and empty it
after reporting the error. Too much work for a small example I guess.

> +   textout_centre_ex(screen, font, "Center the joystick and press a key",
> +                     SCREEN_W/2, SCREEN_H/2, red_color, -1);
> +   readkey();
> +   if (install_joystick(JOY_TYPE_AUTODETECT) != 0) {
> +      abort_on_error("Error initialising joystick!");
> +      return 1;
> +   }<endblock>

If we consider an abort_on_error implementation as suggested by
allegro_error, that return is never reached.

> +      if (!bmp)
> +         abort_on_error("Error loading mybitmap.bmp");</endblock>

Those nasty </endblock> have to be <endblock> for the texinfo
version of the manual to compile. There are three of them.

Good stuff.