Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com)
Tinderbox Users >> Documentation and Tutorials >> Small agent adjustment to aTbRef5

Message started by Amber Vaesca on Dec 30th, 2009, 5:22pm

Title: Small agent adjustment to aTbRef5
Post by Amber Vaesca on Dec 30th, 2009, 5:22pm

Small thing, but wouldn't the following AgentQuery be better for /Atom Feed ?

inside("/RSS Feed")

Or maybe better yet have a Feeds agent in UTILS that both feed exports source from.

Another thing I was thinking of that might be cool is a form of internal version checking. It could be very basic, but the document could output a small page with a version number, and then another note could fetch this generated page from the web site. A very low priority agent would check the contents of both, and if they do not match, would move itself to the top level, set itself red, and declare that the local version is out of date.

Title: Re: Small agent adjustment to aTbRef5
Post by Mark Anderson on Dec 30th, 2009, 5:55pm

The altered agent? Yes, I could though in fairness the agent time is still fairly good and the idea is in part that it should help other with how to set up a feed. To someone lacking you're code skills they might not see that the atom feed is simply copying the result of the RSS agent and think both are necessary.

As to the other - it's a neat idea.  Happy to implement it if a solution emerges. Off to go and start updating for v5.0.1...

Title: Re: Small agent adjustment to aTbRef5
Post by Amber Vaesca on Dec 30th, 2009, 6:40pm

Good point, though I guess I was thinking more along the lines of demonstrating abstracting agent code when two or more agents are using identical methods to show how keeping things central reduces maintenance hassles in the long run, rather than trimming agent times which as you point out are already good. Perhaps abstracting is a bit much for an introductory document, though, you could be right there.

Here is a solution for the version checker which looks like it can be accomplished with a single note and attribute:

Attribute: MyVersion

Note (/UTILS/Version Checker):

Text: `5.0.0`
MyVersion: `5.0.0`
DisplayExpression: `$Name + " (" + $Text + ")"`
AutoFetch: `true`
URL: Set to wherever this note will generate.
Rule: `if ($MyVersion != $Text) { $Color = "red"; $Container="/"; $Name="New version available"; } else { $Color=; $Container="/UTILS"; $Name="Version Checker"; };`

The template for this item would export MyVersion instead of Text, so the website version would fetch with whatever is the current version of the document. However the user’s downloaded copy would have Text set to whatever the website is reporting. The reset stuff in the Rule is probably not necessary, I just had it in there for testing.

One problem with this is that older versions of the web site (say the user was using a pre-release) would report as well. Perhaps a numeric and then math instead of string matching would be an alternate solution.

I have tested this by setting the URL to a text file on my web server[1] that simply says ‘5.0.1’ and then setting MyVersion to ‘5.0.0’. When the document loads, it fetches the URL, notes the mismatch, and moves the note to the top level. The only issue is that it gets moved to the very bottom of the outline, but since OutlineOrder is read-only, I’m not sure how to get around that. Perhaps have the Rule modify the attributes of "/A Tinderbox Reference File" ?

This might be a good recipe for other Tinderbox documents as well that need to keep themselves up to date with a central source, or are distribution based periodicals, et cetera.

  • [1] If you want to test this, the url is here.

Title: Re: Small agent adjustment to aTbRef5
Post by Mark Anderson on Dec 30th, 2009, 6:49pm

Thanks, I'll take a look at this. Another complicated factor is that the folder for the current version changes as I try to leave previous versions so old inbound links don't die (aTbRef is more dynamic in structure than might be thought). The site is likely to move to atbref.com at some point (we have the domain) but the issue of re-baselining for new versions is a problem I've not really figured.

Re the agent issue - perhaps I need to add some notes to the TBX talking about the concepts it displays.  It's only very recently I've had any comment that implies anyone is using aTbRef in TBX or local HTML form. Now I know people are I'm happy to try and support that better.

Ooh, one other thing on the version font.  I often mend typos or add clarifications by exporting and uploading a single page.  I'll try to remember to update the index page and feeds too. Makes for more time for small updates but doing a full TBX export is much faster in v5.

Title: Re: Small agent adjustment to aTbRef5
Post by Mark Anderson on Jan 2nd, 2010, 11:04am

Amber's idea is neat and took me back into some features I rarely use - like AutoFetch. I modified things slightly.

New User Attribute: MyVersion (String data type)

New note at root level "Version Checker"

