Arthur Schwarz schrieb:
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).
Probably a simple MSDN link should be added to the POD.
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.
You probably mean options defined by the parent, should link upwards to
the parent definition, so that all child options, also the derived ones,
are listed.
9. A single file should be provided to describe all common notations and
formats used.
Pleased provide a pod for this, no excel sheet.
> 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.)
e+f: You mean a headline and a MSDN link.
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.
Where is the excel?
pod is the only preferred format. html is generated from this pod.