RH7: Map ID and Frame Topic-Splitting

[______3]

Greetings. Hope someone could help with the following:

I've created a very simple Frame file with two 'Heading2' paragraphs and a handful of other paragraphs types to describe contents.

For illustration purposes, let's say the Map file I have received form my developer has exactly two entries:
HIDD_APP_PREF_FIRST_DIALOG 0x200E8
HIDD_APP_PREF_SECOND_DIALOG 0x200E9

At the beginning of each paragraph I have inserted a custom marker with the name 'HelpMarker'.

(Question 1) What is the exact text that should go in each marker text box?

When I add my Frame file by reference, I specify 'HelpMarker' in the 'Define Context-Sensitive Help Marker' text box.

In the 'Style Settings' dialog...
-- I specify 'H2' as the 'User-Defined HTML Tag'
-- I check 'Heading 2' for pagination settings and click 'Finish'.

Once the Frame file has been processed I have only one topic. I would expect to have two.

(Question 2) What should be done differently to have one topic per 'Heading 2' paragraph type in my original Frame document/
When done

[JainVivek]

You may want to check out this blog post -
http://blogs.adobe.com/techcomm/2007/10/generating_context_sensitive_h_1.html. It says "A unique ID should be specified as the marker text at the time of applying this marker. Since this marker text would be used as the marker ID, the marker text should contain only alphanumeric and ‘_’ (underscore) character as shown in the figure below. The custom marker applied is ‘ExpBank’ and the FrameMaker ID for this paragraph is specified as ‘Marker1_Authorised_Persons’. "

For your second question, please ignore autonumbering for Heading2 and check if you are getting two topics or one.

regards
Vivek Jain

[______3]

Vivek,

Thank you for your response. I have seen the page. Sorry to trouble you but I am missing something basic.
Please see my original post above. I am interested in understanding exactly how to use the hex values that my developer has provided me in the .hm file I received from him.

I understand that in the marker text can be anything as long as it is unique.
I don't understand the following:

(a) Does the marker 'automatically' map the topic if the string it contains forms a match with an entry in the .hm file provided by the developer?

OR

(b) Must I manually match the hypertext marker with a topic using the 'Edit Map IDs Dialog'?

This second approach is the 'traditional' way of accomplishing this task that I am familiar with, but a demo I saw suggested that (a) was another possible approach.

Additionally, if (b) is the correct approach, then I have the following questions:

After adding a FrameMaker file by reference, the right panel in the 'Edit Map IDs' dialog is populated with a large number of entries; a larger number than I have of either Heading2 topics or of 'HelpMarker' markers.

Could you please explain each class of entry that I see here and how they are to be used in this context? The help system does not provide any guidance on these items.

For example I am seeing:

<filename>........................(this one appears twice; I am not really sure why it appears here at all.)

<filename>#CSH_1........(There are a bunch of these entries. From your blog entry I gather that these are what I am supposed to manually link to but there a many of them. If these are what I am supposed to manually link to, then how can I tell which one to use in any given instance as they are simply numbered and do not provide any idea of the text with which they are associated? It'd be very difficult to accurately create links this way; I hope I am wrong.)

<filename>#HTTEXT_TEXT_TEXT.......What are these and how are they to be used in this dialog?

<filename>#XREFTEXT_TEXT_TEXT.......What are these and how are they to be used in this dialog?

Like I said, I think I am close, but am missing something pretty basic -- so I look forward to hearing from you.

Thank You.

[Mayank_Agrawal]

First the answer to your following question
(b) Must I manually match the hypertext marker with a topic using the 'Edit Map IDs Dialog'?

Yes, you are correct in the understanding that "this is the traditional way of accomplishing the required task". So, this is one possible way but this can be done in a better way using FrameMaker integration feature.
It provides a different automated flow for creating Context Sesitive Help map IDs which is discussed below.

So coming to your another question

(a) Does the marker 'automatically' map the topic if the string it contains forms a match with an entry in the .hm file provided by the developer?

The answer to this question is "No. Although it works automatically but not in this manner."

There is a little difference in the flow that RoboHelp provides and the approach that your developer and help author are expecting.

According to my understanding here is your developer and help author's approach. Please correct me if my understanding is not right.
1. Developer uses Map IDs in his application.
2. He puts all the Map IDs along with their values in a .hm file.
3. That .hm file is provided to the help author.
4. Help author is suppossed to make use of those Map IDs present in the .hm file in the Context Sensitive Help he develops.
5. Help author inserts those Map IDs in the marker text in FrameMaker document(s) and expects RoboHelp to make use of the same .hm file as provided by the developer for mapping.

