Automatically Synchronize TOC from F1 Help Link

[jossch]

MadCap Flare 5.0.1

Compiled as WebHelp

'Automatically Synchronize TOC' check box is selected on the skin.

If topics are accessed from within the project they synch in the TOC. However, they do not synch when accessed via the help button (linked via window name and html link to topic in xml file).

Need to know if this can be corrected somehow or if there is some sort of work around.

Thanks,
Josette

[carolynmwallace]

This may be an issue with WebHelp. In our products using Microsoft HTML targets (AKA chm files), the Automatically Synchronize TOC feature works whether the user presses F1, clicks a Help button, or gets to a topic via the Help Index.

However, we don't have context-sensitive help in our Web product, so I can't test my theory.

WebHelp folks with CSH--what's your experience with this issue?

[NorthEast]

I use CSH calls to our WebHelp, and the TOC synchronisation works ok.

If topics are accessed from within the project they synch in the TOC. However, they do not synch when accessed via the help button (linked via window name and html link to topic in xml file).

How do you link the help button to the WebHelp though; do you use a WebHelp CSH call?

By 'WebHelp CSH call', I mean use either the URL or javascript methods outlined in the Flare help:
Features > Context-Sensitive Help > CSH Calls for WebHelp and WebHelp Plus > CSH Calls for WebHelp and WebHelp Plus—Developers

[jossch]

The help call is saved in an XML file that is accessed by the software...it is in the following format...

<HelpURL Window="{Window Name:}" View="{View Name}" URL="helpproj.htm#StartTopic={help topic}"/>

The Window and View references are what the system uses to match the screen the user is on to the reference in the XML file. The View part is only used when necessary, so is not in all links.

Here is an example of what a help reference in the XML file looks like.

<HelpURL Window="Search" View="SearchCase" URL="ePC.htm#StartTopic=/Content/userguide/Case_Searching.htm"/>

[NorthEast]

Ok, that's not the correct format for a WebHelp CSH call.

If you check the help, you'll see the format of the URL should be something like this:

MyWebHelp_CSH.htm#MyTopic.htm


So in your example, you need to change the following:
- You should be linking to the project file with the _CSH filename; i.e. link to ePC_CSH.htm instead of ePC.htm.
- Remove the text StartTopic= from the URL.
- The path to the topic after the # symbol doesn't contain the /Content folder; i.e. use #userguide/Case_Searching.htm instead of #StartTopic=/Content/userguide/Case_Searching.htm.

So for your example URL:

ePC.htm#StartTopic=/Content/userguide/Case_Searching.htm

It should look like this:

ePC_CSH.htm#userguide/Case_Searching.htm

[jossch]

To make sure I'm clear...the links work, they just don't synch in the TOC.

The "start topic" portion is used to make sure that if for some reason the specified .htm is not available that they go to the Start Topic as specified in the help file, so that it doesn't give the user a "page not found" message.

OK. Looked up CSH -- Context-Sensistive Help in the Flare Online Help. We are not using that structure. We do not use header files. Our software requires us to create the "CSH" in an XML file. So these are basically html links. What I don't understand is why when accessed externally the "synch toc" does not work.

BTW, we have been using this format for probably 2 or 3 years. I'm not sure if the not synching is a recent development or if it never has worked.

Thanks,
Josette

[NorthEast]

The "start topic" portion is used to make sure that if for some reason the specified .htm is not available that they go to the Start Topic as specified in the help file, so that it doesn't give the user a "page not found" message.

Hmmm... I don't really follow where you got StartTopic from and why you use it - it's not actually documented, and I'm also pretty sure it doesn't behave in the way you describe.

The only place I've seen StartTopic is in the address bar after WebHelp processes a normal CSH call, and in that case it's set to the topic to display; it's not an alternative topic to display if you can't find it.

I'm guessing at some point someone made a CSH call, and then designed your URL format based on the resulting URL displayed in the address bar, which isn't the URL format you need to use to make a CSH call.

