Configurar la ayuda
Para configurar de forma general la ayuda, pulsaremos en el primer botón de
la pantalla principal, el que muestra en el "tooltip" el texto Change
project options (ver figura 1).
Figura 1. Cambiar las opciones del proyecto
Al pulsar en ese botón, nos mostrará un cuadro de diálogo con varias fichas,
en la primera (General), tal como vemos en la figura 2,
indicaremos el título de la ayuda, cual será la página por defecto (la que se
mostrará al iniciar la ayuda) y la ventana que se usará cuando no se indique
ninguna en particular.
Figura 2. Ficha General de las propiedades del proyecto
En la ficha Files (ver la figura 3), indicaremos el nombre y la ruta del
fichero .chm, además de indicar cuales serán los ficheros que se usarán para el
contenido (Contents file) y para el índice (Index file).
Figura 3. Ficha Files de las propiedades del proyecto
Si marcamos la opción Include keywords from HTML files (está bajo el nombre
del fichero del índice), esto hará que se añadan automáticamente al índice las
palabras clave que hayamos incluido en el código de los ficheros HTML.
Esas palabras clave no se incluyen en el "tag" keywords del encabezado (head) de
la página, sino en objetos especiales que el sistema de ayuda usará para saber a
dónde debe apuntar cuando se seleccione esa palabra clave.
Esas palabras clave las podemos agregar de dos formas, una es usando el
propio HTML Help Workshop. En este caso, debemos abrir el fichero HTML en esa
utilidad, posicionar el cursor en la parte en la que queremos incluir el
"marcador" dentro de la página, y seleccionar Compiler information el menú de
edición (Edit), y del cuadro de diálogo mostrado (ver la figura 4), seleccionar
la ficha Keywords y pulsar en el botón Add para añadir la palabra (o palabras)
que queremos que esté ligada con esa posición del fichero.
Figura 4. Añadir palabras clave a un fichero HTML
Al pulsar en el botón OK se modificará el fichero HTML para incluir esas
palabras clave.
El problema principal que tiene esta forma de hacerlo es que la utilidad
hhw.exe no "entiende" de codificaciones y siempre guardará (y abrirá) los
ficheros de ayuda con la codificación estándar de Windows. Si el editor de HTML
que estamos usando guarda esos ficheros usando la codificación UTF-8, nos
encontraremos que las vocales acentuadas y otras "letras especiales" no se
muestran de la forma correcta.
Para solucionar el problema, debemos asegurarnos de que en la cabecera del
fichero HTML no usamos la codificación UTF-8, que suele estar indicada de esta
forma:
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Si tenemos esta codificación:
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252" />
Podremos editar esos ficheros en ambos editores sin que se conviertan los
"caracteres especiales del idioma" en símbolos irreconocibles.
También debemos saber que el editor HTML que se incluye con HTML Help
Workshop es "simplemente" un editor de textos que no permite la previsualización.
La otra forma de agregar esas palabras clave al fichero HTML es haciéndolo de
forma manual.
Para agregar las palabras clave que vemos en la figura 4, nos posicionaremos en
la parte del fichero en la que queremos poner el "marcador" y agregaremos el
siguiente "objeto":
<object type="application/x-oleobject" classid="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e">
<param name="Keyword" value="New" />
<param name="Keyword" value="File" />
<param name="Keyword" value="Nuevo" />
<param name="Keyword" value="Project" />
<param name="Keyword" value="Nuevo proyecto" />
</object>
Como vemos, podemos agregar varias palabras clave a un mismo "marcador"
dentro de cada fichero, e incluso podemos agregar varios marcadores a un
fichero, (ver la nota), por supuesto, cada uno de los objetos que agregamos con
las palabras clave debería incluir palabras clave diferentes.
Nota:
En las pruebas que he hecho, el incluir varios objetos en un mismo fichero no
tiene el resultado esperado, de que cada objeto marque una posición dentro del
fichero HTML, aunque si que agregará todas las palabras clave al índice, pero en
caso de que haya palabras repetidas, solo se mostrará una vez.
Ejemplo de KLinks que apuntan a palabras clave dentro de la
ayuda. Al pulsar en el botón que hay debajo, te mandará a la página en la que
está definida la palabra clave Guardar (también accesible desde
el índice de la ayuda).
Nota:
En el fichero de ayuda compilada (.chm) se mostrará aquí (debajo) un botón con un link a otra página.
Pero que está quitado del tutorial publicado en mi sitio, ya que te avisaría de que ese control se quiere ejecutar, etc.
Más abajo tienes el código que iría aquí
Aquí iría el "objeto"
Para crear el botón con los links a las palabras clave, el código a usar
sería como el mostrado más abajo, aunque ese código está "modificado" para que
se adecúe a las especificaciones de XHTML, en el que las instrucciones deben
estar en minúsculas o que los valores de los atributos deben estar entre
comillas.
<object id="hhctrl" type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=6,0,6000,16386"
width="100"
height="100"
>
<param name="Command" value="KLink"/>
<param name="Button" value="Text:Prueba de links"/>
<param name="Item1" value=""/>
<param name="Item2" value="Guardar"/>
</object>
Y el aspecto del botón sería como el mostrado en la figura 5.
Figura 5. Un botón para acceder a las palabras clave
Nota:
Para agregar los botones o comandos para ir a palabras clave que tenemos
definidas en los ficheros HTML debemos abrir el fichero en el que queremos
insertar el botón y usar el asistente para la creación de estos "comandos", para
lanzar ese asistente, seleccionaremos la opción HTML Help Control
del menú Tags o bien pulsando en el icono con el dibujo de un
gorro de mago, tal como vemos en la figura 6.
Después debemos seguir los pasos que nos indica el asistente, los cuales no
muestro de forma independiente, ya que desde mi punto de vista no es complicado
y, sobre todo, porque... a mi particularmente no me gustan esos botones... así que...
En serio, en la propia ayuda de HTML Help Workshop se explica
cómo crearlos y simplemente siguiendo las indicaciones del asistente podemos
modificar los elementos que se mostrarán al pulsar en el botón.
Ese tipo de botones se pueden usar para poner links relacionados al final de
cada página o tópico, al estilo de como lo hace la propia ayuda de Windows o de
otros productos de Microsoft.
La verdad es que hay muchas opciones de cosas que podemos hacer con esos
"comandos", incluso podemos mostrar los links como imágenes en lugar de un botón
con texto, hacer que se muestre el contenido, ir a una página específica, buscar
por las palabras clave, etc.
En el fichero final compilado de este "tutorial", (en esta misma página), puedes
ver cómo quedarían un botón para temas relacionados.
Figura 6. Mostrar el asistente de HTML Help Active Control (HTML Help Control)
Por último, en la ficha Compiler (ver la figura 7),
indicaremos que compatibilidad queremos (se recomienda usar la indicada de 1.1 o
posterior) y otras opciones de compilación que podemos dejar con los valores que
tienen por defecto, tal como vemos en la captura de la figura 7.
Figura 7. Ficha Compiler de las propiedades del proyecto
Nota:
En el fichero de ayuda compilada (.chm) se mostrará aquí (debajo) un botón con links relacionados.
Pero que está quitado del tutorial publicado en mi sitio, ya que te avisaría de que ese control se quiere ejecutar, etc.
Este sería el código de ese control con los links relacionados:
Aquí iría el "objeto"
Este sería el código de ese objeto ActiveX con los links relacionados
(este es del código original para el .chm, por eso los links son a páginas .htm en lugar de .aspx)
<object id="hhctrl" type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=6,0,6000,16386"
width="100"
height="100"
>
<param name="Command" value="Related Topics, MENU"/>
<param name="Button" value="Text:Temas relacionados"/>
<param name="Item1" value="Crear el contenido de la ayuda;htm\hhw_04.htm"/>
<param name="Item2" value="Crear el índice de la ayuda;htm\hhw_05.htm"/>
</object>