               ____      _   _   _               _   _      _
              / ___| ___| |_| |_(_)_ __   __ _  | | | | ___| |_ __
             | |  _ / _ \ __| __| | '_ \ / _` | | |_| |/ _ \ | '_ \
             | |_| |  __/ |_| |_| | | | | (_| | |  _  |  __/ | |_) |
              \____|\___|\__|\__|_|_| |_|\__, | |_| |_|\___|_| .__/
                                         |___/               |_|



======================================
============ Introduccin ============
======================================

   Cuando las cosas van mal, a menudo parece buena idea pedir a otras
   personas ayuda. Afortunadamente para las personas en esta situacin, hay
   muchas personas (tanto desarrolladores de Allegro como usuarios) que
   estn dispuestas a responder preguntas de este tipo, pero hay varias
   cosas que puede hacer para que este proceso sea ms eficiente. Este
   documento describe algunos pasos que debe tomar cuando tiene un problema
   con un programa que use Allegro, sugiriendo modos de solucionar el
   problema usted mismo, y enseando trucos sobre cundo y/o cmo pedir
   ayuda. El seguir estas reglas har la vida ms sencilla para el que le
   ayude (porque toda la informacin relevante ser presentada de modo
   conciso y til), y para el ayudado (porque as ser ms probable que
   reciba una respuesta rpida y precisa).



