Improved Access to RPL Documentation -- Revision Notes -- 4-11-2014
Phil Weinstein, CADSWES
Project: BOR IDIQ - 19 Alb Enhancements to RPL

This is a summary of review notes expressed as markups by Patrick and David to the 4-9-2014 draft of the analysis and design document, and some issues raised in accompanying review e-mails (see links below). Most of those have been applied to the draft document; the disposition of each of those markup comments is indicated in this Review Notes document. Significant issues raised are summarized as open issues.

Open Issues:

These are issues with respect to decisions documented in the Analysis and Design document. It does not include all the new issues raised in Patrick's and David's recent reviews. (See links to e-mails above).

  1. David will be writing an ("Executive-") Summary Section for the Analysis and Design document.
     
  2. I didn't incorporate into the document a proposal to bifurcate or otherwise restructure the RPL Palette Buttons documentation content for a reframing of "buttons" as "operations". But that -- and even more significant restructuring of our documentation source -- is on the table. (See both Patrick's and David's discussion e-mails).
     
  3. IMPORTANT: David was surprised (e.g. about the last sentence on page 16) that RiverWare will be dynamically extracting data from the HTML files. That is being proposed for (1) predefined function formal argument names, and (2) predefined function descriptions (with the possiblity of accessing other help fields as well). This is motivated by the idea of maintaining a single copy of our source (whether it be C++ or FrameMaker). We could hedge on that, and redundantly define formal parameter name and possibly description text in both C++ and FrameMaker.
     
    Heck. Maybe we really should just hard code use of Adobe Reader supporting navigating to particular "named destinations" within PDF files. We would still need some external processing to provide a dictionary of relevant RiverWare entities (RPL predefined functions and operators) to FrameMaker's arbitrary name destinations. (A Python script would do that, but we would discard the generated HTML -- this would just be needed to create that "named destination" dictionary built into RiverWare). And we could redundantly hard code formal argument names for predefned functions in C++ and be done with it.
     
    Another reason to consider reverting to navigating to places within PDF documents from RiverWare is the following. Patrick has steered treatment of operator help to navigating to a particular place in a complete document (which is represented in the current draft) AND also allowing the user to do so for RPL Predefined Functions (not yet in the current draft). My direction of using a Python pre-processor to extract and prepare relevant pieces in a structured HTML document didn't anticipate generating a complete presentable HTML version of the entire document (with added semantic markup), with workable links between all documents and everything. That latter detail requires preserving, and possibly working with the pretty-crazy-looking Javascript FrameMaker has generated to implement links in its HTML output. There will be other issues like this too. The point is, maybe this is getting too complicated if we want to, after all, navigate to particular places within these complete documents. (And again, we could decide to redundantly define formal argument names for predefined functions in C++ -- not a hard thing to do).

Suggested Revisions to 4-9-2014 Reference Draft:

Typographical and otherwise minor changes are omitted from this list.

General: I have reverted the reference to "expression types" back to "operators". Changes have been made throughout the document.

General: David requested that my inset (indented) detail notes be moved to footnotes. I've done that.

Page 1: (Not Changed): David suggested removing "(beyond version 6.4)" in the leading descriptive sentence, in reference to "proposed enhancements". That seems fundamental to me.

Page 2: (Not Yet Addressed): David's note: "What is the motivation for this task? What is the problem we are trying to address?" I'll leave that for David's writing of the new Summary.

General: My count of "191" functions was incorrect. That was based on what my prototype script had found which matched the number of items in the FrameMaker documents function index. I had overlooked the fact that many of the "191" are hybrid function sections, representing multiple functions. On my manual count there are 214 functions (in 191 function sections). Most of the hybrid function sections have two functions; one has three functions. The separate function names in a section are usually separated with a comma (",") but are sometimes separated with "and", "&" or "/" -- we'll want to reconcile that. The script and informal HTML schema will need to be enhanced to correctly handle hybrid function sections. I have revised the draft document where it had referred to "191" functions, and have added a detail about these sections on page 3.

Page 4: About this sentence, "We would like to make the following changes to the current RPL Predefined Function documentation:", David observes, "this type of language belongs in design section, not here. Instead say 'This structure has the following limitations:'". I changed it to this: "This presentation has the following issues:".

Page 6: I had indicated that, among existing capabilities of our existing document (tools/procedures) which we would want in a future document infrastructure, is: contents and index generation. David notes "???". I believe that Jim's process does include some tools which assist in the creation of the "contents" (index) document -- to make links work out. In any case, a future document infrastructure certainly should support those things -- I'm going to leave it.

Page 6: To my note about DITA ("Darwin Information Typing Architecture"), Patrick notes: "Isn't the XML Author mode even more designed for DITA doc?" Without spending time to dig into this now, I believe that the "structured mode" is closer to what we would want. Not sure about this detail, but I don't want to get too complicated with this idea here -- it's an area of research that is beyond the scope of this current task. I did however change this to: "FrameMaker’s XML author mode or structured mode".

Page 8: (Feature Scope Analysis section). Clumsy as heck. Patrick requested a rewording, and David suggested removing a redundant bulleted list of the subsequent sections. Done.

Page 11: (Formal argument naming conventions). Both of these two aspects of my original proposal have been reversed: initial letter case AND internal spaces. This is the new proposal:

Formal argument names could start with upper case or lower case letters (but they should be consistent in this regard; we need to decide which we will use).  Spaces will be allowed in these names.

Page 12: Regarding, "The two HTML files and associated image files are incorporated into RiverWare using Qt's resource system.", Patrick notes: "Does that mean that we can't look at the HTML files with a browser? Maybe it would be better to just distribute these help files with the PDF help files". There would be a way (by writing a temporary file). The thing is, since RiverWare will actually be pulling data out from the document, I'd feel safer about this if we bound the document to the RiverWare executable. We could even do both. (I didn't make a change to the document here). [But see the major Open Issue about the larger context of this question].

--- (end) ---