Add anchor to keyword reference for HTML Help and PDFs

Nothing is perfect! This is where you can post your ideas and wishes for functions you'd like to see in Help & Manual. Current version only please (H&M7).

Moderators: Alexander Halser, Tim Green

Post Reply
pmw
Posts: 6
Joined: Thu Feb 09, 2006 11:23 pm

Add anchor to keyword reference for HTML Help and PDFs

Unread post by pmw »

The problem:

As I understand it, keywords in H&M are used to generate the Index for both HTML Help and PDFs. These index items either link to, or have page references for, the associated topic. The problem is that these references are only to the top of the topic for both HTML Help and PDFs.
This means that for a long topic, such as a glossary, you will usually need to scroll down to see the relevant text. The keywords are worse than unhelpful - they appear broken:

In HTML Help, clicking on an Index item in the navigation pane links to the correct topic, but you can't see the text you expect, so you don't know you are looking at the correct topic.
In PDFs, Index items refer to the page on which the topic starts, not the page that the relevant text actually appears on. So in the Index, multiple entries refer to the same page, and almost all of these will be incorrect - an index reference is expected to refer to the exact page. The index appears unreliable.

A suggestion:

Unless I've missed a simple solution, here is a solution...
HTML Workshop seems to compile correctly if you edit the .hhk file to add an anchor to the keyword URL - see attached screenshot. The Index item in the resulting chm links to the anchor in the topic, not just the top of the topic.

So, a control in the Topic Options pane that allowed you to associate an anchor to a keyword, and added a suitable tag in the XML, etc., could fix this problem for HTML Help. It would be much like the existing Anchor in Topic drop-down list control, but would apply to a selected keyword.

A fix is more complicated for PDFs... H&M PDF output needs to be much smarter about cross-references in general.
User avatar
Tim Green
Site Admin
Posts: 23157
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Hi pmw,

Just select Insert > Topic Anchor or double-click on an anchor that you have already edited and you can add and edit both keywords and help context numbers to your anchors.
pmw
Posts: 6
Joined: Thu Feb 09, 2006 11:23 pm

Unread post by pmw »

Thanks for the prompt response Tim.

Now I know what to look for I've found topics on this in the H&M Help too! ; )

And this works really nicely for the PDF as well.

OK - you guys are good!
tomas
Posts: 25
Joined: Wed Jan 07, 2004 12:59 am

Unread post by tomas »

It would be great if there could be a shortcut similar to CTRL-K that adds a topic anchor AND adds the highlighted text as a keyword to that anchor.

Why infact not change CTRL-K so it just does that...

This way it would be possible to get a decent index for PDFs.

Now, if I only could add a list of keywords, and H&M would automatically add all pages where those words or phrases are seen, it would be perfect (preferably the page where it acually is and not the first page of the topic).
/Tomas
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

tomas wrote:Now, if I only could add a list of keywords, and H&M would automatically add all pages where those words or phrases are seen, it would be perfect...
Hi Tomas,

The problem with using a list of keywords this way is that some of the instances will not be important (for example, a list of program functions with no more than a line about each function). I think an index should only point the reader to clear summaries, full descriptions, examples, instruction sets, etc. I feel the same way about putting a range of pages in an index: As long as your index has the starting page of the range, the reader is going to find the information. If I see 44-56 in the index, I'm not going to turn to page 50, just to see if the point of information I'm looking for might possibly be in the middle of the section.

But that's me. I suppose Alexander and crew could add optional functions to use a keyword list and insert page ranges, but there are other functions I'd rather see them develop first.

Happy indexing,
Dean
Post Reply