Automatisches Zusammenführen mehrerer Themen Ihrer Dokumentation zu einem einzigen Thema mithilfe eines Skripts | HelpNDoc

Automatisches Zusammenführen mehrerer Themen Ihrer Dokumentation zu einem einzigen Thema mithilfe eines Skripts

Ein Hilfe-Entwicklungstool wie HelpNDoc ist gewöhnlich eine Software, mit der man Inhalte zur Erstellung von Dokumentationsdateien für Endbenutzer schreiben und gliedern kann. Wenn Revisionen erforderlich sind, müssen die Inhalte übersichtlich bleiben, sodass in der Regel etliche mühsame und fehleranfällige Aufgaben wie etwa Kopieren/Einfügen von Inhalten, Löschen von Inhalten und Verschieben und Zusammenführen von Themen im gesamten Projekt erforderlich sind. Glücklicherweise bietet HelpNDoc einen leistungsstarken Scripting-Prozessor, der eine automatische Erstellung, Pflege und Neugliederung von Dokumenten ermöglicht. Hier zeigen wir Ihnen, wie Sie HelpNDocs Scripting-Fähigkeiten zum Zusammenführen mehrerer untergeordneter Themen in ein übergeordnetes Thema nutzen können.

Anwendung von HelpNDocs Scripting-Fähigkeiten

HelpNDocs integrierter Skript-Editor kann zum Erstellen und Ausführen benutzerdefinierter Skripts zur Automatisierung verschiedener Aspekte von HelpNDoc verwendet werden.

Zusammenführen von Themen in HelpNDoc

Der Zweck dieses Skripts ist das Zusammenführen des Inhalts von untergeordneten Themen in ein übergeordnetes Thema. Dies bedeutet, dass das Skript folgendes tun muss:

  1. prüfen, ob ein Thema derzeit in HelpNDocs Inhaltsverzeichnis markiert ist; dies wird das übergeordnete Thema sein,
  2. einen temporären Editor erstellen, in den der Inhalt aller Themen abgelegt wird,
  3. den Inhalt des übergeordneten Themas in den temporären Editor überführen und eine Liste der untergeordneten Themen erstellen,
  4. alle untergeordneten Themen der Reihenfolge nach durchlaufen und die Inhalte in den temporären Editor überführen,
  5. den Inhalt des temporären Editors in das übergeordnete Thema überführen,
  6. alle untergeordneten Themen des übergeordneten Themas löschen.

Achtung: Da einige Scripting-Aktionen nicht reversibel sind, empfehlen wir Ihnen, Ihr HelpNDoc-Projekt vor dem Ausführen eines Skripts zu sichern. So vermeiden Sie Probleme im Fall eines Fehlers, der Sie dazu zwingt, zu einer früheren Version zurückzukehren.

1. Abrufen des übergeordneten Themas

Das aktuell in HelpNDocs Benutzeroberfläche markierte Thema ist das übergeordnete Thema. Achten Sie darauf, dass ein Thema markiert ist, und rufen Sie seine ID ab:

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

2. Erstellen eines temporären Editors

Der temporäre Editor ist ein Platzhalter für den Inhalt aller zusammengeführten Themen. So können Sie diesen Editor erstellen und freigeben:

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

3. Einfügen des Inhalts des übergeordneten Themas und Abrufen der untergeordneten Themen

Jetzt können Sie den Inhalt des übergeordneten Themas in den Themeneditor ablegen und eine Liste der direkt untergeordneten Themen erstellen, was bedeutet, dass nur die untergeordneten Themen der ersten Ebene in der Liste aufgeführt werden.

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

4. Rekursives Durchlaufen aller untergeordneten Themen und Hinzufügen ihrer Inhalte

Es kann eine rekursive Methode erstellt werden, mit der die untergeordneten Themen ("Kindthemen") und nachfolgend untergeordneten Themen ("Enkelthemen" etc.) in der richtigen Reihenfolge behandelt werden. Sie können diese Methode dann für die Liste der direkt untergeordneten Themen des übergeordneten Themas aufrufen:

// 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. Ersetzen des Inhalts des übergeordneten Themas durch den Inhalt des temporären Editors

Der zusammengeführte Inhalt ist jetzt fertig. Sie können den Inhalt des übergeordneten Themas jetzt ersetzen.

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

6. Löschen aller untergeordneten Themen

Die Inhalte der untergeordneten Themen wurden jetzt in dem übergeordneten Thema zusammengeführt. Da sie nicht mehr benötigt werden, können Sie nun alle untergeordneten Themen löschen.

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

Das vollständige Skript und Updates

Das vollständige Skript steht Ihnen unten zur Verfügung und wird Teil einer kommenden Version von HelpNDoc sein.

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;
  aFirstLevelChildren: THndTopicsInfoArray;
  aCurrentTopicId: string;
  oEditor: TObject;
  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.

HelpNDoc ist mehr als nur eine einfache Hilfe-Entwicklungssoftware: Es bietet verschiedene erweiterte Werkzeuge zum Vereinfachen und Beschleunigen der Dokumentationserstellung wie beispielsweise einen erstaunlichen Skript-Editor und Zugriff auf verschiedene APIs. Laden Sie sich Ihre kostenlose Version von HelpNDoc jetzt herunter, um es auszuprobieren und die verschiedenen verfügbaren API-Methoden kennenzulernen.