I have read Phil's design document and discussed it with him. This e-mail summarizes that discussion, provides some recommendations, and that sort of thing. Perhaps early next week we can talk about where to go from here?

The current proposal is that native RiverWare help for RPL will be based on two HTML files, one for predefined functions and one for operators, with additional image files (approximately 70). These files will be incorporated into RiverWare using Qt's resource system (i.e., included in the build tree, referenced by a .qrc file, compiled using rcc as part of the build process).

These HTML files:

• Need to be created from the Framemaker source document so that we are not maintaining documentation in two places.
• Need to contain non-displaying content (semantic mark-up) that indicate which part of the content is relevant to which function or operator. For the proposed design, it would be useful for RiverWare to identify content with the following semantics: function, function name, function description, function argument name, operator.

The FrameMaker "publish" functionality produces HTML, but it does not have the desired semantic mark-up required by RiverWare. It can't have the mark-up because the source document does not have the relevant information.

Phil has written a script which converts the HTML generated by FrameMaker to HTML with the mark-up required by RiverWare. In addition to adding this mark-up, the script simplifies the HTML while retaining the basic appearance of the original document. This script relies on structure and settings in the source FrameMaker document and on the way FrameMaker uses that structure to create HTML. For example, FrameMaker 12 give a header HTML element a class name corresponding to the name of that section's style in the FramerMaker paragraph designer (or something like that).

Phil can clarify, but I think the basic idea is that whenever we do a release with new on-line help (I think this is usually only for major releases), we add a couple of steps after the release branch is created and after on-line help has been updated for the release:

• In Framemaker, publish the two relevant RPL documents (operators, predefined functions) to HTML.
• Run the python script to generate 2 improved html files with image files.
• Copy these files to the builds tree, recompile, commit

Is there an alternative? We could provide RiverWare with the raw FrameMaker publish HTML and let it do the work that is currently being performed by the Python script. This translation would be performed for every execution of RiverWare, and would introduce into RiverWare very specific assumptions about the documentation. It has to make some assumptions, but in Phil's proposal the Python script makes some and RiverWare makes others.

We could also explore approaches to improving the FrameMaker output, e.g., by defining paragraph styles with more specific semantics, by generating XML instead of publishing HTML, by customizing the publish settings, or by modifying the source in other ways.

The online help Predefined Function section should be revised so that the documentation for each function is structured in a predictable way. This is largely the case already, but we should make sure that:

• There is no text preceding the main table. Any text there should  be moved elsewhere (or deleted when it is redundant).
• The first row of the table, the Description, should provide a concise (1-2 sentence) description of the function's behavior.

• The Arguments widget should display meaningful argument names (instead of arg0, ...), and these should agree with the names used in the online help.
• The QWebView does not need to think the name should only be displayed once

The RPL Palette Predefined functions palette should:

• Display meaningful argument names (instead of arg0, ...)
• Display the 1-2 sentence description for the selected function in a panel at the bottom of the dialog (this could hide-able, but I wouldn't expect users would want to hide it).
• It would be nice to add a Related Function or See Also predefined functions section with links.

Clarification: Phil is proposing that we display raster images for equations in on-line help because we can not get usable vector images for them.

Phil's proposal for accessing on-line help for RPL operators in the context of a RplFrame is to double-click on the operator. This seems risky to me since some operators are small (one symbol) and a mis-click might initiate in-line editing. An alternative would be to provide a "show me help" action which uses the operator of the selected expression as the appropriate context. For the Palette Buttons tab of the Palette, I agree that there doesn't seem to be any great alternative to something like the "Shift-click on a button" that Phil has proposed.

I think Phil is advocating the following treatment for hyper-text links within the framemaker source:

• Remove links to another source document. E.g., a link from the predefined functions document to another document.
• For the operators document, retain links to other sections within the same document.
• For the predefined functions document, retain links to other sections within the same document. When such a link is clicked we would open the appropriate Predefined Function editor.

---