Subject: Displaying RPL Function Documentation in RiverWare
Date: Mon, 24 Mar 2014 23:56:38 -0600
From: Phil Weinstein
To: cadswes software group

At the software meeting today we talked about the "Improved Access to RPL Documentation" task. I would say that, both: (1) the approach I outlined could be streamlined (my estimate was huge), and (2) we might want to consider other approaches to getting key RPL documentation content into RiverWare.

Here is the current "analysis and design" document, and a project index -- not everyone has seen this:

• "RiverWare: Improved Access to RPL Documentation / Analysis and Design" (3-20-2014, 19 pp.)
  https://cadswes2.colorado.edu/~philw/2014/RplDocDesign/EmbedRplDoc-Design2014-Phil-03-20.pdf
• https://cadswes2.colorado.edu/~philw/2014/RplDocDesign/project.html

Considering how stable RPL Predefined Functions AND Language Constructs are -- and the great benefit of having documentation of those items IN RiverWare -- it really might make sense to just PORT that FrameMaker content to ideal HTML (with added semantic structure), and maintain TWO copies of source for a while, while we work out a unified publishing procedure. It's _much_ easier to quasi-hand-munge the HTML content generated from FrameMaker than create automated tools to repeat that process. And new edits are small, few and seldom.

Patrick (or Bill?) suggested that maybe we could choose to maintain RPL Predefined Functions in (only) HTML source (for all media) -- and work out inter-document links between PDF and HTML. (That part might be tricky).

I have been looking at Python XML tools, and that looks very promising. There are actually three standard Python DOM libraries, organized very well. One of them (ElementTree) uses native python maps for XML element attributes, and native lists for child elements -- very streamlined and easy to use -- (i.e. instead of a full formal DOM class collection). I'm going to experiment with this on my own. (It doesn't make sense to use SAX, but that is available too).

• Python Standard Library: Structured Markup Processing Tools
  http://docs.python.org/3.4/library/markup.html
  1. xml.dom — The Document Object Model API
  2. xml.dom.minidom — Minimal DOM implementation
  3. xml.etree.ElementTree — The ElementTree XML API

Once I get some very basic things running, I think that an HTML translator script would be quite easy. (At home, I do have minidom and elementTree "hello worlds" running with Python 3.4 on Windows).

So, a PORT approach for the RPL Predefined Functions AND Language Constructs content (to HTML), I think, would be reasonable to consider -- for the scope of a more limited sponsor project.

---

TECHNICAL CHANGE (to design): Instead of bringing RPL Predefined Functions AND Language Construct doc content into RiverWare as "191" separate HTML documents (albeit, via Qt Resources), I'm now favoring a unified HTML document, but with a distinct ("DIV") element for each function. (The HTML coming out of FrameMaker doesn't have that). (And same for Language Constructs). Qt Resources could still be used for binding those two HTML files to RiverWare (but we would just hook that up by hand).

---