Topic Keywords - can they apply to dynamic content?

Please post all questions on Help+Manual 8 here

Moderators: Alexander Halser, Tim Green

Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Topic Keywords - can they apply to dynamic content?

Unread post by Dave Gehman »

Situation:
(Please excuse the Byzantine stuff to follow... our company likes taking the most complicated routes possible for everything.)

We have around 200+ topics that serve as technical reference for advanced users of our software. The content of those topics are brought into our WebHelp from a separate folder on the server, where the content resides in HTML pages. These separate files/pages are "autodocs" -- documentation automatically created as developers include information in a "doc" bucket (along with the executable code) in the compiled software code.

Anyway, this content is virtually dynamic; it does not exist in the H+M Write editor when H+M compiles the HTML for the WebHelp output. Therefore, the content does not appear in the WebHelp search.

The content is also dynamic in the real-world sense -- it keeps changing as the developers take this or that tack. They insist on having only EXACTLY the words they apply to things. They also insist that the link into our WebHelp ALWAYS has to be draw from the very latest iteration. (New iterations sometimes occur twice a week).

Objective:
Make the autodocs content at least partially searchable -- that is, at least partially find-able via WebHelp's built-in search function.

I think I can make the content searchable by creating a concordance or index based on objects, functions, etc. in the external files (their main headings and object names are unlikely to change). Then I'll place this generated concordance into each topic's respective Keywords pane in H+M.

However, after compiling into WebHelp, the H+M created search hit won't take the user directly to the word in question, only to the topic. The user will have to either use the browser page search (which can see the content of the autodocs at runtime) or by manually scrolling through the autodocs.

Question:
Is there a better way to place the keyword content of the automatically-generated documentation into H+M such that those keywords show up in our WebHelp's built-in search?
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Tim Green »

Hi Dave,
Is there a better way to place the keyword content of the automatically-generated documentation into H+M such that those keywords show up in our WebHelp's built-in search?
Full-text search will always only take you to the topic containing the search terms, along with highlighting of the search terms in the body text. Similarly, the keyword index will also only take you to the topic with which the keyword has been associated and can't highlight anything since the keyword is something attached to the topic, not something in the body text of the topic -- even if it does happen to be there as well, but that doesn't count in this case since the link is to the index keywords.

What you can do is attach index keywords to anchors. Then selecting that keyword in the index will scroll to the position of the anchor. To do this you must ONLY attach the keyword to the anchor and NOT use it in the Topic Options. Otherwise you may not get a link going to the anchor, or you will get two: one that goes to the anchor and one that doesn't, which will be confusing. See this topic in the help for instructions on how to set this up (Using keywords in anchors):

https://www.helpandmanual.com/help/hm_w ... chors.html

Note that anchor keywords can also be used in snippets as they are actually in the body text of the topic. 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Martin Wynne »

Hi Dave,

Have you considered getting your own stand-alone version of the Zoom Indexer:

https://www.zoomsearchengine.com/zoom/

H&M uses a cut-down built-in version of the Zoom Indexer for its search. But if you had your own stand-alone version you could run it on your web site on the server after uploading your webhelp each time. It would then index everything, including any dynamic content. You could create a topic in your webhelp which links to the Zoom Indexer search and results.

Integrating it with the existing H&M search needs some thought. You may not need the existing H&M search results at all. I've had my own copy of the Zoom Indexer for years and never yet done that (there is a lot of stuff on the site in addition to the webhelp, including 20-years-worth of support forum threads), but I've been thinking of moving that way.

p.s. this Zoom Indexer has nothing whatsoever to do with the Zoom online video app much in the news.

cheers,

Martin.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Dave Gehman »

How does the private indexer discover dynamic content?

I'm asking because I'm pretty sure there's nothing in the WebHelp for a given reference topic except a link to the material. The material is loaded when the user lands on a given page and the link is executed... if I'm understanding it correctly.

The links are executed via an HTML iframe. Some tell me it's the wrong thing, others that it's perfectly suited to what we're doing. If you know a better way to place externally-sourced HTML material onto a WebHelp topic page, we're open to anything that works.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Tim Green »

