Errors in the documentation

[allebot]

Originally reported by: markekeller

Original Ticket: "alleg/bugs/107":https://sourceforge.net/p/alleg/bugs/107

Hello,

I really like Allegro, and am planning on using it in an upcoming project of mine. Therefore I've been reading through the docs, and came across a couple errors.

On the Digital Sample Routines page, you have the following:

SAMPLE load_voc(const char filename); Loads a sample from a Creative Labs VOC file. Example: SAMPLE *sample = load_wav("alarm.wav"); if (!sample) abort_on_error("Couldn't alert user!");

As you can see, thought, the example shows the load_wav function rather than the load_voc function. It should probably look like this, instead:

SAMPLE load_voc(const char filename); Loads a sample from a Creative Labs VOC file. Example: SAMPLE *sample = load_voc("alarm.voc"); if (!sample) abort_on_error("Couldn't alert user!");

And on the Keyboard Routines page:

int install_keyboard(); Installs the Allegro keyboard interrupt . . . Example: allegro_init(); install_timer(); install_keyboard(); /* We are not 100% sure we can read the keyboard yet! */ if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0) abort_on_error("Couldn't set graphic mode!")

  /* Now we are guaranteed to be able to read the keyboard. */
  readkey();

The abort_on_error function (which is not part of Allegro, I suppose it's supposed to be a function created by the user?) does not have a semi-colon at the end of its line, and therefore this code snippet does not compile. It should probably look like this (with the allegro_message function, instead?):

  allegro_init();
  install_timer();
  install_keyboard();
  /* We are not 100% sure we can read the keyboard yet! */
  if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0)
     allegro_message("Couldn't set graphic mode!");

  /* Now we are guaranteed to be able to read the keyboard. */
  readkey();

Thanks to all involved in creating this wonderful library, and its extensive documentation, too!

Mark Keller

markekeller@gmail.com

[allebot]

Original comment by: cgamesplay

Logged In: YES user_id=794965 Originator: NO

I don't seem to be able to attach files, but this patch fixes:

Index: docs/src/allegro._tx

--- docs/src/allegro._tx (revision 8069) +++ docs/src/allegro._tx (working copy) @@ -3250,8 +3250,25 @@ provided `callback' parameter is NULL, this function does exactly the same thing as calling rest().

+@@unsigned int @get_milliseconds() +@eref extimer +@shortdesc Returns the time in milliseconds.

• Returns the number of milliseconds elapsed since an arbitrary point in
• time. You can use this function to determine the number of
• milliseconds elapsed since the last call to the function by
• subtracting its value from the value of the last call to it. This
• function gives you fine-grained control over the timing of your
• application (more than is possible with some implementations of
• install_int_ex()). +
• unsigned int start, end, duration;
• start = get_milliseconds();
• rest(1000);
• end = get_milliseconds();
• duration = end - start;
• allegro_message("Waited %u milliseconds", duration); +

@heading Keyboard routines

@@ -3295,7 +3312,7 @@ install_keyboard(); /* We are not 100% sure we can read the keyboard yet! */ if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0)

• abort_on_error("Couldn't set graphic mode!")

•   abort_on_error("Couldn't set graphic mode!");

  /* Now we are guaranteed to be able to read the keyboard. */ readkey(); @@ -9227,7 +9244,7 @@ @shortdesc Loads a sample from a Creative Labs VOC file. Loads a sample from a Creative Labs VOC file. Example:

• SAMPLE *sample = load_wav("alarm.wav");
• SAMPLE *sample = load_voc("alarm.wav"); if (!sample) abort_on_error("Couldn't alert user!"); @retval

[allebot]

Original comment by: cgamesplay

Logged In: YES user_id=794965 Originator: NO

Correction: the docs need to say load_voc("alarm.voc"), not "alarm.wav".

Index: docs/src/allegro._tx

--- docs/src/allegro._tx (revision 8069) +++ docs/src/allegro._tx (working copy) @@ -3250,8 +3250,25 @@ provided `callback' parameter is NULL, this function does exactly the same thing as calling rest().

+@@unsigned int @get_milliseconds() +@eref extimer +@shortdesc Returns the time in milliseconds.

• Returns the number of milliseconds elapsed since an arbitrary point in
• time. You can use this function to determine the number of
• milliseconds elapsed since the last call to the function by
• subtracting its value from the value of the last call to it. This
• function gives you fine-grained control over the timing of your
• application (more than is possible with some implementations of
• install_int_ex()). +
• unsigned int start, end, duration;
• start = get_milliseconds();
• rest(1000);
• end = get_milliseconds();
• duration = end - start;
• allegro_message("Waited %u milliseconds", duration); +

@heading Keyboard routines

@@ -3295,7 +3312,7 @@ install_keyboard(); /* We are not 100% sure we can read the keyboard yet! */ if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0)

• abort_on_error("Couldn't set graphic mode!")

•   abort_on_error("Couldn't set graphic mode!");

  /* Now we are guaranteed to be able to read the keyboard. */ readkey(); @@ -9227,7 +9244,7 @@ @shortdesc Loads a sample from a Creative Labs VOC file. Loads a sample from a Creative Labs VOC file. Example:

• SAMPLE *sample = load_wav("alarm.wav");
• SAMPLE *sample = load_voc("alarm.voc"); if (!sample) abort_on_error("Couldn't alert user!"); @retval

[allebot]

Original comment by: wangp

Logged In: YES user_id=28616 Originator: NO

Fixed, thanks.