Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com)
http://www.eastgate.com/Tinderbox/forum//YaBB.cgi
Tinderbox Users >> Documentation and Tutorials >> aTbRef for v4.6+
http://www.eastgate.com/Tinderbox/forum//YaBB.cgi?num=1236247859

Message started by Mark Anderson on Mar 5th, 2009, 5:10am

Title: aTbRef for v4.6+
Post by Mark Anderson on Mar 5th, 2009, 5:10am

The subtle syntax shifts (improvements!) from old export code-centric styles to action as the core syntax means a massive amount of review & update for aTbRef, so apologies that the new version is out yet. My aim is that it now won't use deprecated examples or concepts (even if they are still supported)  - at least as primary examples - as this is most useful for both the new user and longer-term users wishing to update their knowledge. Much more work than I thoughts, so it may be weeks not days as I'm busy elsewhere, too.

Note that v4.6 will open all your pre-4.6 TBXs as new copies, this is to enable you to review/fix and broken syntax whilst leaving a 'clean' old copy in case you need to roll back. Eastgate's worked hard to support old usage where possible, but you may need tweak some of your queries and action codes. Export codes should continue to function as they did previously.

Title: Re: aTbRef for v4.6
Post by Paul Walters on Mar 5th, 2009, 8:28am

Mark, any good reference takes time.  aTbRef is one I use every day, so it will be worth the wait.

Could I suggest that in the interim you or Mark B. post a guideline in the forum for what you believe the best practice is for performing a quick examination of a pre-4.6 document to ensure compliance with 4.6?  I'm looking for the most likely 5 or 10 things in syntax that might need revision.

Thanks!

Title: Re: aTbRef for v4.6
Post by Mark Bernstein on Mar 5th, 2009, 10:27am

For the main issues that people might encounter moving from 4.5 to 4.6, seehttp://www.eastgate.com/Tinderbox/updates/Tinderbox46/UpdateTo46.html.

This won't be a very big deal for the overwhelming majority of users.  As you can imagine, I myself use a bunch of Tinderbox documents, some very old, and some very tricky.  Only one (my weblog) needed significant corrections, and that took perhaps half an hour.  One or two others required a minor adjustment.

Title: Re: aTbRef for v4.6
Post by Paul Walters on Mar 5th, 2009, 10:42am

Thanks!  I'll bookmark that.

Title: Re: aTbRef for v4.6
Post by Mark Anderson on Mar 5th, 2009, 11:59am

[This was drafted (too slowly!)m against the first post in the thread.]

Oh brother... it's simple in concept but wordy to explain. Most legacy stuff should still work (thanks Eastgate!), but the likely breakers are things that weren't quoted should now be quoted, specifically string values including simple operators */-+ (and probably a few more). For string/set attributes, literal values are quoted.  Boolean and Number type  values are not quoted. Color type values are quoted. Date type values, where they are strings (literal dates and format strings) are quoted.

An exception to quoting (apparent) strings is names/paths. $Color is this note's color.  $Color(Some note) is the color of a note called 'Some Note'. $Color(Alumni/2001/Fred Smith) is the name of a note called 'Fred Smith' with the path from root of 'Alumni/2001'. We don't, by convention, quote names or paths (although it seems you can do so without problem).

Placeholder names - now termed 'designators' - such as child, parent, can now also use paths.  $Name(parent(parent)) returns this note's grandparent's note name. I presume (untested) you can nest further, e.g. $Name(parent(parent(parent(parent)))) and such but I suspect doing so will make things run a bit slower and anyway shouldn't really be needed in real world use (i.e. there's likely a limit but you shouldn't encounter it).

Queries are now TB "expressions" - think of that as meaning action code.  Indeed there are now new action code operators of all the #query codes, so #between(... becomes between(... otherwise changed except where the first point above indicates string parameters values may now need quoting. Apart from syntax within queries, the main impact of the change is a more unified use of code

In Action code (not Export code) we now $-prefix all attribute references both sides of the expression: $Color=$MyColor or $MyString="Krusty". There is one place attribute names aren't prefixed and that is in the query-like use attrbruteName(pattern). In the latter think of it as an action operator that executes a regular expression search for the pattern against the attribute whose name is used as the operator name. Thus generically we have a figurative operator op(regexp) and to search attribute MyString's value for one or more digits, we'd use MyString(\d+) or MyString(red) to match the syllable 'red'. To target a different attribute just use its name, e.g. MyOtherString(\d+).

