Gua para la generacin de archivos de ayuda en formato CHM

Rodrigo Garca Puente www.rodrigogarcia.es.fm

NDICE 1. OBJETIVO. 2. ALCANCE. 3. REFERENCIAS. 4. TIPOS DE AYUDA PARA SISTEMAS MICROSOFT WINDOWS. 4.1. Formato HLP. 4.2. Formato CHM. 5. GUIA PARA GENERAR AYUDAS EN FORMATO CHM. 5.1. Conceptos. 5.2. Crear un archivo CHM paso a paso. 6. COMPILAR CON HTML Help Workshop. 7. INSERCIN DE LA AYUDA EN VISUAL BASIC. 7.1. Adaptando un proyecto de Visual Basic. 7.2. Propiedad HelpContextID. 7.3. Lanzar la ayuda correspondiente a un formulario. 8. INSTALACIN DE MICROSOFT HTML HELP WORKSHOP.

Gua para la generacin de archivos de ayuda en formato CHM

1. OBJETIVO
El objeto de este documento es servir de gua para la generacin de archivos de ayuda de aplicaciones desarrolladas bajo sistemas operativos Windows (versiones 95 y superior).

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

3. REFERENCIAS
Para la redaccin de este documento se han consultado las siguientes referencias:

Artculo Crear ayudas para aplicaciones VB publicado por Jos Luis Monte Galiano en www.redvisual.net/articulos/otros/hlp/indice.htm. Artculo Displaying Help by Using the HtmlHelp API publicado en la web oficial de Microsoft Office 2000/Visual Basic Programmers Guide.

Todos los ejemplos de esta Gua para la generacin de ayudas han sido desarrollados con el programa Microsoft HTML Help Workshop que es un programa gratuito de Microsoft para generar archivos de ayuda y que puede descargarse desde el sitio web oficial de Microsoft (www.microsoft.com).

4. 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.

4.1. Formato HLP

Es el estndar tradicional por excelencia de Microsoft Windows. Desde sus primeras versiones adopt este formato, (RTF y Word), y extensin de archivo HLP para sus ayudas. Con el tiempo, hizo pblico este formato y proporcion un compilador, (bajo MS-DOS), para generar esta clase de ayudas. El compilador evolucion hasta llegar al actual HTML Help

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

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 bastara (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.

4.1. Formato CHM

Con la aparicin de Windows 98, Microsoft cre un nuevo estndar 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 pginas web de internet). Para crear archivos de ayuda CHM son necesarias las siguientes herramientas:

Un editor de pginas web, para generar el contenido de la ayuda (archivos de extensin HTM o HTML). Puede usarse por ejemplo el editor gratuito de Microsoft (Frontpage Express), Microsoft Word u otro editor de pginas 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 extensin CHM. Una herramienta gratuita como Microsoft HTML Help Workshop es suficiente para realizar este trabajo.

5. GUIA PARA GENERAR AYUDAS EN FORMATO CHM

5.1. Conceptos
CHM utiliza un lenguaje de marcas (el popular lenguaje de de marcado de hipertexto o HTML, usado para generar pginas web).

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

Una vez creados los diferentes captulos de nuestra ayuda en diferentes archivos HTM ( o HTML), estos son aglutinados en un archivo de proyecto con extensin HHP. A este proyecto se le aaden :

Archivos H: Aaden un ID para identificador de captulo dado, que luego ser aprovechado por nuestras aplicaciones Visual Basic para lanzar la pgina de ayuda correspondiente. Archivos HHK: ndices. Archivos HHC: Tablas de contenido.

Con todo esto, compilamos el proyecto y obtenemos un archivo de ayuda con extensin CHM. La versin del Help WorkShop recomendada para este tipo de ayudas es la 4.7 del ao 1.999. Esta aplicacin contiene un conversor de proyectos para ayudas HLP a CHM. Por lo tanto, y en teoria, es posible utilizar esta aplicacin para ambos tipos de ayudas.

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

