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.
art