New note's settings:
$Text: 5.0.1
$MyVersion: 5.0.1
$DisplayExpression: $Name + " (" + $Text + ")"
$AutoFetch: true
$URL: http://www.acrobatfaq.com/atbref5/vc
$Rule: $MyVersion= $MyVersion(Change Log);if ($MyVersion != $Text) { $Color = "red"; $Container="/"; $Name="New version available"; } else { $Color=; $Name="Version Checker"; };
$KeyAttributes: MyVersion;URL;AutoFetch;ReadOnly

You don't need to set up the above - it's all done for you in the v5.0.1 aTbRef TBX I just uploaded.

Changes from Amber's demo:
  • I moved the checker out of /UTILS as that container contents are basically non-exporting hidden 'internals' for doc. So, the checker note is now at root level at the bottom of the document. Being at root level the exported checker file is at the website root level too.
  • As part of updating for a new TB release, I add a new agent inside 'Change Log' and its MyVersion value will be set for that release, e.g. currently '5.0.1' The parent Change Log container lists the releases in reverse order so the latest is the first child; it sets its $MyVersion to that of the first child. In turn the Version Checker sets its reference MyVersion from the Change Log.  That way the checker is automatically re-set in the TBX when I add into for a new version - less for me to forget.
A limitation of this is it doesn't tell users of local versions if I update the TBX outside a formal release; I do the latter pretty often.

Anyway, I hope this helps those using my TBX locally - either in TBX or output to local HTML pages. Once you have the v5.0.1+ aTbRef TBX you'll have a zero configuration update checker. If you want to cut down network activity you can always open the Version Checker note and temporarily toggle the note's $AutoFetch to false (un-ticked) though you're then responsible for remembering to turn it back on.