5.2. Crear un archivo CHM paso a paso

A continuacin se mostrarn los pasos bsicos 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 extensin HTM (o HTML). Es recomendable crear una pgina HTML por cada topic de la ayuda. Se puede usar cualquier editor de pginas web, el bloc de notas e incluso Microsoft Word (guardando los archivos con la extensin correspondiente). En el ejemplo que se presenta se han desarrollado 3 pginas 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, imgenes, hipervnculos a otras pginas de ayuda y sitios web, e incluso cdigo de lenguajes de script (JavaScript o VBScript). Es decir, tal y como fueran pginas web normales. Crear el archivo de proyecto (HHP). Un proyecto de ayuda CHM es un archivo de extensin HHP que aglutina todos los dems archivos que conforman la ayuda CHM. Para crear este y los dems archivos podemos utilizar la aplicacin 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 compilacin. ALIAS: Identificador de Nombre de alias y archivo HTM. MAP: Archivo con la definicin de los nombres de alias y un ID para cada uno que despus ser usado en nuestras aplicaciones

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

Visual

Basic

para

lanzar

la

ayuda

de

contexto

(propiedad

HelpContextID). Para crear un nuevo proyecto arrancamos Microsoft HTML Help Workshop y pulsamos en el botn New de la barra de herramientas (o en la opcin 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 continuacin 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 pginas web ya creados. Como no lo tenemos no marcamos nada y pulsamos en Siguiente. Una vez terminado se visualiza la pantalla del proyecto.

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

Haciendo click en el botn de la

ventana

Project

podemos indicar las pginas html que tendr nuestra ayuda (esto nos servir para poder vincular ms tarde el archivo de contenido con las pginas). En la pantalla Topic Files se hace click en el botn Add ... y se seleccionan los archivos htm y html que compondrn nuestra ayuda.

Veamos a continuacin los valores de los parmetros para las distinas secciones. OPTIONS En esta seccin 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).

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

