Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com)
Tinderbox Users >> Off The Wall: Feature Ideas >> Log and debug mode?

Message started by james a. foster on Nov 20th, 2011, 7:03pm

Title: Log and debug mode?
Post by james a. foster on Nov 20th, 2011, 7:03pm

It would be great if one could turn on a "debug mode", which would display a log of each activity that TBX has done and one what items. This could also include a "failed to parse action" message or some such.

I've found the hardest thing about developing TBX repositories has been debugging actions and rules. When I screw up the syntax of something, TBX silently ignores it.

The option of making TBX squeal would be nice.

Title: Re: Log and debug mode?
Post by Mark Anderson on Nov 21st, 2011, 7:02am

I used to think the same but I'm not sure what logging would add - unless it looked inside the rule process, though I suspect the latter would be expensive, not least considering the work needed vs. the number of users able to use it properly.

Remember that output of any action code is normally to set/alter one or more attributes. Here are a few things I've learned from testing action & export code…

You can view attribute values in many ways other than note window key attributes (and more effectively so):
In addition, if your initial try with code doesn't work consider:
  • Breaking down nested and chained expressions so each step results in an attribute. You can then inspect interim values/data formats and check they are as expected.
  • Verifying queries in agents before adding any action code.
  • Using an agent to test queries used inline in find(), collect() and the like. Does such an agent query return the items you expected in your action code?
  • The context of action when using offset attribute reference - i.e. an attribute other than the note in context.
  • Allowing for the possibility that some codes may note evaluate inputs - i.e. they only accepts literal values.
  • The context of execution when using agent actions - are you setting the original's attributes or just those of the alias in the agent? This matters in relation to intrinsic attributes.
  • Making a test rig with a smaller dataset to filter out the noise of testing on an already large/complex TBX (this also pre-empts accidental data damage from badly written user actions). Bear in mind that notes, prototypes, attributes, etc., can be drag-copied from a main to a test TBX so set-up is not as onerous as it may appear.
  • Using 'code' notes with built-in Code prototype. The 'Code note' concept is storing action code in text of (another) note. This makes it easy to see/edit code and use intending, etc., whilst any edits still have immediate effect.  
  • Using ^action^ to record template-only calculations back into user attributes for later inspection - useful with complex exports.
  • Using HTML view's export button to export a note/file. The latter button will always overwrite existing exported files whereas full export may not. This is because the full export looks at whether source attributes have changed. Thus changes in templates code aren't 'seen' and the process can become obfuscated in complex include exports.
  • The effects of $HTMLDontExport and $HTMLExportChildren on the use of ^^include^^. The later can't return data from a note set to not export.
  • For $Text export using ^^text^^ remember the effects of $HTMLMarkupText and $HTMLQuoteHTML.
  • The slightly different effects of ^^title^^ vs. ^^value($Name)^^ and ^^text^^ vs. ^^value($Text)^^.
  • ^^text(plain)^^ exports ASCII and ^^value($Text)^^ exports UTF-8. Non low-ASCII characters in ^^text(plain)^^ will export as UTF-8 codes rather than the intended character. This is not normally the intention in a plain text context.
Having in the past been the same route as the OP - in terms of wanting more logging - I've come to see that the above answer most questions. Those that aren't answered are because either design intent of a code is not clear or it is not (seemingly) operating as documented.  In the former of those two better documentation is the answer and for the latter the user should contact support - ideally with a reproducible set of steps or, if you've made a text rig sent that. My aTbRef attempts to flesh out the documentation (it would overload the manual) and don't overlook the TB Cookbook. Lastly, bear in mind the app is under constant evolution. Things slip through as it's hard to predict (and test) every way users may find to employ action codes. As time goes on more codes evaluate inputs but there's no exact documentation of that (and you can't prove status just by black box testing); hopefully this latter aspect will tighten up.

[edit]Added 4 more export-related bullets to the end of the longer list above.[/edit]

Title: Re: Log and debug mode?
Post by russ lipton on Nov 21st, 2011, 11:34am

@Mark - so helpful, hope you will put into the reference document, with even more tips if possible. Perhaps others have ideas as well? I'm not sure I can add much. I do some of the things you mention, but this is a weakness in my own 'game' ...

Title: Re: Log and debug mode?
Post by james a. foster on Nov 21st, 2011, 11:49am

@Mark: excellent reply. thank you!

I agree that a "best practices" document would be helpful, with this in the "Developing complex actions" section...

Now if only I had a place to keep helpful notes like this!  ;)

