Context-sensitive help in FM 2017 - map file and code

[FM_Sockies]

My company has just updated to Framemaker 2017 in order to generate HTML5-based CSH. This is the first time we are trying to implement context-sensitive help for our software.

Our developers have taken a look at the HTML files I generated ("published") with Framemaker and say they cannot create a link to the markers because they are just listed as "CSH <number>" in the code. This number changes depending on the actual number of CSH markers before in the document.

The infamous map file contains the Map ID and the Map number. But neither of them appear in the generated HTML file. How are the developers supposed to link my markers to the application when the HTML file does not contain any unique information about them?

Can you explain in more detail what the map number does? Are we missing anything? Why do I use a unique Map ID in my markers when it does not appear anywhere in the HTML file? Why are there a Map ID, Map number AND this CSH number in the code?

Thank you for your help.

Best regards,

V.

[Stefan-Gentz]

There is currently another thread on CSH with FM running. Have a look: Context-sensitive help in FrameMaker

[FM_Sockies]

Yes, but that thread is about CSH in general.

I am specifically asking about the application side - I would like to know which ID/number is the right "target" for our developers to call the help. As I pointed out in the original message, there are three different kinds of info: The map ID, the map number and the number in the code (see screenshot above).

[Stefan-Gentz]

The system is like this:

1. Create your content in FrameMaker.
2. Wherever you want to create a context sensitive help "jump in" point in the document, you place your cursor there.
3. Open > Insert > Publish Marker > Apply CSH Marker.
4. The "Apply CSH Marker" dialog opens. Insert the "map ID". This can be anything you want that will help you to identify the marker later more easy in your document. E.g. if you have a section "Installation", you might want to call it "CSH_installation". Click "OK".
   NOTE 1: Make sure the marker name does not contain spaces or one of the following characters: ~!@#$%^&*()+-={}|[]\\:\";'<>?,./
   NOTE 2: Make sure the marker name starts with an uppercase letter (e.g. "Installation", not "installation"). Best practice is to add a prefix like I did here with "CSH_"
   
5. Now a "TopicAlias" marker is created.
   Note: You can see a list of all markers in a document in the markers pod (> View > Pods > Markers).
6. Now create a simple *.h text file (make sure it's UTF-8 encoded) and give it the same name like your FrameMaker document (or book, if you want to have one file for the whole book). E.g. if your book name is "User-Guide.book" name it "User-Guide.h".
7. Place this file in the same folder as your FrameMaker book file.
8. In this *.h file you can now create the mapping following this pattern:
   #define <map ID> <map number>
<map ID> is the text that you have inserted into the CSH marker in your FM document.
   <map number> is the ID that you agree on with your developer. It must be unique! They can use this ID in their software.

Now publish the help.

NOTE 1: You can also add and edit CSH markers via > Insert > Makers. Use the marker type "TopicAlias", which is the marker type that is added when going through > Insert > Publish Markers > Apply CSH Marker.

NOTE 2: You can also manage all markers with > View > Pods > Markers. Double-clicking in an entry "jumps" to the corresponding marker.

[DieterGust · Accepted solution]

Well Stefan,

for HTML5 your answer might be still quite irritating:

HTML5 CSH users want to know  where they can find the mapping between MAP-IDs (mapids) and the URLs, which is not shown in any .h file.

If the FM customer gets a list of mapids from the developers the FM customer creates TopicAlias Markers and inserts the corresponding mapid as the content of the marker as you descibed.

FrameMaker creates the javascript csh.js which represents the mapping between the Map IDs and the relative URL to the HTML topics starting from the location of index.html.

The file csh.js is located in the output folder within the the sub-folder whxdata .

The URL to a topic will be a combination of a fix starting point which is the location of the the index.html of the generated HTML files, combined with the individual relative path to the topic.

Example:

topicurl=\"book/chapter2/Description-19.htm#CSH_25\" /><item mapid=\"IFU_IFUMAP_VENTILATION_SETTINGS_VC_SIMV\" mapnum=\"2\"

Therefore on the developer part they must know this URL creation method only. The "mapid" is defiend by the developers anyway and there seems be no need for a .h file

Am I right?

Dieter

[DieterGust]

In addition I would like to say: the complete URL a software developer must know for creating context sensitive HTML5 help is like this:

output-path>/index.html?rhcsh=1&rhmapid=<mapid>

<mapid> = content of corresponding TopicAlias Marker.

[Hezy A]

I found this post when looking for information about making CSH from HTML 5.

1. Do the developers need to give me map IDs or not?

2. What do they have to do to call the help?

3. Can tool tips be integrated in any way from the HTML 5 help created?  Ideas about how to do this?

[snevhead]

OK, but here I am with a well-established book file that was already successfully used to publish context-sensitive help for our previous release, and now it is no longer generating or reading the .h file.

Facts:

* my FM documents contain TopicAlias markers

* in the same directory as my FM book file there is a .h file called <my_book_file_name>.h

* this .h file contains definitions of mapIDs with unique numbers

* when I generate HTML5 output (even if I do it to a "clean" folder, so not overwriting old output), no .h file is generated.

* the csh.js file in my HTML5 output is empty

what am I missing?

please help!

[Dino-Software Writer]

I have a large FrameMaker book (V2020) with topic alias markers for CSH. I can use Publisher to create HTML5 Help.

But, and this is a sort of a game changer, I cannot get Publisher to use the .h file I created for the map IDs. I used the book.fm name as the prefix to the .h file and added it the FM Source folder.

Publisher creates HTML topics with CSH markers that do not follow the map numbers I have created. Instead, it generates its own map ID with sequential numbering.

Any thoughts? I am running out of hairs to pull out.

[Matt-Tech Comm Tools]

I agree with you, that it would be great to see the original text from the TopicAlias marker.

I posted a feature request to also include that info as an addtional attribute in the output. You can vote for it here:

Tracker