Variables in topic titles not expanded correctly in HTML

Please post bug reports for earlier versions of Help & Manual (3 and 4) here, along with reports for TNT.

Moderators: Alexander Halser, Tim Green

Post Reply
User avatar
brunos
Posts: 218
Joined: Sun Jul 07, 2002 4:27 pm
Location: Bologna, Italy
Contact:

Variables in topic titles not expanded correctly in HTML

Unread post by brunos »

If you use variables in topic titles, e.g. About <APPNAME>, they are not expanded correctly in HTML export, when you export modular help systems. For example, I'm exporting to HTML the GN3.HM3 file, which includes files SHELL.HM3, TED.HM3 and FRED.HM3 (in this order). In all three files, the variable <APPNAME> is used for the name of the application. But, it is expanded correctly only for SHELL (the first file). For other included files, it remains the value of the variable of the first file.

Here's an extract from the content (binary TOC, but it does the same in normal TOC).

tocTab[ir++] = new Array ("4", "Content Manager Shell", "ted_contents.htm", "", "plus.gif", "minus.gif");

"Content Manager Shell" is <APPNAME> in SHELL.HM3, while "Text Editor Ted" is <APPNAME> in TED.HM3. Still, in Ted's part of the TOC, the old variable persists.

I've downloaded 694, but the problem remains.

Regards,
Bruno
User avatar
Alexander Halser
EC-Software Support
Posts: 4098
Joined: Mon Jun 24, 2002 7:24 pm
Location: Salzburg, Austria
Contact:

Unread post by Alexander Halser »

The variables overload each other. This is actually a feature, not a bug. So you can have only one <APPNAME> variable. If you need a different <APPNAME> in the incude files, please choose another variable name.
Alexander Halser
Senior Software Architect, EC Software GmbH
User avatar
brunos
Posts: 218
Joined: Sun Jul 07, 2002 4:27 pm
Location: Bologna, Italy
Contact:

Unread post by brunos »

Oh, I see!

Anyway, the users who use a lot the modular help approach (and I'm one among them), may disagree in judging so quickly this as a feature.

Let me explain: one believes it would be wise to split a huge project in modules, and to include modules at run-time. This is supposed to simplify the maintenance, especially if you update modules rather often.

So you have, let's say, 20 modules (each project in a separate directory) and one main file. In every module file, you've specified <BUILD> as a build number variable. This will help your readers to know when you change something. And you used 20 other variables for other purposes, since they are so beautiful and useful. And, because you're an ordered person, you named all variables that serve the same purpose, in the same way.

So you compile HTMLHELP, and everything works as a charm. The common table of contents is build automatically, and there's no problem with variables or unique topic names of included projects.

And then you export in PDF, and still, everything works.

So you're happy.

Then, you export in HTML (because that's the whole point of the single source - write once, use many times). And everything brokes.

Your variables are all messed up and there's no place where you can say "no, thanks, don't do it".

Your topics are overwritten (only those which do not have unique names - but isn't likely that in all modules the topics about "keyboard" stuff will be named "keyboard"; since there's no way in H&M to tell "use this prefix for all topic names"; nor there's a way to tell H&M "add this prefix to names when exporting to HTM to keep them unique") even if your HM3 files are in separate subdirectories, since HTM exports *everything" in one directory (and there's no way to tell it "please, export in sub-dirs").

And if you export modules separately, then say "goodbye" to the common table of contents.

Conclusion: a modular project that works well in HTMLHELP, is not necessarily a good source for the browser version, unless you were so wise to give unique names (manually) to all topics, and to name (manually) all the variables with different names, even if they're used for the same purpose. You better don't forget it, you'll be very sorry!

In H&M overview (in help file), "modularity" and "variables" are one below each other, but there's no warning on problems if you use them together (I couldn't find any notice about that, anywhere else in the documentation).

So you're unhappy. You report it as a bug. And you got instructed that this is a feature.

What to say, then?

Regards,
Bruno
User avatar
Alexander Halser
EC-Software Support
Posts: 4098
Joined: Mon Jun 24, 2002 7:24 pm
Location: Salzburg, Austria
Contact:

Unread post by Alexander Halser »

Well, that's worth a discussion, but we have been talking about variables and I would disagree here though. Here is why: If you split your help project into modules that get merged at compile time (which is the way most users do it, I think), you may want to use one <BUILD> variable in all your sub-projects but change it only once, in the master project to upate everything. This would not work if variables don't overwrite. Which is far worse because there is no workaround then, compared to the relatively simple workaround of using different variables for sub-projects if you want them to have a different value.
Alexander Halser
Senior Software Architect, EC Software GmbH
User avatar
brunos
Posts: 218
Joined: Sun Jul 07, 2002 4:27 pm
Location: Bologna, Italy
Contact:

Unread post by brunos »

Wouldn't be enough to have a switch which says "Do it", or "Don't do it"?

In my opinion, the worst thing is when a software makes choices instead to let users do it. But, that should be easy to fix - the first step is to avoid to think "the minority of users need that option, so who cares".

Note: I remind our discussion back in November 2001; the HM3 was released few weeks ago, and the only option was run-time merging, so I complained and you replied:
the support for on-compile-time merging is discontinued in version 3. We changed it to run-time merging after many user requests.
Isn't it funny how users change their minds...?

Regards,
Bruno
User avatar
Alexander Halser
EC-Software Support
Posts: 4098
Joined: Mon Jun 24, 2002 7:24 pm
Location: Salzburg, Austria
Contact:

Unread post by Alexander Halser »

Isn't it funny how users change their minds...?
Seems so, yes. After complaints with version 2 that H&M always merges help projects at compile time, we changed it to run-time just to find out that most of the users meanwhile convinced themselfes that run-time merging is far too complicated (needs a lot of planning...) for them and changed to compile-time merging which is easier to handle.
Alexander Halser
Senior Software Architect, EC Software GmbH
Post Reply