Context-sensitive help links after upgrade

[louellen_20210224]

I am [finally] going to start upgrading my RH 2019 Classic projects to RH 2020. I want to make sure I understand how context-sensitive help with the URL method will work in both Responsive HTML5 and Frameless layouts generated with RH 2020.

For our current Responsive HTLM5, the context-sensitive topics are linked in this format:  /path/topic.htm#t=topicfile.htm (where topicfile.htm is a level or two deep in subfolders)

As I understand it, if I want to produce Responsive HTML5 output using RH 2020, all those URLs will have to be edited to use this format: 
/path/index.htm#t=topicfile.htm (where index.htm replaces topic.htm).

And if in the future I want to go with a frameless layout, all those URLs will have to be edited again to use this format: 
/path/topicfile.htm (where the path includes all of the subfolders necessary to get to topicfile.htm)
As I understand it, no intervening reference like "index.htm#t=" is necessary with this layout; you can just link directly to the URL of each topic.

So in other words, if I want to duplicate the current Responsive HTLM5 experience in RH2020, and then I want to replace that with frameless output some time in the future, all those URLs will have to be updated twice. Is that correct? 

[Amebr]

"index.htm" should be whatever file name you specify in the Start Page field of your output preset. 

"index.htm" is recommended because webservers have special rules related to the file name "index.htm" by default, but you don't have to use that name. And for help sites linked to an application it generally isn't a problem, as long as your developers know what that file name is. And webserver administrators can configure the server to treat other file names like "index.htm" if necessary.

Particularly for a project created in an older Classic version, it might be something else. Or if it was changed during the upgrade process, you should be able to specify the old file name in that field and not have to re-write your help calls initially.

BUT.

I was just playing around with the Indigo skin and it seems to work completely differently from every other skin that I've every looked at. 🙂 So if you're using that skin, you'll have to test. But you might not have to change either the Start Page, nor your help call until you change to Frameless output.

[Peter Grainge]

Does this help? RH2020 Calling Context Sensitive Help (grainge.org)

________________________________________________________

My site www.grainge.org includes many free Authoring and RoboHelp resources that may be of help.

[louellen_20210224]

Thank you both for your responses! 

Amber, the issue is not the name of the start page; I'm working with a help site for a platform that's been around a long time and the path is probably set in stone where the developers are concerned. 🙂

Peter, I did read that article on your website, and what I wrote above is what I understood it to be saying about the URL syntax for context-sensitive calls for Responsive and Frameless layouts in RH 2020. 

What I'm trying to figure out is whether two rounds of edits to the URLs would be required if I chose to re-create Responsive HTML5 with RH 2020 and then later generate Frameless help. Based on Peter's article, I'm thinking the answer is yes, we would have to update the URLs twice on the platform side. (I think they keep these references in an XML file.)

[louellen_20210224]

What I'm trying to determine, with this question and the other one I posted yesterday, is whether it's worth the effort to tweak the Indigo layout in RH 2020 so we can keep the help layout that our users are familiar with for a little while longer, or whether we should just go straight to a Frameless layout even if it means that we might have to skip the help updates for a release or two while we perfect the look and feel we want from the Frameless layout. (My company is giving me no choice but to move to RH 2020 no later than June.)

My inclination is to say we should concentrate on Frameless, but I need to have solid reasons my boss will understand 🙂 If we need to do two rounds of edits to the context-sensitive references, plus make the visual tweaks I asked about in my other post, then that just might be enough to persuade him.

[Peter Grainge]

The link to a responsive topic without index.htm opens the topic without the TOC etc and with it you get the TOC as well. The difference depends on how you want to call your CSH topics, topic alone or the same topic with the TOC as well.

________________________________________________________

My site www.grainge.org includes many free Authoring and RoboHelp resources that may be of help.

[louellen_20210224]

Right. I remember reading that on your site 🙂

Currently with our Responsive HTML/Indigo setup, the context-sensitive links open with the full TOC and I would want them to behave the same way. So with RH 2020, do I need to change the reference from topic.htm#t to index.htm#t (or instead of index.htm, the actual name of the start page)?

And in a Frameless layout, can I omit the index.htm#t= part and just use the full path and still get the TOC?

For example, suppose the current reference is /help/admin/topic.htm#t=config/add_user.htm and the start page is mystartpage.htm (rather than index.htm). The /help/admin/ path is determined by where the help files are stored on the server as part of the software platform; I can't change this. The /config/ subfolder reflects how the help output is organized for my project.

Once I upgrade to RH 2020, if I want to produce Responsive help, I think the reference would need to change to

/help/admin/mystartpage.htm#t=config/add_user.htm