Here is the flow in RoboHelp.
1. Help Author inserts his own Map IDs as marker text in the FrameMaker document. (e.g. HIDD_APP_PREF_FIRST_DIALOG)
2. Help Author mentions the name of the marker in RoboHelp during Add/Import of FrameMaker document.
3. RoboHelp reads the marker, marker text and the document content and generates Context Sensitive Help Map IDs. It also generates a .h (equivalent to .hm) file.
4. This .h file is provided by the help author to the developer to be used in his application.

As we can see in one approach .h file is generated first and in the second flow .h file is generated at the end.

As of now, one possible way is to use the RoboHelp's approach and ask the developer to use RoboHelp generated map ID file.
Another possible way is
1. Create a copy of the .hm file provided by the developer and convert it to the following format

#define HIDD_APP_PREF_FIRST_DIALOG 0x200E8
#define HIDD_APP_PREF_SECOND_DIALOG 0x200E9
2. Close the RoboHelp project.
3. Rename the above copy of file with the RoboHelp's CSH mapping file(BSSCDefault.h by default). And replace Robohelp's mapping file with this copy.
4. Open the project and you will find the map ids as provided by the developer.

And answer to your following query

Could you please explain each class of entry that I see here and how they are to be used in this context?

Robohelp's Edit Map IDs functionality is a RoboHelp's generic functionaliity and is not specific to FrameMaker integration feature.
A help author using FrameMaker integration feature need not open this dialog ever if he uses the RoboHelp's approach as described above.
However, for other users this feature provides the funcionality of creating Context Sensitive Help for any topic or bookmark present in the project.
Since, topics and bookmarks generated during a FrameMaker document Add/Import are no different from the generic topics and bookmarks in RoboHelp, they are also listed and can be mapped from the dialog.


Mayank
RoboHelp Team

[______3]

Mayank,

Thank you for your detailed reply. Now I see the core issue. The primary assumption in RoboHelp is that the developer will receive Help IDs from the help author. While I have never known that to be the case in development, I suppose an organization could function that way.

That said, in my workflow, I receive the map file from the developer... I now understand replacing the 'BSSCDefault.h' file; and never opening the 'Map IDs Dialog'... (I certainly won't miss it!) Great!!!

One last and very important follow up question, so let's assume I have done all mentioned above.
Let's also say I want to map a topic to the following entry in the .hm file:

#define HIDD_APP_PREF_FIRST_DIALOG 0x200E8

What exactly should I put in FrameMaker's marker text dialog?
(1) HIDD_APP_PREF_FIRST_DIALOG 0x200E8 ?
(2) HIDD_APP_PREF_FIRST_DIALOG ?
(3) 0x200E8 ?
(4) The decimal equivalent.
(5) Something else.

Once this is clear I think I will be off and running!

PS: Your response was great, for the sake of others, please make sure that these two very different approaches are clearly documented in the help system.

#define HIDD_APP_PREF_FIRST_DIALOG 0x200E8

[Mayank_Agrawal]

The Map ID, i.e., HIDD_APP_PREF_FIRST_DIALOG in your case should be put in the FrameMaker's marker text dialog.
The file 'BSSCDefault.h' should be replaced only when you are done with FrameMaker document Add/Import to RoboHelp's project.

[______3]

Mayank,

Fantastic! Thanks again.

Your last statement begs another question:

"The file 'BSSCDefault.h' should be replaced only when you are done with FrameMaker document Add/Import to RoboHelp's project."

Help me understand why this is the case. Ongoing development is an ad-hoc process whereby either the Map ID (.hm) file may be updated first or the help topic may be created first. Additionally I'd like to go iteratively through my project 'FM file by FM file' to unit test each section and ensure its links are correct. Your statement suggests I must add all files to the project before updating BSSCDefault.h; this approach seems problematic to most current engineering workflows. What 'breaks' or needs to be undone if I do not follow this approach?

[______3]

Mayank, you wrote:

"The Map ID, i.e., HIDD_APP_PREF_FIRST_DIALOG in your case should be put in the FrameMaker's marker text dialog.
The file 'BSSCDefault.h' should be replaced only when you are done with FrameMaker document Add/Import to RoboHelp's project."

I tried this approach and it did not work.

Only when I then went into the Map IDs dialog and manually mapped the IDs did the links to the help system work form the application. Could you please re-read your response and advise... I'd very much like to follow the work flow you have outlined, but I fear something is still missing.

Would it be possible to send you my small, representative project?

[Mayank_Agrawal]

Yes, it is a good idea if we can have a look at your sample project and suggest the workflow accordingly.
Please provide us the following
# Sample RoboHelp Project
# Sample .hm file
# Sample FrameMaker files added to the project

You can mail a zip file to me at magrawal AT adobe DOT COM
A zip file may be blocked by the mail server. So please change the extension of your zip file to some unknown extension(say .abc or .adobe)
It will be better if you could upload your samples at some location and provide me the download link.

Mayank
RoboHelp Team

[JainVivek]

This is addressed in the RoboHelp patch 7.0.1.