Valid topic ID characters.

[Tim Frost]

The pop-up message reports that #=+*%!@> are invalid. I was going to report that it occasionally pops up incorrectly because I never use any of these characters. But I found to my horror today that it has been silently stripping dollar signs from my topic names. Luckily I have only worked on a few of our topics with such names, but I need to work on more.

This is a showstopper and I cannot use version 7 until it is fixed, or unless you can provide a workaround which I can set somewhere to bypass this restriction. I luckily made a separate folder tree with copies of all my v6 projects, to which I will now have to return. I also have to remember the few normal updates and spelling errors which I have spotted and fixed in the course of upgrading to v7, and go back and make them in v6.

We have 414 topics containing a $ in the topic ID and several programs which reference these topic IDs to open help. And customers who will try to use links we have sent them in the past, or older versions of programs, and find they no longer work. Even if we changed all the topic names and all the programs, we would still have customers who use a few older builds of specific programs, which would not be able to use the links to the latest help.

There has never been the slightest reported problem over many years with these topic names in any browser. I cannot understand why you would consider suddenly and without warning excluding dollar signs. I have always been aware that you advise against using certain characters, but I have not seen dollar-signs listed before, and it seems a bit draconian to suddenly strip them and break a project where they work perfectly.

Please tell me it was a mistake, and that the list in the message is correct!

[Tim Green]

Hi Tim,

Among other things, it depends where the $ character is in the ID -- the worst place is the first character. They will cause complete failure and serious errors if you try to store your project in Team Foundation Server, so projects with these characters in the IDs are now invalid, at least for that purpose. However, I'm not aware of any silent stripping -- I've asked our developers about that and will let you know. We may be able to provide a solution for this, but I'm not sure at the moment.

For what it's worth, we have always urgently recommended being extremely conservative with characters used in topic IDs. The only way to future-proof them is to only use a..z, A..Z, 0..9 and the - and _ characters, nothing else.

[Simon Dismore]

I found the behavior when a topic ID is generated from the title has changed:

• HM6 silently strips all $ signs (e.g. $tarts, In$ide, End$ become Tarts, Inide, End).
• HM6 allows manual editing of topic IDs to restore $ signs.
• HM7 converts leading $ signs to leading underscores, and preserves non-leading $ signs (e.g. $tarts becomes _tarts, while In$ide and End$ are unchanged). Topics with leading underscores are skipped by the indexer.
• HM7 prevents manual editing of topic IDs to restore leading $ signs.
• HM7 prevents saving HM6 projects that contain leading $ signs in topic IDs.

Here are my test steps, comparing HM7 build 3608 and HM6 build 3019.

1. Create an empty folder ready for a new project.
2. Start Help and Manual
3. Set up an empty new project in the empty folder.
4. Unset the 'compressed zip' checkbox.
5. Define three topics named $tarts, In$ide, and End$.
6. Click the 'Create' button.
7. Append three more topics named $tarts2, In$ide2, and End2$.
8. Put a unique word into each topic. I used Alpha, Bravo ... Foxtrot.
9. Save the project.
10. Publish to WebHelp with no skin.
11. Check the output in the browser.
    HM6 and HM7: All topics are present, and can be selected by TOC entry and using top/prev/next.
12. Search for $tart.
    HM6 and HM7: Search box converts the string into "tart".
    HM6: finds 2 results $tarts and $tarts2.
    HM7: finds no results.
13. Search for In$ide.
    HM6 and HM7: Search box converts the string into "In ide" and finds 2 results: In$ide and In$ide2.
14. Search for End$.
    HM6 and HM7: Search box converts the string into "End" and finds 2 results: End$ and End2$
15. Search for each of the unique words.
    HM6: The words are found successfully with no exceptions.
    HM7: The words are found successfully except for the ones in $tart and $tart2.
16. Examine the HTML output directory and the xml Topics directory.
    HM6: The xml and html topic files are tarts, tarts2, inide, inide2, end and end2.
    HM7: The xml and html topic files are _tarts, _tarts2, in$ide, in$ide2, end$ and end2$. By default, files beginning with an underscore are skipped by the indexer, which explains the search results.
17. Return to the project and attempt to change the ID for the topic titled $tarts to include a leading dollar sign.
    HM6: The change is accepted. After saving and publishing, the xml and html topic files are $tarts.xml and $tarts.htm.
    HM7: The change is rejected with the message that #=+*%!@> are invalid.
18. Save the HM6 project, load it into HM7 and republish.
    HM7: The html topic output file is $tarts.htm. It has been indexed and will be included in search results.
19. Attempt to save the HM6 project from HM7.
    HM7: The save is rejected with the message that #=+*%!@> are invalid.

[Tim Frost]

Simon's detailed analysis (thanks) confirms my findings, and clarifies the position. All I am asking for is the ability to override the new behaviour regarding dollar signs. I have no plans ever to use Team Foundation Server and do not see why I need to be put to lots of unnecessary work just because some of your users are using this product and may perhaps on occasion fail to heed the warnings that you already make. And all my dollar signs have for many years been at the start of the ID, because the topic references an application keyword of this name, and when it was first written there were no such restrictions.

By 'silent' I was referring to the pop-up. First, the list of characters is incorrect. Worse, it does not give any opportunity for the user to choose a different ID, it simply strips the offending characters without saying that this will happen.

Ideally you could go back to the v6 behaviour and I could restore the wanted topic ID in the new topic dialog. But having the ID 'corrected' every time I edit the topic, or even having to override a warning message every time, is not something I could live with.

