[AD] First batch of doc changes

[Evert Glebbeek <eglebbk@xxxxxxxxxx>]

I'm going to post my proposed documentation changes section for section, 
otherwise I'm afraid it's going to be too much to look at each section.
Attached is my first proposal for the `Using Allegro' section. It documents 
some hither-to undocumented (but public and in one case even mentioned) 
macros and adds a few simple examples.

Evert

Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.337
diff -u -r1.337 allegro._tx
--- docs/src/allegro._tx	3 Jun 2005 16:39:31 -0000	1.337
+++ docs/src/allegro._tx	5 Jun 2005 12:06:16 -0000
@@ -154,8 +154,8 @@
    In order to maintain cross-platform compatibility, you have to put this
    macro at the very end of your main function. This macro uses some `magic'
    to mangle your main procedure on platforms that need it like Windows,
-   Linux or MacOS X. On the other platforms this macro compiles to nothing,
-   so you don't have to #ifdef around it. Example:
+   some flavours of UNIX or MacOS X. On the other platforms this macro 
+   compiles to nothing, so you don't have to #ifdef around it. Example:
 <codeblock>
       int main(void)
       {
@@ -177,7 +177,19 @@
 @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:
+<codeblock>
+      int main(void)
+      {
+	 if (allegro_init() != 0) {
+            allegro_message(allegro_error);
+            return -1;
+         }
+	 /* more stuff goes here */
+	 ...
+	 return 0;
+      }
+      END_OF_MAIN()<endblock>
 
 @@#define @ALLEGRO_VERSION
 @shortdesc Defined to the major version of Allegro.
@@ -217,6 +229,31 @@
       allegro_message("Year %d, month %d, day %d\n",
 	 year, month, day);<endblock>
 
+@@Macro @AL_ID(a,b,c,d)
+@shortdesc Converts four 8 bit values to a packed 32 bit integer ID.
+@xref DAT_ID
+   This macro can be used to create a packed 32 bit integer from 8 bit
+   characters. Example:
+<codeblock>
+      #define OSTYPE_LINUX       AL_ID('T','U','X',' ')<endblock>
+
+@@Macro @MAKE_VERSION(a, b, c)
+@shortdesc Create a 32 bit integer from the Allegro version
+@xref ALLEGRO_VERSION, ALLEGRO_SUB_VERSION, ALLEGRO_WIP_VERSION
+   This macro can be used to check if some Allegro version is (binary)
+   compatible with the current version. It is safe to use &gt; and &lt; to
+   check if one version is more recent than another. This is mainly useful for 
+   addon packages and libraries. See the `ABI compatibility information'
+   section of the manual for more detailed information. Example:
+<codeblock>
+      /* Check if the current version is compatible with Allegro 4.2.0 */
+      #if (MAKE_VERSION(4, 2, 0) == MAKE_VERSION(ALLEGRO_VERSION, \
+                         ALLEGRO_SUB_VERSION, ALLEGRO_WIP_VERSION))
+         /* Allegro 4.2.0 compatibility */
+      #else
+         /* Work-around */
+      #endif<endblock>
+   
 @@extern int @os_type;
 @xref allegro_init, os_version, os_multitasking
 @shortdesc Stores the detected type of the OS.
@@ -294,7 +331,9 @@
 @shortdesc Sets the window title of the Allegro program.
    On platforms that are capable of it, this routine alters the window title 
    for your Allegro program. Note that Allegro cannot set the window title 
-   when running in a DOS box under Windows.
+   when running in a DOS box under Windows. Example:
+<codeblock>
+   set_window_title("Allegro rules!");<endblock>
 
 @@int @set_close_button_callback(void (*proc)(void));
 @xref set_window_title
@@ -318,6 +357,32 @@
    
    Also note that the supplied callback is also called under MacOS X when
    the user hits Command-Q or selects "Quit" from the application menu.
+   Example:
+<codeblock>
+      #include <allegro.h>
+      volatile int close_button_pressed = FALSE;
+
+      void close_button_handler(void)
+      {
+         close_button_pressed = TRUE;
+      }
+      END_OF_FUNCTION(close_button_handler)
+      
+      int main(void)
+      {
+         allegro_init();
+         LOCK_FUNCTION(close_button_handler);
+         set_close_button_callback(close_button_handler);
+         ...
+         
+         while(close_button_pressed == FALSE) {
+            /* Do stuff */
+         }
+         
+         /* Shutdown */
+         ...
+      }
+      END_OF_MAIN()<endblock>
 @retval
    Returns zero on success and non-zero on failure (e.g. the feature is not
    supported by the platform).