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.

Fusion de chapitres dans 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

Catégories: articles
Tags: script trucs et astuces