Export code syntax remains unchanged - you don't need to quote text (except in a few where it's expressly requested such a creating link sets) and you don't need to $-prefix attribute names (again except if/wher.  Note that ^value($MyString)^ equates to ^get(MyString^ and ^value($MyString(parent)^ equals ^getFor9parent,MyString)^ and ongoing best practice is to substitute action code for export code wherever possible.

If this all seems a bit wooly it's because Eastgate have pulled of revising a lot of stuff under the hood without breaking anything much in current docs. As v4.6 shakes down, I'd expect the boundary cases above to be clarified and where legacy support conflicts with new needs it will fall away so don't adopt a policy of no change.

Oh, and I fully expect Mark B will tell me something above is wrong.  I too am feeling my way!



Title: Re: aTbRef for v4.6
Post by Mark Anderson on Mar 26th, 2009, 6:58pm

OK, this is an early draft of aTbRef v4.6. Please note the new base URL : http://www.acrobatfaq.com/atbref46/index.html. I'd suggest not bookmarking too much inside this release for now as things may change.

Errors/omissions/ambiguities welcomed - please! Unless you want to discuss a point publicly I'd suggest using the email link for my sig to sent comments to me directly.

The syntax changes in v.6, whilst subtle on the surface, have necessitated a fair amount of updating and restructuring.  We've more explicit string quoting, ^code deprecated outside the export context and queries now becoming action expressions.  Although there's a bit of pain for existing users, I think these moves represent a real tidying of code that's going to make it easier for people to learn.

But, comments please!  (I reserve the right to use English English spelling - outside code examples where US spelling matters  e.g. $Color vs. $Colour <g>).

[If anyone eagle-eyed spots this is published with a beta, that's we've found some unintended consequences with very permissive export filenames & Windows servers (such as aTbRef lives on). You're unlikely to meet the issue unless you're using things like | and ! in your note names. Suffice to say a fix is in hand. The current content is based on v4.6.1]

Title: Re: aTbRef for v4.6
Post by Paul Walters on Mar 26th, 2009, 7:20pm

Mark, thank you very much for your work!

I think that the Google search is looking at the 4.5 version of aTbRef -- links clicked there go to the 4.5 version.

Title: Re: aTbRef for v4.6
Post by Mark Anderson on Mar 26th, 2009, 7:45pm

Oops - good spot. I've re-exporting as as write. Fixed pages should be up within the hour. The glitch you report affects only Google searching - until fixed pages are up. [Done - hope that's now fixed]

I've also found some outbound lniks from included content aren't linking correctly though not sure why as yet.

Keep the input coming!

