Re: [lmi] Generating screenshots automatically

[Greg Chicares]

On 2009-02-17 01:10Z, Vadim Zeitlin wrote:
> On Sat, 14 Feb 2009 14:51:18 +0000 Greg Chicares <address@hidden> wrote:
> 
> GC> On 2009-02-12 15:15Z, Vadim Zeitlin wrote:
> GC> 
> GC> > 3. Currently only wxPanels are supported, and not wxDialogs or wxFrames.
> GC> 
> GC> For lmi, the hardest part is annotating the tabbed dialogs, which are
> GC> large, complex, and likely to change often; so that's where automation
> GC> is most beneficial.
> ...
> GC> When that's all finished, we can return to wxMenu etc. in a future month.
> 
>  I'm afraid my question was insufficiently well-formulated. In fact I
> didn't think at all about wxMenu and wxToolBar. And I'm very glad to leave
> them for the future as I have no idea how to make menu screenshots right
> now anyhow.
> 
>  All I wanted to ask is whether each individual window for which we want to
> generate a screenshot is always going to be a wxPanel or if we also need to
> be able to take such screenshots of wxDialogs (I don't see any wxFrames at
> all in LMI XRC files). I.e., to be even more precise, should this work for
> "dialog_containing_preferences_notebook" and "dialog_containing_notebook"?

