Changing CSH strategies

[argus08-7xWR1K]

My client has finally decided that we will upgrade from Tech Comm Suite 1.5 to the latest version, just not right now (the decision alone is progress at least).

They also want to switch to using numeric map IDs for CSH (instead calling the path/filename which is linked externally to the application form name), which is how they originally wanted to call help. Currently I have a separate CSH paragraph style that lists the form name as well as xrefs to create the path and html.filename. There are often multiple such paragraphs within a topic, because multiple forms call the same topic. I generate a list of these paragraphs, do a little search/replace magic, and hand off a "mapping file.txt" to the developer. I don't remember how or why we came up with this as the best solution, but it's worked for several years now, so we've stuck with it.

I have read many forum posts to understand the correct process for using map IDs with TCS, but still have some questions.

1. I understand (largely thanks to many of Jeff Coatsworth's posts!) that I should create a FM marker (instead of TopicAlias) and reference this in the RH project import settings. I think I should create one marker for each form linked to the topic, and use the form name as the marker text, does that sound right?
2. When I import the project, RH will create numeric map IDs for each of these markers; I can provide this .h file to the developer. Presumably it will show the original form name and map ID# so the dev knows where to plug in the #s?
3. Are these Map IDs then static from one version of the project to the next? If they change with each new FM>RH conversion, does the developer need to update something in each form, or does he just include the .h file (i.e. is it adding work to him if the map IDs change each time)? Is it better to have them provide a list of map IDs, then I use those as the marker text in FM? As a vendor, I'm removed from the developers and don't fully understand what they do to call the help files we send to our clients!
4. One thing that may have initially spawned the current process is the need to identify the path since the FM>RH conversion creates a folder for each FM file in the book. Do I still have to somehow identify the path, or will the Map IDs magically find the topic? This is something I haven't seen mentioned anywhere, so hopefully it's not a totally stupid question!
5. Since I'm stuck using TCS 1.5 for now, is it worth implementing these changes now, or is it better to wait until we upgrade to TCS 5 (or whatever is current when they finally say Go)? If it matters to this question, after converting from FM8>RH7, I then open the project in RH10 so that the output works in Chrome.

All guidance is greatly appreciated,

Laurie

[Willam van Weelden]

I'm not too big on FM->RH integration so I'm hoping Jeff will jump in.

Before I start, a little clarification on terms used: A topic id is an alphanumeric string to identify a topic. A map number is a numeric id. What you refer to as map ID is what RoboHelp calls a map number.

1. I'm not sure on this point, so I'll leave that to Jeff. One global remark: If you use the screen code as marker text (will be transformed to topic id), you will make it easier for your developers to call the help. You can then use that name to call the help instead of a numeric id (map number). (But that requires changes in the application as well.)
2. Yes. The map file holds the topic id (which is than the same as the form name) and the map number generated by RoboHelp. Developers can use either map numbers or the topic id (provided you generate WebHelp/HTML5. If you use CHM, the developers must use the numeric ID.)
3. Map numbers are regenerated every time you import the content. Depending on how the developers implemented the CSH call, they may need to change a resource that transforms form names to numbers. I hope they don't manually add those numeric id's in every form.
4. You don't have to specify the path. That is taken care of in RoboHelp. If you want to know the path to the topics, the file <projectname>.ali holds the link between topic path and topic id.
5. If FM allows you to specify markers you can start right away. I would suggest trying it out in a copy of the project to get a feel for it. You can first create an RH7 project and upgrade that to RH11. But you can also convert the FM files directly into the latest version of RoboHelp. I would advise updating the FM8 files first and when that works upgrade those files to the latest version. Then import that into RoboHelp.

You may also be interested in: https://www.wvanweelden.eu/article-category/context-sensitivity

Kind regards,

Willam

[argus08-7xWR1K]

Thanks Willam. Your response (and your site) were very helpful. I also learned a lot from a recent Adobe webinar I found ("GUEST BLOG: Setting the Help Hooks: Context Sensitive Help Using RoboHelp « TechComm Central by Adob...).

I am still unclear on some of the particulars of creating the MapIDs in Framemaker, and hope Jeff jumps in. Here's what I did:

1. I created a new marker type in FM (CSH) and created two markers in one chapter, just to test the process. These markers contain the form name from the app.
2. I linked the FM book into RH, defining the CSH marker to be used.
3. I've read conflicting info whether this will update the default .h file or if I have to create a new blank one. So I just opened the default one, and it shows one entry, which relates to the proper chapter name, but does not match either of the markers' text (Topic IDs).

I've read recommendations that if you're just using RH to process the files (i.e. using FM as the main authoring tool), then you should enter the CSH markers in FM and link to the FM files in RH, but if you are doing any post-processing in RH, you should import the FM files and create the .h file in RH. Sounds like Jeff creates the markers in FM but imports the FM files. So I started over and tried it that way.

After importing the book into RH, I looked at the default .h file again. This time there was still only one entry, but it was to the cover chapter from the FM book.

This thread (Re: Context-Sensitive HELP!!!!!) says I still have to import the .h file before the Topic IDs will appear - I want to create a .h file, so what exactly am I importing? I've tried Force Update, I tried creating a new .h file and exporting that -- nothing is getting me the two Topic IDs that I created in FM.

I hope someone can help me to bridge FM8>RH7 and come up with map files that I can give the developer.

Thanks,

Laurie

[Jeff_Coatsworth]

Hi Laurie, I'll try to explain my process and show what I'm getting with some screenshots.

For this project I author in FM and import to RH currently using TCS4. I tried linking initially, but because I'm using the FM concept of a master book of books, RH seemed to choke on the linking process way back in TCS2, so I ditched that method and went the import route (supposedly it's improved, but I haven't had any time to test). I set up a CSH marker type in FM with the product's program name as the marker text. That program name comes across as the Map ID in RH (hopefully seen in these 2 screenshots):

and the end of that line that got cut off -

The FM content is busted up into topics using the Heading 1 and Heading 2 FM paragraph types and you'll notice that CSH bookmark (#CSH_124) gets generated and placed on the topic (see HTML view of this Cash Requirements Lists topic):

This all ends up producing a BSSCDefault.h file with a series of lines like this:

#define GJP86 1731

#define GJP10 1732

#define GJP23 1733
(that's a number sign, the word define the program name and the Map number that RH assigned in case that text gets mangled).

I take that .h file and use it as the source for the program to use to launch the CSH help when the user is on that program screen and presses F1. We're using the JavaScript method of invoking the help that will translate the program name and find that Map# to use.

[argus08-7xWR1K]

Thanks Jeff. The first screenshot was what I was expecting. Here's what I did and the results:

1. In FM8, created CSH marker type with form name as marker text. I created five markers in two chapters.
2. In RH7, created new Webhelp project, imported the FM book:
   • Import settings1: convert TOC/Index, defined the name of the marker type (CSH), apply conditional text expression
   • Import settings2: load style mapping file, break topics at H1/H2/H3 (markers are in H2 or H3 level)
3. When I look at the HTML view, I see the CSH bookmark (thanks for including that screenshot, that step was helpful):
   
4. But when I double-click to open the BSCCDefault.h file, this is what I see:
   
5. Am I missing a step to create/update the BSCCDefault.h file? Or is this a TCS1.5 issue?

Laurie

[Jeff_Coatsworth]

May be a bug - want me to have a look at your sample FM book?

[argus08-7xWR1K]

That would be great, thanks Jeff. I'll send it privately.

[Jeff_Coatsworth]

You may still have my e-mail on file – if not, PM-me

[argus08-7xWR1K]

On a whim, since I'm now importing rather than linking, I tried importing from FM8 directly into our standalone version of RH10, and I do get the Map IDs correctly that way. I need to figure out the mapping and topic breaks - is there anything I need to watch for doing it this way, without TCS? It seems too easy, i.e. why would anyone buy TCS if they can just import FM files directly into RH?

[Jeff_Coatsworth]

Pricing – cheaper to buy the suite than the individual programs

[argus08-7xWR1K]

Yeah, but are there any other TCS integration bits that would be missing that might be important?

For me, having FM8 and RH10 already, is there anything I need to do differently or watch for?

[Jeff_Coatsworth]

Only for the linking functionality

[argus08-7xWR1K · Accepted solution]

For posterity, here is the resolution we came to offline.

• There appears to be a bug in the TCS1.5 (FM8>RH7) process re map IDs.
• Since I have a standalone copy of RH10, I will skip the TCS/RH7 and just import the FM8 files directly into RH10. The map file is created correctly that way and I did not ever need the linking/synching feature anyway; I always created a new RH project.
• A map ID is erroneously created for the cover file, which also appears to be a bug but it's easy enough to delete that entry.

I think we'll be safe for a few years at least, until browsers outpace RH10. Maybe by then the client will be able and willing to change our doc strategy/delivery and we can upgrade to something more current.

So glad to be able to ditch RH7 and all the workarounds I had to juggle to get TCS1.5 to behave!

Now I just need to hope the developers can figure out how to work with the new map files and API!

MANY many thanks to Jeff Coatsworth for his time helping me to get to this point!

Laurie