Well, being in a Lofty mode, I did a review of all options that I could find in the latest HTML file download. Recommendations follow. As always, these are comments and not criticisms. The effort to get to this point seems huge and worthwhile, and I am greatful.
I do have a cross-reference of Options vs. HTML files in excel, and would like to e-mail it to others for review, use, and change. It shows where each option is used, and it says something about the information given in the HTML documentation (good for tips, good for help, values provided, and defaults provided). The document is in sore need of review.
Comments (only on %Option):
1. The version of the Microsoft Windows GUI being implemented should be provided.
2. A more extensive reference for methods, events, objects, etc. should be provided.
3. A source book(s) that can be purchased and used as a reference should be provided (if different from 2. above).
4. Missing index file (global reference). An HTML file referencing all other files was provided in v1.03 and is missing here.
5. Commonality of topic. Each HTML file should be organized in exactly to same fashion. Topics which are deliberately absent should be marked as deliberately absent. In looking for %Option (always given under 'new' something), sometimes it's there, sometimes it's not. However, for a casual user, a missing topic can be interpreted as missing by inadvertance or by deliberate intent. If the topic is marked as deliberately missing then there is no ambiguity of purpose.
6. Commonality of invocation. There seems to be two means to create a GUI object. Either as a 'new' something or as an 'add' something. If both are appropriate, both should be included, and if one should be excluded, then it should be explicitely excluded.
7. Commonality of invocation description. All descriptions should look identical. For example in ImageList.html we see 'new(X, Y, FLAGS, INITAL, GROW)' with a comment concerning the use of 'common options', and in Button.html we see '
new(PARENT, %OPTIONS)' with descriptions of the options. It would be a good thing to describe acceptable formats in a single place and to use them throughout.
8. Do not use an abbreviated or truncated form for an invocation. My beef is that the use of 'new' for options doesn't appear correct. Shouldn't it be 'new Win32::GUI::Object(%OPTIONS)' or 'new Win32::GUI::Object(<positional parameters>, <non-positional parameters>)' or ?
9. A single file should be provided to describe all common notations and formats used. 10. Options. Options have inconsistent uses, values, and order within the HTML documents (my llittle excel spreadsheet can be used to show this). For ease of maintenance and ease of description I suggest the following:
  a. All options be collected into a single file and a program developed to distribute the information to HTML files from this file. Maintenance is reduced because only a single file needs to be reviewed and modifiied..
  b. All options contain a default value (as appropriate) or a statement saying that there is not default value.
  c. All options contain their values or references to files containing their values. 'COLOR' or 'IMAGELIST' or 'FONT' just doesn't seem descriptive enough.
  d. Where the distribution of values is not symmetric to all objects, then a separate mechanism should be invented to indicate which objects can use which values.
  e. All options should include at least a 'tip' to indicate what it does. A statement that 'Set/unset option' is non-descriptive. The question is not whether the option can be turned on or off, but what service does the option perform.
  f. All options may contain 'help' information. Information more extensive that the 'tip'. I note here that it seems to be possible to generate a 'tip' from an extensive 'help', and so, given a 'help' a 'tip' is unnecessary. (A mouthful if I do say so myself.)
I am willing to provide any support in implementing these features that you'd like. I admit to being the lowest common denominator in any group of my peers, but a ready hand is a ready hand.
The gathering of descriptions and information on options has already been done (the excel file). I intend to continue this effort on events and methods and option values. This is to provide me with a global picture of what has been implemented in Win32::GUI and to enable me to build an editor based on that. For my own effort, any comments and/or support is more than welcome.