Using HelpNDoc scripting capabilities to automatically reset all help context numbers

HelpNDoc includes a very powerful script editor with access to multiple API methods which provides a way to automate almost all parts of your documentation creation and maintenance process. We've already seen how to use HelpNDoc's scripting capabilities to automate help and documentation creation, update the path of your external media elements when they are moved and export Help IDs and Help Context numbers for your developers.
Let's now see how we can create a handy script to automatically reset help context numbers for all topics in the documentation project.

What are Help Context numbers ?

Topic identifiers (Help Id and Help Context numbers) can be used to access a specific topic from a third party application: HelpNDoc ensures that each topic has a unique Help Id and Help Context number attached.

HelpNDoc automatically creates two unique identifiers for every topic that you add to your project:

  • An alpha-numeric Help Id which is set to a filtered version of the topic caption ;
  • A numeric Help Context which is set to the lowest unique positive integer available in the project.

When the first topic is created, its Help Context number is set to "0". The second one is set to "1", the third one is set to "2" and so on. When a topic is deleted, let's say the second one, its Help Context number is available for the next created topic: when the fourth topic is created, its Help Context number will be set to "1". Over time, Help Context numbers can be confusing as they are not always incremented from one topic to the next one.
Thankfully, we can create a script to automatically reset the Help Context number of every topic to make sure the first topic starts at "0" and next topics' Help Context numbers are incremented accordingly.

HelpNDoc script to reset Help Context numbers

Instead of manually updating every single topic's Help Context number by hand, let's leverage HelpNDoc's scripting capabilities to automate this repetitive and error-prone task

As HelpNDoc ensures that Help Context numbers are unique, we cannot iterate over each topic and set their Help Context number starting at 0 and up: other topics might already use those numbers which can break the clean iteration we are looking for. That's why we make a first pass to set high context numbers for each topic. The second pass will set the final values. Here is the full script.

Warning: This action can't be undone. If you or your team mates are relying on Help Context numbers to access specific topics of your help file, you shouldn't update those numbers. This action should only be done when you design your help document and want to have a consistent set of Help Context numbers.

const
  // Temporary context number used. MaxInt is the maximum possible number.
  TEMP_MAX = MaxInt div 2;

  // Update context number for all topics starting with "StartingAtNb"
  procedure UpdateContextNumbers(const StartingAtNb: Integer);
  var
    aTopicId: string;
    aCurrentNb: Integer;
  begin
    // Init
    aCurrentNb := StartingAtNb;
    // Get first topic
    aTopicId := HndTopics.GetTopicFirst();
    // Iterate over topics
    while aTopicId <> '' do
    begin
      // Set the context number for the current topic
      HndTopics.SetTopicHelpContext(aTopicId, aCurrentNb);
      // Set next number
      Inc(aCurrentNb);
      // Move to next topic
      aTopicId := HndTopics.GetTopicNext(aTopicId);
    end;
  end;

begin
  // Make sure all topics have unique large context numbers
  UpdateContextNumbers(TEMP_MAX);
  // Update all topics with context numbers starting at 0
  UpdateContextNumbers(0);
end.

Copy / Paste this script in HelpNDoc's script editor, hit "Run script" and voilà! Your topics' Help Context number are automatically set up incrementally.

Once again, we've seen how powerful and fast HelpNDoc's scripting engine can be: by automating this lengthy and error-prone process, we were able to quickly and reliably clean-up our project's Help Context numbers.
And HelpNDoc's API is not restricted to topics and their help identifiers: you can use it to automate various parts of your documentation creation process. So, if you haven't already done so, download your free Personal Edition of HelpNDoc now to start experimenting with its amazing capabilities and make sure you check the various textual and video step-by-step guides to quickly learn all aspects of HelpNDoc!