Inserting Code Comments into Legacy Topics

[kristil]

We have created some topic templates (Concept, Reference, and Task), and we're about to start updating our legacy topics to match these templates, plus of course we will be writing all future topics using these templates.

There are two things we'd like to be able to do with these three types of topics:
Find all the topics of one type - useful for making a change that can't be done by find-and-replace, or for taking inventories
More importantly, make batch edits - find-and-replace

We are thinking that this can be done if we can get a code comment for each type inserted into the topics. That way we can search for the comments with FnR. It's easy for new topics--we'll just add the comments to the templates, so each new topic that is created with the template will automatically have the comment.

The challenge is getting the comment into legacy topics. Ideally, we'd like to insert it two places: right after the opening body tag and right before the closing body tag. We want to insert a different comment for each topic type, so a simple search for all body tags will not work. Each topic type does have some unique or dominant style that we can search for, but not necessarily near the body tags. I'm up for trying to write a script, if need be, but I could use a point in the right direction.

I've tried to think of a way this could be done in the Flare GUI, but I don't see a way. I thought maybe using the TOC to somehow get a bit of code inserted that we can then search for, since it's relatively quick to identify the topic types there? But so far, no go. Since one of our projects can have up to 2000 topics, we would certainly think twice before opening up each topic to insert the comments one-by-one.

Thanks!

[LTinker68]

Sounds like you want to categorize your topics. Easiest way would just be to create three folders with those three titles and put the concept-type topics into the Concept folder, the reference-type topics into the Reference folder, and so on. The TOC is where you set up the order in which the topics appear in the output, so the folder structure can vary greatly from the TOC structure.

If you want to keep your topics organized more by book/chapter, then I think the easiest way would be to create three new conditional tag types called Concept, Reference, and Task. You then apply the appropriate conditional tag to each topic. That will result in the color block next to the topic in the Content Explorer showing that color. You can then go to View > File List, and sort the list by the condition type (sort using the Conditions column, not the untitled column containing the color block). So initially it takes some time because you have to apply a condition to each topic, but from that point on you just add the condition when you create the topic. In fact, if you have an actual template file with the conditional tag specified or just copy an existing topic to create a new topic, then the template or original topic will pass its conditional tag to the new topic.

[kristil]

Yes, one thing we'd definitely like to do is categorize the topics. I think the second option could work for us in that regard.

I've been contemplating your response for a few days because I got pretty attached to the idea of code comments so that we could find them and insert something automatically within the body of the topic. But comments are not necessarily that useful, unless we happen to want to insert something at that place in the topic where the comment is located. I don't have a clear idea of what we may want to insert, but I do know we want to categorize the topics, so your suggestion to use conditions could be what we need.

Thanks!

[GregStenhouse]

Have you thought about using topic styles? That carries a number of benefits I can see:
1) You can use different master pages to customise the look of backgrounds or breadcrumbs etc depending on the topic type, or add code comments at the master page level rather than every topic.
2) In View>File List you can sort topics based on topic style, so can easily identify them.
3) If any bulk search and replace is needed, you can search for "class="task"" etc
4) It's consistent with how Flare implements DITA, and there may be other benefits for Relationship Tables

Your problem still remains though how to catergorise ~2000 topics. Is there anything unique in the filename that would help? For example, do task topics using -ing words, do concept topics begin with "About" etc?

Cheers
Greg

[kristil]

I wasn't aware of the topic styles! Now we have a couple of options. I think that, combined with the ability to sort the files by their various properties in the File List option, this will help ease the pain of categorizing topics.

It would be nice to have a check box to apply the topic styles according to the relationship table.
Also to apply a find-and-replace to only some of the topics. I submitted feature requests.

Thanks, you guys.

[TheGreatAndPowerfulOz]

Have you thought about using topic styles?

Excellent suggestion, Greg! I had read (briefly) about topic styles before, but never got to the bottom of Flare's Help topic which mentions how they allow you to apply different Master Pages to a set of topics. I had never thought much about them since that time (I just figured they related to DITA, which we don't deal with in my shop). This is actually just what I was searching for!

Regards,

[LTinker68]

... but never got to the bottom of Flare's Help topic which mentions how they allow you to apply different Master Pages to a set of topics.

See this KB article --> http://kb.madcapsoftware.com/default_CSH.htm#FMP1001F

[TheGreatAndPowerfulOz]

See this KB article

Thanks, Lisa. I found the corresponding Help topic in Flare once I read Greg's post. The KB articles were helpful, as well!

[rob hollinger]

FYI -
In V6, there is a way you can tag topics with Custom Tags and then generate a report listing topics that have assigned tags.
In the Project Organizer -> Advanced folder, you can add your own tag sets.
In the properties of each topic, you can assign these tags.

See the Help topic "About File Tagging".