WebHelp back-arrow - why can't we go back?

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

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

WebHelp back-arrow - why can't we go back?

Unread post by Dave Gehman »

Output type: WebHelp.
Question summary: how in WebHelp can we enable readers to return exactly where they clicked on a link?

Background:
I've inherited a new reviewer of my documentation project and he has sold management on the need to provide a link to definitions of every term and concept. I'm to link EVERY time a given term appears ANYWHERE in the text of the WebHelp.

Prior to this new need, I've created targets for these kinds of links as terms fitted with Anchors, the terms residing in a "Terms and Definitions" chapter in a reference section.

In this new link-everything-at-all-times schema, I'm finding it difficult to enable readers to return to the original link location so that they may continue reading.

For example (this from the current Reference Terms and Definitions topic), "Mixin" and "Designs" in the following definition for "BaseAssembly" link to a Mixin and a Design definition, definitions that appear well down the list of definitions:

"BaseAssembly - The fundamental Mixin that must be included in all instantiable Designs...."

In the WebHelp output, If as a new reader I click on "Mixin" and move down the topic to the Mixin definition, I can't find a way to get back to my "BaseAssembly" definition to continue reading. Backspace does nothing in Chrome*. My browser back arrow takes me to the WebHelp's Home page.

How do I explain this situation to my new reviewer? He expects me to enable readers to return to where they clicked on a given link - in other words, in this example, some sort of reverse link that takes the reader back to the word "Mixin" in the "BaseAssembly" definition.

Is there a way to do this - sort of a reversing Anchor? In Word, this is done with ALT+LEFT ARROW.

In Chrome, ALT+LEFT ARROW = backspace = backarrow icon at upper left = go to previous page, which in this case is not the original link on the current Terms and Definitions page, but whatever page was open prior to turning to the Terms and Definitions topic.

__________________________________
*We're constrained to Chrome since the application being documented works ONLY in Chrome. This will open out to other browsers eventually, but multi-browser comparability is far in the future at the moment.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: WebHelp back-arrow - why can't we go back?

Unread post by Dave Gehman »

Or maybe I don't want a link to an anchor in this instance?

Tool-tip?

Popup?

I'll explore those.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: WebHelp back-arrow - why can't we go back?

Unread post by Martin Wynne »

Hi Dave,

I just tried the back-arrow-icon in Chrome and it's working fine here. Takes you back to whatever you clicked on last.

Also if you hover over it, you get a drop-down list of recent locations, so you can jump back several links if you want to.

Google Chrome Version 71.0.3578.98 (Official Build) (64-bit)

Is there something special about the way you are coding the links? Are you testing the actual web site and not a local installation? Few browsers work properly on local files.

cheers,

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

Re: WebHelp back-arrow - why can't we go back?

Unread post by Dave Gehman »

Thanks, Martin. Yes, testing on the Web, not locally.

I'm pretty sure that we're going to need Javascript pop-ups. I'm poring over the H+M topics around these... biggest question is how to maintain the content in the pop-up, since the golden version of the words wil reside in the Terms and Definitions topic.

So the question becomes - can the content of a pop-up automatically draw from another topic in the H+M project?
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: WebHelp back-arrow - why can't we go back?

Unread post by Dave Gehman »

Dave Gehman wrote: So the question becomes - can the content of a pop-up automatically draw from another topic in the H+M project?
I don't see a way to have a Popup class topic automatically contain (and display) text from another topic. I can link to it... but then I'm back to the original problem - the reader is sent to a location and can't return to the sentence containing the word that must be defined, the word where the reader clicked the link to the Popup.

:cry: We have 50+ terms. It looks as though we have to create 50+ new Topics of the Popup Class, one for each term, then manually enter the definition into each of them.

At that point, we have a maintenance nightmare... yes, in our world, each of the terms can change meaning (many of them have changed 4-5 times during the development of the software we're documenting).

When a term changes, I'll have to update the changed definitions both in the overall Terms and Definitions (Default)-class help topic and in the separate Popup topic, which is buried among all the topics of the help file in Project Explorer > Topic Files > Topics... and thus pretty hard to find... wish I could change their color in the Project Explorer tree.

Please, guide me to the light if I'm missing something.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: WebHelp back-arrow - why can't we go back?

Unread post by Martin Wynne »

Hi Dave,

The "H&M way" to do this is not pop-ups, but Snippets. Create each definition as a separate snippet. It then needs to be maintained and edited in only one place, your Snippets folder. Your "terms" topic then becomes simply a list of inserted snippets.

Don't link to them. Put a Toggle in your text, and in the toggle insert the same snippet.

There is a nicer non-H&M way, using a lightbox div and an iframe containing your existing terms topic and anchors, but that requires some scripting. And won't work in PDF or any other non-HTML format. I could post some code if you are interested? Are you using a skin? Which one? Special stuff is much easier if you use native H&M without a skin.

cheers,

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

Re: WebHelp back-arrow - why can't we go back?

Unread post by Dave Gehman »

Thanks for the suggestions. The down side to the toggle is that - if I'm understanding it correctly - some element of it has to be visible at all times. I'd rather have something like what's in the pop-up world, where the fact that there's a link is obvious, but nothing impedes the eye that's scanning the sentence. Some of our sentences will have 3, 4, 5, or 6 or more terms to be linked.

(Yes, the current drive is to ALWAYS give a link to EVERY term, in EVERY bit of text that it appears. And yes, the drive behind this is certifiable OCD behavior...)

Your coding might be a way out. We will be extensively modifying a skin from H+M, however. And, how in the world do you obtain WebHelp output - or Web-based help output - without a skin?
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: WebHelp back-arrow - why can't we go back?

Unread post by Martin Wynne »

Hi Dave,

You can have an inline text toggle, which looks just like a link, but as far as I know it can contain only plain text, not an inserted snippet. H&M is restricted in what it can do by the need to compile to several output formats.
And, how in the world do you obtain WebHelp output - or Web-based help output - without a skin?
Just remove the skin and see. :) There was a time before skins with H&M. It worked fine and still does. I've gone back to using it a lot to allow much easier customising of stuff.

