Suggestion: Improving scripting guide and API documentation

TaskPaper
1

I’m not sure if anyone else has had trouble with this, but I am finding the scripting documentation hard to understand.

I really wish this page was fleshed out a lot more.

http://guide.taskpaper.com/creating_scripts.html

Many more examples would be helpful, especially for calling TaskPaper Javascript from the Applescript context.

I think the API Appendix could also benefit from a few introductory paragraphs better explaining how the objects logically relate to each other. Currently, this information is spread out across multiple pages and is quite sparse in detail or examples. Having API examples in both Javascript and Applescript would be very helpful.

1 Like
2

Having now made the transition from AppleScripting to JavaScripting myself, I find the API documentation quite full and clear – not a bottleneck – but I do know that shifting languages benefits from examples. (Don’t hesitate to ask here for examples or clarifications of particular things that come up).

On running the JS code from an AS context, it may well be a sensible transitional stage, but things get a lot easier when you start to call the JS from JS. In particular, if you call from AppleScript, the code

  • Needs to be a quoted string
  • Shows no syntax highlighting, and
  • requires escaping of a various characters, including string quotes.

(For making a more general transition, the obvious resources that come to mind are the Crockford book, and Marijn Havebeke’s Eloquent JavaScript, as well as the JXA Cookbook website, the JavaScript for Automation release notes, and comparison of AppleScript and JavaScript versions on Rosetta Code).

JavaScript is useful, of course, not just for web pages, but also for iOS, which is bound to remain an AppleScript-free platform.
(You can use JavaScript in Drafts4, TextExpander, 1Writer etc on iOS).

PS Perhaps one approach might be to start building up a scripting examples page on the Wiki ?

3

Thanks for the reply and offer of assistance. You’re probably correct that a large part of my trouble is unfamiliarity with JavaScript. I will just go ahead and learn the syntax.

4

As things come up, do send on particular queries, they would be very useful as a source of examples etc for Wiki entries. houthakker72 is a google mail address.

I will just go ahead and learn the syntax.

I think the core rewards of the syntax, at least for my uses, are probably:

  • .map()
  • .reduce()
  • .filter()
  • .sort()

and, of course, much richer built-in functions than Applescript, with baked-in regexes, url encode/decode etc etc

The Mozilla pages are the best - I would skip the w3schools : - )

(FWIW you can see AppleScript equivalents of map, reduce, and filter here:
Higher-order functions - Rosetta Code )

5

Thanks again for the generous offer of help. I may take you up on that. In the meantime, I have a lynda.com subscription, so will start with their JavaScript course. I watched this Apple video on JavaScript for Automation this morning and gained some insight from that:

https://developer.apple.com/videos/play/wwdc2014/306/

Hopefully, I will be contributing some useful scripts soon.

2 Likes