==========================================================
============ Parte 1 - quin es el culpable? ============
==========================================================

   Es un problema de Allegro, o de su cdigo? Para descubrirlo, pruebe
   ejecutar los programas test de Allegro, en particular test.exe (si tiene
   problemas con los grficos), play.exe (problemas de sonido), y el
   contenido completo del directorio examples (para cualquier cosa que vaya
   mal). Si no puede reproducir el problema con uno de stos, entonces
   probablemente es un fallo suyo, por lo que salte a la parte 3 ms abajo.

   Si el problema est relacionado con los modos grficos del DOS, debera
   empezar por conseguir una copia del programa Display Doctor de
   http://www.scitechsoft.com/.
   Si esto soluciona el problema, significa con toda seguridad que su driver
   VESA original estaba estropeado de alguna manera.
   No estoy interesado en leer mensajes sobre problemas de este tipo: no hay
   nada que pueda hacer para corregirlos, por lo que me temo que su nica
   opcin es conseguir un driver VESA mejor, ya sea solicitando al fabricante
   de su tarjeta que solucione sus errores, comprando Display Doctor, o
   escribiendo un driver FreeBE/AF para su tarjeta (mire en
   http://www.talula.demon.co.uk/freebe/).

   Si el problema tiene que ver con los modos grficos, debera conseguir
   una copia de UniVBE de http://www.scitechsoft.com/. Si esto soluciona
   el problema, significa que su driver VESA original estaba estropeado de
   alguna manera. No estoy interesado en or problemas de este tipo: no hay
   nada que pueda hacer para solucionarlos, me temo que su nica opcin es
   conseguir un driver VESA mejor, obligando al fabricante de tu tarjeta a
   que solucione los fallos, comprando UniVBE, o escribiendo un driver
   FreeBE/AF para su tarjeta (mire en http://www.talula.demon.co.uk/freebe/).



========================================================
============ Parte 2 - cuando Allegro falla ============
========================================================

   Si sigue creyendo que el problema es de Allegro, mande un mensaje con una
   descripcin sobre su sistema y el problema, indique la versin de Allegro
   y su plataforma, su configuracin de hardware, y una lista exacta de los
   programas que pueden reproducir su problema (es importante saber qu
   programas no funcionan, y cuales s, en caso de que funcione alguno).

   Si el problema est relacionado con modos grficos del DOS, tambin
   debera mandar los resultados producidos por los programas afinfo y
   vesainfo (la versin reducida es suficiente a no ser que se le indique
   especficamente usar el parmetro -v: esos datos extra no son necesarios
   normalmente). Pruebe ejecutar el programa test.exe con varios drivers de
   Allegro (otros drivers nativos que crea puedan funcionar con su tarjeta,
   el driver VESA 1.x y VESA 2.0), en varios modos de vdeo, y describa
   exctamente qu resoluciones causan problemas. Si es capaz de ejecutar los
   programas en resoluciones SVGA, ejecute test.exe con la opcin Autodetect
   e indique el texto completo que aparece en el medio de la pantalla.

   Si el problema est relacionado con el sistema de sonido del DOS, pruebe
   usar el programa setup para configurar manualmente su tarjeta. Quizs
   tenga que introducir manualmente los parmetros del hardware, y si se
   trata de una tarjeta clon de la SB, pruebe seleccionar una versin
   anterior a la que est siendo autodetectada (SB Pro, SB 2.0, o SB 1.0). Si
   sigue sin conseguir que funcione, su mensaje de ayuda debera incluir el
   nombre y descripcin de los drivers que estn siendo autodetectados (sta
   informacin es mostrada por el programa play.exe).



============================================================
============ Parte 3 - cuando su programa falla ============
============================================================

   Cuando un programa djgpp falla, normalmente volcar el contenido de la
   pila que parecer algo como esto:

      Exiting due to signal SIGSEGV
      General Protection Fault at eip=00001eca
      [corte]

      Call frame traceback EIPs:
        0x00001eca
        0x00001590
        0x00001aea

   Esta informacin le indica exactamente dnde ocurri el fallo. Para que
   estos datos tengan sentido, debe compilar su programa con informacin de
   depurado (usando el parmetro -g), y ejecutar "symify programa.exe" cuando
   est viendo el contenido de la pila en pantalla. Eso cambiar los datos
   a algo parecido a esto:

      Call frame traceback EIPs:
        0x00001eca   _strcpy+14
        0x00001590   _main+56, line 7 of t.c
        0x00001aea   ___crt1_startup+138

   En este caso, puede ver que el bloqueo ocurri en la funcin strcpy(),
   que fue llamada en la lnea 7 de la funcin main() del fichero fuente
   t.c. Ahora slo tienes que ir a esa lnea, mirar lo que est haciendo
   all, y corregirlo :-)

   Nota: si el bloqueo ocurre dentro de una funcin de Allegro, el mensaje
   de error puede no ser muy til. Cuando esto ocurra puede recompilar
   Allegro con informacin de depuracin (lea el fichero readme), y enlazar
   su programa con esta versin de la biblioteca de funciones.

   Nota 2: incluso cuando el traceback apunta a una funcin de Allegro, no
   significa que sea fallo de una rutina de Allegro. Cualquier rutina
   fallar si le pasa parmetros invlidos, por lo que a no ser que pueda
   duplicar el problema con uno de los programas de ejemplo de Allegro,
   debera asumir que es un caso de error de operador y chequear dos veces
   qu valores le est pasando a la funcin de Allegro.



==========================================================================
============ Parte 4 - lo que la gente no hace (pero debera) ============
==========================================================================

   Uno de los errores ms comunes cometidos por los programadores es ignorar
   el valor de retorno de una funcin que puede fallar. Tal error
   normalmente llevar a otros errores inusuales e inesperados, convirtiendo
   la depuracin en una pesadilla. Hay muchas funciones dentro y fuera de
   Allegro que pueden funcionar o no dependiendo de las circunstancias. Sin
   embargo le harn saber si funcionaron o no gracias a los valores de
   retorno documentados.

   Siempre que llame a una funcin que puede fallar (sobre todo
   set_gfx_mode(), install_sound(), y cualquier cosa que carga datos del
   disco), es _esencial_ que chequee el valor devuelto por la funcin, y
   acte en consecuencia.

   Otra herramienta importante comnmente olvidada es usar las opciones que
   activan los mensajes de aviso del compilador ms estrictos (gcc usa
   -Wall), cuando compile su cdigo. Cualquier mensaje de aviso que de el
   compilador con sta opcin representar casi con toda seguridad un error
   en su programa, y debera ser corregido antes de hacer nada. Si usa gcc,
   un truco til es compilar adems con el parmetro -O, porque esto fuerza
   al compilador a examinar las acciones del programa con ms detalle,
   activando comprobaciones ms tiles. Sin embargo debera desactivar las
   optimizaciones mientras depura su programa. A pesar de ofrecer mejores
   mensajes de aviso, posiblemente moleste ms tarde a las herramientas de
   depuracin que vaya a usar.



==================================================
============ Parte 5 - pidiendo ayuda ============
==================================================

   Bueno, as que ha probado todo lo descrito arriba y su programa sigue sin
   funcionar. No tiene ni idea de qu hacer ahora, por lo que es tiempo de
   aventurarse en las entraas de la red, con la esperanza de encontrar
   algn hombre sabio, adivino u orculo que tenga la respuesta a su
   pregunta...

   El mejor lugar donde puede preguntar es probablemente la lista de correo
   de Allegro: ms detalles en el fichero readme.txt. Sin embargo, recuerde
   que esta lista es especfica de Allegro. Los problemas relacionados con
   el lenguaje C o el compilador djgpp pertenecen a otros forums
   (comp.lang.c y comp.os.msdos.djgpp respectivamente).

   Tanto la lista de emails de Allegro como la de djgpp son archivadas, y
   puede ojear los mensajes desde sus pginas web respectivas. Es muy
   probable que encuentre una solucin a su problema mirando las respuestas
   a preguntas previas, lo que le evitar hacer la pregunta.

   Segn la netiqueta usual, se asume que cuando hace una pregunta en
   cualquier forum de Internet al menos ya ha consultado primero la
   documentacin relevante, leyndola por completo. Si el problema que tiene
   merece ser planteado a cientos de personas para que lo resuelvan,
   seguramente merecer la pena tomarse unos minutos extra para solucionar
   el problema usted mismo. Allegro est documentado extensivamente y se
   considera un prerequisito para hacer una pregunta no slo el haber ledo
   la documentacin, sino tambin haber examinado los programas de ejemplo.



=========================================================
============ Parte 6 - aprenda de mis fallos ============
=========================================================

   Qu no hacer, Primera Parte:

      "Mi programa se bloquea. Por favor, dime porqu."

   Si, a veces recibo preguntas como sta :-) A pesar de aos de prctica,
   todava no soy capaz de leer el pensamiento, por lo que es intil este
   tipo de pregunta. Para conseguir ayuda con un problema debe describirlo
   con suficiente detalle como para que otras personas lo entiendan y puedan
   reproducirlo: esto normalmente significa mandar parte de su cdigo.


   Qu no hacer, Segunda Parte:

      "Tengo un problema con mi programa. Junto con este email mando un
      fichero zip de 500k que contiene diez mil lneas de cdigo y todos los
      grficos y sonidos necesarios: por favor, puedes depurarlo y decirme
      cual es el problema?"

   Despus de desperdiciar tiempo y facturas de telfono para recibir un
   fichero tan grande, es poco probable que nadie _quiera_ ayudarle, sin
   olvidar el tiempo que se necesitara para leer y entender tal enorme
   cantidad de informacin. Tiene que aislar una parte ms pequea de cdigo
   que demuestre el problema: cuanto ms corto sea, ms probable ser que
   alguien le ayude. Recuerde que est pidiendo a otros que le hagan un
   favor, por lo que es su responsabilidad hacerles este proceso tan
   sencillo como pueda.



