Batch rename all the topics in a project

Are you missing a feature? Request it's implementation here.
293799
Posts: 5
Joined: Thu Apr 16, 2020 4:42 am

Batch rename all the topics in a project

Post by 293799 » Sun Apr 26, 2020 10:25 pm

It would be nice if we can rename (refactor) all the topics in a project to match their titles.

Currently we can change the topic IDs to match their file name, but I think a more useful feature would be to change the file names to match their title.

Radu
Posts: 6981
Joined: Fri Jul 09, 2004 5:18 pm

Re: Batch rename all the topics in a project

Post by Radu » Mon Apr 27, 2020 7:22 am

Hi,

Sorry but we do not have such a feature, I added an improvement idea based on your suggestion to our issues list.
For now you will probably need a custom script to perform the renames.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

kirkilj
Posts: 101
Joined: Fri May 14, 2010 12:14 am

Re: Batch rename all the topics in a project

Post by kirkilj » Fri May 15, 2020 2:26 am

I had to write a script to do this very thing a few weeks ago to deal with thousands of numeric filenames exported out of a CMS. I hacked something together using a combination of Bash shell scripts and the xmlstarlet command line tool to grab the title element value of each such file. It extracted the title text with xmlstarlet and then ran through a few stages of regex substitutions to produce a valid filename. As I recall, it had to do the following to honor our file naming conventions:
  • trim any leading and trailing spaces
  • extract just the text portion, including that of any child elements within the title element, such as <filepath>, <cmd>, etc.
  • dereference any nested keyref'd elements to retrieve the referenced text
  • collapse 2 or more spaces to one
  • replace all remaining spaces and punctuation with underscores
  • replace all punctuation characters with underscores
  • replace all instances of camelCased strings with intervening underscores
  • lowercase the entire title
  • leave the filename unchanged if there either was no title element or if there was one and it was empty
Once the file was renamed, the script had to change any references to the renamed file from anywhere in the documentation set as well.

Oxygen does a similar thing in the new file dialog when you type in a title and it creates the equivalent filename as you type.

Radu
Posts: 6981
Joined: Fri Jul 09, 2004 5:18 pm

Re: Batch rename all the topics in a project

Post by Radu » Fri May 15, 2020 7:56 am

Hi John,

Thanks for the details. If we were to add such a feature to Oxygen we'll probably need to be very flexible in allowing the end users to choose the rules which would convert the existing file name in the new file name given a certain title. Maybe the rename tool could have some kind of configurable Javascript function which Oxygen would call with the current file name and the title of the topic and the function could return the new file name.
Because there are various use cases which would need to be covered, some people want to just add or remove a certain prefix from all files, others want to use the title.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

kirkilj
Posts: 101
Joined: Fri May 14, 2010 12:14 am

Re: Batch rename all the topics in a project

Post by kirkilj » Fri May 15, 2020 10:05 pm

Besides constructing filenames based on a file's <title> element, we also had issues where many image filenames had both a numeric portion and a human-readable portion, like "XHAU-D1847-LG634-alert_configuration_diagram.png", the script had to strip the numeric portion based on a regex to parse the name and determine what to keep.

So, yes there are many types of rename use cases to consider.

Btw, is Oxygen's file dependency list in a format our scripts could use? I had to search through every other file in the docset with a recursive grep to find the original references and replace them, which was not very performant, but still much better than asking a writer to do this manually. The average time for a rename and re-reference operation on a single file was approximately 5 seconds.

Radu
Posts: 6981
Joined: Fri Jul 09, 2004 5:18 pm

Re: Batch rename all the topics in a project

Post by Radu » Mon May 18, 2020 7:50 am

Hi John,

We do not expose our dependencies graph via API so you cannot ask Oxygen what resources refer to a specific file, so that you could only change those.
About this remark:
The average time for a rename and re-reference operation on a single file was approximately 5 seconds.
You would probably need to try and do this in one step, create a mapping between all the old and the new file names, rename the files on disk and then using this mapping go once through the entire user's manual and change all references.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Post Reply