Re: [perl-win32-gui-users] HTML comments on Win32::GUI 1.03_04

[Robert M. <rm...@po...>]

Arthur Schwarz wrote:
> 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.

Thank you for the time you have put in to write this mail.

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

Or, in various place, the version of the relevant DLL.  If you look at 
the new NotifyIcon documents, the version required for various features 
is mentioned.  This is often more accurate, as various of the DLL's get 
updated with (for example) IE updates.

> 2. A more extensive reference for methods, events, objects, etc. should 
> be provided.

Agree.  But equally I don't see that the Win32::GUI documentation should 
be teaching people about the Widows API - MSDN is good for that.  It'd 
be good to find a way of putting references to the relevant MSDN pages 
in the docs, in a way that would be easy to update whenever MS 
re-organise their site (which seems to happen more than occasionally).

> 3. A source book(s) that can be purchased and used as a reference should 
> be provided (if different from 2. above).

Now there's aiming high.  It's a nice idea, but has anyone really got 
the time?

> 4. Missing index file (global reference). An HTML file referencing all 
> other files was provided in v1.03 and is missing here.

Really.  There shouldn't be anything that was in 1.03 that's not in the 
latest beta.

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

Generally agree, but more specifically we need to start treating the 
different types of classes differently (e.g.Resources that don't take 
standard window options, like fonts etc. should reference the common 
options).

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

Windows/Controls should all have new() and AddXXX().  Other classes 
should have new() (and possibly other constructors).

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

Agree with the commonality. This would need us to agree the common 
format, document it, and them apply it.

> 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 ?

Sorry, but I don't understand this point.

> 9. A single file should be provided to describe all common notations and 
> formats used.

I think that Win32::GUI::UserGuide::Concepts would be the right place 
for this.

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

Currently all documentation is in-line with the source.  The way the 
source is split between pure perl and XS is somewhat inconsistent, but 
the documentation is already scraped from the source by a script to 
build the POD docs (from which the HMTL is generated).  I'd like for the 
options to remain documented near the code that implements them.

>   b. All options contain a default value (as appropriate) or a statement 
> saying that there is not default value.

Agree.

>   c. All options contain their values or references to files containing 
> their values. 'COLOR' or 'IMAGELIST' or 'FONT' just doesn't seem 
> descriptive enough.

Don't understand your point.

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

If you're suggesting that each constructor (for example) should list all 
allowed options, then I don't have a problem with that.

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

Agree.  Although in most cases it doesn't take long on MSDN to find out.

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

Each option should be sufficiently documented to allow someone with a 
little win32 understanding to know what the option will do for them - of 
course this is subjective, as a short description may be enough for me, 
but it won't be for others.

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

Contributions are always welcome.  If you download the source, then 
there's some documentation in the 'docs' directory explaining how the 
POD docs are currently built.  Take a look and see if you want to 
propose a change.  Additionally patches to the source files to improve 
the documentation is welcome.

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

Regards,
Rob.