Para poder establecer estos valores hay que hacer click en el botn Change project options de la pestaa Project. Antes de establecer valores como el archivo de contenido o de ndice, ser necesario crearlos previamente (para ello hacer click en la pestaa Contents e Index respectivamente). Un ejemplo para esta seccin 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=Espaol (alfabetizacin 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 botn HTML Help API Information de seccin ALIAS. Por ejemplo : [ALIAS] ID_topic0=paginas\principal.htm ID_topic1=paginas\capitulo1.htm ID_topic2=paginas\captiulo2.htm MAP Relacin de archivos H en el que se definen los ALIAS descritos en la seccin 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 botn HtmlHelp API Information de MAP. Por ejemplo : [MAP] #include Ejemplo.h la pestaa Project y en la seccin la pestaa Project y en la

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

Crear el archivo de contenido (HHC). Para crear el archivo de contenido hacer click en la pestaa Contents o bien en la opcin New del men File eligiendo la opcin Contents file (archivo de contenido): En un archivo HHC se define la estructura del libro de contenidos de nuestra ayuda. El proceso es ir aadiendo carpetas y pginas para ir generando los libros de la ayuda. Una carpeta es un contenedor de carpetas y de pginas. Para ello hacer click en los botones y .

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 tpico de la ayuda (para vincularlo hacer click en el botn Add y seleccionar la pgina correspondiente). Crear el archivo de ndice (HHK) [opcional].

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

10

La creacin de un archivo de ndice es opcional. En l referenciamos todas las cadenas de bsqueda para cada captulo. Para crear un nuevo archivo pulsar en la pestaa correspondiente ( Index) o bien en la opcin 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 pginas. Si pulsamos en el icono aparecer una ventana en la determinadas que se podrn Aadir pginas y vincularlas con

palabras clave. Por ejemplo si en un tpico de la ayuda hablamos del entorno grfico de nuestra aplicacin podemos poner como palabras clave entorno, grfico, mens o lo que se desee y vincularlo con la/las pginas deseadas mediante la opcin Add de la ventana que aparezca cuando se hace click en el icono correspondiente. Crear el archivo de cabecera, declaracin de ID de contexto (H). En un archivo con extensin H definimos, (con el comando #define), los alias que referenciaremos a cada captulo, (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

6. 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 opcin Compile del men File. Aparecer una ventana en que se nos pedir confirmacin del proyecto a compilar, (por defecto ofrece el que est cargado en ese momento). En el proceso de compilacin aparece una ventana de log en la que se nos informa del estado de dicha compilacin. Si ocurre un error aparece reflejado en esta ventana. Otra utilidad prctica de Help WorkShop es la opcin de View Compiled Help File del men View. Con est opcin vemos cualquier archivo de ayuda; sea este CHM o HLP una vez compilado.

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

11

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

12

7. INSERCIN 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 relacin estriba en que en un control de nuestro formulario, (o en el propio formulario), es posible referenciar un captulo concreto de nuestra ayuda. De esta forma se muestra la ayuda concreta sobre el tema referenciado para ese control. Debido a que la implementacin actual de la ayuda HTML no permite la insercin 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.

7.1. Adaptando un proyecto de Visual Basic

A pesar de que al pulsar la tecla F1 no se lanza la ayuda automticamente, la propiedad HelpContextID de los controles de VB puede seguir siendo utilizada, para que, en funcin del formulario en el cual estemos, se lance un captulo 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 mdulo de cdigo debemos copiar la siguiente declaracin del API y dos constantes pblicas: 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 funcin HtmlHelp y su respectiva funcionalidad son los siguientes: Argumento HwndCaller Descripcin Es un manejador de una ventana de aplicacin o Null. Este manejador debe ser usado como el propietario o el contenedor de la ayuda HTML, dependiendo como sea usado. En VBA, en PszFile vez de usar vbNullString establecer este parmetro a 0. Es el string que se corresponde con el path del archivo de ayuda. Opcionalmente puede especificar en que tipo de

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

13

UCommand

ventana se ha de visualizar. Es la accin a realizar, o como mostar tpicos de ayuda. Pude ser usado con cualquiera de los dos comandos declarados como constantes HH_HELP_CONTEXT o HH_DISPLAY_TOPIC. Slo se ha llegado a probar con xito HH_HELP_CONTEXT. Especifica el topic ID.

DwData

7.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 numrico entero que indica el ID del tpico 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 seccin MAP de la ayuda HLP referenciamos estos nmeros con los captulos de la ayuda que deseemos.

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

14

7.3. Lanzar la ayuda correspondiente a un formulario

Para lanzar la ayuda correspondiente a un formulario nicamente hay que hacer una llamada a la funcin HtmlHelp con los parmetros deseados. En nuestro ejemplo, se hizo en el evento Click del botn 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

8. INSTALACIN 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 pgina oficial de microsoft. Haciendo doble click se arranca automticamente el programa de instalacin y se visualiza la siguiente imagen indicando que se estn extrayendo los archivos de instalacin:

Una vez se ha terminado de extraer los archivos aparece el programa de instalacin que nos pide que aceptemos la Licencia de uso, en la pantalla titulada License Agreement pulsar el botn Accept. Una vez aceptado el acuerdo de licencia se visualiza el asistente de instalacin de Microsoft HTML Help Workshop (ver siguiente imagen), pulsar Next >.

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

15

A continuacin aparece otra pantalla que solicita que seleccionemos el directorio de destino de instalacin 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 continuacin la siguiente pantalla: Que solicita que seleccionemos el tipo de instalacin deseada. Elegir la

instalacin Complete y pulsar el botn Next >.

Rodrigo Garca Puente Marzo de 2001

Gua para la generacin de archivos de ayuda en formato CHM

16

A continuacin 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 instalacin 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.

Rodrigo Garca Puente Marzo de 2001