Admin edit: moved to a new thread, as suggested by @entropydave in this post
Perhaps we could start with text export somewhere, because it may be a more gentle approach to the problem of “markup elements” and templates. If you disagree, please use this as a seed for another thread.
Quoted from the Tinderbox Help page “Simple Export”, followed by my queries of incomprehension.
When exporting text or RTF, Tinderbox interprets several useful markup elements.
– I take it we are to infer that we must put the following markup elements into the $Text of the note that is exported during one of the File:Export sub-commands. Is that right?
^include(which) is replaced by the styled text of the designated note.
– what is a “designated note”? Is it the value of ‘which’, here functioning as a special keyword? When would I use this, won’t simple export traverse all notes anyway?
^value(expression) is replaced by the value of the expression. For example, 3 will be replaced with the value of the width of the exported note.
– what is the syntax of an ‘expression’? How is ‘3’ an expression that evaluates to the width of the exported note? Baffled. Are expressions those of the normal scripting language?
^if(expression){….} ^endif and &^if(expression){…}^else{…} ^endif permit conditional export; the material within the curly braces will be exported only if the expression is true.
– this I get, provided that it is indeed the normal scripting language that is used for the boolean conditional.
Now (v6+) that text export doesn’t use export template explicitly, I believe Text Export (plain or RTF) can only employ export codes inline in notes. If that seems a restriction, I think the design intent (pragmatic compromise) is that formatted export (i.e. HTML export) allows very rich and nuanced construction of data layout. HTML text can always be copied and pasted to RTF editors. Ergo, if you want non-$Text data in your export and don’t want inline export mark-up you’ll need to master HTML Export(as discussed in a separate thread).
As to the immediate questions:
Yes, I believe so.
^include(which) is replaced by the styled text of the designated note.
– what is a “designated note”? Is it the value of ‘which’, here functioning as a special keyword? When would I use this, won’t simple export traverse all notes anyway?
No, ‘which’ isn’t a designator. It’s the author’s shorthand for ‘whichever note you want to include’. The most normal input, i.e. the ‘designated note’ is the $Name or $Path of a single note, but it can be the designator for a group of notes (or a find() for such. Optionally, a template can be specified for the included content. In a text export context, the include could call ‘this’, i.e. the current note, but using a template that returned a table of attribute data; more explanation is a thread in its own right.
Text/RTF already traverses notes within the scope you set in the pop-up on the text export dialog. ‘Entire document’ traverses the whole outline. ‘Selected notes’, only those notes selected in (I assume) $OutlineOrder order. ^include^ allows you to pull data from outside that scope.
Ah - a typo. The Help is written in Tinderbox. The source note forgot to escape the ^ in the code, i.e. not ^^value($Width)^^ instead of ^value($Width)^ so we get the $Width of that note - 3! I think the intended rendered Help text is:
For example, ^value($Width)^ will be replaced with the value of the width of the exported note.
An ‘expression’ is short for an action code expression. At simplest it is the reference to a single attribute, e.g. $Width but could be:
$Height * 4
"This is " + $MyString
(2 / 4) *6.5
i.e. valid action code. The evaluated result of the expression is what is passed for export.
The first only export the code in curly braces if the condition is true. in the second case the ‘else’ code is exported if the condition is false. Way back in Tinderbox’s history there was separate syntax for conditions (so don’t be confused by very old examples. Since v5 at least, the condition is a query written in action code. Put another way, you use a query in the same manner/syntax as you might write one for an agent.
I’d agree that on re-reading this section of Help that it could do with some clarification, especially to reflect changes in the text export process. I too, don’t find terms like ‘which’ to be informative and these can probably be improved.
Meanwhile, please continue with practical suggestions for better export tutorials along the manner already discussed for HTML export.