Screenshots for wxDialog are of less immediate importance to lmi than even
for wxMenu or wxToolBar (which we're already putting off to the future).

In particular, screenshots for the two XRC dialogs you named wouldn't be
very useful. Those dialogs add only a static-text control for diagnostics
and a few customary pushbuttons. All those controls are unlikely to change,
so, if we feel a need to document them graphically, we can make screenshots
manually.

IOW, the error-prone, costly, and tedious screenshot-maintenance chore that
we seek to alleviate stems almost exclusively from wxPanel. We can leave
everything except wxPanel for sometime in [a later month, never).

> GC> > 4. You need to specify the name of the panel to load from the XRC file 
> as
> GC> >    shown above. The tool could also iterate over all panels but it's not
> GC> >    clear what should be used for the output file name and the title in 
> the
> GC> >    screenshot in this case (currently both can be specified on command
> GC> >    line).
> GC> 
> GC> Iterating over all panels automatically is pretty important.
> 
>  Ok, I'll add it, thanks. Vaclav, is there a way to find all top-level
> objects defined in an XRC file or will I need to parse XML to do this? (VQ1)
> 
>  Also, I assumed we wanted to have one PNG (or one HTML) file per top-level
> object, but maybe we want to have one output file per each input XRC file
> or even one output file combining everything defined in all input XRC files?

We want one output file per wxPanel. Thus, for 'skin.xrc', this command
  grep wxPanel skin.xrc
identifies the twelve output files we'd want.

> GC> > 5. HTML is currently hardcoded but could be made configurable by using a
> GC> >    template in an external file.
> GC> 
> GC> I'm not quite sure what the template would look like;
> 
>  Something like this:
[snip example]
> This (ugly) syntax is used by google-ctemplate library (see
> http://code.google.com/p/google-ctemplate/).

I'd rather avoid adding a dependency on one more library.

Hardcoded html doesn't bother me much.

>  And the syntax is not that important anyhow. What counts is that you (or
> anyone else familiar with HTML) could modify it in any way you want in
> order to achieve the appearance which you prefer. E.g. you could replace it
> with
[snip example]
> And just rerun the program -- without any need to recompile it.

I don't mind recompiling.

> GC> but might this question vanish if we pursue the alternative in (2)
> GC> above?
> 
>  I don't think so, rather on the contrary: if you produce HTML you probably
> want more control over it than over PNG. E.g. you may want to be able to
> specify CSS for the different elements and so on.

Perhaps someday we'll want to make it fancy, but OTOH we may find that we
don't really need to.

>  So my question still remains: do you need to be able to configure the HTML
> produced by the program (whether it's output directly or used to generate
> PNG) or do you think hardcoding it inside the program itself is acceptable?

I'd rather hardcode it.

> On Sat, 14 Feb 2009 15:33:16 +0000 Greg Chicares <address@hidden> wrote:
> 
> GC> Yet another variation: instead of drawing lines or arrows to connect a
> GC> control to its annotation, enumerate both serially. Then the annotations
> GC> read as footnotes. Here's a specimen wherein to save time I number only
> GC> five fields, but I think it makes the idea clear:
> GC> 
> GC>   
> https://savannah.nongnu.org/file/skin_plan_panel-numbered.png?file_id=17447
> 
>  I really like this, it seems very clear. I wonder if we need to keep the
> window names in the output if we do it like this -- aren't they superfluous
> now?

Although they do appear superfluous at present, we can easily remove them
at any time. But I think they may soon become useful.

For example, item #3 in the screenshot above is [abbreviated]:

  <object class="wxRadioBox" name="DefinitionOfLifeInsurance">
      <help>Definition of life insurance</help>
      <label>Definition of life insurance</label>
      <content>
          <item helptext="Definition of life insurance is cash value 
accumulation test">CVAT</item>
          <item helptext="Definition of life insurance is guideline premium 
test">GPT</item>
          <item helptext="Do not comply with US definition of life 
insurance">Not 7702 compliant</item>
      </content>

We see $(label) rendered graphically, and a "footnote" (which will become
html) formed as '$(name): $(help)'.

Now, certain input fields are defined at the bottom of this page:
  http://www.nongnu.org/lmi/pasting_to_a_census.html
and this field isn't one of them, but someday it ought to be defined there
(or somewhere equivalent). It's enumerative in nature, and end users have
asked for a complete dictionary that specifies all permissible enumerators
by internal name, e.g.
  DefinitionOfLifeInsurance {GPT, CVAT,...}
The internal name is important because they can paste it from a spreadsheet,
or find it in an xml input file. So, ultimately, we may want a footnote like
this:

  <a href="input_dictionary.html#DefinitionOfLifeInsurance">Definition of life 
insurance</a>

which is, schematically,

  <a href="some_page.html#$(name)">$(help)</a>

and, visually, the <help> element, hyperlinked via an invisible internal
$(name) to a definition elsewhere.

> GC> What's most important, though, is that numbers are probably easier to
> GC> implement than arrows,
> 
>  Absolutely.

And IMO they've turned out to be clear and unambiguous, as well as
cost-effectively minimalist. And even attractive.

> GC> The form of the numbers is an implementation detail, but let me toss
> GC> out an idea or two here. Placement of the numbers on the screenshot
> GC> could become tricky if we want them aligned with titles. In the specimen
> GC> above, I manually placed 2-5 just outside the northwest corners of their
> GC> controls, but put 1 in a different spot. Instead of letting this devolve
> GC> into another NP-hard problem, why don't we just center each number on
> GC> the center of its control?
> 
>  I could do it like this. OTOH placing them near the label shouldn't be too
> difficult if we assume that the label is always the control preceding the
> one we're processing (which should be always true, except for radio boxes,
> as usual).

Your example here:
  https://savannah.nongnu.org/file/skin_panel_20090219.png?file_id=17486
looks good enough. If we later find any problem with the above heuristic,
we can fall back on centering the numbers and see if we like that better.

> GC> I generally avoid using color on dialogs, but it can nevertheless be
> GC> introduced by OS theming. I would suppose that most themes would let us
> GC> use a full-hued red as a contrasting color in general.
> 
>  In the worst case I think it wouldn't be a huge restriction to ask people
> to switch to the standard theme when producing the screenshots. After all,
> the screenshots are supposed to represent the standard view of the dialog
> and if you make it in some kaleidoscopic theme people might be confused.

That's yet another advantage of embedding your code in lmi: it would
let users generate documentation customized according to their theme.

> GC> Drawing a circle around each number might make its footnote-nature more
> GC> apparent. I suppose that'd be nice if it's not too difficult to do.
> 
>  No, at least not on the image itself. I don't think it's possible to use
> rounded numbers in wxHTML easily though

Again, your example here:
  https://savannah.nongnu.org/file/skin_panel_20090219.png?file_id=17486
seems clear enough: circled-numeral graphics above, text numerals below.

>  This finishes the discussion of the current version of the tool, let me
> now turn to its future evolution possibilities:
> 
> On Sat, 14 Feb 2009 18:29:35 +0000 Greg Chicares <address@hidden> wrote:
> 
> GC> On 2009-02-14 14:51Z, Greg Chicares wrote:
> GC> > Okay, you're rendering the screenshot and its annotations all together 
> into
> GC> > one graphic, as we originally discussed.
> GC> > 
> GC> > Perhaps we should consider an alternative idea:
> GC> >  - render the screenshot into a graphic
> GC> >  - embed the screenshot in an html <img>
> GC> >  - write the annotations in html <p> paragraphs
> GC> > Then the result is html instead of (e.g.) png. What I think we gain
> GC> > is that the html annotations could someday contain hyperlinks.
> GC> 
> GC> Let me say more about that. Here's a brief example:
> GC> 
> GC> <h2>The "Plan" screen</h2>
> GC> <p>
> GC>   <img src="plan.png" alt="[screenshot]">
> GC> </p>
> GC> <p>
> GC>   <em>ProductName</em>:
> GC>   <!-- All we have today is a one-word explanation: -->
> GC>   Product
> GC> </p>
> GC> ...more annotation paragraphs
> 
>  There is no problem with generating this, of course. As a side note, this
> probably automatically answers GQ2 above: if we do it like this, we need
> one PNG per top-level object

Agreed.

> (unless we embed the image in HTML itself
> using data:// schema but I don't think it's reasonable to do it for such
> big bitmaps)

http://en.wikipedia.org/wiki/Data_URI_scheme#Disadvantages

http://en.wikipedia.org/wiki/Just_Say_No

> but presumably only a single HTML file for all inputs.

I think we want one output file per wxPanel.

>  I also think that this answers GQ3: we absolutely do need a template
> defining the non-variable parts of HTML in this file as otherwise you'd
> almost surely need to manually edit the tool output every time after
> running it.

I don't understand. I guess it's time for me to look at the code. Then we
can avoid an abstract discussion: either I can demonstrate some simple-
enough way to do it without an html template, or I cannot.

> GC> The problem, though, is that then there's no obvious way to create
> GC> this html from the WXXRC file.
> 
>  It's worse than non-obvious, I still don't see any satisfactory way to do
> it even after discussing it with Vaclav.

In light of the ensuing discussion, I'll try to look for a way. Perhaps
I'm relying on some aspect of the problem domain that's simpler than I
have expressed.

> GC> Well, I could replace the <help> text:
> GC> 
> GC>   <object class="wxListBox" name="ProductName">
> GC> -     <help>Product</help>
> GC> +     <help><a href="external.html">External html link</a></help>
> GC>   </object>
> GC> 
> GC> but then I've broken the wxHtmlHelp facility.
> 
>  Actually my preferred solution for the current state of wx is to do
> something like this and define a custom help controller which would
> separate the information which really needs to be shown in
> context-sensitive help from the rest. This is a bit heavy but should work.

If you think self-generated screenshots would be a generally-useful facility
for wx, then this is a question for wx developers. Otherwise, just for lmi,
it does seem a bit heavy.

> GC> I could propose adding a <userdata> element to the "common attributes"
> GC> enumerated in 'tn0014.txt' for all controls--of course, only if that
> GC> makes sense for wx in general--but if <userdata> is wanted today, then
> GC> surely tomorrow a need for <userdata0>, <userdata1...> will arise; so
> GC> that's probably not a good idea.
> 
>  Indeed. We need a generic extension mechanism.

Which might already exist: the discussion that follows here and in later
messages indicates that <lmi:any_custom_tag_I_want> is valid, by design.

> GC> I guess that'd mean we'd have to parse the xml, but then again we'd
> GC> save the effort of rendering the text to png. What do you think?
> 
>  This would certainly work and Vaclav thinks that this is the best
> solution. I don't like it that much because currently XRC parses XML but
> simply throws away this information and I will need to reparse it again to
> recover it. I'd prefer to be able to hook handlers for custom tags into XRC
> parsing process but this would require some changes in wx. Please let me
> know if you think it could be worthwhile to do it from LMI point of view.

Maybe this is the best way:

On 2009-02-17 16:22Z, Vaclav Slavik wrote:
| you'd only have to scan the already-parsed wxXmlNode tree

but you and Vaclav understand this better than I.

>  To finish with this I'd just like to mention the possibility that we might
> not need any extra information at all: in principle we could just always
> generate HTML of the form
> 
>       <a href="details.html#window_name">window_help</a>
> 
> and write details.html manually and simply ensure that the anchors with the
> right names are defined.

AIUI, this means that we'd have descriptions in WXXRC <help> elements,
and parallel descriptions somewhere else--in html, or in code that
generates html.

Ideally, we'd have no duplication. We already haven't achieved that ideal:
this command
  grep -A3 ProductName skin*.xrc |sed -e'/name=\|<help/!d'
shows that "<help>Product</help>" is duplicated in every 'skin*.xrc' file.
That would seem to argue for writing code to generate these files. (In the
long term only--I have no wish to do that today.)

OTOH, maybe that's the wrong ideal. If your firm starts selling insurance,
though not in the US, then 'skin_tt.xrc' might have custom <help> for you:

  <object class="wxRadioBox" name="DefinitionOfLifeInsurance">
      <help>Veuillez sélectionner toujours le troisième bouton radio</help>
      <label>Definition of life insurance</label>
      <content>
          <item helptext="Definition of life insurance is cash value 
accumulation test">CVAT</item>
          <item helptext="Definition of life insurance is guideline premium 
test">GPT</item>
          <item helptext="Do not comply with US definition of life 
insurance">Not 7702 compliant</item>
      </content>

All that being said, however, it would seem wrong to increase the amount of
duplication.

> On Sun, 15 Feb 2009 16:38:57 +0000 Greg Chicares <address@hidden> wrote:
> 
> GC> On 2009-02-14 22:28Z, Greg Chicares wrote:
> GC> One more idea that might be useful: can your work be embedded in lmi?
> 
>  I don't see why not. But I don't know how exactly do you plan to invoke it
> from the LMI GUI so for now I'll continue developing it as a standalone
> utility -- but we will always be able to plug its code wherever you want to
> call it from, it's already packaged as a simple function taking a couple of
> parameters and returning a wxBitmap (this would be slightly more
> complicated with HTML though).

Could I ask you to post it as an attachment here
  https://savannah.nongnu.org/support/?106639
?