And if I want to produce Frameless help, the reference would need to change again to the unique URL:

/help/admin/config/add_user.htm

Is that correct? I really appreciate your patience in answering these questions!

[Peter Grainge]

Your current call is /path/topic.htm#t=topicfile.htm. There are two files there, topic.htm and topicfile.htm. What is the file name for your start page? I'm guessing it is topic.htm which would make it the same as index.htm on my page.

________________________________________________________

My site www.grainge.org includes many free Authoring and RoboHelp resources that may be of help.

[louellen_20210224]

OK, I see what you are saying. I appreciate the time you've taken already to explain this to me, so I'm going to spare you a long explanation of what seems to be going on with this project, but let's just say that in short, topic.htm does seem to be my start page. 

So, that being the case, will my context-sensitive references in this form:

/path/topic.htm#t=topicfile.htm

still work in Responsive help generated with RH 2020?

And when I move on to the Frameless layout, will they all have to be edited to remove the reference to the start page?

/path/topicfile.htm

[Amebr]

As i said, Indigo in RH2019 works completely differently to every other help output and doesn't follow Peter's instructions for URL help calls. Instead of using the Start Page as every other skin does, it uses some auto-generated file called topic.htm.  I'm not currently at a computer with RH2020 so I can't check if this behaviour is the same in a RH2020 generated project.

If it works the same way in RH2020, then I think you wouldn't have to change your help call when you upgrade to a RH2020 responsive output. In this scenario you'd only have to change the help call when you decide to move to Frameless,.

If it doesn't work the same way as Rh2019, you will have to change the help call when you upgrade. In this scenario you'd have to change your help call twice - once to the format for Responsive, and again when you move to Frameless.

[Peter Grainge]

@Amebr I'm not following you. The start page is defined in the preset, not the skin. Where are you seeing topic.htm being used?

Using 2019 I added an Indigo skin generated an output with index.htm as the start page. The output shows index.htm in URL.

________________________________________________________

My site www.grainge.org includes many free Authoring and RoboHelp resources that may be of help.

[Amebr]

That's the thing. The Indigo skin doesn't work the same way. If you define the url method context link  using the start page, it only loads the start page instead of the topic you want. You have to use this special 'topic.htm' output file instead. I don't know why. 

[louellen_20210224]

What Amber is saying is exactly what I'm experiencing. I thought maybe this project was set up wrong, but apparently this is the expected behavior with the Indigo layout 🙂 I get the same result (topic.html file) when creating Responsive HTML output using the Indigo skin with RH 2020.

In the preset, I specify the starting page as (let's say) productname.htm and when the output is generated, I get that file plus another file called topic.htm. I can't read the code well enough to tell you how these files work, but it seems that topic.htm has a reference to productname.htm.

From what Amber is saying, I think I might be able to leave my context-sensitive references as they are if I need to produce Responsive output using RH 2020.

[Peter Grainge]

I set up a new Indigo skin that has no reference to index.htm or topic.htm, as expected as that is defined in preset. Presets by default use index.htm. That's why I have said to Amber that I am not following.

I think if you change topic.htm in your preset to index.htm it would use that so the path would be as I describe. However, it doesn't matter what it is as long as you amend the call to the start page defined in the preset. Mickey_Mouse.htm is fine. All that matters is the path in the call uses the same start page as the preset.

Pending Amber's comments I think nothing needs to change when you go to 2020 responsive but you will need to change for frameless.

________________________________________________________

My site www.grainge.org includes many free Authoring and RoboHelp resources that may be of help.

[Peter Grainge]

I've just seen @Amebr response. So what you are saying is the preset can have any start page name but CSH calls have to substitute topic.hm for it. Correct?

________________________________________________________

My site www.grainge.org includes many free Authoring and RoboHelp resources that may be of help.

[louellen_20210224]

So it seems. I'm not sure how or why topic.htm gets created, but it is not specified anywhere in the preset options that I can find. 

The application I'm documenting has two help options. The user can select "Help for this page" and they will get a context-sensitive topic that is mapped to the current screen using the topic.htm#t= reference. The user's other option is to select "Help Index" [terrible name, I didn't choose it], which opens the full help site and displays the starting page I specified in the preset (call it productname.htm).

I think we have determined that my context-sensitive references should still work for Responsive HTML help, but they will need to change when I move to Frameless. I really appreciate all the helpful discussion on this question. Thank you so much for your time and research!

[Peter Grainge]

Please see RH-10604 | Tracker (adobe.com)

________________________________________________________

My site www.grainge.org includes many free Authoring and RoboHelp resources that may be of help.