Well, maybe I am pretty optimistic here. Yet, for a user to sit and
scroll the list of several hundred chapters, eventually hoping to hit
something that says "Minimum Required Version" - it just seems
hopelessly, and may discourage a developer from making usage of other
than the very most "safe" instructions. Then, to ask the next user do
the same job, and the third user, the fourth user - you all get the idea.
Chip, the reply you refered, not only seem pretty weak. It even holds
very little water. Now, imagine you are a new-comer in the developer
community. You are aware that the last oficial release of WinEyes is
8.4, and that 9.0 is on its Beta. So searching the CHM manual for those
two numbers is of course an alternative. And you perhaps happen to know
that the Scripting-capability was implemented from version 7, so you
could search for 7.1, 7.2, 7.3, and all the way up to 8.4 - getting
certain hits on some of the numbers, and no match on the rest. But then,
how about version 7.5.1, 7.5.2 and so forth? What chances does any
new-comer have, to know which version numbers to look out for? And even
we "old guys", who has been scripting more or less since day one, how
much do we remember all the versions released? Even so, should I happen
to have a list of version numbers, it would take me an hour or so, to
scroll the list of versions, making a manual search for every one of
them - and see what hit-and-miss results I would get. Sorry, but I have
a slight feeling, that not even the developers at AISquared does this
kind of skeeming. Just seems ten times more simple, to reference a list
of requirements, whenever you want to make sure your app can be run
under any version of the screen reader.
As it stands now, chances are that we might release a new app, claiming
that it can be run under a certain version. Then after a few days, we
get a ton of messages, telling us that it failed for any user who happen
to run it under that version. OK, in the dream-world, every user would
be just about up-to-date with their screen reader, and hence it should
not matter. You go ahead and develop your app, make use of whatever
instructions are available, and everything jumps the scene troublefree.
Yeah, that is the dream of it. Fact is, though, that in certain places
the newer version of the screen reader may not even yet be available.
should you, as the developer, have a realistic chance of ensuring that
user even in those areas are being cared for, the list of
requirement-bound instructions, would really prove helpful.
On the other hand, GW (AISquared) has the access to all the text in the
manuals. Even I, with no idea about the structure of CHM files, would
say it should be a matter of a breeze, to write a small script for this
job. Once you have all the text files, your script would simply crawl
the whole collection, and search out any chapter with the minimum
requirement and save the list to a file - which you in turn would
include in the CHM archive. Really staff, how troublesome is that? :)
For the end-user, I am not aware of any easy way of scripting such
"chapter-harvesting" on a CHM archive. But for the staff, who has the
access to the underlaying material it really doesn't seem much of a job.
In general, I do agree with you Chip. Here we once again have a
situation, where it would have been nice with a little more than a Quick
Reference manual. Whether that being a WIKI, or it be some kind of an
internal implementation in the CHM, or whatever solution would be the
more smooth for all parts.
I do see it as a rather tremendous job, to manually sit and read all the
manuals and making notes of every chapter that has a requirement tied to
it. Once such a harvesting job had been done though, it should be quite
easy for the staff to maintain it, whenever there would be new
instructions added to the API, or old ones get their requirements
changed for some reason.
One thing I got from your message Chip, under the risk of having
misunderstood you, is that this wish for a list, not only is for the
basic Developer's Reference but also would apply to things like
GWToolkit. I agree. In one way, did we have a standalone document,
holding this list, it could have included sections for any part of the
API that would have this kind of requirements. So, maybe simple as this:
Make the whole thing a plain straight forward text file, and put it on
the App Central for everyone to download.
David
On 1/12/2015 1:09 PM, Chip Orange wrote:
> I absolutely agree David, and I've asked for this before. GW at that
time told me to do a search on the contents of the app developers
manual, for each and every version number released! I thought that was
an unbelievably poor support answer, so I second this request.
>
> One thing that will help at times, is to look through all of the
readme files for each WE release. Changes to script commands are
documented there, but I have no idea how you go about getting older
read.me files.
>
> The other info which should be included in this info should be apps
they've released which are meant for other app developers to use
(starting with the toolkit, going on to anything else which provides
shared objects or methods which have a minimum version of WE associated).
>
> If we had our wiki back, and if this couldn't make it into the
official documentation, it would be a nice example of an ever-growing
sharable document.
>
> Ok, I see everything but the kitchen sink is in this email, so I'll
stop for now; but yes, app developers could use a little support now and
again.
>
> Chip
>
>
> -----Original Message-----
> From: David [mailto:trailerda...@hotmail.com]
> Sent: Saturday, January 10, 2015 5:10 AM
> To: gw-scripting@gwmicro.com
> Subject: Minimum Version Required
>
> This might likely be for the staff, or anyone who wants to undertake the
> job. :)
>
> Now, imagine you are developing a new app. You base the app's activity
> on a set of instructions, given to you through the scripting environment
> and the GWToolkit. As you build the app code, you may or may not, read
> the individual chapters of the Developer's Reference. All you know, is
> that the app runs nicely on your computer, which may have the newest
> version of the screen reader installed.
>
> Later on, you may update the code of the app. Things may change in the
> provided set of routines - like now that the new Browse Mode is being
> introduced. And, I could likely come up with a few more cases, where
> your app would base its activity on certain routines, that will require
> a minimum version of the screen reader, before it will run smoothly.
>
> True enough, if you are good and sit half a day with the reference
> manual, tiredlessly looking up each and every instruction call of your
> app, you may be able to determine if any of the thousand of calls you
> make, would have a restriction tied to it. But sorry for asking, how
> many of you driven developers do ever do that? :)
>
> My idea here, would be if we could please have a table all gathered and
> provided, which would hold all the instructions that have a minimum
> requirement tied to it. The table should hold the instruction, and the
> version number for its minimum. And, it should be quick to find, like
> directly from the root-level of the chapter list in the reference
> manual. I then could simply bring out that table, and quickly check if
> the instruction I am going to base my next activity on, would have any
> minimum restriction. At least I, would find that far more simple and
> quick, than having to look up numerous chapters, and jump in and out of
> the reading window, search box and so forth, in the chm window. If we
> could have it all collected on one and same page, I would only have to
> work that one page in my restriction hunting.
>
> Hope this idea makes sense, and that we could have such a list provided.
> I guess, it should not be too much for the staff to collect the list,
> based on the raw text of the chm file. Otherwise, the only way I could
> think of, is that someone had undertaken the grand job of scrolling all
> the chapters of the manual, looking out for the minimum requirement. So
> staff members, would you be willing to provide us such a quick-list?
>
> Thanks,
>
