"J. P. Gilliver (John)" wrote in
:

Sometimes I wish someone would just give me the answer. I would if
asked. Saves time letting them hang themselves reaching for un-needed
complexity, or wondering if a thing ever worked right. As a kid I
learned best from breaking

Any good teacher will say it's better to guide you until you find the
answer for yourself; you'll be much more satisfied, and know _why_ it's
the answer as well as just what the answer is.


That's true, but takes time. Coders seem to dislike spending time on anything
other than their work, even when willing to help, so will usually give a
terse collection of function details, arguments for them, etc. (And
occasionally, RT(F)M should be taken to mean 'I don't know, and don't want to
admit it or spend time discussing it'). I recently got the impression that
coders who use C++ may not even know how to open a file in ANSI C.

The API references usually just give the calls in an abstracted manner, parts
to assemble, without working context. The wxWidgets guide goes further, it
does exactly this too, but almost always gives a short example of actual code
where you can see contexts like path specifiers to file-open type functions,
stuff that may not be explained otherwise, or known to the newcomer who looks
at the documentation. By running the example, more useful deductions can be
made, and even on the page, it's more self-explanatory.

I remember that the 'worked example' was a major part of even the driest
textbooks from schools in the last quarter of the last century, the idea
being that study of it would show one context, and the aim being to
understand how to modify it to fit others.

People now seem to think that asking for this is asking for fish when we
should learn to fish. It's not, it's like asking for a working fishing rod.
Which is reasonable, If we break it, we learn more than if we never see it
work to start with. In a situation where teachers are at hand (most coders
probably had good teachers, maybe went to universities too) there are people
to call on regularly for help. Fortunately the wxWidgets CHM manual doesn't
assume this. It's much more aimed at people from independent situations who
need to code to solve a problem, rather than those who are part of an
academic network.

I think the reason why that method is lacking in older API references may be
because when the MSDN network was new, the assumption was that coders would
get together and ask each other. When that happens, people don't think to log
working details as if the supply will dry up otherwise, let alone organise a
coherent record fit to publish. Stuff like that usually came out of book
shops. I remember that a reduced set of that MSDN stuff was released on
multiple CD's but it was a rambling set of disparate output, far from the
organised publication that wxWidgets manuals are. But we do at least HAVE a
Win32API reference, which counts for a lot.

stuff, but I only learned a lot fast if it worked in the first place.
That's a hell of a motivator, especially when the stuff wasn't mine
because the sooner I fixed it, the less trouble I'd be in.

(-:

The lessons were memorable.


Re HLP files, I agree, most of them ARE tiny. I wasn't prepared for 20
MB.

(That's a minor novel - or did it include some images?)


It did, but not many (and most of them tiny). Even novels are fairly small. A
scan of The Time Machine (H.G. Wells) is less than 0.5 MB in DOC format, and
90.5KB zipped. If it were plain text it would be smaller. This API reference
is nearly 60MB when fully unpacked and converted to either RTF with images,
or HTML. (Actually I keep wondering if stuff got left out, in that 7MB CHM.
Looks complete though, as far as I can tell).