Dave Gehman wrote: Tue Jun 09, 2020 11:28 am I'm asking because I'm pretty sure there's nothing in the WebHelp for a given reference topic except a link to the material. The material is loaded when the user lands on a given page and the link is executed... if I'm understanding it correctly.The links are executed via an HTML iframe. Some tell me it's the wrong thing, others that it's perfectly suited to what we're doing.

Do you mean you are putting your own external content dynamically into WebHelp pages at runtime with iFrames inside the topic pages? If that is the case it is also a problem for Zoom to index, even with the full standalone version. It would index the additional pages if it could access them, but the search results for content in those pages would take the user to the locations of those pages, NOT to the pages containing the iFrames into which they are loaded.

That is the reason for the common Pavlovian knee-jerk response saying that iFrames are evil for searching and indexing. When they are set up like this, they are, because not all the content is on the same page and you can't provide search results for the entire page content. The way the standard skins in Help+Manual use iFrames is different: There they are only an "efficiency/layout container" on the main layout page. The full topic content is always loaded into the iFrame and it is available in a regular HTML file in the same location as the main page. So the regular HTML pages are indexed and searched and the full content is always available in the search results.

What you could do is to combine your external content when you publish instead of dynamically when the WebHelp is displayed. Then everything would be in the topic pages and would be included in the search directly. However, you would have to republish every time your external content changes.

The only other option would be to set up the external pages as regular pages for your website that can be displayed normally. Then link to the external pages from your WebHelp instead of trying to embed them. Then if you use the standalone version of Zoom you could include those pages in your search, and they would also open as standalone pages from the search results.

BIG CAVEAT: If you use the standalone version of Zoom and include pages and other content that are not part of your WebHelp in your search index you CANNOT use the Search pane in WebHelp for that. You must create a completely separate search page with Zoom for that, that is NOT part of your WebHelp, and link to that for doing your searching.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Dave Gehman »

Thanks, Tim, you give me much to think about. I'll be able to open the discussion with the development group that's creating the auto-docs later today -- one way or another, we'll get this worked through, hopefully with the best option for the end-user.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Dave Gehman »

Tim Green wrote: Tue Jun 09, 2020 2:08 pm What you could do is to combine your external content when you publish instead of dynamically when the WebHelp is displayed. Then everything would be in the topic pages and would be included in the search directly. However, you would have to republish every time your external content changes.
How is this combine-at-compile time done?
The only other option would be to set up the external pages as regular pages for your website that can be displayed normally. Then link to the external pages from your WebHelp instead of trying to embed them.
This option is possible. I think. But it results in the user jumping from website (the WebHelp) to website (the HTML auto-docs pages). We have to add support material to the auto-doc content, which is mathematically pure and completely free of examples, screen shots, and other elements that are useful to normal people. So a user will have to bounce from WebHelp > autodocs site > WebHelp (via browser back button) for examples/screens. That might be more than an ordinary person wants to do.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Tim Green »

Hi Dave,
How is this combine-at-compile time done?
If it exists as Help+Manual topic or snippet files you can insert the content directly as snippets. If they are regular HTML pages you can use the #MERGE command to embed the HTML in the output HTML pages at compile time. See here for details (Inserting external HTML files with a code object):

https://www.helpandmanual.com/help/hm_w ... _html.html
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Dave Gehman »

And again, many thanks. Looks like #MERGE is the way.

EDIT: Hmm -- if I'm reading your docs right, the HTML files have to be on my computer (because #MERGE appears to work on sources that are stored relative to the H+M project).

In this case, the desired HTML is on the Web, residing in a virtual folder that is different from the server folder that contains the WebHelp output.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Martin Wynne »

Dave Gehman wrote: Tue Jun 09, 2020 2:59 pmIn this case, the desired HTML is on the Web, residing in a virtual folder that is different from the server folder that contains the WebHelp output
Hi Dave,

Instead of an iframe, you could use a data object. In that case the linked content becomes a part of the parent page and the search indexer will be able to link to it as part of the page:

Code: Select all

