[AD] [ alleg-Bugs-1752387 ] Errors in the documentation

["SourceForge.net" <noreply@xxxxxxxxxx>]

Bugs item #1752387, was opened at 2007-07-11 23:51
Message generated for change (Comment added) made by cgamesplay
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105665&aid=1752387&group_id=5665

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Mark Keller (markekeller)
Assigned to: Nobody/Anonymous (nobody)
Summary: Errors in the documentation

Initial Comment:
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@xxxxxxxxxx

----------------------------------------------------------------------

Comment By: Ryan Patterson (cgamesplay)
Date: 2007-07-12 09:01

Message:
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()).
+<codeblock>
+      unsigned int start, end, duration;
+      start = get_milliseconds();
+      rest(1000);
+      end = get_milliseconds();
+      duration = end - start;
+      allegro_message("Waited %u milliseconds", duration);
+<endblock>

-
 @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();<endblock>
@@ -9227,7 +9244,7 @@
 @shortdesc Loads a sample from a Creative Labs VOC file.
    Loads a sample from a Creative Labs VOC file. Example:
 <codeblock>
-      SAMPLE *sample = load_wav("alarm.wav");
+      SAMPLE *sample = load_voc("alarm.wav");
       if (!sample)
         abort_on_error("Couldn't alert user!");<endblock>
 @retval


----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105665&aid=1752387&group_id=5665