[Tim Green]

Hi Tim,

We do appreciate your concerns and we're looking into ways of dealing with this.

@Simon:

Thanks for the detailed testing. Where do you find time for this stuff? Do you have a job that pays you full time but only requires you to actually work about 20% of that time?

[Martin Wynne]

Hi Tim F,

Assuming you are referring to Webhelp, you can probably edit the htaccess file on your server so that links including the $ prefix are automatically redirected to a file without the $ prefix. However, this may mean changing every one of your files. To get round that you could redirect them to a .php file which checks whether the $ version is present and redirects accordingly. It is all a bit messy, but there is probably a solution which allows you to stop using $ prefixes without changing all of them, so that existing links continue to work.

But the matter of HM7 replacing leading $ with a leading underscore, preventing indexing by Zoom, looks like a bug. In which case I guess you can expect a quick fix from Alexander.

Martin.

[Tim Green]

But the matter of HM7 replacing leading $ with a leading underscore, preventing indexing by Zoom, looks like a bug. In which case I guess you can expect a quick fix from Alexander.

No, it's not a bug. It's intentional -- Michael put this in as part of the TFS support changes. However, I agree with Tim F. that this is a bit too drastic since it's only necessary for TFS. What we're probably going to do is update it so that it only kicks in when you try to bind to TFS, and then also with a confirmation: If you want to bind to TFS you have to accept the removal of all $-characters from all your topic IDs. If that's OK you can then go ahead. If not, you have to cancel and not bind to TFS.

What may not change is that you will no longer be able to create new topic IDs containing $ characters.

[Simon Dismore]

Where do you find time for this stuff?

I'm quite an efficient tester: I just start from the assumption that someone has been overzealous, lazy, thoughtless and/or stupid and I'm very rarely disappointed . I feel a bit guilty that I didn't help as much with HM7 beta-testing as I'd have liked. Anyway Help and Manual is a special case for several reasons. I like the product, which is extraordinarily good value compared to the alternatives. It should be more widely known. The Wikipedia stuff I knew off by heart because I'm planning to liberally license our next UI. And I'm still hoping to persuade Alex to allow SVG images as media posters and HTML code placeholders... that would really make my day. Please...

[Tim Frost]

It would be great if the prohibition and stripping of dollar signs was restricted to TFS users! But it seems you would like to extend this to a blanket prohibition for all new topic IDs, with or without TFS. This is not going to help us at all. For example: in several applications we have a table of a selection of our keywords (all with $) which we can use both for syntax highlighting and as topic IDs for help. It works well. If new IDs must be without the dollar sign, it's worse than changing them all: we have to keep separate tables or tinker about to find those that differ. And for no good reason, that I can see, if we never intend to use TFS.

This is really an issue of product philosophy: one of the joys of H&M (which we try to replicate in our own applications) is that for any action which is both useful and harmless, there is almost always a way for a reasonably experienced user to achieve it. Warnings are welcome, when justified (as here). But I feel it would be a pity if this started to change to 'Nanny says you mustn't climb that tree, you might fall'. I accept, however, that this has to be set against the problem of supporting new users and making everything work out of the box, which is another worthy goal.

Despite all this, if I must change lots of our topic IDs, I will have to find a way do so, because we cannot deny ourselves for ever the benefits of the latest H&M.

[Tim Green]

Hi Tim,

Don't worry! We've changed this from the ground up and a new build with the changes is coming tomorrow. The $ character will now be generally permitted again, and nothing will be changed automatically. That was really a no-no, particularly in topic IDs, and should never have got into the release version. Sorry about that -- it's been a hectic few months.

Help & Manual 7 will now allow the $ in topic IDs normally, just as it did in previous versions. You will only get blocked if you try to link a project with $ in any IDs to TFS, but even then nothing will get changed automatically. You will just be informed that you can't connect to TFS until you remove the $ characters from your IDs. Then it's up to you.

In any case, TFS is only something you should ever use if you have no choice -- i.e. if your company is already deploying it and you must use it. If you are choosing your own version control for Help & Manual then there is no question: Always go with Subversion.

[DeWayne Rosene]

Generation of Topic ID's seem to have changed in 7.0.5 Build 3680. Blanks in the Topic Title were formerly converted to "_" (underscore) but are now becoming "-" (dash) in the Topic ID. Is there a parameter somewhere that allows me to set the substitution character or is this a bug?

[Tim Green]

Hi DeWayne,

We have made this configurable now but this won't be available until the next maintenance update (7.06) which is coming out soon. If you need it right away you can get it by installing the current stable beta from here:

http://download.ec-software.com/help-an ... p-v706.exe

You can find the new setting in View > Program Options > Editor: Auto-replace blanks in topic IDs with character

We recommend only using either _ or - for this. You can enter other characters but if you enter a character that is invalid in HTML file names the blank will simply be deleted instead of being replaced.

[Martin Wynne]

Generation of Topic ID's seem to have changed in 7.0.5 Build 3680. Blanks in the Topic Title were formerly converted to "_" (underscore) but are now becoming "-" (dash) in the Topic ID. Is there a parameter somewhere that allows me to set the substitution character or is this a bug?

Hi DeWayne,

We have been here before, but no joy from Tim and Alex. I am now routinely changing - to _ on auto-generated topic IDs, in addition to lower-casing them. There was one glorious version of HM6 which was all lower case and underscores, but it didn't last.

Martin.

[Martin Wynne]

We have made this configurable now

Oh joy unconfined!

And all lower case? Please?

Martin.