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!
See also...
Mastering Content Updates with HelpNDoc's Search and Replace Tools for Technical Writers
Are you tired of the constant struggle to keep documentation consistent, up-to-date, and error-free? For technical writers and content authors, managing these challenges can be a daunting task. …
Read More →
Transform Your Classroom with HelpNDoc: The Ultimate Back-to-School Tool for Teachers and Students
As the back-to-school season approaches, educators and students are on the lookout for tools that can simplify content creation, improve collaboration, and enhance the overall learning experience. One …
Read More →
How to Customize the Initial Position and Size of CHM Help Files
Creating CHM (Compiled HTML Help) files with HelpNDoc is a breeze, thanks to its user-friendly interface and powerful features. In this article we’ll look into the specifics of how you can set the …
Read More →
Balancing Security and Usability: Best Documentation Formats for Internal Sharing
Sharing documentation effectively and securely is critical in the modern workplace. Whether you’re distributing internal manuals, project documentation, or company policies, the HelpNDoc help …
Read More →