Fusionner automatiquement plusieurs chapitres de votre documentation en utilisant un script

Un outil de création d’aide standard, comme HelpNDoc, est un logiciel dans lequel vous rédigez et organisez généralement le contenu afin de produire des fichiers de documentation pour les utilisateurs. Lorsque des modifications sont nécessaires, le contenu doit rester organisé et cela implique généralement beaucoup de labeur tout en étant sujet à des erreurs avec des taches telles que copier/coller du contenu à travers le projet, supprimer du contenu, déplacer et fusionner des chapitres… Heureusement, HelpNDoc dispose d’un puissant processeur de script qui peut aider à automatiser la création, la maintenance, la réorganisation, etc. de la documentation. Voyons comment profiter des fonctions de script de HelpNDoc pour fusionner plusieurs chapitres enfants dans un chapitre parent.

Utilisation des capacités de script de HelpNDoc

L’ éditeur de scripts de HelpNDoc peut être utilisé pour créer et exécuter des scripts personnalisés afin d’automatiser divers aspects de HelpNDoc.

Le but de ce script est de fusionner le contenu des chapitres enfants dans un chapitre parent. Cela signifie que le script doit :

1. Vérifier qu’un chapitre est déjà sélectionné dans la table de matières de HelpNDoc. Ce sera le chapitre parent ;
2. Créer un éditeur temporaire dans lequel le contenu des chapitres sera publié
3. Placer le contenu du chapitre parent dans l’éditeur temporaire et obtenir une liste de ses chapitres enfants
4. Intégrer tous les chapitres enfants dans l’ordre et insérer le contenu dans l’éditeur temporaire
5. Insérer le contenu de l’éditeur temporaire dans le chapitre parent
6. Supprimer tous les enfants du chapitre parent

Attention : certaines actions du script étant irréversibles, nous vous recommandons de toujours sauvegarder votre projet HelpNDoc avant son exécution, au cas où une erreur vous obligerait à revenir à une version antérieure.

1. Récupérer le chapitre parent

Le chapitre sélectionné dans l’interface utilisateur de HelpNDoc est le chapitre parent. Nous devons nous assurer qu’un chapitre est sélectionné et en obtenir l’identifiant :

// Get the currently selected topic
aParentTopicId := HndUi.GetCurrentTopic();
// Make sure that we have a valid selection
if aParentTopicId = '' then
  Exit;

2. Créer un éditeur temporaire

L’éditeur temporaire permet de remplacer le contenu de tous les chapitres fusionnés. Voici comment créer et libérer cet éditeur :

// We need a temporary editor
oEditor := HndEditor.CreateTemporaryEditor();
try
  // Here we can insert content into oEditor
finally
  oEditor.Free;
end;

3. Insérer le contenu du chapitre parent et récupérer ses enfants

Nous pouvons désormais placer le contenu du chapitre parent dans l’éditeur de chapitre et obtenir une liste de ses enfants directs, cela signifie que seuls les enfants du premier niveau sont ajoutés à la liste.

// Add the parent topic's content
HndEditor.InsertTopicContent(oEditor, aParentTopicId);
// Get a list of direct children
aFirstLevelChildren := HndTopics.GetTopicDirectChildrenList(aParentTopicId);

4. Intégrer tous les chapitres enfants de façon récursive et ajouter leur contenu

Une méthode récursive peut être conçue pour traiter les enfants, les sous-enfants, etc. dans le bon ordre. Nous pouvons alors utiliser cette méthode pour la liste des enfants directs du chapitre parent :

// Recursive method
procedure DoInsertChildrenContent(aList: THndTopicsInfoArray; anEditor: TObject);
var
  nTopic: Integer;
begin
  // Iterate through children
  for nTopic := 0 to High(aList) do
  begin
    // Insert content
    HndEditor.InsertTopicContent(anEditor, aList[nTopic].Id);
    // Handle children
    DoInsertChildrenContent(
      HndTopics.GetTopicDirectChildrenList(aList[nTopic].Id),
      anEditor
    );
  end;
end;

// Add parent topic's children content
DoInsertChildrenContent(aFirstLevelChildren, oEditor);

