HelpNDoc incluye un editor de scripts muy potente con acceso a múltiples métodos API que ofrece un medio para automatizar prácticamente todas las partes del proceso de creación y mantenimiento de la documentación. Ya hemos visto cómo usar las funciones con scripts de HelpNDoc para automatizar la creación de documentos y archivos de ayuda, actualizar la ruta de los elementos audiovisuales externos cuando los mismos son trasladados y exportar códigos de ID de Ayuda y Contexto de Ayuda para tus desarrolladores. Veamos ahora cómo podemos crear un script muy conveniente para restablecer de manera automática los números de Contexto de Ayuda para todos los temas del proyecto de documentación.

Tabla de contenido de HelpNDoc desplegada

¿Qué son los números de Contexto de Ayuda?

Se puede utilizar identificadores de tema (los códigos de ID de Ayuda y Contexto de Ayuda) para acceder a un tema específico desde una aplicación de terceros: HelpNDoc se asegura de que cada tema vaya unido a una ID de Ayuda y un número de Contexto de Ayuda únicos.

HelpNDoc crea automáticamente dos identificadores únicos para cada tema que añadas a tu proyecto:

  • Una ID de Ayuda alfanumérica, que se establece mediante una versión filtrada de la leyenda del tema;
  • Un número de Contexto de Ayuda, que se establece como el integer positivo único más bajo disponible en el proyecto.

Al crear el primer tema, su número de Contexto de Ayuda se establece en “0”. El segundo se establece en “1”, el tercero en “2” y así sucesivamente. Cuando se elimina un tema, digamos que el segundo, por ejemplo, su número de Contexto de Ayuda quedará disponible para el siguiente tema creado: al crear el cuarto tema, su número de Contexto de Ayuda quedará establecido en “1”. Con el tiempo, los números de Contexto de Ayuda pueden volverse confusos, ya que no siempre son la cifra siguiente al tema anterior. Afortunadamente, podemos crear un script para restablecer automáticamente el número de Contexto de Ayuda de todos los temas, y asegurarnos así de que el primer tema empiece en “0” y los números de los Contextos de Ayuda de los siguientes se incrementen en consecuencia.

Script HelpNDoc para restablecer los números de Contexto de Ayuda

En vez de actualizar manualmente el número de Contexto de Ayuda de cada uno de los temas a mano, saquemos partido a las funciones con scripts de HelpNDoc para automatizar esta tarea repetitiva y propensa a los errores

Como HelpNDoc se asegura de que los números de Contexto de Ayuda sean únicos, no podemos repasar cíclicamente cada tema y establecer sus números de Contexto de Ayuda para que empiecen en 0 y asciendan: es posible que otros temas ya estén utilizando esos números, lo cual rompería la iteración limpia que estamos buscando. Esta es la razón por la que daremos una primera pasada para establecer números de Contexto de Ayuda altos para cada tema. Con la segunda pasada, estableceremos los valores finales. Este es el script completo:

Advertencia: Esta acción no se puede deshacer. Si tú o uno de los miembros de tu equipo utilizáis los números de Contexto de Ayuda para acceder a temas específicos de tu archivo de ayuda, no deberías actualizar dichos números. Esta acción solamente debe llevarse a cabo cuando estés diseñando tu documento de ayuda y quieras tener un conjunto consistente de números de Contexto de Ayuda.

const
  // Número temporal de contexto utilizado. MaxInt es el máximo número posible.
  TEMP_MAX = MaxInt div 2;

  // Actualizar el número de contexto para todos los temas empezando con "StartingAtNb"
  procedure UpdateContextNumbers(const StartingAtNb: Integer);
  var
    aTopicId: string;
    aCurrentNb: Integer;
  begin
    // Iniciar
    aCurrentNb := StartingAtNb;
    // Obtener el primer tema
    aTopicId := HndTopics.GetTopicFirst();
    // Repasar los temas cíclicamente
    while aTopicId <> '' do
    begin
      // Establecer el número de contexto para el tema actual
      HndTopics.SetTopicHelpContext(aTopicId, aCurrentNb);
      // Establecer el número siguiente
      Inc(aCurrentNb);
      // Pasar al siguiente tema
      aTopicId := HndTopics.GetTopicNext(aTopicId);
    end;
  end;

begin
  // Comprobar que todos los temas tengan números de contexto elevados
  UpdateContextNumbers(TEMP_MAX);
  // Actualizar todos los temas con números de contexto, empezando por 0
  UpdateContextNumbers(0);
end.

Copia y pega este script en el editor de scripts de HelpNDoc, dale a “Ejecutar script” ¡y voilà! Los números de Contexto de Ayuda de tus temas se establecen automáticamente en orden creciente.

Una vez más, hemos comprobado lo potente y rápido que puede llegar ser el motor de scripts de HelpNDoc: automatizando este proceso largo y proclive a los errores, podemos limpiar fácil y fiablemente nuestros números de Contexto de Ayuda del proyecto. Y la API de HelpNDoc no se limita a los temas y sus identificadores de ayuda: puedes usarla para automatizar diversas partes del proceso de creación de documentación. Así que, si todavía no lo has hecho, descarga tu Edición Personal gratuita de HelpNDoc ahora y empieza a experimentar con sus impresionantes funciones. ¡Y no olvides echar un vistazo a nuestras guías paso a paso en texto y vídeo para aprender rápidamente todos los aspectos de HelpNDoc!

Ver también...

Produce MarkDown con la Herramienta de Documentación HelpNDoc [markdown] [featured]
Equilibrio entre seguridad y usabilidad: los mejores formatos de documentación para compartir a nivel interno

Compartir documentación de manera eficaz y segura es fundamental en el entorno laboral actual. Ya se trate de la distribución interna de manuales, documentación de proyectos o políticas de empresa, la …

Lee Mas →
Ilustración del analizador de caracteres de HelpNDoc [illustration] [Featured]
El arma secreta de los escritores técnicos: las ventajas únicas de usar el Analizador de caracteres de HelpNDoc

HelpNDoc lleva tiempo siendo la solución perfecta para los profesionales que quieren crear documentación fácil de usar, interesante y de alta calidad. Sin embargo, no son solo su interfaz fácil de …

Lee Mas →
Escritor técnico contento usando HelpNDoc [happy] [Featured]
Aprovechar HelpNDoc al máximo: Beneficios de la función "Mantener Archivos Temporales" para los escritores técnicos

Al trabajar creando documentación técnica, toda herramienta y función de la que dispongamos puede marcar una diferencia considerable en la productividad y la eficacia. En HelpNDoc, una de estas …

Lee Mas →
Convertir archivos antiguos de WinHelp en documentación moderna [converting] [Featured]
Revitaliza tus archivos de ayuda: convierte archivos antiguos WinHelp HLP en documentación moderna con HelpNDoc

En una época en la que la información se consume en una enorme variedad de dispositivos y plataformas, los archivos clásicos WinHelp HLP (que en su momento fueron la documentación de ayuda estándar …

Lee Mas →

Categorías: artículos