<div style="width:100%; height:900px; padding:10px; overflow:auto; border:0px;> 
  <object type="text/html" data="http://the_external_page"></object>
</div>
The downside is that it then reflects your styles and formatting for the parent page, which may conflict with its own formatting. But worth experimenting.

Also, if it contains any images, etc, they will need to be copied to the webhelp folder.

cheers,

Martin.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Tim Green »

In that case the linked content becomes a part of the parent page and the search indexer will be able to link to it as part of the page:
...
The downside is that it then reflects your styles and formatting for the parent page
Unfortunately, it doesn't quite work like that, although it would be nice if it did. Current browsers treat HTML pages inserted with the <object> tag pretty much the same way as iFrames, rendering a complete encapsulated #document object in the DOM, with populated <html>, <head> and <body> sections even if your HTML file only contains HTML paragraphs and nothing else. (You can see this in action with the Inspect tool in Chrome, for example.) The object is encapsulated from the parent page in pretty much the same way as an iFrame, with some differences as regards security and accessibility.

Basically, the <object> has all the same restrictions for this as an iFrame. It doesn't use the CSS from the parent page and at least as far as Zoom is concerned, its content won't be indexed as part of the parent page because Zoom reads the HTML pages as text, not as rendered DOM.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Martin Wynne »

Thanks Tim.

In that case, I think we need some PHP scripting in the topic, to pull in the <body> section of a linked page. I will have a look at that, it would be useful for my own stuff. I want to upgrade my Zoom Indexer to the latest version, and make better use of it.

cheers,

Martin.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Tim Green »

Martin Wynne wrote: Wed Jun 10, 2020 1:28 pmIn that case, I think we need some PHP scripting in the topic, to pull in the <body> section of a linked page.
That won't work either, because it is also something that gets pulled in at runtime. Zoom indexes the physical HTML files, nothing else. It will/can only index what is physically in the files on the disk. It won't look at anything dynamic -- it can't because it only reads the physical files, not the rendered DOM.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Simon_Dismore
Posts: 205
Joined: Thu Jul 13, 2017 2:57 pm

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Simon_Dismore »

Dave Gehman wrote: Tue Jun 09, 2020 2:59 pm Looks like #MERGE is the way. [but] if I'm reading your docs right, the HTML files have to be on my computer (because #MERGE appears to work on sources that are stored relative to the H+M project).
In this case, the desired HTML is on the Web, residing in a virtual folder that is different from the server folder that contains the WebHelp output.
I just tested #MERGE using remote content in four scenarios:
  • #MERGE \\192.168.1.2\wwwroot\hm\source_for_merge_via_symlink\source_ip.htm
  • #MERGE remotefolder_ip\source_ip.htm, where remotefolder_ip is a directory symbolic link to \\192.168.1.2\wwwroot\hm\source_for_merge_via_symlink\
  • #MERGE W:\hm\source_for_merge_via_symlink\source.htm, where W:\ is a local share name for \\192.168.1.2\wwwroot\
  • #MERGE remotefolder\source.htm, where remotefolder is a directory symbolic link to W:\hm\source_for_merge_via_symlink\
Remote content was merged correctly, and was searchable via Zoom indexer, in each scenario. So the documentation is wrong. Tested in 8.1.0 and an old H&M 7 build 4434.

Directory symbolic links weren't needed in this case, but they're very useful if you want to be able to swap brand or locale specific graphics instantly before publishing. Open an admin command prompt on your H&M publishing system, navigate to your H&M project folder and enter something like:

Code: Select all

mklink /d remotefolder_ip \\192.168.1.2\wwwroot\hm\source_for_merge_via_symlink
Last edited by Simon_Dismore on Wed Jun 10, 2020 4:26 pm, edited 1 time in total.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Topic Keywords - can they apply to dynamic content?

Unread post by Dave Gehman »

Thanks, Simon - I'm much obliged to you.

Do I have this right: symlink = symbolic link or soft link? (I'm looking at Wikipedia's entry for symbolic link, much as a dog watches television, unfortunately.... Luckily there will be some people in my company that know them.)
Post Reply