El PHP3 es otro lenguaje de script que nos permite programar aplicaciones que se ejecutarán en nuestro servidor. Es uno de los lenguajes más utilizados en el mundo Unix con el servidor Apache aunque también se puede ejecutar bajo Windows.

En este caso vamos a utilizar la base de datos en formato Access de nuevo junto con el PWS.

Lo primero que le indicamos al browser es que vamos a ejecutar código PHP3. Esto lo hacemos con la directiva <?php para que sepa cómo interpretarlo.

Lo demás es bastante parecido a perl o a asp. Se trabaja con objetos.

Primero creamos el objeto conexión:

 

$cnx = odbc_connect(  'Ejemplo1' ,  'Alejandro',  'pasword' );  
    if (!$cnx) {  
        Error_handler(  "Error al conectar odbc" , $cnx );  
    }

Después definimos la sentencia sql:

$SQL_Exec_String =  "select * from Clientes";

Lo ejecutamos:

 

$cur= odbc_exec( $cnx, $SQL_Exec_String );  
    if (!$cur) {  
        Error_handler(  "Error en odbc_exec( ) " , $cnx );  
    }

Obtenemos los resultados en un objeto cursor y se los mandamos al cliente en una tabla.

echo  "<table border=1><tr><th>Dni</th><th>Nombre</th>".  
         "<th>Apellido1</th><th>Apellido2</th></tr>\n";  
    $nbrow=0;    //Variable local para contar el nº de filas 
    while( odbc_fetch_row( $cur ) ) {  
       $nbrow++;  
       $Dni= odbc_result( $cur, 1 );  
       $Nombre= odbc_result( $cur, 2 );  
       $Apellido1= odbc_result( $cur, 3 ); 
       $Apellido2= odbc_result( $cur, 4 ); 

        echo  "<tr><td>$Dni</td><td>$Nombre</td>".  
             "<td>$Apellido1</td><td>$Apellido2</td></tr>\n";  
    }  

    echo  "<tr><td colspan=2>$nbrow entradas en la bd </td></tr></table>";

Cerramos la conexión.

odbc_close( $cnx);

Insertar, borrar...

Para las demás opciones de la base de datos ( insertar, Borrar, modificar ...) tan sólo tenemos que modificar le sentencia sql y volver a hacer un select * para devolver la nueva tabla al usuario, como se ve en el ejemplo:

function Enter_New_Entry($Dni,$Nombre,$Apellido1,$Apellido2) {  
  

    $cnx = odbc_connect(  'Ejemplo1' ,  'Alejandro',  'Password' );  
    if (!$cnx) {  
        Error_handler(  "Error en odbc_connect" , $cnx );  
    }  

    $SQL_Exec_String =  
            "Insert Into Clientes (dni, Nombre, Apellido1, Apellido2)  
            Values ('$Dni', '$Nombre', '$Apellido1', '$Apellido2')";  

    $cur= odbc_exec( $cnx, $SQL_Exec_String );  
    if (!$cur) {  
        Error_handler(  "Error en odbc_exec(  ) " , $cnx );  
    }  

    odbc_close( $cnx);  
}

Hemos Creado dos ficheros php3 uno es el que nos enseña el estado actual de la base de datos y nos presenta un formulario por si queremos añadir un registro a ella.

El segundo fichero es la respuesta a la inserción que hemos realizado y nos presenta el estado de la BD antes de insertar y después.

Debes copiar los dos en un directorio de tu servidor con permiso de ejecución.

Desde los ochenta aparece la tendencia de sustituir la documentación impresa del software, dirigida al usuario, por la documentación electrónica llamada en línea.

• Actualmente, 2010, la mayoría de los manuales del usuario se entregan en discos compactos para ser visualizados con programas especiales, como el WinHelp de Windows, Acrobat Reader y otros. Tales programas podríamos denominarlos lectores electrónicos. Algunos de ellos permiten la navegación a través de tópicos relacionados y vinculados con ligas de fácil acceso. Proporcionan ayuda sensible al contexto como respuesta a la pulsación de una tecla (normalmente la tecla F1). Otros lectores electrónicos muestran la información a imagen de una página impresa común que contiene elementos de texto, gráficos, tablas, etc.