At the bottom of the Select Skin drop-down on the Publish page:
remove_skin.png
cheers,

Martin.
You do not have the required permissions to view the files attached to this post.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: WebHelp back-arrow - why can't we go back?

Unread post by Dave Gehman »

Thanks. I'll try the skin-less option. We're about to have a Web/CSS/JS person bring our WebHelp into line with the website of the program that the help file is documenting, and skin-less might make his work less cumbersome.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: WebHelp back-arrow - why can't we go back?

Unread post by Martin Wynne »

Hi Dave,

Going back to your original question, I've been testing in Chrome, and I can't reproduce the problem in any form. Anchors and the browser Back button work fine every way I have tried, on the same page or between pages.

Are you sure you have the latest version of Google Chrome? A re-install might be worth a try.

One of the problems in Chrome is that it caches every damn thing, forever, regardless of your cache settings. The solution to that is to use a .php extension on your topics instead of .htm -- I do that for everything now, and it also fixes the similar caching problem for iframe content in Firefox.

If you still can't fix it, a possible solution is to open the link in a separate browser tab. Then to get back to where you were, you can simply close that tab and revert to the previous one. Or leave several additional tabs open if you want to refer to and fro. To make an H&M topic link open in a separate tab, use the Internet Link option instead of Topic Link. Enter the file name for the topic and #anchor_name. Set the target to New Window. It might not work in all skins.

cheers,

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

Re: WebHelp back-arrow - why can't we go back?

Unread post by Dave Gehman »

Thanks again, Martin.

Chrome > Help > About Chrome tells me " Google Chrome is up to date - Version 71.0.3578.98 (Official Build) (64-bit)". Going to Google.com via Edge, I can't find the exact version number or a page with version history, so I don't know 100% that 71.0.3578.98 is indeed the latest.

The perfect solution is to (re)place the cursor where the reader left the text to pursue the link. Getting back just to the original page won't do for our mechanical engineer, OCD folks. So, pop-up or "silent" toggle - if there is one - is likely to be the best solution.

By "silent" I mean, a toggle with no visible toggly-window until the link is clicked. I think that pop-up is the best option so far, as only the link is obvious on the original page, until clicked.

Additionally, we ran into problems with translation using the Toggle + Snippet/Repository schema... exact problem escapes my memory but I think it had to do with the fact that the text doesn't reside in a snippet-laced topic XML and therefore the translator had problems with context.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: WebHelp back-arrow - why can't we go back?

Unread post by Martin Wynne »

Dave Gehman wrote:The perfect solution is to (re)place the cursor where the reader left the text to pursue the link
Hi Dave,

But that is exactly what happens in Chrome (on Windows10) for me. The Back button jumps back to the exact place where the link was clicked. Either on the same page, or a different page.

I will do some more testing to see if I can replicate your problem. Maybe it is related to F7 (caret browsing).

Or the specific skin you are using. Which one?

cheers,

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

Re: WebHelp back-arrow - why can't we go back?

Unread post by Dave Gehman »

Clearly I don't know enough to explain the difference experience.... no idea what F7 browsing is.

The skin is a customized version of WebHelp_SlateGrey.hmskin.

EDIT: after some experimentation, apparently it is the skin. Most other sites via Chrome have a back arrow/button that works ok - not perfect, because there exact placement is still iffy.

I'll still be experimenting with pop-ups, as that (from the user's perspective) seems to be the most intuitive modality.
Last edited by Dave Gehman on Sun Jan 06, 2019 2:13 pm, edited 1 time in total.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: WebHelp back-arrow - why can't we go back?

Unread post by Martin Wynne »

Dave Gehman wrote:no idea what F7 browsing is.
Hi Dave,

In most browsers (I think in Chrome it requires an add-on) you can press the F7 key to toggle "caret browsing" on and off. The caret is the flashing vertical line which shows where text is being edited. Some folks call it the cursor, although technically that is the name for the mouse pointer.

With caret browsing turned on, a web page shows a caret flashing between the text anywhere on the page. This makes it much easier to navigate the page using only the keyboard, especially selecting text to copy (arrow keys with Shift). It also changes the behaviour of the End and Home keys which then refer to individual lines instead of the whole page. Add the Ctrl key if you do want that. To click a link in caret browsing, move the caret into it using the arrow keys, and press Enter.

cheers,

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

Re: WebHelp back-arrow - why can't we go back?

Unread post by Dave Gehman »

We seem to have posted around the same time...

Apparently Chrome needs the F7 add-on. That's off the table for us as our software is targeting companies, and departments within companies, that have restrictions that prevent 3rd party add-ons unless blessed by IT - and the blessing process can take months.
Post Reply