Default_CSH.htm, Default_Left.htm, and Pane Position

[Thomas Tregner]

Background
Using WebHelp with WebHelp Setup > Navigation Pane > Pane Position > Left selected, a Default_Left.htm file is generated. Depending on the Pane Position selection, Default_Right.htm, Default_Top.htm, or Default_Bottom.htm may be generated. The optional "Open topic with navigation" link (Setup > Topic Settings > Show navigation link at top of topic) which appears in topics is a link to Default_CSH.htm with a fragment for the topic file:
http://www.example.com/example/Content/ ... xample.htm

But what ultimately appears is something like this:
http://www.example.com/example/Content/ ... me=Example

If you examine Default_CSH.htm from a WebHelp output, you can see how it constructs the URL using the fragment. You can also examine Default_CSH.htm in an HTML5 output to see how that skin constructs the URL. They are different. The HTML5 target does not include a Default_<pane position>.htm file. Furthermore the "Open topic with navigation" link is also different:
http://www.example.com/example/Content/ ... xample.htm

Notice there is no _CSH. When clicked, there is no redirection either.

Question
For the most part, a WebHelp output can be replaced with an HTML5 output without breaking many external links. But given the background above, there are some places where breaking can occur. To mitigate this, a copy of Default.htm called Default_Left.htm can be made and placed in the same folder. Can anyone think of a better way?

[NorthEast]

Question
For the most part, a WebHelp output can be replaced with an HTML5 output without breaking many external links. But given the background above, there are some places where breaking can occur. To mitigate this, a copy of Default.htm called Default_Left.htm can be made and placed in the same folder. Can anyone think of a better way?

In what circumstances is there "breaking" for CSH links?

A CSH link to WebHelp will be to Default_CSH.htm, not Default_Left.htm (or any other file); so these links will still work for HTML5.

Or are you saying that end-users might bookmark the WebHelp URL to Default_Left.htm, and may try to use the same URL when it is updated to HTML5? I'm not sure how you compensate for that, but at least if the user bookmarks the new HTML5 URL, then the link will always work as it is unmodified from the original CSH URL.

Also, for HTML5, note that the Flare CSH help (and CSH test) says to link to Default.htm, not Default_CSH.htm.

[Thomas Tregner]

I agree that for most cases, links will convey. This is almost an edge case. But the user behavior is what you described. Users have opened topics in a new tab via the link in the TOC, clicked the open topic with navigation link, and copied the resulting URL to share specific content with others.

[NorthEast]

Ok, well if the copy of the HTML5 CSH file handles the links to Default_Left, then that's probably the best way to cater for 'old' links of this type.

On the other hand, if you don't do this, then it might prompt people to update their links to the HTML5 format!

[Thomas Tregner]

That is a strong argument to leave it alone. I don't want to add a post-build step even if it is automated and I don't want _Left to propagate after the conversion. I guess we will have to balance current needs against future needs.

[Thomas Tregner]

If anyone else runs into this, you can adapt this PowerShell script and run it on your output after a build:

Code: Select all

$CshFile = Get-ChildItem -Path "C:\Example" -Filter *_CSH.htm -Recurse

for($i = 0; $i -lt $CshFile.Count; $i++)
{
   Copy-Item ($CshFile[$i].FullName.Substring(0, $CshFile[$i].FullName.Length-8) + $CshFile[$i].Extension)($CshFile[$i].FullName.Substring(0, $CshFile[$i].FullName.Length-8) + "_Left" + $CshFile[$i].Extension)
}

This script checks all of the folders in the path in the first line. Replace C:\Example with your desired path. It looks for any file ending in _CSH.htm such as Default_CSH.htm. If the script finds one, the script makes a copy of the corresponding main help file such as Default.htm and names it with _Left appended to the base name such as Default_Left.htm.