• Los programas de lectura electrónica facilitan la búsqueda de términos, párrafos, páginas y otras referencias. También agilizan la navegación a través del documento electrónico y la impresión de sus contenidos. Con estas facilidades se convierten en el medio idóneo para las enciclopedias modernas y material educativo en todos los niveles. Los medios de almacenamiento y la memoria principal de los sistemas de cómputo han crecido formidablemente, fomentando con ello que los fabricantes de software prefieran los manuales electrónicos a los manuales impresos, en beneficio del medio ambiente natural, motiva que se utilice menos papel para la conservación de los bosques.

  El diseñador de aplicaciones debe suministrar al usuario final un sistema de ayuda en línea con varios niveles y así:

  • Reducir sus costos por capacitación y soporte técnico
  • Mejorar su percepción del valor que le reporta la aplicación
  • Disminuir su curva de aprendizaje para el mejor aprovechamiento de la aplicación.

  • ¿Que es esto?

    El diseñador de aplicaciones se empeña en crear interfaces de usuario claras y amigables, sin embargo no todos los usuarios finales responden de la misma manera y para algunos la operación y conocimiento de las aplicaciones ofrece mayor grado de dificultad.

    La ayuda en línea es un poderoso auxiliar para resolver dudas, conocer la operación básica de las aplicaciones, determinar errores que se cometen frecuentemente al operarlas y la manera de corregirlos.

    En las herramientas de desarrollo integrado de software, la ayuda en línea es casi imprescindible.

    En cualquier caso, la proporción del espacio en el disco duro ocupado por la ayuda en línea con respecto al volumen completo de la aplicación asociada varía según su naturaleza.

    En la máquina del autor se muestra un caso típico con diversas aplicaciones, la siguiente tabla presenta para cada aplicación el espacio en megabytes ocupado por los archivos de ayuda y el total ocupado por la aplicación así como el porcentaje de la ayuda.

  • Como se hace la ayuda en línea

    A continuación se muestran los pasos generales para construir un Sistema de Ayuda en Línea.

    • DISEÑAR LA ESTRUCTURA LÓGICA

      El primer paso es quizás el más difícil en la mayoría de los sistemas de ayuda en línea. Es un paso pleno de creatividad y que exige del autor del sistema, talento e imaginación.

      La estructura lógica del sistema de ayuda en línea se basa en los contenidos y sus relaciones entre sí. Para un buen diseño, es crucial establecer la correspondencia entre la ayuda y los diversos entornos y situaciones que se le presentarán al usuario al operar la aplicación asociada.

    • CREAR LOS TÓPICOS INDIVIDUALES

      Los tópicos (temas) de ayuda deberán ser, de preferencia, breves y su relación con otros deberá permitir una navegación fácil y productiva. El balance entre extensión y profundidad de los temas es difícil de establecer y no se puede generalizar. La propia aplicación asociada y la experiencia del autor de la ayuda determinarán el alcance de cada tópico.

      El contexto para el que se proyecten los temas será un factor importante para su definición. Si el autor considera conveniente "hilvanar" algunas ideas deberá seleccionar los enlaces con otros temas relacionados y sugerir al usuario su revisión.

      Los sistemas de ayuda en línea no presentan la información en forma secuencial, como en un libro normal, sino que están diseñados para navegar a través de los temas y, aunque su naturaleza es fragmentaria, se pueden establecer relaciones convenientes entre los temas para que el usuario los consulte siguiendo una ruta lógica que le permita aclarar sus dudas y mejorar su conocimiento sobre la aplicación asociada para un mejor aprovechamiento.

      La estructura lógica es la disposición de los tópicos o temas de ayuda que facilita al usuario acceder a la información que le permite conocer mejor la aplicación asociada, o que le aclare las dudas naturales que surgen al operar cualquier producto de software.

      Al igual que la tabla de contenidos de un libro, el tema de entrada en la estructura lógica debe ser el denominado tópico de contenidos. En un diagrama jerárquico, el nodo raíz sería el tópico de contenidos y en el desarrollo arborescente aparecerían los temas principales en los primeros niveles. Luego habría un cúmulo de temas relacionados unos con otros formando una red más o menos compleja. A continuación se muestra una estructura lógica en Delphi 7:

      

      WinHelp opera los archivos de ayuda *.HLP de tal manera que las ligas son bidireccionales, lo que permite ir de un tópico a otro y regresar al anterior. Obviamente el tópico de contenidos no tiene liga hacia atrás.

      1. Los tópicos individuales

         Los tópicos son unidades completas de información que expresan una idea. El conjunto de tópicos constituyen la materia prima del sistema de ayuda en línea. Cada tópico proporciona diversos controles para la navegación en hipertexto, permitiéndole al usuario saltar de un tópico a otro.

         Los tópicos se crean utilizando un procesador de palabras que facilite la inserción de notas al pie de página, que pueda guardar los archivos en formato de texto enriquecido *.RTF; WordXP de Microsoft tiene las características necesarias para crear los archivos fuente de los tópicos de ayuda.

         Normalmente los tópicos incluyen los siguientes elementos:

         • Notas al pie de página
         • Un título
         • Texto del tema

         Además el tópico puede incluir gráficos y ligas para saltar a otros tópicos. En la nomenclatura especializada se les denomina hotspots. Un hotspot es un texto o gráfico sobre el que el usuario puede con una pulsación del botón izquierdo del ratón (clic) iniciar alguna acción. Por ejemplo, saltar a otro tópico, desplegar un tópico en una ventana diferente o ejecutar una o varias macros (una macro es una rutina independiente).

      2. Las notas al pie de página y los códigos de control

         Las notas al pie de página se utilizan para insertar los códigos de control en los archivos de ayuda. A continuación se presentan los códigos predefinidos, aunque se pueden crear otros con la opción Multikey en el archivo del proyecto; éste se describe después.

         CÓDIGO	PROPÓSITO
         #	Define una cadena contextual.
         $	Para el título del tópico.
         +	Para secuencia de tópicos.
         K	Define una palabra clave para búsqueda.
         *	Etiqueta para exclusión de tópicos.
         ¡	Referencia de macro.
         @	Comentario.

      3. Título del tópico

         El título del tópico normalmente aparece en la primera línea. WinHelp no requiere que los temas tengan un título; sin embargo, los títulos tienen el mismo propósito en la ayuda en línea que en los documentos impresos. Sirven para identificar el tema (o capítulo) y describen su contenido.

         Además WinHelp ofrece diversas maneras para que el usuario busque los temas que existen en otra parte de la ayuda. La mejor manera de identificar el tema es por el título. El código ‘$’ especifica el título que se despliega en el historial, la caja de dialogo Buscar y en el menú del marcador. El archivo de ayuda contiene los controles que opera el programa WinHelp. Para hacer el título, se puede usar un formato como se haría con un título impreso: tamaño diferente al del texto, negrita o en color.

      4. Texto del tema

         El texto debe ser breve, claro y conciso. Normalmente cabe en una ventana o dos. Se escribe abajo del título, tal como se haría con un documento impreso. Cuando WinHelp despliega el texto, se desarrolla hacia abajo y se ajusta de manera automática, independientemente del ancho de la ventana. Por lo tanto, el autor de la ayuda no debe preocuparse por la longitud de cada línea al momento de crear el archivo fuente. Al final del texto se debe insertar un salto de página para que WinHelp lo trate como un tópico separado en el archivo compilado *.HLP.

         Al escribir el tópico se pueden emplear las facilidades de formato que brindan los procesadores de palabra como WordXP de Microsoft: diversas fuentes, tamaños, colores estilos, líneas cajas, etc. Se sugiere utilizar una fuente de 10 puntos, NonSerif, tales como Arial o Helvética para la mayor parte del texto.

         WinHelp utiliza los caracteres especiales que se insertan en el tópico como notas al pie de página, tanto para identificarlo como para agregar los controles de navegación: botones y otros controles que permiten el desplazamiento fácil a través del archivo de ayuda. Los botones de Indice, Buscar, Atrás, Historial, << (Anterior), >> (Siguiente), son buenos ejemplos de controles de navegación.

         La mayoría de los tópicos incluyen en su texto hotspots, los cuales funcionan como enlaces para acceder a otros tópicos. Cuando el hotspot es una cadena de caracteres, ésta aparece en el archivo de ayuda compilado como una cadena de color verde y con un subrayado sencillo.

         WinHelp utiliza notas al pie de página para identificar los tópicos y proporcionar algunos controles de navegación. En general se utilizan cuatro caracteres como nota al pie de página: #, $, K, +.

         Con el procesador WordXP, las notas al pie de página se insertan de la siguiente manera:

         1. Colocar el punto de inserción de texto en la posición donde se desea colocar el identificador de la nota al pie, casi siempre antes del primer carácter de la primera línea del tópico.
         2. Especificar la marca que se desea utilizar (#, $, K, +). Insertar la nota al pie de página.
         3. En el sitio de la nota al pie, escribir la información correspondiente.

         WinHelp utiliza la cadena contextual para identificar cada tópico. El usuario final nunca ve esas cadenas. Pero sirven para especificar el salto a un tópico. La cadena contextual no debe ser mayor a 255 caracteres. Se aceptan las letras (mayúsculas y minúsculas), los dígitos decimales, el punto y el subrayado, pero no el espacio en blanco. Para definir la cadena contextual se deberá utilizar el carácter # como marca de nota al pie de página.

         Para el nombre del tópico (título) deberá utilizarse el carácter $ como marca de nota al pie. Para asignar un título al tópico:

         1. Colocar el punto de inserción de texto en seguida del carácter # en la misma línea que contiene al título del tópico.
         2. Insertar la nota al pie con $ como marca.
         3. En la posición de la nota al pie, escribir el título del tópico. Normalmente se escribe el mismo nombre que se anotó en la primera línea del tópico. Este nombre es el que verá el usuario final en la caja de diálogo Buscar y en la lista del historial.

         Para añadir palabras y frases a la lista de Buscar, se utiliza el carácter K como marca de nota al pie de página.

         1. Mover el punto de inserción del texto después del carácter $ y antes del título del tópico en la primera línea.
         2. Insertar con K la nota al pie de página
         3. En la nota al pie, escribir palabras y frases como se desea que aparezcan en la lista de búsqueda. Cada elemento se separa con un punto y coma.

      5. Inserción de Hotspots en el tópico

         Como ya se mencionó, un hotspot es texto o un gráfico sobre el que el usuario da un clic con el botón izquierdo del ratón para iniciar una acción. Un hotspot pude ejecutar un salto a otro tópico, desplegar un tópico en una ventana diferente, o ejecutar una o varias macros. El uso más frecuente es que una o varias palabras se designen como hotspot para que el usuario pueda saltar a otro tópico.

         Para crear un hotspot que permita el salto a otro tópico:

         1. Escribir el texto o insertar el gráfico que se desea convertir en hotspot.
         2. Seleccionar el texto y aplicarle el doble subrayado. En WordXP se puede abrir la caja de dialogo de formato de fuente a partir del menú principal con Formato/Fuente y seleccionar Subrayado/Doble.
         3. Inmediatamente al texto subrayado o al gráfico del paso 1 escribir la cadena contextual del tópico destino después del salto.
         4. Seleccionar la cadena contextual y aplicarle el efecto de texto oculto. En WordXP tomar del menú principal Formato/Fuente y abrir la caja de diálogo y marcar el efecto Oculto.

         El tópico de contenidos se crea como un tópico que contiene los títulos de los tópicos de segundo nivel. Cada título se convierte en hotspot que permite el salto al tópico correspondiente. No olvidar que los tópicos deberán separarse en el archivo fuente con saltos de página (en WordXP Ctl+Enter).

      6. Salvar el archivo fuente

         El archivo fuente deberá salvarse en formato de texto enriquecido (.RTF). En WordXP utilizar la opción Archivo/Guardar como, y Seleccionar Guardar como tipo: Formato RTF. El compilador de WinHelp solamente puede compilar archivos RTF.

         El formato RTF, es un archivo ASCII que contiene instrucciones de formato (tales como fuentes, salto de página, estilos, etc.) además del propio texto.

    • Salvar el archivo fuente

      El archivo del proyecto del sistema de ayuda

      El archivo del proyecto es del tipo texto con la extensión .HPJ. Contiene la información que utiliza el compilador del archivo de ayuda. El archivo del proyecto puede incluir muchas instrucciones que controlan diversos aspectos del archivo de ayuda.

      Para escribir el archivo del proyecto utilizar un editor de textos:

      1. Crear el archivo con el mismo nombre que tendrá el archivo de ayuda compilado y agregar la extensión HPJ.
      2. Agregar las siguientes líneas al archivo. Las palabras en español son espacios genéricos que debe utilizar el autor de la ayuda para sus propios nombres o valores. Los comentarios van precedidos con un punto y coma.

                     [OPTIONS]

                     CONTENTS=CadenaContextual ;(para el tópico de contenidos)

                     TITLE=Título ;(este es el nombre de la barra del título de la ventana de ayuda)

                     COMPRESS=NivelCompresión ;(FALSE,MEDIUM,HIGH,0,1,NO,TRUE,YES)

                     ERRORLOG=ArchivoErrores ;(nombre del archivo de errores de la compilación)

                     [CONFIG]

                     [FILES]

                     ArchivoRTF1 ;(archivo fuente en formato RTF)

                     ArchivoRTF2 ;(archivo fuente en formato RTF)

                     ArchivoRTF3 ;(archivo fuente en formato RTF)

                     ...

                     ... Guardar el archivo como texto.

    • COMPILAR LOS ARCHIVOS FUENTE

      Cabe recordar que al inicio de este trabajo se estableció que la metodología descrita correspondía a la construcción de archivos de ayuda *.HLP operados con el programa WinHelp a 16 bits y que por la compatibilidad se pueden operar perfectamente con la versión de WinHelp a 32 bits. Así que para la compilación se propone el uso del compilador de ayuda HCP.EXE o el H31:EXE. Para el caso de archivos *.HLP a 32 bits deberá utilizarse la herramienta WorkShop con prestaciones más avanzadas.

      Antes de una compilación conviene asegurarse que se tiene lo siguiente:

      • Todos los archivos fuente (con los tópicos) guardados en formato RTF.
      • Todos los archivos fuente en el mismo subdirectorio.
      • El compilador de la ayuda HCP.EXE
      • El archivo de errores del compilador (HCP.ERR or HC31.ERR)
      • El archivo del proyecto (.HPJ).
      • Los archivos referenciados bitmap (.BMP).

  • Interfaz de ayuda

    La mayor parte de las interfaces actuales incluyen, normalmente, para la ayuda en línea del usuario los siguientes recursos:

    • Temas de consulta:
      que ofrecen el acceso a bibliotecas clasificadas en temas, a comandos de programación, a términos o tareas concretas.

      Búsquedas y Ayudas a comandos de Nero Burning ROM 6.0

    • Ayuda sensible al contexto:
      que permite acceder al estado de la aplicación o a cuadros de diálogo. En muchas ocasiones haciendo uso de asistentes personales con la ayuda de la tecnología de agentes.

      

      Ayuda contextual con un asistente (Microsoft Word)

    • Test de ayuda:
      generalmente accesible desde las teclas de función, menús o iconos.

      Mensajes de texto, que se generan al pasar por encima de un icono y no se mueve de encima durante un instante, lo que permite en el sistema inferir que el usuario no conoce el significado de la imagen del icono. Este mensaje de ayuda que aparece bajo el icono permite reforzar el modelo mental del usuario respecto de la aplicación.

      

      Ayuda icónica de Microsoft Windows XP

      Para insertar un archivo de ayuda en DELPHI debemos Seleccionar del menú Project la opción Options…

      Una vez seleccionada esta opción se desplegará la siguiente ventana:

      

      En esta seleccionamos el archivo de ayuda de nuestro software. Al hacer clic en OK quedará automaticamente registrado el archivo de ayuda deseado.

      Luego se debe utlizar un procedimiento para llamar el archivo de ayuda con el comando de un boton o presionando la tecla F1. El procedimiento será el siguiente:

      procedure TForm1.Ayuda1Click(Sender: TObject);

      begin

      messagedlg('clickea en help para ver la ayuda',mtConfirmation, [mbcancel,mbhelp], 1);

      end;

      Para insertar un archivo de ayuda en C++ Builder debemos Seleccionar del menú Project la opción Options…

      Una vez seleccionada esta opción se desplegará la siguiente ventana:

      

      En esta seleccionamos el archivo de ayuda de nuestro software. Al hacer clic en OK quedará automaticamente registrado el archivo de ayuda deseado.

    A continuacíon adjuntaré, como complemento, la informión necesaria para la “Generación de Archivos de Ayuda en formato CHM, pero esta vez utilizando HTML Help Workshop.

  • Guía para la generación de archivos de ayuda en formato CHM

    • OBJETIVO

      El objeto de este documento es servir de guía para la generación de archivos de ayuda de aplicaciones desarrolladas bajo sistemas operativos Windows (versiones 95 y superior).

    • ALCANCE

      Este documento debería aplicar a aquellos proyectos software que sean desarrollados para ser ejecutados bajo sistemas operativos Microsoft Windows (versiones 95 y superior).

    • TIPOS DE AYUDA PARA SISTEMAS MICROSOFT WINDOWS

      Existen dos formatos de ayuda disponibles para ejecutarse en sistemas operativos de la familia Microsoft Windows: HLP y CHM.

      1. Formato HLP

         Es el estándar tradicional por excelencia de Microsoft Windows. Desde sus primeras versiones adoptó este formato, (RTF y Word), y extensión de archivo HLP para sus ayudas. Con el tiempo, hizo público este formato y proporcionó un compilador, (bajo MS-DOS), para generar esta clase de ayudas. El compilador evolucionó hasta llegar al actual HTML Help WorkShop con el que es posible compilar los dos formatos actuales: HLP y CHM.

         Para generar este tipo de ayudas son necesarias las siguientes herramientas:

         • Un procesador de textos, para crear el cuerpo de la ayuda en formato RTF. Un procesador que soporte el formato de texto enriquecido bastaría (por ejemplo Microsoft Word).
         • El compilador de ayuda, para crear el proyecto y archivo de contenido (HPJ y CNT respectivamente) y el resultado final, el HLP.

      2. Formato CHM

         Con la aparición de Windows 98, Microsoft creó un nuevo estándar de ayudas. Los archivos CHM son un nuevo sistema de ayudas cuya principal diferencia con su antecesor, el HLP, es que no utiliza el formato RTF para generar los cuerpos de la ayuda sino que, claro está, utiliza HTML (Hyper Text Markup Language, o Lenguaje de Marcas de Hipertexto conocido por ser la base de las páginas web de internet).

         Para crear archivos de ayuda CHM son necesarias las siguientes herramientas:

         • Un editor de páginas web, para generar el contenido de la ayuda (archivos de extensión HTM o HTML). Puede usarse por ejemplo el editor gratuito de Microsoft (Frontpage Express), Microsoft Word u otro editor de páginas web.
         • El compilador de ayuda, para crear el proyecto, archivo de contenido e índice (HHP, HHC y HHK respectivamente) y, finalmente compilar todo para obtener el archivo de ayuda definitivo con extensión CHM. Una herramienta gratuita como Microsoft HTML Help Workshop es suficiente para realizar este trabajo.

    • GUIA PARA GENERAR AYUDAS EN FORMATO CHM

      1. Conceptos

         CHM utiliza un lenguaje de marcas (el popular lenguaje de de marcado de hipertexto o HTML, usado para generar páginas web).

         Una vez creados los diferentes capítulos de nuestra ayuda en diferentes archivos HTM ( o HTML), estos son aglutinados en un archivo de proyecto con extensión HHP. A este proyecto se le añaden:

         • Archivos H: Añaden un ID para identificador de capítulo dado, que luego será aprovechado por nuestras aplicaciones Visual Basic para lanzar la página de ayuda correspondiente.
         • Archivos HHK: Índices.
         • Archivos HHC: Tablas de contenido.

         Con todo esto, compilamos el proyecto y obtenemos un archivo de ayuda con extensión CHM.

         La versión del Help WorkShop recomendada para este tipo de ayudas es la 4.7 del año 1.999. Esta aplicación contiene un conversor de proyectos para ayudas HLP a CHM. Por lo tanto, y en teoria, es posible utilizar esta aplicación para ambos tipos de ayudas.

      2. Crear un archivo CHM paso a paso

         A continuación se mostrarán los pasos básicos para crear una ayuda CHM.

         Crear el contenido de la ayuda (archivos HTM,HTML).

         El primer paso es crear el contenido de la ayuda. Para ello generaremos archivos con extensión HTM (o HTML). Es recomendable crear una página HTML por cada topic de la ayuda. Se puede usar cualquier editor de páginas web, el bloc de notas e incluso Microsoft Word (guardando los archivos con la extensión correspondiente).

         En el ejemplo que se presenta se han desarrollado 3 páginas webs: principal.htm, capitulo1.htm y capitulo2.htm (que han sido guardados en el directorio c:\ayudahtml\paginas). En estos documentos HTML se pueden insertar texto, imágenes, hipervínculos a otras páginas de ayuda y sitios web, e incluso código de lenguajes de script (JavaScript o VBScript). Es decir, tal y como fueran páginas web normales.

         Crear el archivo de proyecto (HHP).

         Un proyecto de ayuda CHM es un archivo de extensión HHP que aglutina todos los demás archivos que conforman la ayuda CHM. Para crear este y los demás archivos podemos utilizar la aplicación HTML Help Workshop o un editor de textos sencillo como el bloc de notas, aquí se hará con el primero.

         Un archivo de proyecto HHP es un archivo de texto estructurado por secciones que se referencian entre los caracteres

                     “[“ y “]”.

         Las secciones mas importantes son :

         • OPTIONS: Opciones de compilación.
         • ALIAS: Identificador de Nombre de alias y archivo HTM.
         • MAP: Archivo con la definición de los nombres de alias y un ID para cada uno que después será usado en nuestras aplicaciones Visual Basic para lanzar la ayuda de contexto (propiedad HelpContextID).

         Para crear un nuevo proyecto arrancamos Microsoft HTML Help Workshop y pulsamos en el botón New de la barra de herramientas (o en la opción New del menú File). En la ventana que aparece elegimos Project y pulsamos OK, en la ventana siguiente nos pregunta si deseamos convertir un archivo de ayuda en formato HLP a formato CHM, pulsar en Siguiente porque no se quiere hacer esto. Y a continuación pedirá el nombre que se quiere dar al proyecto (en nuestro caso, lo hemos colocado en el directorio C:\ayudahtml\ejemplo.hhp). Luego pregunta si tenemos archivo de contenido, índice y páginas web ya creados. Como no lo tenemos no marcamos nada y pulsamos en Siguiente.

         Una vez terminado se visualiza la pantalla del proyecto.

         Haciendo click en el botón de la ventana Project podemos indicar las páginas html que tendrá nuestra ayuda (esto nos servirá para poder vincular más tarde el archivo de contenido con las páginas).

         En la pantalla Topic Files se hace click en el botón Add ... y se seleccionan los archivos htm y html que compondrán nuestra ayuda.

         Veamos a continuación los valores de los parámetros para las distinas secciones.

         OPTIONS

         En esta sección damos a conocer al compilador de ayudas informaciones tales como:

         • Title: Titulo de nuestra ayuda.
         • Language: ID del idioma utilizado para nuestra ayuda.
         • Index file: Archivo de indice, (HHK)
         • Contents file: Archivo de contenido, (HHC).
         • Compiled file: Nombre del archivo de ayuda compilado, (CHM).

         Para poder establecer estos valores hay que hacer click en el botón Change project options de la pestaña Project. Antes de establecer valores como el archivo de contenido o de índice, será necesario crearlos previamente (para ello hacer click en la pestaña Contents e Index respectivamente). Ejemplo:

         [OPTIONS]

         Compatibility=1.1

         Compiled file=EJEMPLO.chm

         Contents file=EJEMPLO.hhc

         Default topic=paginas\principal.htm

         Display compile progress=No

         Index file=EJEMPLO.hhk

         Language=Español (alfabetización internacional)

         Title=Ayuda de ejemplo en formato HTML

         Un ejemplo para esta sección seria : [OPTIONS]

         Compatibility=1.1

         Compiled file=EJEMPLO.chm

         Contents file=EJEMPLO.hhc

         Default topic=paginas\principal.htm

         Display compile progress=No

         Index file=EJEMPLO.hhk

         Language=Español (alfabetización internacional)

         Title=Ayuda de ejemplo en formato HTML

         ALIAS

         Cada archivo HTM de nuestra ayuda puede identificarse por un alias, (nombre o variable), que lo identifica y relaciona con un ID que es utilizado posteriormente en nuestras aplicaciones Visual Basic.

         Para poder establecer estos alias hay que hacer click en el botón HTML Help API Information de la pestaña Project y en la sección ALIAS.

         Por ejemplo : [ALIAS]

         ID_topic0=paginas\principal.htm

         ID_topic1=paginas\capitulo1.htm

         ID_topic2=paginas\captiulo2.htm

         MAP

         Relación de archivos H en el que se definen los ALIAS descritos en la sección anterior y se relacionan con un ID que se utilizará posteriormente en nuestras aplicaciones Visual Basic.

         Al igual que la anterior se accede haciendo click el botón HtmlHelp API Information de la pestaña Project y en la sección MAP.

         Por ejemplo : [MAP]

         #include Ejemplo.h

         Crear el archivo de contenido (HHC).Para crear el archivo de contenido hacer click en la pestaña Contents o bien en la opción New del menú File eligiendo la opción Contents file (archivo de contenido):

         En un archivo HHC se define la estructura del libro de contenidos de nuestra ayuda.

         El proceso es ir añadiendo carpetas y páginas para ir generando los libros de la ayuda. Una carpeta es un contenedor de carpetas y de páginas.

      En la ventana Table of Contents Entry (entrada de la tabla de contenido), se solicitará el texto que se desea visualizar (Entry title), así como el archivo html al que se desea vincular ese tópico de la ayuda (para vincularlo hacer click en el botón Add y seleccionar la página correspondiente).

      Crear el archivo de índice (HHK) [opcional].

      La creación de un archivo de índice es opcional. En él referenciamos todas las cadenas de búsqueda para cada capítulo. Para crear un nuevo archivo pulsar en la pestaña correspondiente (Index) o bien en la opción New del menú File elegir Index.

      Este apartado es similar a los anteriores de manera que se visualizan una serie de botones para insertar una nueva clave y vincularla con diferentes páginas.

      Si pulsamos en el icono aparecerá una ventana en la que se podrán Añadir páginas y vincularlas con determinadas palabras clave. Por ejemplo si en un tópico de la ayuda hablamos del entorno gráfico de nuestra aplicación podemos poner como palabras clave entorno, gráfico, menús o lo que se desee y vincularlo con la/las páginas deseadas mediante la opción Add de la ventana que aparezca cuando se hace click en el icono correspondiente.

      Crear el archivo de cabecera, declaración de ID de contexto (H).

      En un archivo con extensión H definimos, (con el comando #define), los alias que referenciaremos a cada capítulo, (archivos HTM/L), de nuestra ayuda.

      En nuestro ejemplo, se crea el archivo EJEMPLO.H con el siguiente contenido: #define ID_topic0 0

      #define ID_topic1 1

      #define ID_topic2 2

    • COMPILAR CON HTML Help Workshop

      Compilar con HTML Help Workshop es una tarea extremadamente sencilla. Simplemente hemos de cargar el archivo de proyecto, (HHP o HPJ dependiendo del formato de nuestra ayuda), e ir a la opción Compile del menú File.

      Aparecerá una ventana en que se nos pedirá confirmación del proyecto a compilar, (por defecto ofrece el que esté cargado en ese momento). En el proceso de compilación aparece una ventana de log en la que se nos informa del estado de dicha compilación. Si ocurre un error aparece reflejado en esta ventana.

      Otra utilidad práctica de Help WorkShop es la opción de View Compiled Help File del menú View. Con está opción vemos cualquier archivo de ayuda; sea este CHM o HLP una vez compilado.

    • INSERCIÓN DE LA AYUDA EN VISUAL BASIC

      En nuestras aplicaciones en Visual Basic es posible referenciar un archivo de ayuda en cualquira de los formatos explicados, (HLP o CHM). La potencia de esta relación estriba en que en un control de nuestro formulario, (o en el propio formulario), es posible referenciar un capítulo concreto de nuestra ayuda. De esta forma se muestra la ayuda concreta sobre el tema referenciado para ese control.

      Debido a que la implementación actual de la ayuda HTML no permite la inserción de la misma en un formulario y pulsar F1 para visualizarla, se hace necesario el uso de la llamada a una API. El nombre de esta API es HtmlHelp

      1. Adaptando un proyecto de Visual Basic

         A pesar de que al pulsar la tecla F1 no se lanza la ayuda automáticamente, la propiedad HelpContextID de los controles de VB puede seguir siendo utilizada, para que, en función del formulario en el cual estemos, se lance un capítulo de la ayuda u otro.

         En primer lugar debemos tener una variable en la cual almacenar el path del archivo de ayuda CHM (en nuestro ejemplo: c:\ayudahtml\ejemplo.chm).

         En un módulo de código debemos copiar la siguiente declaración del API y dos constantes públicas:

                     Declare Function HtmlHelp Lib “HHCtrl.ocx” Alias “HtmlHelpA” _                (ByVal hwndCaller As Long, ByVal pszFile As String, _                ByVal uCommand As Long, dwData As Any) As Long

                     Public Const HH_DISPLAY_TOPIC = &H0

                     Public Const HH_HELP_CONTEXT = &HF

         Los argumentos de la función HtmlHelp y su respectiva funcionalidad son los siguientes:

         Argumento	Descripción
         HwndCaller	Es un manejador de una ventana de aplicación o Null. Este manejador debe ser usado como el propietario o el contenedor de la ayuda HTML, dependiendo como sea usado. En VBA, en vez de usar vbNullString establecer este parámetro a 0.
         PszFile	Es el string que se corresponde con el path del archivo de ayuda. Opcionalmente puede especificar en que tipo de ventana se ha de visualizar.
         UCommand	Es la acción a realizar, o como mostar tópicos de ayuda. Pude ser usado con cualquiera de los dos comandos declarados como constantes HH_HELP_CONTEXT o HH_DISPLAY_TOPIC. Sólo se ha llegado a probar con éxito HH_HELP_CONTEXT.
         DwDataCommand	Especifica el topic ID.

      2. Propiedad HelpContextID

         Entre las propiedades del formulario o de cualquier control contenido en él hay una de nombre HelpContextID. Esta propiedad acepta cualquier valor numérico entero que indica el ID del tópico al que se hará referencia si se llama al sistema de ayuda en ese momento con la tecla F1, como ya se ha dicho, con la ayuda HTML y Visual Basic 5 es imposible que funcion este sistema.

         En el archivo H de la ayuda CHM o en la sección MAP de la ayuda HLP referenciamos estos números con los capítulos de la ayuda que deseemos.

      3. Lanzar la ayuda correspondiente a un formulario

         Para lanzar la ayuda correspondiente a un formulario únicamente hay que hacer una llamada a la función HtmlHelp con los parámetros deseados. En nuestro ejemplo, se hizo en el evento Click del botón cmdAyuda (dado que no puede ser lanzada pulsando la tecla F1), pero claro está puede hacerse la llamada desde el evento que se desee.

                     Private Sub cmdAyuda_Click()

                         Call HtmlHelp(0, "c:\ayudahtml\ejemplo.chm", HH_HELP_CONTEXT, _

                     ByVal Me.HelpContextID)

                     End Sub

    • INSTALACIÓN DE MICROSOFT HTML Help Workshop

      Para instalar el compilador de ayuda HTML gratuito de Microsoft hay que ejecutar el archivo HTMLHELP.EXE que se puede descargar de la página oficial de microsoft.

      Haciendo doble click se arranca automáticamente el programa de instalación y se visualiza la siguiente imagen indicando que se están extrayendo los archivos de instalación:

      Una vez se ha terminado de extraer los archivos aparece el programa de instalación que nos pide que aceptemos la Licencia de uso, en la pantalla titulada License Agreement pulsar el botón Accept.

      Una vez aceptado el acuerdo de licencia se visualiza el asistente de instalación de Microsoft HTML Help Workshop (ver siguiente imagen), pulsar Next >.

      A continuación aparece otra pantalla que solicita que seleccionemos el directorio de destino de instalación del programa. Podemos seleccionar uno existente pulsando en Browse ... o bien escribir una ruta deseada (por ejemplo c:\Archivos de programa\HTML Help Whorkshop. Y pulsar Next > cuando se haya seleccionado/escribo el directorio de destino.

      Se visualizará a continuación la siguiente pantalla:

      Que solicita que seleccionemos el tipo de instalación deseada. Elegir la instalación

      Complete y pulsar el botón Next >

      A continuación pide que seleccionemos el grupo de programas donde deseamos que sean creados los iconos de acceso al programa o bien si queremos que se cree un grupo de programas nuevo. Elegir lo deseado (preferiblemente crear un grupo de programas que se llame Microsoft HTML Help Workshop). Y pulsar Next >.

      Por último se pide un nombre para personalizar la copia que se va a instalar del programa. Escribir lo que se desee y pulsar Next > .

      Se comienzan a copiar los archivos de instalación y cuando esta termina mostrará el siguiente mensaje:

      Pulsar OK para terminar.

      Se habrá creado un grupo de programas denominado Microsoft HTML Help Workshop, desde el cual se puede arrancar el programa haciendo click en el elemento HTML Help Workshop.

• HELP: MAS AYUDA EN LINEA
  | HELPSCRIBBLE | Funcionalidad | Delphi C++ Builder | Kylix (Delphi para Linux) |

  Para lograr un sólido Diseño en nuestra interfaz, es necesaria implementar algunas estrategias que ayuden a la conversación en línea con el usuario. Entre unas de ellas podemos mencionar: “Archivo de Ayuda”.

  • Crear un archivo de ayuda superior aumenta la calidad de su software. Los usuarios de la aplicación esperan recibir la documentación detallada de una manera rápida presionando la tecla F1.

  • Usted venderá más copias de su software si incluye un archivo de ayuda pensado para facilitar las perspectivas de interacción del usuario con el producto.

  • Es una Herramienta Grafica que como dijimos antes ayuda a que el usuario, en forma “didáctica”, a que cononazca las herramientas que brinda nuestra aplicación. Además de proporcionarle información útil.

  • Existe un programa conocido como “HELPSCRIBBLE” que te permite desarrollar en forma intuitiva “Archivo de Ayuda” , a continuación damos algunas directivas:

  • Sobre HelpScribble

    HelpScribble es un authoring tool completamente equipado, fácil de utilizar para crear archivos de la ayuda,desde comienzo hasta el final. Usted puede crear los archivos de WinHelp (hlp) , los archivos de la ayuda del HTML (chm) , una documentación manual y en línea impresa (en un Web site) toda del mismo proyecto usando HelpScribble.

    • Escribir un Archivo de Ayuda es fácil:

      Antes debemos aclarar que un archivo de Ayuda consiste en una serie de asuntos. Un asunto es una sola pagina en el archivo de ayuda. Cuando usted presiona F1 en una aplicación, le mostrará un asunto de su archivo de ayuda. Cada asunto explica generalmente un aspecto especifico del uso: un articulo de menú, una caja de dialogo pequeña, etc. La mayoría de los asuntos contiene vínculos a otros asuntos que proporciona información sobre los aspectos relacionados al uso.

    • En HelpScribble, usted puede crear nuevos asuntos seleccionando “asuntos nuevos” del menú. Entonces si usted utiliza el procesador de texto incorporado HelpScribble para mecanografiar adentro del texto del asunto. Para crear un vinculo a otro asunto simplemente hacemos clic derecho en ese asunto de la lista en la izquierda, y seleccionamos “crean acoplamiento” del menú pop-up. Eso es todo hasta aquí para crear un archivo de ayuda!

    • Un estrategia útil esta a primero crear todos los asuntos usando “asunto nuevo “. Escribir adentros sus títulos , pero no escriba adentro el texto real con todo, hasta que no se hayan creado todos los asuntos. De esta manera, creando asuntos vacíos, usted puede centrarse en la estructura general del archivo de ayuda. Además puede centrarse en el contenido de los asuntos individuales. Que a su vez facilita la creación de vínculos entre los asuntos mientras escribe el cuerpo del texto, puesto que usted habrá creado todos los asuntos.

• Toda la Funcionalidad Que Usted Necesita

  • Usted puede construir fácilmente el contenido de su archivo de ayuda usando el redactor del contenido del “built-in”. Haga Clic sobre "Header", escriba adentro el "título" y seleccione el botón de la adición (botón de signo más verde) para agregar un jefe. La adición de asuntos es incluso más fácil. El doble-clic en ellos en la lista que demuestra todos los asuntos en su ayuda se archiva simplemente.

  • HelpScribble construirá automáticamente el índice para su archivo de ayuda. Todo lo que usted tiene que hacer es especificar las palabras claves apropiadas para cada asunto. Usted puede hacer esto directamente en la rejilla del asunto de la ventana principal de HelpScribble, o usando el redactor conveniente del índice de HelpScribble.

  • Con el redactor de la secuencia, usted puede crear listas de los asuntos que pueden ser seleccionados utilizando los botones en WinHelp. Seleccionar las secuencias es lo más útil si su archivo de ayuda contiene una sección de referencia. Usted podría crear una secuencia con todos los asuntos de la referencia en orden alfabético.

• Cómo hacer sus enlaces Clickable en la pantalla

• Usted sabe del proverbio chino que dice que un buen cuadro vale más que mil palabras. Mientras que cualquier authoring tool de la ayuda permite que usted inserte enlaces de la pantalla y otros cuadros, con el redactor de “SHG” de HelpScribble usted puede hacer que sus cuadros tengan mayor alcance. Usted puede agregar regiones “clickable” a sus imágenes que, cuando están seleccionadas, para que muestren un asunto de la ayuda con más información sobre el área que fue seleccionada. Los nuevos usuarios no sabrán el nombre de todas las características en su uso, sino que sabrán señalar en un cuadro.

• El redactor de “SHG” de HelpScribble hace esto muy fácil. Si usted ha hecho ya el enlace de la pantalla (o a cualquier imagen que usted desea utilizar), abra simplemente el archivo a memoria de imagen en el redactor de SHG. Si usted todavía no ha hecho el enlace de la pantalla, presione la pantalla de Alt+Print (capturar la ventana activa) o la pantalla de impresión (capturar la pantalla entera). Entonces cambie al redactor de “SHG” de HelpScribble y el uso corrige “Inserte La BITMAP”.

• Para agregar un hotspot (región clickable), dibuje simplemente un rectángulo en la BITMAP con el mouse. Justo como usted haría en un paint. Entonces usted puede fijar las características de los hotspot en la sección derecha del redactor de SHG. Generalmente, usted solamente dará a hotspot un nombre para la referencia fácil más adelante y seleccionará el asunto del vinculo de la lista drop-down.

• Una de las razones por las que HelpScribble es popular entre los reveladores de Delphi y de C++Builder, es la manera que integra con esas herramientas de desarrollo. Esta integración es proporcionada por el redactor de la característica de HelpContext que se incluye con HelpScribble.

• Agregar una ayuda sensible al contexto del uso dentro de Delphi o C++Builder puede ser un poco una tarea. Pero el redactor de la característica de HelpContext de HelpScribble permite ligar encima del archivo de la ayuda a su uso un broche de presión. Primero usted necesita tomar un minuto para instalar el paquete del redactor de la característica en Delphi o C++Builder. Entonces usted puede hacer doble- clic en cualquier característica de HelpContext en el inspector del objeto demostrar el redactor de la característica de HelpContext. En el lado izquierdo del redactor de la característica, usted verá un árbol de todos los componentes en la forma actual. En el lado derecho, usted verá una lista de todos los asuntos en el proyecto actual de HelpScribble. (HelpScribble debe funcionar en el fondo.) Para enganchar encima de un asunto con un control, selecciona encendido el control y entonces el doble-clic en el título del asunto. ¡Fácil! No más de algo de voluntad de su parte.

  Ayuda del HTML

  • Si usted desea utilizar el nuevo formato de la ayuda del HTML que Microsoft quisiera que usted utilice, usted puede todavía emplear el redactor de la característica de HelpContext. En las opciones del proyecto de Delphi, seleccione el archivo del chm en vez del archivo del hlp. Desde Delphi (más específicamente: el VCL) apoya solamente WinHelp fuera de la caja, usted necesita agregar un cierto código adicional a su uso. Si no, las peticiones de la ayuda causarán un mensaje de error que su archivo del chm que no sea un archivo válido de la ayuda (de WinHelp).

  • Las unidades libres de UseHTMLHelp y de HTMLHelpViewer se cercioran de que Delphi sepa utilizar ayuda del HTML. Agregue UseHTMLHelp.pas a la cláusula de las aplicaciones de su archivo de proyecto del dpr si usted está utilizando Delphi 3, 4 o 5.

  Ayuda del HTML con Delphi 6 y 7

• Utilice HTMLHelpViewer.pas si usted está utilizando Delphi 6 o 7. Delphi 6 tiene totalmente una nueva arquitectura de la ayuda para permitir utilizar más de un sistema de ayuda. Desafortunadamente, Borland no hizo uso que la arquitectura para apoyar ayuda del chm archiva. La unidad de HTMLHelpViewer.pas toma el cuidado de esto. Observe que no es semejante de un cierto código de fuente que esté libremente disponible en el Internet para hacer el trabajo de Delphi 6 con ayuda del HTML.