[NOTE, as yet there is no source TBX to download - I'm waiting for the new structure to settle first. If you simply must have a copy now, email me]

[Note: should now have fixed and issue with screengrabs being referenced from the wrong location.]

Title: Re: aTbRef for v4.6
Post by Mark Anderson on Mar 27th, 2009, 1:56pm

Image links fixed (more here) and ^ancestors^ format recovered.  In v4.6. ^ancestor^ now default to an HTML bullet list like other list-generating codes. To recover the old format, you must add a format string like so: ^ancestors("",""," : ","")^

Title: Re: aTbRef for v4.6
Post by Paul Walters on Mar 27th, 2009, 4:50pm

Mark, I'm unable to get the Google search return results in the new aTbRef.  No matches for any search.  Also, I think the ^ancestor^ default HTML bullet list might not be in the 4.6 release notes TBX.

Title: Re: aTbRef for v4.6
Post by Mark Anderson on Mar 31st, 2009, 10:25am

aTbRef46 updated today. Lots of removal/deprecation notes added, code examples updated for v4.+. Any errors/corrections to me as before, please.

Title: Re: aTbRef for v4.6
Post by Mark Anderson on Apr 2nd, 2009, 4:59am

Source TBX uploaded here, ZIP includes export templates.

Title: Re: aTbRef for v4.6
Post by Mark Anderson on Apr 10th, 2009, 5:09am

The aTbRef46 site is updated to v4.6.2 as it the TBX download. Hope it's of use.

Title: Re: aTbRef for v4.6
Post by Mark Anderson on Apr 15th, 2009, 5:17pm

I noticed a few comments recently about peole 'discovering' stuff in aTbRef that been there for ages. I figured an outline of all the pages might help expose the depth of content (1500+ pages), so here's a site map page:
http://www.acrobatfaq.com/atbref46/aTbRefSiteMap.html

Title: Re: aTbRef for v4.6
Post by maurice on Apr 17th, 2009, 10:42am

Thanks Mark - that outline makes an enormous difference!

Title: Re: aTbRef for v4.6
Post by Mark Anderson on Apr 17th, 2009, 12:11pm

Good! I've since added a link to the outline on all pages - look top right, above the TB logo.  I've done a lot of fixing tidying in the last couple of days and just uploaded the current TBX to my .mac pages. The TBX includes all templates so you can see how the outline is produced.

Title: Re: aTbRef for v4.6+
Post by Mark Anderson on Jun 25th, 2009, 7:01pm

The current aTbRef (baseline v4.6.0) has been updated for v4.7.0. - change log for the new version is here and it mainly covers new/changed features. For info on lots of minor fixes see the Release notes TBX accessed from the app's Help menu.

The manual has added a few references to point to new features but for now your best starting reference for new things is probably the aTbRef v4.7.0 change log page.

Please let me know if you find any missing images, broken links, typos, etc.

~~~~~~~~~~~~~~~

The Help-as-TBX site is not updated yet. I need to difference the v4.6 and v4.7 manuals and haven't had time to do that yet.

Title: Re: aTbRef for v4.6+
Post by Mark Anderson on Jul 14th, 2009, 4:40am

Further updates to reflect things clarified by the recent thread on textual analysis, re text import, exploding, Text Export view. Reflecting the fact queries are now conditional action code, content from the Agent Queries section has been re-factored to Actions & Rules or Objects & Concepts. Note: some inbound links from here and other sites may now not work.

Title: Re: aTbRef for v4.6+
Post by Paul Walters on Jul 14th, 2009, 7:34am

Mark,
I've noticed a minor disconnect in the documentation.  AppleScripts added to the Scripts pop-up menu in the Note sidebar should be uncompiled.  The manual (4.7 and predecessors) tells us to use compiled scripts (incorrect).  The Wiki says to ignore the manual and use uncompiled (the correct answer).  aTBRef mentions adding scripts, but is silent on their correct flavor.

Title: Re: aTbRef for v4.6+
Post by Mark Anderson on Jul 14th, 2009, 8:01am

Good point. Happy to correct that but terminology has changed.  In Script Editor, the default option for saving is as 'script' which I believe equates to 'compiled'.  Uncompiled format equates to what - 'text'?

Title: Re: aTbRef for v4.6+
Post by Mark Anderson on Jul 14th, 2009, 8:10am

Just tested as in today's terminology 'uncompiled' = save as 'text'.  Now see here, here and here which have been updated to reflect this.

Title: Re: aTbRef for v4.6+
Post by Paul Walters on Jul 14th, 2009, 8:12am

"Compiled" and "Uncompiled" are terms used in the TBX documentation (as noted above) - as you mentioned, the terms are outmoded.  I've found that the Tinderbox Scripts pop-up in the sidebar accepts scripts saved as "text" - and rejects .script files.

Title: Re: aTbRef for v4.6+
Post by Mark Anderson on Jul 21st, 2009, 4:39pm

The aTbRef46 resource has been updated to v4.7.1. The TBX download is not yet available as I need to re-write my.mac pages since Homepages were retired.

Title: Re: aTbRef for v4.6+
Post by Paul Walters on Sep 19th, 2009, 10:16am

@mark-a: I think the links to sub-pages on Attributes > Attribute Groups > Appearance in aTbRef are broken.  This is to pages such as Badge, Border, etc.  (There are other ways to find those pages; this is not critical; just FYI).

Title: Re: aTbRef for v4.6+
Post by Mark Anderson on Sep 19th, 2009, 11:41am

Thanks. No, really, I appreciate the heads up. There are a lot of pages nad incremental update mean things sometimes get out of alignment. I've just nuked the existing site and done a full re-upload which should fix this. Give a shout if you still have problems.  I think an agent somehow got set not to export it's children, plus at v?? the TBX reset itself to use long filenames rather than 8.3-style ones. I think I've flushed all the bad links now.

Always happy to get reports about typos or broken links.  It's the best proof there is that people are reading the pages!

Title: Re: aTbRef for v4.6+
Post by Mark Anderson on Sep 28th, 2009, 6:23pm

Updated the Date format page to correct the examples for the "L" format. Originally (and in the manual still) the examples relate to what is now the OS' "full" date. Over time something's changed and the "L" output is the OS "long" date, which is likely more useful; the manual will get updated in due course.

Meanwhile, it's also very easy to make up a custom string for the OS "full" date format. The following example is for a UK "full" date (i.e. day/month order): "W, d MM y"

Use as in:
    Export code:  ^get(MyDate,"W, d MM y")^
    Action code:  format($MyDate,"W, d MM y")

Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com) » Powered by YaBB 2.2.1!
YaBB © 2000-2008. All Rights Reserved.