5. Remplacer le contenu du chapitre parent par le contenu de l’éditeur temporaire

Le contenu fusionné est alors prêt. Nous pouvons désormais remplacer le contenu du chapitre parent.

// Set the final content to the initial topic
HndEditor.SetAsTopicContent(oEditor, aParentTopicId);

6. Supprimer des chapitres enfants

Le contenu des chapitres enfants est désormais intégré au chapitre parent. Nous pouvons enfin supprimer tous ces chapitres enfants, car ils ne sont plus nécessaires.

// Delete children topics
for nTopic := 0 to High(aFirstLevelChildren) do
begin
  HndTopics.DeleteTopic(aFirstLevelChildren[nTopic].Id); 
end;

Ensemble du script et aller plus loin

L’intégralité du script est disponible ci-dessous et fera partie d’une prochaine version de HelpNDoc.

procedure DoInsertChildrenContent(aList: THndTopicsInfoArray; anEditor: TObject);var
    nTopic:Integer;
  begin
    // Iterate through children
    for nTopic := 0 to High(aList) do
    begin
      // Insert content
      HndEditor.InsertTopicContent(anEditor, aList[nTopic].Id);
      // Handle children
      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
  // Get the currently selected topic
  aParentTopicId := HndUi.GetCurrentTopic();
  // Make sure that we have a valid selection
  if aParentTopicId = '' then
   Exit;  
  // We need a temporary editor 
  oEditor := HndEditor.CreateTemporaryEditor();
  try
    // Add the parent topic's content
    HndEditor.InsertTopicContent(oEditor, aParentTopicId);
    // Get a list of direct children
    aFirstLevelChildren := HndTopics.GetTopicDirectChildrenList(aParentTopicId);
    // Handle them
    DoInsertChildrenContent(aFirstLevelChildren, oEditor);
    // Set the final content to the initial topic
    HndEditor.SetAsTopicContent(oEditor, aParentTopicId);
    // Delete children topics
    for nTopic := 0 to High(aFirstLevelChildren) do
    begin
      HndTopics.DeleteTopic(aFirstLevelChildren[nTopic].Id); 
    end;
    // Current topic is not automatically updated: focus the project topic to change the selection
    HndUi.SetCurrentTopic(HndTopics.GetProjectTopic);
  finally
    oEditor.Free;
  end;
end.

Plus qu’un simple logiciel de création d’aide, HelpNDoc inclut divers outils avancés pour simplifier et accélérer le processus de rédaction de documentation, tels que son incroyable éditeur de script et les différentes API auxquelles il peut accéder. N’hésitez pas à télécharger sans tarder votre version gratuite de HelpNDoc pour découvrir et essayer les diverses méthodes API disponibles.

Voir aussi...

Comment Personnaliser la Position et la Taille Initiales des Fichiers d'Aide CHM

Créer des fichiers CHM (Compiled HTML Help) avec HelpNDoc est un jeu d’enfant, grâce à son interface conviviale et à ses puissantes fonctionnalités. Dans cet article, nous examinerons comment vous …

Lire la suite →

Équilibrer la sécurité et la facilité d'utilisation : Les meilleurs formats de documentation pour le partage interne

Le partage efficace et sécurisé de la documentation est essentiel sur le lieu de travail moderne. Que vous distribuiez des manuels internes, de la documentation sur des projets ou des directives …

Lire la suite →

L'arme secrète des rédacteurs techniques : les avantages uniques de l'analyseur de caractères de HelpNDoc

HelpNDoc est une solution de choix pour les professionnels qui cherchent à créer une documentation de haute qualité, attrayante et conviviale. Cependant, ce n’est pas seulement son interface …

Lire la suite →

Obtenir le meilleur de HelpNDoc : Comment la fonctionnalité "Conserver les fichiers temporaires" peut-elle aider les rédacteurs techniques ?

Lorsque l’on travaille sur de la documentation technique, chaque outil et chaque fonctionnalité à notre disposition peut faire une grande différence en termes de productivité et d’efficacité. L’une de …

Lire la suite →