Re: [AD] First batch of doc changes

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

On 2005-06-05, Evert Glebbeek <eglebbk@xxxxxxxxxx> wrote:
> +   Note that if you are using hardware accelerated VRAM->VRAM blits, you should
> +   not call acquire_bitmap().

The greater than symbol should be encoded with &gt.

> -   A version of load_bmp which reads from a packfile.
> +   A version of load_bmp which reads from a packfile. Example:
> +<codeblock>
> +   PACKFILE *f;

Identation.

> +   BITMAP *bmp;
> +
> +   f = pack_fopen("mybitmap.bmp", F_READ);
> +   bmp = load_bmp_pf(f, pal);
> +   pack_fclose(f);</endblock>
> +
> +@retval

One empty line too much. I just posted an update for
load_wav/_pf(). The examples should try to avoid leaving return
values unchecked unless the documentation says it is optional for
the programmer to check the value. Therefore I invented that magical
abort_or_error() thingy.

I didn't close the packfile too, maybe the user would have a use
reading a few bitmaps sequentially from the same file? Is this
possible at all?  Anyway, the example is about load_bmp_pf, the
rest is quite cosmetical.

> -   A version of load_pcx which reads from a packfile.
> +   A version of load_pcx which reads from a packfile. Example:
> -   A version of load_tga which reads from a packfile.
> +   A version of load_tga which reads from a packfile. Example:

A version of load_pcx() which reads from a packfile.

>     type parameter should usually be JOY_TYPE_AUTODETECT, or see the platform 
>     specific documentation for a list of the available drivers. You must call 
>     this routine before using any other joystick functions, and you should 
> -   make sure that the joystick is in the middle position at the time.
> +   make sure that the joystick is in the middle position at the time. Example:
> +<codeblock>
> +   if (install_joystick(JOY_TYPE_AUTODETECT) != 0) {
> +      set_gfx_mode(GFX_TEXT, 0, 0, 0, 0);
> +      allegro_message("Error initialising joystick\n%s\n", allegro_error);
> +      return 1;
> +   }<endblock>

For the purposes of the example, I would cut out all the code
in the branch and replace that with the magical abort_on_error()
function. It is more important to have the user center the joystick,
so maybe the example should be:

    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!");

Hmmm... now that I look at it your version is better at highlighting
the use o allegro_error.  Hmmm... today I feel evil, how about this?

@@extern char @allegro_error[ALLEGRO_ERROR_SIZE];
@xref set_gfx_mode, install_sound
@eref Available Allegro examples
@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. Example:
<codeblock>
      void abort_on_error(const char *message)
      {
         if (screen != NULL)
            set_gfx_mode(GFX_TEXT, 0, 0, 0, 0);

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

         exit(-1);
      }
      ...
         if (some_allegro_function() == ERROR_CODE)
            abort_on_error("Error calling some function!");<endblock>

> +      /* Get joystick input */
> +      poll_joystick();
> +      
> +      /* Process input */
> +      if (joy[0].button[0].b)

I would use /* Process just the first joystick's input. */ or try
to change the example to use a loop.

>     page flipping, so you don't need to call vsync() before it. This means
> -   that show_video_bitmap() has the same time delay effects as vsync().
> +   that show_video_bitmap() has the same time delay effects as vsync(). Example:
> +<codeblock>
> +   int current_page;

Identation.

> +   the comments about request_scroll(). Example:
> +<codeblock>
> +   int current_page;

Identation.

> +   There are a few things you need to be aware of for scrolling:
> +   most VESA implementations can only handle horizontal scrolling in four 
> +   pixel increments, so smooth horizontal panning is impossible in SVGA modes. 
> +   A significant number of VESA implementations seem to be very buggy when it 
> +   comes to scrolling in truecolor video modes, so you shouldn't depend on 
> +   this routine working correctly in the truecolor resolutions unless you can
> +   be sure that SciTech Display Doctor is installed.

Maybe add too that hardware scrolling is impossible under Windows
(IIRC).