For 'local' users there's one other tip. If you can't download the images but have web access, the $URL for notes using grabs currently  holds an absolute URL for the image (NOTE: I'm not promising to keep doing this as I don't use it and it's a pain to keep updated). To make your local pages use my online images, open the templates using images, and find the ^do(ImgTag... references. You then replace the macro's first parameter:

Title: Re: Small agent adjustment to aTbRef5
Post by Mark Anderson on Jan 14th, 2010, 12:27pm

If you're a local user of the aTbRef TBX download, check out this section of aTbRef online about improvements to the version checker. In short I'd added a 'build' checker to allow you to keep up with between-version updates. I've also added an automation to the HTML export to (on my system) zip the source TBX and place it in the root of the export folder ready for up load. The later is partly because my Transmit favourite setting for aTbRef have the 'my stuff' pane set to the HTML output folder whereas the TBX is actually a folder above that.  The 'Zipper' note - and it template - are what do the work. It is deliberately at the end of the outline so it's the last task and not impeding export of HTML pages.

I still have to remember to save the TBX before I export. TB doesn't have internal support for Applescript but I'm thinking I could drive the UI via the Universal Access method.  It's a shame there's no Export to HTML call that doesn't invoke a dialog.  Thus a note could call an AppleScript that saved the TBX and invoked an Export to HTML - I'd still have to press the button on the export dialog - but perhaps that no bad thing.  Anyway, that's an enhancement for another day - but suggestions welcome.

Title: Re: Small agent adjustment to aTbRef5
Post by Mark Anderson on Jan 14th, 2010, 1:51pm

Just fixed a couple of typos and more importantly the TBX zip no longer includes path info so unzips in site rather than recreating it's path on my system. If you downloaded the TBX since my previous post, pick up the latest. The build checker should alert you anyway. For reasons I don't quite understand, the checker AutoFetch can take a minute or two to sync properly - even if I press the 'Fetch Now' button on the Network dialog.

Title: Re: Small agent adjustment to aTbRef5
Post by Amber Vaesca on Jan 14th, 2010, 5:55pm

This seems to be working well for me. Originally I was going to say just forget minor updates, as a system like this would potentially be more interesting for items other than typo fixes and other errata, but having a second agent monitor the minor versions is a good way of handling the situation. One suggestion, I’d change the red text version to better indicate the announcement addresses a minor release. The way it is right now, “New build of aTbRef v5.0.1 available for download!”, it is somewhat ambiguous. I don’t think “build”, while technically accurate to a code junkie, is the best word choice.

One other small improvement, link these two notes to “Obtaining the aTbRef source TBX file”. That would make finding the right download spot quick and easy.

It is a pity that Tinderbox doesn’t do interpretive language style type coercion, so that two strings can be compared numerically. Right now, for instance the current aTBRef file is at build 16, while the server is reporting 10. While a new version is not actually available, it appears as such because it simply using negative equality matching.

On responsiveness of AutoFetch, I too have experienced similar issues with it. At times the fetch routine will take a long time to gather anything, even if manually running fetch, other times it snaps things up instantly. I’ve also had occasions where fetch returns a null ending up with a blank note. This happens most often in a Tb document I have with about six fetches getting database information from some web-site APIs.

Title: Re: Small agent adjustment to aTbRef5
Post by Mark Anderson on Jan 14th, 2010, 6:43pm

Very happy to change the message. Care to suggest a better title? How about "aTbRef for v[version] has been updated. Download from $MyURL". I've added $MyURL as as a key attribute to each checker note. If the note turns red, open the note and click the globe nest to $MyURL. Simple enough?

Ah fixed the comparison.  The build checker was emitting a space before the number - tracked to TB's ANNOYING habit of inserting white space, on an arbitrary basis before pasted content.  Fixed that so now the vbc contents should be just a number. I coerce it to a number ($MyNumber=$Text) then text if $MyBuild is less than $MyNumber.

Update with above changes uploaded. See what you think.

[Later...] Here's the new-style checker:

Title: Re: Small agent adjustment to aTbRef5
Post by Amber Vaesca on Jan 14th, 2010, 7:18pm

Good solution with the coercion, though I think perhaps the logic is backwards, shouldn't it be $MyBuild < $MyNumber?

Also, I think "edition" is a good nomenclature, and matches back to the more commonly understood paper publishing models.

The $MyURL solution is perfect.

Title: Re: Small agent adjustment to aTbRef5
Post by Mark Anderson on Jan 15th, 2010, 3:42am

$MyBuild < $MyNumber? Doh! I was forgetting that my local version should always be in date. Fixed: edition 21 uploaded.

I think it's worth using Cmd+3 to open the Network dialog and push the "Fetch now" to get the update process working. Indeed I find I need to push the button 3 or 4 times before TB actually responds.

Beyond my skills but it did occur to me, from making the 'Zipper' process that the last note to export could actually go on to call an FTP upload or network synch. That said I tend to do updates by hand in Transmit as most automation tools are too slow/dumb to do it right.  Synching local and remote sizes can take 20 minutes whereas a full upload is a fraction of that time - partly because the latter uploads up to 8 files at a time and the synch does one (is there a workaround?). Also, an update process needs to know that the key change markers (basically the root folder contents) should be uploaded last.

Still I note this latter idea in case it might be of use to others doing this sort of output.

Title: Re: Small agent adjustment to aTbRef5
Post by Amber Vaesca on Jan 15th, 2010, 9:49am

Not too sure about Transmit as I've never used it. YummyFTP has a mode where you can set up an FTP link to monitor a directory structure on your hard drive, and whenever anything in that structure changes, it will automatically upload the changes to the server. It's a bit like mirroring, but without the initial full scan. Perhaps Transmit has something similar. Another thing it can do, which I would imagine Transit can as well, is create a watcher.app which sits in a folder and uploads changes to a single directory. It's a much more simple version of the above. In the case of the former you need yFTP open in order for the magic to work, in the case of the latter all of the connexion information is stored in the app and it will automatically spawn FTP processes even if the parent application is closed. I'm not trying to sell Yummy, but merely am guessing that since these two compete, they have some parity that you might find available in Transmit.

As for merely uploading one or two known files,

ftp -u "ftp://user:password@ftp.host.com/dir/to/files/" file_one file_two
works really well and can be executed safely from unattached processes. Just be careful because, since it is meant for non-interactive usage, it will blow away whatever is in the way on the server without confirmation.

Perhaps something like that, since these last two are static and can be assumed to always need to be uploaded (or it doesn't matter if the server is overwritten anyway), could be used to handle the special cases required.

Title: Re: Small agent adjustment to aTbRef5
Post by Mark Anderson on Jan 15th, 2010, 10:10am

Thanks, some nice ideas now.  I think I'll stick to 'manual' FTP for now - if only to give more chance for me to avoid mistakes.  It's not like I upload the whole site every day.

Title: Re: Small agent adjustment to aTbRef5
Post by Mark Bernstein on Jan 15th, 2010, 10:23am

I use Fetch's Mirror function for ftp; a good compromise of speed and simplicity.

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.