Window handling and HHP settings...

[Scott Prentice <sp@leximation.com>]

Hi All...

I sent a query to the dita-users list on Sept 10 trying to get some 
feedback on our proposed ua-window element and asking about how people 
handle the assigning of HHP settings. There weren't a lot of responses, 
but I've aggregated them all in the attached text file.

In summary ..

- the idea of a ua-window element sounded like a good idea to one person 
(the only one who replied on that subject), but he had concerns that it 
might be difficult to get it to work for all Help types

- in general, people thought that the HHP settings should be controlled 
by content in the map, although if possible some of the settings 
(language, title, etc.) could be derived from elsewhere. There may be 
some issues around how to get the title, especially for merged help systems.

Just thought I'd send this out before the meeting today in case we 
wanted to discuss it further.

Cheers,

...scott
================== Original message from Scott Prentice, Sep 10, 2009 :
Online Help and window handling via DITA... 

The DITA-Help subcommittee is looking for input on how best to support
the specification of online Help specific data within DITA. Two current
areas of discussion are ..

- If there was a ua-window element that could be defined as the target
for DITA-defined content, would you want to be able to (and does it make
sense to) be able to define the properties of that window within the
DITA source (as attributes or metadata of some kind)? The properties
could include things like height/width, relative/absolute positioning,
resizable, scrollable, scripting(?), ... other?

- In the current process for building a CHM, much of the data in the top
section of the HHP file is hard-coded in the build scripts. Would it
make sense to have this data defined as metadata in the map? Have you
already tweaked your build process to accommodate this type of data
transfer?


=============== kyleschwamkrug:
We haven't implemented it yet, but we're planning on using metadata for many of
the fields in the HHP. We have a ton of complex merged help systems and need to
be able to control all the window type names and settings.

We're probably going to go as far as to create a <chmmap> specialization.

Some of the settings will probably stay hard-coded for us because we use the
same settings for all our CHMs (window size comes to mind), but something like a
ua-window element makes sense to me. I don't know if it could be simplified down
to a single element for all Online Help outputs though. CHM files have different
options from Eclipse, Help 2.0, etc.

Since we have merged help systems, we also have a lot of linking between
separate CHMs, many of which will probably never be DITA-sourced. We can
implement those with href="some.chm::/some.topic", but I think it would be nice
to separate the help file, be it a CHM, Eclipse plugins, or whatever, from the
HTML filename or whatever the topic identifier is.

================= Rob Cavicchio:
> - In the current process for building a CHM, much of the data
> in the top
> section of the HHP file is hard-coded in the build scripts. Would it
> make sense to have this data defined as metadata in the map? Have you
> already tweaked your build process to accommodate this type of data
> transfer?


It seems like a lot of those settings ("Language", "Title", etc.) should
be automated based on source data that already exists for other
purposes. A few like "Full-text search" could reasonably be made
optional, although even that seems like a generic setting that would
affect all types of Help output. I would be more concerned about other
Help functionality, such as how you specify Help shortcuts that run
executables.


================= kyleschwamkrug:
> It seems like a lot of those settings ("Language", "Title", etc.) should
> be automated based on source data that already exists for other
> purposes.

That's true. "Title" can be a bit more involved though, especially for 
merged systems. Granted, we may do strange things, but we often use 
a different title in the window type definition versus the [OPTIONS] 
section to affect what shows up in the full-text search results tab:

[OPTIONS]
Compatibility=1.1 or later
Compiled File=myweird.chm
Default Window=$global_myhelpsystem
Default Topic=defaultpage.html
Display compile progress=No
Error log file=errorlog.txt
Full-text search=Yes
Index File=lvhowto.hhk
Language=0x409 English (United States)
Title=I Show Up In Full-Text Search
Binary TOC=No
(other stuff)

$global_myhelpsystem="My Window Title","toc.hhc","index.hhk","homepage.html","defaultpage.html",,,,,0x63520,225,0x180E,[150,75,875,675],0xB0000,,,,,,0

We've also got a few cases where a CHM uses multiple window type 
definitions. I imagine this kind of thing is unique to a given online help 
format, so I think having tagging specific to each help format would be 
nice  (<chmmap> versus <eclipsemap>? Domain extensions for each 
help format?). That way, an author who deals only in Eclipse wouldn't 
be exposed to CHM-specific features, and vice versa.

================== Pam Noreault:
In my humble opinion, I would prefer that these settings be handled in the map.
I do understand the case for handling it the other way, but the map would be my
preference.

=================== Glenn Emerson:
One of the reasons we used Webworks when I was at Xerox was the tremendous
flexibility and comparative ease it afforded authors in this regard. We
supported web-based help, CHM, and Javahelp, all with varying degrees of context
sensitivity and screen presentation requirements.

In answer to your question, I think it makes sense to put as much of the
technical metadata (window defs, csh aliasing, custom css, etc.) in the map.