[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. ·
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 |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]