This document proposes enhancements to RiverWare (beyond version 6.4) to display "online help" content within RiverWare for RPL Predefined Functions and RPL language constructs (statements and operators).
Document Status:
3-18-2014: Initial writing in progress.
Contents:
This analysis and design document addresses this task:
Design and estimate improved access to RPL documentation.
CADSWES staff will design and estimate mechanisms for more convenient access to RPL documentation. For example, the Predefined Functions tab of the RPL palette should provide access to function documentation that is comparable to that contained in on-line help. This includes a description of the purpose of the function as well as meaningful names and descriptions for the function parameters. Similarly, the Predefined Function editor should provide convenient access to the same information. RPL editor dialogs should provide context-sensitive access to on-line help based on the current selection.
RiverWare documentation is currently authored with Adobe FrameMaker 10. It consists of about 30 related documents, made available only in PDF, with hyperlinks to specific sections. A one-page "menu" document provides access to the individual documents. This documentation is available from these places:
An important feature of FrameMaker used in RiverWare documentation is the ability to compose mathematical expressions, displayed with vectored graphics in the generated PDFs. The process of generating the PDFs includes use of an external tool to implement hyperlinks between PDF documents.
Appendix A presents an outline of the types of information in the RPL components of RiverWare documentation. This makes up six (6) of the thirty (30) individual RiverWare documents (including "Rulebased Simulation"). One of these is the RPL Predefined Functions document which currently defines 191 RPL Predefined Functions (in RiverWare 6.4).
RPL Predefined Function documentation is provided in a single FrameMaker-sourced document (currently made available in PDF). For RiverWare 6.4, it contains 191 functions. 77 of those contain mathematical formulas. One has an associated graph image. In the PDF, the formulas look very good, e.g. when zooming; they are apparently generated as vectored graphics in PDF. When generating HTML, it seems that only raster graph files are generated mathematical formula items (i.e. GIF or PNG or JPEG); the SVG scaled vector graphics format would be much preferable, as that is currently supported in all modern browser products (including in Qt WebKit, used within RiverWare).
Each RPL Predefined Function has its own section, with most of the information layed out in a table. Here is an example. Note: not all functions have an introductory sentence above the table; we are planning on moving that text to either the Comments section or under the table.
RPL Statements and Operators represent most of the sixty (60) buttons on the first tab of the RPL Palette. (See RPL Palette images in the next section). As a fundamental quality of the use of these buttons, each of these buttons corresponds to a selectable sub-expression within a RPL block or expression (shown in a RPL Frame). Help content for each of these items is presented as one row in a table of related items. Here is an example:
This is a good presentation for full-page media. But displaying content for just one item (one row) in the user interface, we may want to rearrange the content. (This should be done automatically either in the preparation of content for RiverWare, or dynamically within RiverWare).
In the future, we may want to consider a more sophisticated structure and process for all RiverWare documentation which would support ideal presentations in these media:
Some of the qualities we will want from a modernized RiverWare documentation system are:
Existing qualities and capabilities of our current document infrastruture which will continue to be important include:
This proposal focuses on two of the "Enumerated Item" topics (of the various RPL documentation topics enumerated in Appendix A).
 |
|
 |