Title: Re: Log and debug mode?
Post by Mark Anderson on Nov 21st, 2011, 1:01pm

Yes, in writing the answer I was thinking this out to be an aTbRef article (if not in the manual too). As regards aTbRef, it won't be for a couple of weeks though as I'm busy tinkering with that doc so won't be adding any new pages in the interim.

I should add that I wish I was as diligent in applying the above techniques as my comments might make it appear. The irony is that it's so easy to dive into quite complex things in TB that one also all too easily moves quickly past the point of realising "Ah, I ought to make some modular tests, before using my live data.". However, the worst penance for that error is usually only frustration. Most care needs to be taken when synching with other systems or using complex cascading actions. The latter, especially are worth testing on a deliberate testbed and/or a copy of real data before using your real live data. As with much in life you generally find the correct point for shifting to a deliberate test by getting it wrong … (at least) once.  :)

Saving notes like above?  Open your reference TBX, add a note and open it's text window. Now open the URL such as http://www.eastgate.com/Tinderbox/forum//YaBB.pl?num=1321833832/1#1(my notes upthread) in a web browser and drag the URL into the taxt pane. $URL is set and displayed as a key attribute. Or just drag the URL into your main view (outline, map, etc.) and a new note is made for you with $URL set.  Or just use Yojimbo, DevonThink, etc. to store the URL.

Incidentally, from experimentation, the thread URL syntax is like this:


The red is the UD for the thread.  Leave off the rest of the above after the ID and the thread opens at the opeing post.  Want to open the thread scrolled to answer #4? Just add the blue bit above, in this example '/4#4' after the UID. BTW, no idea why the post number's repeated, i.e. why it's /4#4 not /#4.

Title: Re: Log and debug mode?
Post by Paul Walters on Nov 22nd, 2011, 5:43am

Regarding saving helpful forum posts - the "Print" button in this fourm at the top and bottom of most pages is a hidden gem.  It opens a very nicely formatted printer-friendly display of a complete thread (i.e., all pages of that thread) that's suitable for saving to PDFs using the browser's own print-to-PDF feature.  Of course this is most useful when a thread has pretty much run its course.

Title: Re: Log and debug mode?
Post by Mark Anderson on Nov 22nd, 2011, 5:54am

Good tip - thanks. I'd never tried that. I presume that if you always print the same source page (URL) the PDF's default saved name would be the same. If you always save such PDFs to the same folder then if the thread continues you can save a new PDF back over the old, as required, with no great extra effort.

Your suggestion of using this 'print' archive method strikes me as very useful. Some topics aren't generic enough to push on into general documentation. Nicely the 'print' data still maintains working URL links to other threads, specimen files, etc. Re linked demo files and such, I'd always suggest saving your own local copy of such files as their source URL may not live for ever.

Side note, for those who don't look at release notes, if you're re-reading saved solutions from months/years back it is well worth checking that the app hasn't fixed/improved the issue since the original thread.

Title: Re: Log and debug mode?
Post by Paul Walters on Nov 22nd, 2011, 7:20am

Since the forum "Print" button merely yields a URL with a particular format that invokes the printer-ready CSS for a forum thread, that URL can be saved as a bookmark, added to Tinderbox, DEVONthink, and so forth.  When clicked, the "Print" URL will always yield an up-to-date pretty-printed page for a forum thread.  Using a bookmarked "Print" URL, rather than making and saving a "static" PDF, combines Mark A's tip with mine.

(BTW, lots of forums work this way if they use YaBBB, PHPbb, or similar forum software.)

Title: Re: Log and debug mode?
Post by james a. foster on Nov 22nd, 2011, 10:07am

Last night I came up with a "Tinderbox way" to help with debugging.

Why not include two new system attributes, say ParseOK and ParseError. The first would be a Boolean whose value indicates whether the last action on this note succeeded. The second would say something abut why it failed, if it failed. For example, $ParseOK==0 and $ParseError=="missing expected semicolon, you silly git" would save me hours and hours of debugging time.

Title: Re: Log and debug mode?
Post by Mark Anderson on Nov 28th, 2011, 6:40am

The debugging suggestions at answer #1 upthread are now in two new aTbRef documents re debugging action code and export code. N.B. these articles are not in the uploaded source document (for now)t.

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.