First and foremost, I meant to suggest that a built-in tutorial like Getting Started with Tinderbox would help, beginning as that one does on page 6. E.g. create a new document, create a few notes (or copy and paste this TSV in), create a container called templates, create a note, make it a template, etc. It seems to me that these export features need that level of walk-through.
Now, for me, I'd also like a big picture walk-through such as you've done with inheritance. But in this case, it would look like more like this:
- User selects export.
- TB determines scope of notes to be exported as follows….
- TB traverses notes in this order (e.g. all level 1, then all level 2 OR tree-wise, bottoming out to the left, then across, then up, then across…)
- For each note, it checks for a template. If there is one, then #5; else phi.
- For each note with a template, it evaluates things as follows. This would point to an exhaustive list of export codes, markup elements (the nomenclature in this area seems inconsistent).
Then perhaps, it would help to explain some things I find anomalous. It seems perverse that ^title^ is not ^Title^ so as to match the case of the attributes of the same name. Why are some elements fenced by carets (like ^title^) and some not (like ^randomChildOf)?
From Tinderbox help page "Exporting to HTML":
^url exports the relative URL of the designated note, relative to current, the page being exported.
Evidently there are special designators (like 'current') that exist solely during export. Which are these, how do are they generated and disposed of? Are these the same designators used in action code for Agents?
Somewhere in this, I am also confused at the big picture level of when the export process will result in many files and when it will result in one. Sometimes the help documentation speaks, unhelpfully, of web pages, which I assume is several files. On the other hand, this process seems reminiscent of a markup processor (encouraged by talk of markup elements) which typically targets a single file--e.g. the way LaTeX will read many source files to produce one dvi or pdf output file. If I had 1000 notes, I might want one file or 1000 files, so I assume there is some control for this. So one reason I have more or less punted in trying to understand export, is that I am not sure which model to assimilate this to: database export (i.e. per record, per field) or markup compilation (i.e. consolidated source files).
I hope this gives some idea of the conceptual holes that I have perceived in the available documentation.
Deprecated codes are listed separately here and should not now be used.
I believe 'here' is meant to be a link. It is not, so the page reads in a contradictory way seeming to indicate that the codes here presented are deprecated, but then it is indicated that these are valid. I also find the moral of that page somewhat opaque. Is it that everything now can be done using ^value()^ but one can use the below export codes; or that these are the sole codes one could not do with ^value()^?
That is a bit of a grab bag. I hope it seems more concrete.