[texworks] Scripting: import libraries, retrieving saving text. web location, Api

[Paul A Norman]

On 11 November 2010 19:51, Stefan Löffler <st.loeffler at gmail.com> wrote:
> Hi,
>
> I finally got to take a look over what you've put online so far. It's
> really amazing! This definitely has the potential to become a great
> source of information for script authors.
>
> A few things I noted so far (these are mainly personal opinions, feel
> free to ignore ;)):

No I've come to always appreciate you comments thanks Steffan.

>  * The correct spelling is "TeXworks", you seem to be mixing some
> spellings (TexWorks, TeXWorks, ...)

No worries.

>  * I'm personally not a big fan of the typesetting in the pdf (mainly
> the spacing/kerning seems odd), but I'm probably spoiled by TeX ;)

Yes we'll be able to follow the export to Open Office route to then
export a LaTeX version and "get it right" :)

>  * I'd remove the "System requirements" in "Getting Started". They are
> of interest only for compiling Tw, which is beyond the scope of the
> manual. As far as scripting is concerned, the "system requirement" is to
> have Tw (and possibly plugins) installed
>

No worries, good point, its really just a copy and paste place holder at present

> Am 2010-11-08 12:17, schrieb Paul A Norman:
>> Got a bit more done on the TW.target hierarchy.
>>
>> Stefan, I'll be able to pass you the source for all that once its
>> useful - even as an Open Office document or LaTeX from there, but if
>> you're not using MS Windows, the actual help generator may run under
>> WINE but would require a couple of things if it would work there at
>> all. If you still have access to Windows I can give you the .hnd file
>> for HelpNdoc, that will all end up on the web with the 'finished' help
>> any way.
>>
>> Any one with any Scripting Api or related notes, even if rough, please
>> throw them at me.
>>
>> I'll do my best looking through the .cpp(s) but I am not a native C++ developer.
>
> If you want, I can certainly give you a hand here (e.g., writing (some
> of) the function documentation) if you send me the relevant sources and
> tell me what conventions to follow. (and if I find the time ;)).
>

That would be a really great help thanks.

Time is the thing for me too, I can only do so much of this each day.
And sometimes nothing. I am going to aim at ten Api points a day to
get through - with hopefully some better days as well.

Would Open Office be ok for us to work in?

I could generate an APi list when I finish writing the skeleton if you
like, and pass it to you for "revisions" - don't worry about
formatting it.

(Just use OpenOffice Menu:// Edit / Changes / Record

You choose it again before saving the document.)

Then I'll edit it back in,  and format it, in the help file generator.

> BTW: Two things I'd like to put up for discussion:
> * Whether to use things like QWidget* or QString in the function
> documentation. It exposes script authors to the underlying internal
> implementation, which should not be necessary and is probably
> contra-productive (at least for new scripters). Maybe call them just
> "window", "string", etc. or something? Or does this require more effort
> (e.g. in telling people what we mean) than it does good
> (Also note that
> ideally, this documentation should be implementation-independent, i.e.
> be useful for Python/lua as well)

Yes while focussing on QtScript (which is what we ourselves will use
mostly internally along with a bit of Python as it appears now) I
thought that  I'll start out doing what I know (QtScrpit) and let
things develop from there.

I've been looking at it from what you're saying "ideally, this
documentation should be implementation-independent" and have seen it
as  worthwhile to use  Qt types and casts, as our Rosetta stone to the
diverse script's equivalents as explained below.

So I've been thinking to introduce the script writers to the
JavaScript conventions / types and relate them to Qt's equivalents
from the beginning with an introductory section and equivalence
tables.

Yet make it possible for any one to glance at the Api and have a good
immediate sense of what to do (examples).

I had always thought to take the "educational" route, but introduce it
in a way that eases them into it gently. Explain  what is actually
happening as much,  and as simply, as possible.

Whether most "scripters" yet know it or not, they will actually have
encountered most of the needed concepts already in different ways in
other things they have already done, even in the browser technologies.

There will be real pay offs I think - especially as QtScript --
related to the underlying Qt framework, is appearing in many more
applications now, as is JavaScript in many fomrs being used far more
widely outside the browser.

Also, it will be easier for many QtScript/JavaScript, Lua, and Python
people to have the same Qt reference material to work off - every one
on the same page, able to relate things through the realities of the
actual Qt underlying framework directly to their own environment.

Rather than thinking,  'what is the JavaScript equivalent of this Lua
thing', instead: 'what is Python doing here related to Qt, and from
that point of reference what does JavaScript/QtScript do with that
same Qt thing' - common point of reference less room for confusion.

Plus really importantly  this will prepare people both for using
findchildren type functions more accurately, and ui(s) development
where you need to think a bit in Qt terms.

ui is where a lot ot people will want to head - so carefully and
slowly introducing any necessary Qt concepts in an educational way
from the beginning will again save a lot of Mail List work and lessen
the steepness of the learning curve.

If we get the writing of this stuff right now - we won't have to keep
trying to explain it later or can just refer to a reference page or
link.

I'm sort of doing that kind of moving people from known things to new
things in a different way with the intros to TW, TW.app and TW.target,
trying to draw comparisons to known working models that some will
already be familiar with.

    http://twscript.paulanorman.com/docs/html/files/TW.html
    http://twscript.paulanorman.com/docs/html/files/app.html
    http://twscript.paulanorman.com/docs/html/files/target.html

> * What to do with functions that are not intended (or useful) for
> scripting? Should these be included in the documentation (marked
> "internal", for example)? Or just omitted to make things cleaner and easier?
>

I have been  thinking all along that  we'd better list them and
comment them as either not available, or inaccessible, otherwise when
Scripting picks up in usage volume, *someone* will just have to answer
questions about them time and again on the Mail List :) :)

> Cheers,
> Stefan
>