Re: Reference Draft (4-9-2014), PDF Copy: EmbedRplDoc-Design2014-Phil-04-09.pdf

I reviewed the document and provided Phil with a marked-up copy, but I thought I'd mention a few broader points in e-mail:

(1) It occurs to me that our use of QWebKit within RiverWare constitutes a potential security concern. When they are being used to view documents that we have created, we can be confident that there is no risk, but if those HTML documents contain links to additional pages that we have not authored, that is another matter. It is perhaps worth mentioning in this design that all of the HTML content accessible via the proposed web viewer authored by RiverWare and safe.

On the other hand, we should perhaps revisit the Model Report preview panel and make sure that is is configured to disallow viewing of external documents (this is a configurable and I don't remember how I configured it).

(2) In section 1d, I'd re-work the sentence "RPL Expression Types represent most of the sixty (60) buttons on the first tab of the RPL Palette." For one thing, the types don't represent the buttons; for another, I'm sure what you're trying to say.  Perhaps something like: the the buttons are associated with various ways of editing the selected expression? Looking at the on-line help for the palette, I see that the term "operation" is used, as in: On the Palette Buttons tab, each of the buttons represents an operation. Maybe you could give this section a title like Expression Edit Operations or Expression Editing.

I think that the difficulty in coming up with a term is due to the fact that the two contexts in which the users might want to access documentation are very different. From the user point of view: looking at an expression and asking questions about it, like "how is that expression evaluated?" "what does the function being called there do?", versus looking at the palette and wondering "what does that button do?" or "what does that function do?". When the object of the question is a predefined (or user) function, the questions and answers are the context is not so important, but the objects are different in the other cases, though at times we might take them to the same place in the documentation -- they're asking a question about an expression in one context and about an edit operation button in the other case. it would probably be more clear to make this distinction explicitly in the document. I think this distinction is maybe less clear because the on-line help does not currently make the distinction. I would make more sense to me to document in one place the different types of expressions that are supported, and then in another place the edit operations associated with each of the palette buttons (which would often have a link to the documentation for the relevant expression type). Such a re-organization might also help with the statement documentation.

(3) My personal recommendation is to use an external web browser to view the expression and palette button help document (not a singleton Qt Web View window). I also think it would be nice to allow similar access to the full predefined functions document. This way users get the full-featured navigation, searching, etc., to which they are accustomed.

Patrick

We do not in fact support the embedding of arbitrary links in model reports (I thought we did) because we encode special XML characters like "<". This is good and bad -- good because it's safe, bad because allowing HTML-knowledgeable users to insert links into their reports might be useful to some.

In the future, we should avoid this encoding as appropriate and be sure to set the QWebPage::LinkDelegationPolicy for the previewer pane so that the previewer is not displaying arbitrary pages.

Patrick

See David's subsequent review e-mail (4-11-2014).