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
When a feature is not available in HelpNDoc, simply use the script editor and leverage its scripting API to build it yourself.
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 below 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;
var
// 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.
See also...
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 →Tech Writers' Secret Weapon: The Unique Advantages of Using HelpNDoc's Characters Analyzer
HelpNDoc has been a go-to solution for professionals seeking to create high-quality, engaging, and user-friendly documentation. However, it’s not just its user-friendly interface or its versatile …
Read More →