Improved Access to RPL Documentation -- Scope Notes -- March 2014
Phil Weinstein, CADSWES, edit: 3-13-2014 (d)
Project: BOR IDIQ - 19 Alb Enhancements to RPL

Reference Documents:

• R:\doc\RPL\EditorImprovements\2013\PriorityRpImprovements.2014.fm
• R:\doc\RPL\EditorImprovements\2013\RplImprovements.fm

  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.

Analysis Introduction

We are limiting the scope of this particular development to providing access to the most needed parts of the RPL documentation (e.g. Predefined Functions) using our current document authoring procedures and tools (using Adobe FrameMaker), possibly accommodated with some changes to the documentation source.

In the future, we may want to consider an entirely different structure and process for all RiverWare documentation which would support ideal presentations in these media:

• Hard-copy printing / whole chapters or books, or individual items.
• External viewer/browser
• RiverWare GUI / panels within existing application dialogs or separate windows.

Some of the qualities we will eventually want in a modernized RiverWare documentation system are:

• Flexible granularity. It should be possible to independently present individual sections of the RiverWare documentation, e.g. down to the level of individual RPL Predefined Functions or Engineering Methods.
• Variable width presentations with wrapped text. It should be possible to reasonably view documentation content within a narrow window or "panel". It should also look good in a printed page format.
• Single-source for all media: Print, External viewer (browser), RiverWare GUI panels and windows.
• Support for hyperlinks, contents and index generation.
• Support for easy authoring of mathematical formulas and inclusion of externally generated images.

It's virtually a forgone conclusion that RiverWare documentation will need to support HTML as a display format. This is not to say that HTML should be the source format. We will want to manage our content with high level tools which will support, for example, specification of mathematical formulas for display (as does FrameMaker). This will require a much broader analysis of available technologies and products.

But with respect to enhancing RiverWare to display more RiverWare documentation within the GUI, an intermediate step is doing so with the HTML format -- regardless of how that HTML content is generated. 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.

RiverWare documentation is currently authored with Adobe FrameMaker 10. We now generate only PDF. An external tool is used to define hyperlinks between PDF documents. FrameMaker has the capability to generate HTML, but has some limitations which would have to be addressed.

Note: I did take a look at some possible technologies to display PDF within Qt. It 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.

Functional Requirements

The Appendix, "RPL Documentation Content" summarizes the types of information in RPL documentation. This current effort will focus on the "Enumerated Item" topics:

1. RPL Predefined Functions (191 functions with images for about 77 formulas, 3 workspace screenshot details, 1 graph).
2. Possibly: RPL Operators / Buttons in the RPL Palette (60, in 8 categories).
3. Possibly: RPL Data Types (7) (10 pages).

Controls to show relevant content for selected "items" could be added to these RiverWare GUI components:

1. RPL Palette: Predefined Functions Tab: The documentation for the single selected predefined function would be shown in an optionally-displayed panel below the function list. This is similar to the optionally shown "Description" panel on the "User-Defined Functions" tab.
    
2. RPL Palette: Palette Buttons: Context menu operation on each of the 60 buttons -- to show relevant documentation in either a panel or a separate popup window (TBD).
    
3. RPL Editor panels (in various RPL Object Dialogs): Context menu operation on the following types of selected subexpressions -- to show relevant documentation in either a panel or a separate popup window (TBD):
   1. Uses of Predefined Functions
   2. Uses of RPL Operators (corresponding to RPL Palette buttons).
   3. Uses of RPL Values (description of one of the seven RPL Data Types).

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: HTML Generation

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:

1. This warning is generated many times:  The "ZapfDingbats BT" Font is not available. "Times New Roman" will be used in this session.
2. Text style properties are not optimal. See the larger text size in the HTML screenshot above.
3. Table cell background color is not generated. This applies to the first column in the parameter/comment table. As a result white text is displayed against a white background in that column. (i.e. the text is invisible).
4. Mathematical Equation (Formula) image generation is broken. (Google finds a lot of complaints about this):

	PDF:
	HTML:

5. There IS an HTML Setup option (Paragraph Formats >> From: Heading1) to "Start new, Linked Webpage" which generates separate webpages for each "Header1" element (which is how individual function headers are formatted in the FrameMaker document). Here is the generated top-level HTML file:
• http://cadswes2.colorado.edu/~philw/2014/RplDocDesign/Example1/Test1/RPLPredFuncs.htm
   
6. Text for manually authored hyperlinks is lost. (See screenshots above). In the HTML, I'm seeing this empty anchor (<A>) element. (Notice that there is no text between the <A> tag and the </A> tag):
   

      <A HREF="../Objects/storageReservoir.htm#10002" CLASS="XRef"></A> 

7. When generating separate HTML files, the names of the files are not related to the associated text. There is the same problem with names of internal section anchors when generating a single large HTML file.

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.

Other Technical Notes:

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).

Appendix: RPL Documentation Content:

(A) Enumerated Item Topics
(B) Discussion Topics
(C) User Interface Description

(A) Enumerated Item Topics:

• RPL Predefined Functions (191 functions with images for about 77 formulas, 3 workspace screenshot details, 1 graph).
• RPL Operators / Buttons in the RPL Palette (60, in 8 categories).
• RPL Data Types (7) (10 pages).

(B) Discussion Topics

• Units in RPL: Unit operators / Slot Value Units (2 pages)
• RPL Language Structure (8 pages)
• Developing Efficient RPL Expressions [in RPL User Interface] (1 page).
• Hypothetical Simulation Overview [in RPL Predefined Functions] (1 page).
• How Rulebased Simulation Works [in Rulebased Simulation]
  ... Rules and Rulesets, Rule Execution, ...

(C) User Interface Description

• RPL Debugging and Analysis Tools
  • Building and Validation Errors
  • Evaluation and Runtime Errors
  • RPL Debugger (12 pages)
  • Diagnostics (4 pages)
  • Rulebased Simulation Model Run Analysis Tool (link to Model Run Analysis doc)
  • RPL Analysis Tool (9 pages)
• RPL Editor Dialogs (32 pages)
• RPL Printing and Formatting (6 pages)
• Exporting and Importing RPL Sets (4 pages)
• RPL External Documentation (user defined) (14 pages)

--- (end) ---