Re: Window Definitions in Context-Sensitive Help

[ian balanza-davis <ibalanza_davis@yahoo.co.uk>]

Hi Tony

I think my main concern about the information inside a ditamap is -- for want of a better phrase -- the feature creep to make it work as a CHM project file.

At the moment, the map file looks more akin to an HHC than HHP. And in order to produce a CHM with the controls authors might expect, the map file might (potentially) need to hold multiple window definitions, HHC options, context-sensitive help and HHP options (language, initial display file, etc).

I think by that point, the ditamap would become XML spaghetti, which might not be a problem if much is hidden by tool vendors, but it would have moved far beyond the current ditamap usage and may become unusable except through a HAT.

Personally, I would have thought something like external links to a file or files for window definitions and HHP options from the ditamap, HHC options and (possibly) CSH within the ditamap might make a good split. The ditamap would remain the "project" file, but would not become overly large dealing with the structural information for a display engine. (I say this from the point of view of someone who uses a text editor rather than an authoring tool.)

Regards

Ian

---

From: Tony Self <tself@hyperwrite.com>
To: ian balanza-davis <ibalanza_davis@yahoo.co.uk>
Cc: dita-help@lists.oasis-open.org
Sent: Wednesday, 18 March, 2009 5:10:47
Subject: Window Definitions in Context-Sensitive Help

Dear Ian

 

Thanks very much for your thoughts on the CSH proposals, and in particular your thoughts on window definitions. I’ve copied the DITA Help Subcommittee list on this reply, because I think it is of broad interest and needs discussion.

 

If you could have more than one window definition in a map, wouldn’t that provide a pathway to all the HTML Help options? To a large extent, the map in DITA has to be the container for the information that might be stored in an HHP project file in an HTML Help project. There isn’t any other project container.  (Of course, it may be possible that we need a project container, but I can’t see a strong argument for one at the moment.)

 

With regard to the context hooks (context identification names and numbers) being scattered through the ditamap, I think the way we should look at it is whether the storage of the information is semantically and logically correct, rather than whether it is easy to read. A tool will presumably make the allocation of the hooks easy. For scenarios where the hooks are specific to the map (that is, a topic needs to have different hooks in different publishing contexts), it would seem that a direct reference (where the hook is stored within the topicref element) is a better approach than indirect, where the hooks are stored apart in something like a reltable. That approach also provides some sort of “cascade” options where topics with hooks stored within the topic metadata could also be drawn up into the context map file.

 

Does anyone else have some thoughts on the matter?

Cheers

 

Tony Self

 

 

 

From: ian balanza-davis [mailto:ibalanza_davis@yahoo.co.uk]
Sent: Wednesday, 4 March 2009 7:25 PM
To: Tony Self
Subject: Re: [dita-help] Summary of Context-Sensitive Help Progress

 

Hi Tony

I have managed to have a bit of a look at this, and my only real comment is about the window definition proposed. Personally, I do not think that a single element would give the required scope for the options available in HTML Help. Providing information for a window feels (to me), more like a project file than an addition to the ditamap.

On the basis I find XML can become cluttered and difficult to read, I was musing whether the the context sensitive information might be easier to manage in something mimicking the <reltable>? This would mean the whole set of information could be referenced externally so does not become dispersed throughout the map file.

Ian