Combina automáticamente varios temas de tu documentación en uno solo usando un script

Una herramienta de creación de documentación de ayuda estándar como HelpNDoc es un programa de software en el que generalmente se escribe y organiza contenido para producir archivos de documentación para el usuario final. Según van haciendo falta revisiones, es imprescindible que el contenido permanezca organizado, algo que habitualmente implica gran cantidad de tareas pesadas y propensas a los errores, como pueda ser copiar y pegar contenido por todo el proyecto, eliminar contenido, desplazar o combinar temas… Por suerte, HelpNDoc incluye un poderoso procesador de creación de scripts que puede ayudar a automatizar la creación de documentación, el mantenimiento, la reorganización… Ahora veremos cómo sacar partido a las funciones de creación de scripts de HelpNDoc para combinar varios temas hijos en un tema padre.

Uso de las funciones de creación de scripts de HelpNDoc

El editor de scripts integrado de HelpNDoc puede usarse para crear y ejecutar scripts personalizados con el fin de automatizar diversos aspectos de HelpNDoc.

El propósito de este script es combinar el contenido de los temas hijos en un tema padre. Esto quiere decir que el script debe:

Comprobar que haya un tema actualmente seleccionado en la tabla de contenido de HelpNDoc. Este será el tema padre;
Crear un editor temporal en el que se colocará el contenido de todos los temas
Colocar el contenido del tema padre en el editor temporal y obtener una lista de sus temas hijos
Repasar todos los temas hijos en orden y colocar el contenido en el editor temporal
Colocar el contenido del editor temporal en el tema padre
Eliminar todos los hijos del tema padre

Advertencia: Dado que algunas acciones con scripts no son reversibles, siempre recomendamos hacer una copia de seguridad del proyecto HelpNDoc antes de ejecutar un script, por si alguna incidencia obliga a volver a una versión anterior.

1. Recuperar el tema padre

El tema actualmente seleccionado en la interfaz de usuario de HelpNDoc es el tema padre. Es preciso asegurarse de que haya un tema seleccionado y a continuación obtener su ID:

// Obtener el tema actualmente seleccionado
aParentTopicId := HndUi.GetCurrentTopic();
// Comprobar que tenemos una selección válida
if aParentTopicId = '' then
  Exit;

2. Crear un editor temporal

El editor temporal es un marcador de ubicación para el contenido de todos los temas combinados. Así es como podemos crear y liberar dicho editor:

// Necesitamos un editor temporal
oEditor := HndEditor.CreateTemporaryEditor();
try
  // Aquí podemos insertar contenido en oEditor
finally
  oEditor.Free;
end;

3. Insertar el contenido de un tema padre y obtener sus hijos

Ahora podemos colocar el contenido del tema padre en el editor de temas y obtener una lista de sus hijos directos, lo que quiere decir que sólo se incluyen en la lista los hijos de primer nivel.

// Añadir el contenido del tema padre
HndEditor.InsertTopicContent(oEditor, aParentTopicId);
// Obtener una lista de los hijos directos
aFirstLevelChildren := HndTopics.GetTopicDirectChildrenList(aParentTopicId);

4. Repasar todos los temas hijos recursivamente y añadir su contenido

Se puede crear un método recursivo para manejar hijos, nietos, etc. en el orden correcto. Luego podemos llamar a este método para la lista de hijos directos del tema padre:

// Método recursivo
procedure DoInsertChildrenContent(aList: THndTopicsInfoArray; anEditor: TObject);
var
  nTopic: Integer;
begin
  // Repasar los hijos cíclicamente
  for nTopic := 0 to High(aList) do
  begin
    // Insertar contenido
    HndEditor.InsertTopicContent(anEditor, aList[nTopic].Id);
    // Gestionar los hijos
    DoInsertChildrenContent(
      HndTopics.GetTopicDirectChildrenList(aList[nTopic].Id),
      anEditor
    );
  end;
end;

// Añadir el contenido de los hijos del tema padre
DoInsertChildrenContent(aFirstLevelChildren, oEditor);

5. Reemplazar el contenido del tema padre con el contenido del editor temporal

El contenido combinado ya está listo. Ahora podemos sustituir el contenido del tema padre.

// Colocar el contenido final en el tema inicial
HndEditor.SetAsTopicContent(oEditor, aParentTopicId);

6. Eliminar los temas hijos

Ahora se combina el contenido de los temas hijos en el tema padre. Por último, podemos eliminar todos los temas hijos, ya que no son necesarios.

// Eliminar los temas hijos
for nTopic := 0 to High(aFirstLevelChildren) do
begin
  HndTopics.DeleteTopic(aFirstLevelChildren[nTopic].Id); 
end;

El script completo y planes futuros

El script completo está disponible a continuación y formará parte de una próxima versión de HelpNDoc.

procedure DoInsertChildrenContent(aList: THndTopicsInfoArray; anEditor: TObject);var
    nTopic:Integer;
  begin
    // Repasar los hijos cíclicamente
    for nTopic := 0 to High(aList) do
    begin
      // Insertar contenido
      HndEditor.InsertTopicContent(anEditor, aList[nTopic].Id);
      // Gestionar los hijos
      DoInsertChildrenContent(
      HndTopics.GetTopicDirectChildrenList(aList[nTopic].Id),
        anEditor
      );
    end;
  end;

var aParentTopicId: string;
var aFirstLevelChildren: THndTopicsInfoArray;
var aCurrentTopicId: string;
var oEditor: TObject;
var nTopic: Integer;
begin
  // Obtener el tema actualmente seleccionado
  aParentTopicId := HndUi.GetCurrentTopic();
  // Comprobar que tenemos una selección válida
  if aParentTopicId = '' then
   Exit;  
  // Necesitamos un editor temporal 
  oEditor := HndEditor.CreateTemporaryEditor();
  try
    // Añadir el contenido del tema padre
    HndEditor.InsertTopicContent(oEditor, aParentTopicId);
    // Obtener una lista de los hijos directos
    aFirstLevelChildren := HndTopics.GetTopicDirectChildrenList(aParentTopicId);
    // Gestionarlos
    DoInsertChildrenContent(aFirstLevelChildren, oEditor);
    // Colocar el contenido final en el tema inicial
    HndEditor.SetAsTopicContent(oEditor, aParentTopicId);
    // Eliminar los temas hijos
    for nTopic := 0 to High(aFirstLevelChildren) do
    begin
      HndTopics.DeleteTopic(aFirstLevelChildren[nTopic].Id);
    end;
    // El tema actual no se actualiza automáticamente: dirígete al tema de proyecto para cambiar la selección
    HndUi.SetCurrentTopic(HndTopics.GetProjectTopic);
  finally
    oEditor.Free;
  end;
end.

Mucho más que un simple programa de software para la creación de documentación de ayuda, HelpnDoc incluye varias herramientas avanzadas para simplificar y acelerar el proceso de creación de documentación, como su impresionante editor de scripts y las diversas API a las que puede acceder. Te animamos a descargar ahora tu versión gratuita de HelpNDoc para conocerla y probar los diversos métodos API disponibles.

Ver también...

Domina las actualizaciones de contenido con las herramientas de búsqueda y sustitución para escritores técnicos de HelpNDoc

¿Estás cansado de la lucha constante para mantener la documentación consistente, actualizada y sin errores? Para los escritores técnicos y autores de contenido, gestionar estas dificultades puede ser …

Lee Mas →