If Date and Date2 are two Date attributes, and N is a numerical attribute, the rule

    N=$Date-$Date2    (corrected from earlier posting)

sets N to the number of days between Date and Date2.

If Date is a Date attribute, then the rule

    N=$Date-"June 1, 2008"

sets N to the number of days since June 1.  

   N=$Date="today"

gives the expected result, 31, if Date is September 3, 2008 4pm and today is August 3, 2008 2pm.

I think part of the problem is you've (unintentionally) conflated two issues: date arithmetic and parsing expressions. The problem arises because the common maths symbols (+-*/) all have other meanings in different contexts; plus is the string concatenate, minus can be a text hyphen, multiply can be a text asterisk, and divide can be either a forward slash or a POSIX path folder delimiter.

Regular Expressions inside TB itself can find these symbols in your data but ultimately it (TB) must rely on context to figure out whether '-' is a hyphen or a subtraction and so on. The flip side is that for the learner, such areas of confusion even if understood in principle aren't easy to predict when writing actions and rules. This thread is worth reading to get an understanding of why your DisplayExpression doesn't work as expected - you have to allow for how TB can mis-interpret your intent for text as maths and vice versa.

I'm sorry if the aTbRef page confused you (I'll review that text) but I think you interpreted it a little narrowly.  You can do maths using Date format attribute data, it is the final output of that maths that is a string (except where stated). The most usual exception are functions like days() that document that they return a number (of days) - this is so the figure can be used in further calculation.  With care it can be turned into a string. The latter is a scenario where you might want to use a secondary attribute - for instance to concatenate a number to a string to make it all a string before passing it through any further expression evaluation, such as DisplayExpression.

Remember, if you write a multi-part/stage action or rule that doesn't work, make a small test TBX (or test section in you TBX) and break out each stage and look at the result. That way you can see where TB is not giving you the result expected. Often the format of the incorrect result will indicate what's happening and help indicate an alternate approach. User attributes can help, if you think of them as like code variables; the counter-intuitive part is that each attribute exists for all notes and attributes are normally seen by users as being visible things - not under-the-hood calculations. If you get past that last oddity, TB's not phased by a few extra attributes.

Upon further investigation, it looks like we will be able to support the expected behavior for Date1-$Date2 in string contexts like DisplayExpression in an upcoming release.

A handy rule of thumb is that any attribute on the right side of an '=' assignment needs a $ prefix so TB knows to what you refer:
OK: MyAttr = $OtherAttr
Not OK: MyAttr = OtherAttr

Placeholders for dates (today, year, etc.) don't take a $ prefix.  If you use action code that refer to attributes, such as any(), said attributes also need a $ prefix.

Incidentally, you can use a $ on the left side of an assignment, though few examples use this syntax:
$MyAttr = $OtherAttr

Date placeholders - I certainly not acquire the habit of using $ with them - the fact that syntax works now is probably accidental and something that may get 'fixed' (due to unrelated work elsewhere) in later version.

With left-side attributes the 'rule' is in principle that you do use a $ prefix like the right-side but it may be omitted and usually is by long-standing users of the app (ergo older demos, examples, etc.).