Home Forums General XMetaL Discussion Xmetal Customisations – Element Description too long Reply To: Xmetal Customisations – Element Description too long

Derek Read

Reply to: Xmetal Customisations – Element Description too long

This is a known limitation with the Element List (affecting the 5.x releases). It should expand vertically and wrap to accomodate the entire description but it does not. There is nothing you can do to fix this yourself. Users can make the Element List wider if they need to see a description that does not fit in the current width. The Attribute Inspector (when supplied with a dtdname.att file) does not suffer from this limitation.

Better Help – Option 1:
An alternative solution (if your users need detailed help) is to document your DTD/Schema in a CHM file.

With XMetaL Author Enterprise, for DITA documents, we include the DITA Language Reference as part of the documentation in the xmetal.chm file. There are APIs for accessing and showing users specific topics within CHM files and those can be scripted in a similar way to the Alt+F1 functionality we provide for DITA documents that takes you directly to the Language Reference topic describing the current element. The trick in this case is to pass the name of a particular HTML file contained within the CHM as an additional portion to the path to the CHM file itself. The DITA Language Reference, thoughtfully, has used the names of each element for each topic with the corresponding HTML's filename also using the same name.

If you were to organize your CHM file the same way (giving each topic and HTML file the same name as an element or attribute) you can then simply use Selection.ContainerName to locate the right topic in the CHM. For example:


or (if folders are used inside the CHM:

This type of “::” path is not special to XMetaL Author, it is a standard format supported by the Microsoft HTML Help Viewer application (hh.exe).

Better Help – Option 2:
We have also had some partners create “live documentation” that sits in the Resource Manager (one or more HTML pages). I've seen customizations created by partners that automatically load (or scroll to) detailed help. The page(s) is loaded into the Resource Manager and as the user navigates the current document Selection.ContainerName is checked and Internet Explorer is told what to do to display the topic based on that element name. This involves script in the On_Update_UI event macro. This can be done via script on that HTML page (calling a function with a given parameter value), or more simply by specifying a URL in the form filename.html#value when using the WebBrowser API. That will require you to include corresponding elements in the HTML (this is standard HTML linking stuff supported by IE).

Information on APIs related to theĀ  Resource Manager is documented in the Programmers Guide (search for “Resource Manager” and “WebBrowser”).

If I had an example of this I'd include it here, but unfortunately I don't.

3rd Party DTD and Schema Documentation Tools:
There are quite a few tools out there (free, opensource and some commercial) that will read a DTD or Schema and generate various forms of documentation for it (HTML is almost always included as one format). Searching for [url=http://www.google.ca/search?&q=dtd+doc+generator]dtd doc generator[/url] or [url=http://www.google.ca/search?&q=schema+doc+generator]schema doc generator[/url] (or similar) should find some of them.

At the very least they document which elements are allowed as children. In some cases they also include parents, attributes, allowed attribute values, mandatory elements and attributes, and other things. You would either use these docs directly or expand on them depending on the level of help you need to provide. In some cases the tools support additional supplementary files that can be automatically read in and integrated into the final output in some fashion.

Most of these do not produce CHM files, but anyone familiar with HTML Help Workshop can take a set of HTML files and produce a CHM from them.