===========================================================
============ Parte 7 - escribiendo su peticin ============
===========================================================

   La cosa ms importante es incluir cdigo que puede ser compilado y
   comprobado por la persona que lee su mensaje. No mande simplemente todo
   su programa: extraiga una seccin pequea que incluya las lneas
   especficas que causan su problema, o reproduzca el problema de forma ms
   simple (a menudo descubrir que puede encontrar el error usted mismo al
   hacer una versin simplificada de su programa, por lo que es un buen
   ejercicio que puede hacer). Este cdigo debera ser un programa pequeo
   pero completo que puede ser compilado y ejecutado, ya que es muy difcil
   depurar fragmentos incompletos de cdigo.

   Es mejor incluir el cdigo directamente en el texto de su email, porque
   a la gente le resultar ms sencillo leer esto que si tuviesen que extraer
   el cdigo de un attachment.

   Idealmente su ejemplo debera evitar el uso de grficos externos y
   ficheros de datos. Est bien incluir un pequeo zip (mx 2k) que contiene
   informacin, o si no puede hacerlo, de una descripcin de qu ficheros
   necesita (ej: "pon un fichero .pcx de 32x32 llamado "tile.pcx" en el
   mismo directorio que el programa). Si no hay modo alguno de simplificar
   las cosas, debera copiar su programa y sus datos a una pgina web, y
   entonces dar la URL del fichero zip en su mensaje.

   Debera decir que lnea de comando gcc ha usado para crear el programa,
   y sta debera incluir el parmetro -Wall.

   Describa qu es lo que intenta hacer el programa (puede no ser obvio
   instantneamente para otras personas), y tambin qu es lo que hace
   realmente cuando lo ejecuta. Normalmente no hace falta indicar el
   traceback de su programa cuando se bloquea (otras personas pueden
   duplicarlo por s mismas siempre y cuando consigan compilar su cdigo),
   pero debera indicar si aparece este traceback, o se bloquea el
   programa, o si devuelve resultados incorrectos (si es as, en qu
   difieren estos de los que esperaba). Es til marcar su cdigo con
   comentarios para indicar a qu lnea apunta el traceback del programa.

   Otra informacin que pueda aadir puede ser til. Lo ms importante es
   una descripcin corta de su hardware, informacin relevante de sus
   controladores, y la versin de Allegro que est usando (por favor no diga
   "WIP" a secas, sino la fecha exacta si est usando una versin que no sea
   oficial).



===========================================================
============ Parte 8 - un modelo de perfeccin ============
===========================================================

   Como referencia, aqu tiene un ejemplo de lo que yo considerara un
   mensaje ideal:


   Estoy teniendo algunos problemas al intentar usar modos hicolor en mi
   programa, a pesar de que estos modos funcionen bien con los programas test
   de Allegro. Estoy usando Allegro 3.0 con djgpp 2.02 (versin gcc 2.8.1) en
   un p166, ejecutando el programa bajo win95 y usando el driver VESA 2.0
   incluido por defecto, descrito por el programa vesainfo como "Matrox
   Graphics Inc.".

   Este programa debera seleccionar una resolucin 640x480 de 16 bits,
   dibujar un rectngulo azul cerca de la esquina superior izquierda de la
   pantalla, y entonces esperar la pulsacin de una tecla antes de salir,
   pero simplemente recibo un General Protection Fault cuando lo ejecuto.

   Lo compilo usando "gcc -Wall t.c -o t.exe -lalleg", y no obtengo ningn
   mensaje de error.


   --- corta aqu, t.c ---

   #include <stdio.h>
   #include <allegro.h>

   void main()
   {
      BITMAP *bmp = screen;

      install_keyboard();

      if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0) {
         printf("Error seleccionando modo de vdeo\n");
         return;
      }

      set_color_depth(16);

      /*  se bloquea cuando llama rectfill ! */
      rectfill(bmp, 32, 32, 64, 64, 0x001F);

      readkey();
   }


