OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-help message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: FW: DITA to CHMs


Hi Everyone
 
Here is an expansion on the issues raised recently by Ian Balanza-Davis relating to creating HTML Help from a DITA source .  Ian has added some useful suggestions on how the issues might be addressed.
 
Best regards,
 
-Matthew Ellison


From: Ian Balanza-Davis [mailto:Ian.Balanza-Davis@portraitsoftware.com]
Sent: 27 August 2008 11:18
To: Matthew Ellison
Subject: DITA to CHMs

Hi Matthew

 

I know my comments below would mean a lot of work to implement, but I am taking the approach of this is how I would do things, with no restriction. The main  reason is that I need to create new XSLT in many places for the output I require, so I am making this work for me. That may not be the best for DITA as a whole, but may be an interesting start.

 

I ran out of steam a little as my thoughts were interrupted by the birth of our second child. So if they are confused, or you want clarification on anything please let me know.

 

·         Child CHMs cannot be included in a ditamap, as there is no type=”chm” option that could be picked up and used during processing.

This is for adding external CHMs, not something to batch-create CHMs. The latter is the job of something like ANT, make or shell scripting.

 

I think adding a new type to a topicref would be the easiest option -- with the chm name in the href -- and leave the hard work to the clever people who write XSLT to sort out how it works  -- wasn’t too difficult... ;-)

 

The only issue with this approach is the HHC name, some vendors do not use the same name for their HHC as the CHM (I know madcap do this -- I can only assume because no-one has bothered changing test code), so there is a requirement to allow a different HHC name. This could most simply be included in the href of the topicref and the whole href copied over. Alternatively otherprops might be used, or a new attribute introduced. I would favour using only the href -- I know this is a little bit of “hacking”, but is the easiest way of using the current structure.

 

I am using a type of chm at the moment, but because we are only using a subset of elements, and I want different output, I need to rewrite much of the XSL. However, I think formalising a type and placing it in the “processing required” list of types would be sensible.

 

·         Window definitions cannot be created. Currently a definition is hardwired into the DITA open toolkit, but again there is nothing in place to define windows through DITA. (This would also be more than a little helpful for context-sensitive help.)

I am struggling to see much beyond a new “topic” style for the HHP windows. There are some interesting points however:

·            We are only dealing with a single ditamap, so multiple  HHC files should be beyond scope.  The HHC created from the ditamap should therefore be carried through to any window definitions.
In order to create multiple HHC files (that is, by using multiple ditamap files), I think a whole new “project” XML file would need to be introduced. I would not be a fan of this approach as it would not be extending DITA, more writing a replacement for RoboHelp/Madcap and the like.

·            Multiple windows may be used, and the default window needs to be defined in the same way as the default topic below. For example <defaultWindow name=”id_of_window_definition”>. This should be added to the ditamap, one element per ditamap. Where the windows are defined in a different file the same approach as conref could be used to link the default window definition to the ditamap.

 

If there were no constraints, I would do something like the following:

<windows>

  <window name=”id_of_first_window>

    <attribute name=”” value=”” />

    ...

  </window>

  <window name=”id_of_next_window”>

    <attribute name=”” value=”” />

    ...

  </window>

  ...

</windows>

 

This sort of style seems to fit the style of the top level elements, but has the considerable drawback that the elements making up the window definition must then be known in detail. (Something I do not know myself completely.) BTW, if you do know the elements and want me to try this approach any information you can pass on would be very helpful.

 

The other option would be to individually define the elements. This may be better if there are mandatory entries, and could be explained easier but might be less flexible. (Really, this needs to be tried before a firm decision could be made.)

 

·         I can only create a hierarchy of HTML headings by having multiple topics within a single file rather than through a ditamap. (I have raised this with John Hunt, but have yet to get a reply.)

I am currently trying to create the headings myself as I have not heard anything from Mr Hunt. When I have a better idea of how to make this work, I shall drop a line with my approach to see if it might be useful.

 

·         The default topic in a TOC is hardwired in the output, but there are many good reasons not to have the first topic in a TOC as the default.

This should probably be a new element <defaultTopic href="”path_to_file”/>," and only one element per ditamap. There would be some duplication, but could be a candidate for a conref?

The other option could be as an attribute to  a topicref, but there could be problems with this as someone would be guaranteed to add the attribute to multiple topicref elements.

If there is a separate “topic” for window definitions, this should be carried through to that topic and used if no other definition presents itself.

 

·         There seems to be no way to convert see also links to Active X, or include JavaScript in DITA. I may be missing something, but that seems to be a bit of a hole for IE-based resources (and web-based in general).

JavaScript could possibly be included by allowing one or more actions to be added to the element. This could be something like:

<image outputclass=””>

  <actions>

    <action name=”onClick” value=”onButtonClicked(this);” />

    <action name=”onMouseOver” value=”rollOver();” />

  </actions>

</image>

The XSL could simply convert each action into an attribute of the output XHTML element. Clearly any form of checking that the action is appropriate to the element would be nearly impossible. I am planning to use simple JavaScript calls (no function arguments) so this would work for me. I also understand this would be a lot of work as  almost every element inside DITA topics would need to allow it to be used.

 

Another tag would needed to be added to the content to link to a script file, and it would seem to be sensible that this is a <script> tag -- of the same style as the XHTML tag. I do not think that the script should allow CDATA as this would (potentially) mix content with style.

 

 

Best wishes

 

Ian

DISCLAIMER: This e-mail is intended only for the addressee named above. As this e-mail may contain confidential or privileged information, if you are not the named addressee, you are not authorised to retain, read, copy or disseminate this message or any part of it. If you received this email in error, please notify the sender and delete the message from your computer.


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]