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

[Stefan Löffler]

Hi,

Am 2010-11-11 11:01, schrieb Paul A Norman:
> On 11 November 2010 19:51, Stefan Löffler <st.loeffler at gmail.com> wrote:
>> 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.

Great. OpenOffice should be no problem.

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

OK, so we'll stick to the Qt internal notations, plus some notes
somewhere that tell people how these things relate to QtScript, Lua,
Python, ... Fine with me.

>> * 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 :) :)

Sounds reasonable. Especially since I have a vague idea just who might
belong to the group of "someone"s ;).

Cheers,
Stefan

PS: We probably should continue discussions about details off the
mailing list so we don't spam people with (from their POV) irrelevant stuff.