HelpNDoc 6.0 added support for topic status, which greatly simplifies the maintenance of documentation projects for technical authors: topics can be tagged as being “Out of Date”, “In Progress”, “Needs Review”, “Complete” or any custom status you define. You might be tempted to leverage that feature to update an old project and change the status of all your topics to “Needs Review” to start reviewing them one by one. But individually updating every topic in a big project will be time consuming. Thankfully, HelpNDoc’s scripting support can update the status of the whole documentation project in a fraction of a second. Let’s see how this can be done.
Using HelpNDoc’s script editor
The script editor can be used to automate most parts of the documentation writing and maintenance process. Here is how to use the script editor in HelpNDoc:
- From the “Tools” ribbon tab, click “Script Editor”. This shows the “Script authoring and execution” window;
- Enter the content of your script in the code editor. Check the documentation for available API methods to learn what is available in your custom script;
- Use the “Build script” button (or SHIFT-F9 keyboard shortcut) to check that its syntax is correct;
- Use the “Run script” button (or F9 keyboard shortcut) to run the script;
Writing the script
The algorithm we need to develop to update every topic to a specific status is very simple: we first need to get the unique identifier of the status, we then iterate through all topics in the project, and we set the topic’s status to the correct identifier.
1. Get the identifier of the status
Before applying the status to every topic, we need to get its unique identifier. Fortunately, HelpNDoc’s API for the HndStatus object includes the
HndStatus.GetStatusByCaption() method which greatly simpifies this task. Here is a script showing how this can be done:
const // Name of the status STATUS_TO_LOOK_FOR = 'Needs Review'; var // ID of the status aStatusId: string; begin // Get the unique ID of the status aStatusId := HndStatus.GetStatusByCaption(STATUS_TO_LOOK_FOR); end;
2. Iterate through all topics
We now have retrieved the unique identifier of the status we’d like to apply to every topic. We can now iterate through each of them as follows:
var // ID of the current topic aTopicId: string; begin // Get the first topic aTopicId := HndTopics.GetTopicFirst(); // Loop through all topics while aTopicId <> '' do begin // ... Set the status of the topic here ... // Get next topic aTopicId := HndTopics.GetTopicNext(aTopicId); end; end.
3. Set the status of the topic
We can now simply use the correct HndTopics method to set this topic’s status:
// Set its status HndTopics.SetTopicStatusId(aTopicId, aStatusId);
The whole script
We now have all the pieces of code ready to write the full script topic status change throughout the documentation project. Let’s review the full script.
The script bellow will automatically change the status of all topics in the currently opened project to “Needs Review”. It can be customized if needed: simply change the value of the constant named
STATUS_TO_LOOK_FOR to set another status. One can also enhance that script to only apply the status to topics meeting a condition, such as having a specific parent, help id, current status… the possibilities are endless.
The full script can be pasted into HelpNDoc’s script editor and will be included in a future version of HelpNDoc:
const // Name of the status STATUS_TO_LOOK_FOR = 'Needs Review'; var // ID of the status aStatusId: string; // ID of the current topic aTopicId: string; begin // Get the unique ID of the status aStatusId := HndStatus.GetStatusByCaption(STATUS_TO_LOOK_FOR); // Get the first topic aTopicId := HndTopics.GetTopicFirst(); // Loop through all topics while aTopicId <> '' do begin // Set its status HndTopics.SetTopicStatusId(aTopicId, aStatusId); // Get next topic aTopicId := HndTopics.GetTopicNext(aTopicId); end; end.
- How to schedule automated user documentation generation ?
- How to locate and fix broken hyperlinks in your user manuals, eBooks and help files
- Create a new HTML template to customize your online documentation projects
- How to migrate a custom template when a new version of HelpNDoc is released
- Automatically merge multiple topics from your documentation into a single one using a script