Guía rápida de creación de Ayudas en formato .HLP con el Help Compiler Workshop (hcw)

  1. Guía rápida de creación de ayuda (formato HLP) con el Help Compiler Workshop (HCW) (5/Ene/99)

Creación del fichero con el Word:

Configurando la ayuda con el Help Compiler Workshop (HCW):


Guía rápida de creación de ayuda (formato HLP) con el Help Workshop (HCW) (5/Ene/99)

Estaba yo trasteando con la librería gsAxDLL cuando me dio el punto de crear la ayuda de este componente y probar los ID de contexto y esas cosas, ya sabes para que al pulsar F1 sobre el nombre de una propiedad de la clase te muestre la ayuda asociada. Entonces me planteé si usar el nuevo sistema de ayuda HTML o el "añejo" formato HLP.

La ayuda en el formato HTML es más fácil de crear, siempre que se le tenga cogido el tranquillo al tema de crear páginas HTML, pero tiene el inconveniente de que no está plenamente integrado con el Visual Basic, al menos con la versión 5 que es en la que estoy haciendo la referida DLL.

El sistema de ayuda en formato HLP es algo más complicado, pero tiene la ventaja de que estará disponible para más gente, no necesita tener el Internet Explorer instalado ni tampoco comprobar si tenemos el control hhctrl.ocx

Por lo cual me decidí por el sistema HLP. Al fí y al cabo tenía en mis páginas un "mini-tutorial" que explica cómo crear este tipo de ayudas, y podía seguirlo en caso de que no recordara cómo hacerlo, cosa que al final resultó ser así... con lo cual se "demustra" que lo que hay en mis páginas es útil hasta para mi mismo, je, je...

Pero después de buscar y leer lo que hay en esa sección de ayuda (desde la que posiblemente habrás llegado a esta página), me di cuenta de que para los más "expertos" sería necesario crear una guía rápida, ya que, se supone, no necesitamos de todas las explicaciones "paso a paso".
Como resultado, aquí está esta Guía rápida para poder encontrar de forma rápida las cosillas que nos pueden hacer falta.

También hay cosas que o no están "claras" o no está incluidas en el citado tutorial, por tanto sería conveniente que le echaras un vistazo a lo que viene a continuación.

Recuerda que necesitas el Help Compiler Workshop (HCW.exe) para crear la ayuda con las explicaciones que doy aquí; ese programa puedes instalarlo desde el CD del Visual Basic, en el que se incluye desde la versión 4 y posteriores, normalmente está en un directorio llamado \Tools\HCW.

Creación del fichero con el Word:

Lo que viene a continuación, (en los siguientes cuatro puntos), se refiere a la creación del texto en un editor de texto, normalmente el Word, el tipo de documento a usar debe ser en formato RTF; crea un nuevo documento y dale a guardar como y selecciona ese formato, deberá mostrarte esa extensión.

Cada página contendrá cada uno de los tópicos y/o mensajes a mostrar en ventanas emergentes.

Para crear una nueva página, sitúate al final de donde la quieres introducir y pulsa Control+Intro (Ctrl+Intro)

 

 Títulos, marcadores, palabras claves, etc

Para crear estas cosillas, (que después se usarán al hacer los links, mostrar el índice, etc.), situate al principio de la página que quieres "marcar".

En el Word, que es el editor que uso para estas cosas, (ya que el WordPad no tiene estas "opciones"), selecciona del menú Insertar, Notas al pie.

En el diálogo, selecciona Marca Personal y en la caja de texto, escribe alguna de estas claves, según la tarea que quieras realizar:

 

 Clave/Marca

Descripción

$

El título a mostrar en el índice

k (minúscula)

La palabra o palabras claves a usar, estas se mostrarán al selecciona índice.
Cada palabra debe estar separada de la siguiente con un punto y coma ";"

#

Nombre del marcador, usado para crear los enlaces (links).
Este nombre no debería contener espacios ni símbolos raros y recuerda usar después el mismo estado de mayúsculas y minúsculas.

+

Número de secuencia, en el caso de que se muestren los botones de navegación (browse).
Estos números son ordenados como si fuesen cadenas de texto, por tanto el orden no es numérico, por ejemplo el 1000 estaría antes que el 220.
Yo suelo usar estos mismos números para el ID de la ayuda de contexto, así me lio menos.

 Crear un enlace (link)

Selecciona la palabra o palabras que quieres que se marquen como el link (se mostrarán subrayadas en la ayuda)

En el menú Formato, selecciona Fuentes y selecciona del combo Subrayado la opción Doble, también puedes seleccionar Tachado, (el normal, no el doble).

