Re: Window Definitions in Context-Sensitive Help

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 <>
To: ian balanza-davis <>
Cc: 
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:] 

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