Generate HTML Report for DITA Map Element Usage Metrics in FrameMaker
Thank you for your feedback on the survey shared along with the last post that we made around “How to run FrameMaker on Mac“. We have got ample responses that would help us take the decision going forward.
Today, I’m going to share with you an ExtendScript utility that would help the DITA Map authors generate a report that would contain the overall count of topics, task, concepts, links, xrefs or any other element used in the DITA Map. This report would be helpful if you want to find out the number of topics, cross references and images etc that are contained/referenced in a DITA project. The total number of DITA topics, for example, can help an author determine the current completion status of the project. It can also indicate whether appropriate number of topics and images are being used from a project management perspective. The frequency and the usage density of each element in the report can be gauged. Also if this script is used periodically(daily or weekly basis) the progress of the entire project can be tracked easily.
Download the zip resource and unzip it in the “<FrameMaker Installation Directory>\startup” folder.
Launch FrameMaker 10 again and you are “good to go”.
How it works:
Once utility scripts are configured, open a DITA Map you want to generate the report for.
The script adds a sub-menu to the DITA menu **“DITAMap Element Usage Report” **when a DITA Map is open in the RM View. Click the menu item.
The menu item that gets added to the FrameMaker DITA Menu
To avoid any misreporting in case of unsaved changes in the topics which might be already opened in FrameMaker, make sure you close all the topicrefs of the map. Or else all open references in the map will be closed.
The script first reads the element inclusion DITAElementStatConfig.ini that resides in %appdata%/FrameMaker/10 directory. If it is not present, say when used for the first time, the utility will create a new ini file with the default element inclusion list which includes-topic, task, concept, fm-xref, fm-linktext, image and table.
NOTE: If you want to add/remove any other elements as part of the report generation, you can modify the DITAElementStatConfig.ini in your user area.
DITA Map is then parsed as per the element hierarchy. The topicrefs and child DITA Maps referenced using maprefs would participate in the report generation.
A text log file “DITAElementStatisticsReport.log” also gets created in the %appdata% folder that records most execution steps of the utility. It might come handy when you would want to debug the script execution.
HTML report creation begins dumping details of individual topicrefs and an overall status for the entire map. The HTML report gets saved in the same folder where the DITAMap resides. The report gets opened automatically when the utility execution completes.
The final report contains two sections.
Snapshot of the DITAMap Element Usage Statistics Report
One contains the information on each individual topic component of the map and the other one at the end aggregates the information for the entire DITA Map. Initial view of the HTML report has all individual topic section in collapsed state and the overall summary is presented. You can choose to expand the individual topic section by clicking the “Expand/Collapse All” button on the report.
How to make the most of the script?
The script highlights the starting point to create a utility that would generate a report on the current status of the DITA documentation. You can use the script to address the DITA metrics specific to your TechPubs department. ExtendScript users can use the script to go a step further and extend it to-
- Report the count and list the elements in a DITA Map that have particular attributes set to some value.
- Generate a list of element exclusions that get filtered out using the Filter by Attribute(FBA) functionality in FrameMaker.
- Build up a logic to determine the number of unresolved xrefs/images in a DITA project.
- And many more possibilities.
Let me know if you find this utility to be beneficial. Would also look forward to hear suggestions on how you think this script could be made even more useful for any specific scenarios that you might use it for.
Lead Software Engineer, FrameMaker Team