|
The places within the RiverWare RPL GUI in which online help for these topics is relevant are:
Content for these online help topics could potentially be displayed in these places. These possibilities are discussed more below.
(1) Showing help within a panel within the dialog from which context-help was requested: There are several types of dialogs in which RPL Frames (editor panels) are used (this being one of the types of places from which context help would be requested). Each of these contexts, plus the two relevant RPL Palette tabs (see above) have their own GUI layout constraints, and would require different, and seperately implemented changes to add a "help content" panel. We're deciding that this lack of conformity and broad development scope is undesirable.
(2) Showing help within the dialog corresponding to the item for which context-help is being requested: Of the two types of help topics being considered, the only topic this applies to is RPL Predefined Function help. The "editor" dialog for the predefined functions is parallel with the editor dialog for user defined RPL functions. However, the main panel (which, for user defined functions is a RPL Frame) currently shows only this message: "See Online Help for documentation of predefined functions." This is a natural place to show documentation for the predefined function.
(3) Showing help within a single reusable (singleton) online help viewer window within RiverWare: Being that there is no dialog associated with individual RPL statements and operators, this is a reasonable place in which to show help topics for those RPL language constructs, whether from the RPL Palette button tab or from a selected statement or operator within a RPL Frame (editor).
(4) Showing help within an external viewer/browser. (This is what's currently being done for online help, to show PDFs in a PDF viewer, typically Adobe Reader). While are ways of having certain versions of certain viewers navigate to specific places within an external document, how this is done can be dependent on which viewer program the user has installed and configured. It is not generally a reliable approach for implementing primary help functions. If possible, this approach will be attempted for links within RPL Predefined Function and RPL language-construct displayed in RiverWare (to other online help published in PDF), we will not use this approach for that primary help content (i.e. the new functionality proposed by this document).
Given the set of requirements of a future, modernized documentation architecture (described above), it is a forgone conclusion that RiverWare documentation will need to support HTML as a display format* in addition to PDF. This is not to say that HTML should be the source format. We will want to manage our content with high level tools supporting associated meta-data (so that specific content can be accessed programmatically) and integrated advanced authoring capabilities (such as for mathematical formula display).
*Technically, conveying documentation content to the RiverWare program with XML and associated XSLT files for generating HTML would be the preferred approach. This is effectivly equivalent to providing HTML for display, but also with the advantage of providing well-defined and easily usable meta-data.
With respect to the current task of enhancing RiverWare to display some RiverWare RPL documentation within the GUI, an intermediate step is doing so with the HTML format -- regardless of how that HTML content is generated. In this way, any use of that HTML content by the RiverWare program will not have be changed very much when a new documentation architecture is devised.
Note: RiverWare's recently developed model report capabilities demonstrate displaying HTML content with CSS and JavaScript. This makes use of Qt WebKit in Qt 4.8 which continues to be in active development in Qt 5. Qt WebKit does support transforming XML documents to HTML via XSLT. It also supports SVG, scaled vector graphics, image file rendering. RiverWare is currently using Qt 4.8.5. We anticipate upgrading to Qt 5.2 or beyond within the next year or two.
Note: We did take a look at some possible technologies to display PDF (existing RiverWare documentation) with Qt in RiverWare. That would require integration of new special 3rd-party libraries (e.g. Poppler, or the Adobe PDF Library SDK). But the fact that PDF content is presented with a fixed-width limits the value of this approach, given that, in some contexts, we would want to display documentation content in narrower panels.
The scope of this particular development is limited to providing access to the most needed parts of the RPL documentation using our current document authoring procedures and tools (using Adobe FrameMaker), possibly accommodated with changes to the documentation source, an upgrade to a newer version of FrameMaker (upgrading from version 10 to 12), and post-processing of generated HTML files (if needed).
Content will be provided as HTML, and may contain references to image files of a format typically supported in webpages (PNG, GIF, JPG). To the extent possible, text should wrap to the available visible horizontal space, though the presence of an image may define the content width. In that case, a horizontal scrollbar may be displayed when the panel is narrow.
FrameMaker 10 supports HTML output (and also an alternative HTML-like XML output, which is very similar). It's got some problems which hopefully can be worked out -- possibly with the newest version of FrameMaker (version 12). The problems are characterized below.
Here is a comparison of the PDF and HTML output for a particular function. (See also a link to the actual generated HTML file, below):
http://cadswes2.colorado.edu/~philw/2014/RplDocDesign/Example1/Test1/RPLPredFuncs-30.htm
I have these observations about generating the RPL Predefined Functions document:
| PDF: |  |
|
| HTML: |  |
<A HREF="../Objects/storageReservoir.htm#10002" CLASS="XRef"></A>
As mentioned above, some of these problems may be addressed by a newer version of Adobe FrameMaker (i.e. upgrading from version 10 to version 12). But quite likely, we will need to post-process the HTML (or XML) generated from FrameMaker to fix things up. This would probably be a custom script, maybe written Python. We might also need the post-processor to generate a translation dictionary for filenames and/or anchors, for use by RiverWare.
The HTML files (and associated CSS and image files) would need to be distributed with the RiverWare executable (ideally in a distinct subdirectory). Alternatively, we could embed these files within the RiverWare executable using Qt Resources (i.e. as we do with RiverWare icon images).
RiverWare 6.4 Documentation includes six (6) documents covering "RPL" topics (including "Rulebased Simulation"). For the purpose of analysing the types of information to which this RiverWare enhancement could apply, three types of topics have been characterized:
(A) Enumerated Item Topics
(B) Discussion Topics
(C) User Interface Description
(A) Enumerated Item Topics:
(B) Discussion Topics
(C) User Interface Description
--- (end) ---