OK. Looked up CSH -- Context-Sensistive Help in the Flare Online Help. We are not using that structure. We do not use header files. Our software requires us to create the "CSH" in an XML file. So these are basically html links. What I don't understand is why when accessed externally the "synch toc" does not work.

You don't need to use header files if you're making the CSH call with the full filename/path.
You only need header files if you're using an alias file and making the CSH call using identifiers or numbers (which are linked to the filenames in the alias editor).

Your current method is clearly not initiating the WebHelp correctly, so the TOC synchronisation isn't being triggered. If you use CSH calls in the correct format, then TOC synchronisation will work.

[jossch]

Well kids LOL

I removed the #StartTopic reference and added "_CSH" to the epc.htm reference

Now it's not working at all. I receive a "404" error. However, if I add the "#StartTopic" reference back, I at least receive the online help structure with the TOC, but I still have the "404" error where the help topic should display.

Any ideas?

I really appreciate any help with this issue. The structure for this was developed by a previous tech writer and then updated by the programmer when a Flare version change broke the links.... the original tech writer is gone and neither the programmer or I remember when exactly the last change was made to the XML file. Prior to my current company I worked with Header files and Alias files, so this is all new to me.

Josette

[NorthEast]

Ok, if you're getting a 404 error, then I'm guessing you're running the WebHelp from a server.

If the link to the ePC.htm opens the WebHelp frames, but the link to ePC_CSH.htm doesn't, then I would check that the ePC_CSH.htm file is actually present on the server. (The *_CSH.htm file is built with your WebHelp and will be in the output folder.)

Also, apart from removing StartTopic=, you'd also need to make sure that /Content/ isn't included in the file path; the path after the # is the topic location inside the content folder.


Going forward, if you're familar with using header files and identifiers, then it might be worth looking into Flare's alias editor and using indentifiers in your CSH calls instead of file names. Then a change in filename won't break your CSH calls.

[jossch]

I verified that the _CSH.htm is located in the correct location on the server. I software is accessed from servers.

The current format allows the online help to appear correctly. The issue is that the topics are not highlighted in the TOC when displayed. The new format is not displaying the help at all. I receive a 404 Error message. I am including the current and new formats below to show the differences between the two in the links in the helpurllist.xml file and what is displayed in IE. I'm not sure if I'm missing something...

Current Format:

Code: Select all

<HelpURL Window="CaseImportUtility" URL="ePC.htm#StartTopic=/Content/userguide/Utilities_Case_Import.htm"/>

URL that appears in IE:
http://epc/eBizSys/Help/en/ePC.htm#StartTopic=/Content/userguide/Utilities_Case_Import.htm

New Format:

Code: Select all

<HelpURL Window="CaseImportUtility" URL="ePC_CSH.htm/userguide/Utilities_Case_Import.htm"/>

URL that appears in IE:
http://qacurrent/qamss/Help/en/ePC_CSH.htm/userguide/Utilities_Case_Import.htm

Thanks again for any help,
Josette

[LTinker68]

You're missing the # sign in the new URL. For instance, to get to a topic on the MadCap KB called CSH1005F_CSH_Resources.htm, the URL to use (if not using a map ID) is http://kb.madcapsoftware.com/default_CS ... ources.htm. Notice the pound sign and the path to the file -- the /Content/ wasn't included in the URL, even though that is the parent folder in the output. "Flare" is the first sub-folder beneath the Content folder.

If you use a map ID instead of the file name, then the URL is http://kb.madcapsoftware.com/default_CSH.htm#CSH1005F.

As Dave mentioned, when using the map ID method, you could rename CSH1005F_CSH_Resources.htm without worrying about your CSH call. If you use the URL method, though, you have to not only worry about the name of the file, but the path to it.

[jossch]

YIPPEE! It's working.

Thanks Dave and Lisa.

Josette