Capabilities and limitations of contextual help - and how do I set it up?

[johnvarvatsis]

Hi

As I understand it:

Contextual help enables us to link specific screens in the application to topics in our help systems, so when a user clicks the help button on a certain screen, the corresponding help file is displayed.

This is done by means of a "map file" which links the screen's unique ID to a specific topic.

So I'm guessing each screen in my company's application will have a unique "context id" and the programmers will know what this is and where to find it. Presumably the help file will be identified simply by its filename and path.

The Adobe documentation does not appear to go into much detail about the actual steps required. Is this because it varies depending on the programming language used to produce the application or because any developer worthy of the name will have no provlem working out how to do it?

When I open up a new map file in RH2017 i get the following view, which appears to be a bunch of empty folders echoing the hierarchy of my existing help system, but with no actual help topics. What do I do next?

I realise this may be a huge question and if nobody has the time to answer is there a resource or book / tutorial type thing I can refer to in order to find out more about setting up CSH?

[Jeff_Coatsworth]

That screenshot looks like you're producing old CHM help, not HTML5 Responsive help - with the HTML5 layout, you should see something like "Map Files" and "All Map Files" listed (and that's it).

You can also call CSH help by using URL strings to point at the topics - see Peter's site (grainge.org) and Willam's (https://www.helpessentials.com/2017/08/05/context-sensitivity-in-responsive-and-multiscreen-html5/ ) for some guidance.

[johnvarvatsis]

Not sure about this. Im definitely producing Responsive HTML 5 help. (Indigo) I have been for about a year.

Have I somehow managed to open up the wrong "Map file" panel? Is there some preliminary activity I should have completed or settings I should have made elsewhere?

[Peter Grainge]

I'm not sure why Jeff has concluded you are generating CHMs so I will let him respond to that.

Within the Context Sensitive Help folder, as well as seeing the folders in your project, you should see further down the H files which is where map IDs are created. You can either use the default or create your own and then give map ids to whichever topics will be called or to all topics.

Your developers then use the map ids by adding them with their code. Alternatively they may give you a list of their screens and tell you to set up the IDs they have set. You then apply that ID to topic that screen needs to call.

---

See www.grainge.org for free RoboHelp and Authoring information.

@petergrainge

[Jeff_Coatsworth]

Sorry, I was thrown off by the "What's This?" help folder - I thought that only applied to CHMs.

[Captiv8r]

Heya Jeff

I think if you open ANY project, you will note that RoboHelp will show you a "What's This?" section.

I miss that kind of help in Windows.

Cheers... Rick

[johnvarvatsis]

OK Chaps,

*Apologies in advance, Im not a technically minded person and I'm struggling to get my head round how to implement CSH.*

Thanks for all the help so far. I've read the documents several times and my understanding is that if I employ the "Regular method" then I "Trigger the context sensitivity mode thus :

In order to let RoboHelp decide the best output for the device used, you call the file default.htm in the output folder. You add the options for context sensitivity using URL parameters. To trigger the context sensitivity mode, add the parameter rhcsh:

http://localhost/index.htm?rhcsh=1

I'm guessing this is the path that appears in the Output Folder and Start Page box, in the Responsive HTML5 Settings dialog shown below.

I add parameters shown in the table to define the type, size and behaviour of the help window/s

And then I map the help pages to the corresponding screens using a "map file"

Alternatively I can call help from the app screen by URL.

"Using URLs is simple. You just call the file you want directly"

I'm guessing this means the Help link or icon on each screen of the app links directly to the corresponding topic in the online help. (in which case I'd imagine I have to tell the programmers which help file to call from each screen of the program and they code the help button and the link to the corresponding topic per page. (In which case I do not use "Map files")

Am I missing something?

[Captiv8r]

Hi there

Sounds like you have a fairly decent grasp on things.

I think of it like this in my own mind. A map file is literally like a map that you would have all folded up and kept in the glovebox of your vehicle. It provides the route you take to get to a destination. You know where you are at any given moment. In an application, you might be on the File > Open dialog. And just as any location on our planet has "geo coordinates", where you are should have a unique identifier. So in the application, there is typically an identifier with the "geo coordinates" for that specific dialog. (or sometimes, each field within a dialog)

Of course, the goal is to determine where the matching help topic is for that location. And that's what you create (or open) the map file to configure. So the developer knows their beginning locations, the help file developer knows their destinations. And it's up to the help file developer to kind of "dance" with the application developer to make it all happen.

Sometimes, the application developer creates a header (.h) file with only a list of all the "geo coordinates" for each dialog or field and provides the .h file to the help file developer. If this is the case, the help file developer opens the .h file and begins the process of mapping locations to topics.

And sometimes, the help file developer creates the .h file with things all mapped up and provides it to the developer. Presumably to ensure things are correctly mapped.

I don't fully understand how the next bits work, but when the help file is compiled (for CHM) or generated, the map file is used. I'm assuming it is stored as a single file inside a CHM, and the calls that are made to open the help are understood by the process used to link up a CHM. I'm even more unclear on exactly what happens if a web based output such as WebHelp or Responsive HTML5 help is created. I'm aware of something known as an API comes into play. For the web based outputs, I understand that the API exists as essentially a JavaScript file that is used and the calls to open help topics contain parameters that the API understands.

Cheers... Rick

[Amebr]

I'm just popping in to say the web site linked above is more aimed at developers, rather than the technical writer. The nitty-gritty of how the url is formed sits with them, although you will need to work with them to determine which parameters you want to use. Especially if you decide to include filters in the call. Your developers link each help button/F1 to a function that says "okay, here's the URL I need to use with all my pre-defined parameters (path to web site, size, skin, etc). Let me add the id you sent me in the correct spot and open the URL".

In Robohelp itself, you only decide which topic is associated with which mapid and map number pair in the "map file".