A continuación, (normalmente esto lo hago antes de seleccionar el subrayado doble), escribe la clave a la que quieres ir cuando se pulse en ese link, (recuerda que es el nombre que escribiste en las notas al pie del nombre del marcador #), selecciona el texto que acabas de introducir y en el menú Formato/Fuentes, selecciona oculto. Con esto ya tienes el link creado.

Si cualquiera de los links que crees quieres que se muestren en una ventana que tengas definida con el HCW, (después veremos cómo hacerlo), tienes que poner después del nombre del marcador el signo mayor seguido del nombre de la ventana en la que quieres que se muestre.

Por ejemplo: UnMarcador>unaVentana, esto hará que lo que esté en el marcador llamado UnMarcador, se mostrará en una ventana llamada UnaVentana.

 

Crear un enlace (link) para mostrarlo en una ventana emergente

Se hace como en el enlace normal, pero las palabras a usar como link en vez de estar "doblemente subrayadas o tachadas, deben estar subrayadas (simple), es decir el subrayado que está en la barra de herramientas.

En la ayuda el link se mostrará con un subrayado de puntos, indicando que el enlace se mostrará en un menú emergente.

 

***Mostrar el título de la página separado del texto normal

Esto no estaba antes, creo...

Para que los títulos o cabeceras que se muestran en las páginas de la ayuda estén en la parte superior, (normalmente divida y con otro color), selecciona lo que quieres que se muestre, (normalmente el texto que está en la parte superior) y en el menú Formato/Párrafo, selecciona la solapa Líneas y saltos de página y marca la casilla que dice Conservar con el siguiente.

La parte destinada al título se selecciona en el HCW al crear una ventana.

Esto es prácticamente todo lo que necesitas saber sobre lo que escribas en el fichero RTF, ahora vamos a ver cómo configurar el resto de las cosas en el HCW.

Configurando la ayuda con el Help Compiler Workshop (HCW):

El siguiente paso, una vez que tenemos creado el fichero RTF, es crear, configurar y compilar el proyecto de ayuda, todo esto se hace desde el HCW, por tanto carga el programa, crea un fichero con la extensión hpj y sigue leyendo.

Para crear un nuevo proyecto de ayuda, en el HCW, selecciona New del menú File y elije proyecto de ayuda (Help Project), escribe el nombre que tendrá tu fichero de ayuda.

Especificar el fichero RTF y crear las ventanas.

Una vez que hemos especificado el nombre del proyecto, en la casilla que hay junto a Help File, se mostrará el nombre del fichero de ayuda, que será el mismo que el del proyecto, pero con la extensión hlp.

Para especificar el fichero RTF a usar, pulsa en el botón Files... en el cuadro de diálogo que se muestra, pulsa en Add... y selecciona el fichero que acabas de crear o que ya tenías creado en ese formato. Si son varios los ficheros, selecciona los restante y una vez que tenga todos los que formarán parte de la ayuda, pulsa en OK.

Si quieres crear ventanas para que se puedan mostrar los diferentes tópicos en diferentes ventanas, pulsa en el botón Windows... crea una nueva ventana, si es la primera, te recomiendo que el nombre sea Main, no es por nada, pero es una especie de norma. El tipo de ventana suele ser del tipo Procedure, las otras opciones son: Reference y Error message.

Para que la ventana muestre los diferentes botones de Buscar, >>, <<, etc. pulsa en la solapa Buttons y selecciona las casillas pertinentes, algunas estarán en gris, por tanto no puedes seleccionarlas... elemental, mi querido Guille...

Si pulsas en la solapa Color, verás a lo que me refería antes con lo de mostrar los títulos separados del texto normal. Para especificar el tamaño de la ventana, selecciona la solapa Position, si pulsas en el botón Default positions, la ayuda se mostrará en el centro de la pantalla y el tamaño será el habitual, para que se adapte a la resolución que en ese momento se tenga, marca la casilla Adjust for user's screen resolution. Juega con el resto de las opciones y ve comprobando los resultados.

 

Mapear las claves para usar con la ayuda del Visual Basic

Lo siguiente que vamos a hacer es mapear las claves creadas con # en el fichero RTF para que el Visual Basic pueda acceder a ellas, porque como sabrás, en el VB se especifican números y no palabras al indicarle el valor del Context ID, para hacer esto, en el HCW pulsa el botón Map..., pulsa en el botón Add... y en la casilla de arriba te pide el nombre del tópico (Topic ID), escribe la clave que quieres asociar con un número, en la siguiente casilla escribe el número que será el mismo que escribiste en el cuadro del Context ID, esto también es válido para cualquier control o formulario, pero el nombre de esa propiedad es HelpContextID. De esta forma, si ese valor está asociado con un textbox de un formulario, al pulsar F1 en ese textbox, te mostrará la ayuda asociada.

Ahora que tienes todas estas cosas, puedes pulsar en Save and Compile para guardar los cambios y crear el fichero de ayuda.

Creo que con esto, tendrás una guía rápida, al menos para crear el fichero RTF y el proyecto de ayuda, para crear los contenidos (los libritos esos), leete lo que hay en la otra página sobre la creación de ayuda referente a la creación de libritos, ya que allí está más o menos bien explicado, si me da el punto, lo añadiré a esta página, pero creo que no será necesario.

De todas formas, aquí te añado el proyecto que he creado para la ayuda del componente gsAxDLL, aunque no está terminada la ayuda, te servirá de guía.