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!
- Produce a Rich Text Format (RTF) file from your documentation project using the HelpNDoc help authoring tool
- Context sensitive HTML help and URL aliases for help topics in your HTML documentation web-sites
- 3 ways to speed-up hyperlink creation in your help file, user manual or eBook
- How to define robots.txt and Robots meta tags in your HTML documentation ?
- How to manage HelpNDoc's panels: move and dock them where you want