Better (HTML) Export examples?

(Mark Anderson) #1

To take a glass half full approach what is missing, in more concrete terms? If I interpret correctly, I think @bcrane’s tutorials resonate for some because they take a (deliberate) reverse approach. IOW, take the finished product and substitute sections with the code that would generate them from source. I think it’s a useful concept.

Some folk seem to have got a basic start from some annotated examples I created (here: Although written under v6, they are unchanged in v7. In contrast to the above, they approach the task from a scope context.

The templates in the aTbRef source TBX (here), viewed in the TBX show some fairly advanced techniques such as include of scripts and boilerplate.

BoxPress is an interesting and complex configurable TBX though I suspect too complex for the starter.

There has also been discussion of the bewildering number of attributes in the ‘HTML’ group of System attributes. Perhaps this needs some narrative description to explain what they all do.

Does the (only) built-in default HTML export template make sense to the new starter (with some grasp of HTML basics)?

So, practical question: using the above to seed ideas, what might those of use trying to help users best document to aid that process?

Note: I’m not ignoring text export but it is a complex and separate topic needing some different resources.

Better Text Export examples
A cordial community
(Mark Anderson) #2

A post was split to a new topic: Better Text Export examples

(David) #3

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:

  1. User selects export.
  2. TB determines scope of notes to be exported as follows….
  3. 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…)
  4. For each note, it checks for a template. If there is one, then #5; else phi.
  5. 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.

From atbRef:

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.


(Mark Anderson) #4

Oops - misread the above. Post deleted.

(Mark Anderson) #5

Fixed. the ‘here’ was a link to a page i no longer publish. The data for the latter is still in the TBX for anyone who might want it.

Grab bag it may be but your post has a lot of useful suggestions. So thanks, I’ll mull on that. Further suggestions welcomed from others, especially on the initial understanding phase.

(Mark Ware) #6

It may not suit everybody but I learned a lot from this detailed 2010 tutorial by @lmorchard

Creating an article in HTML with Tinderbox

As well as having a detailed step-by-step tutorial you can also download the whole article as a Tbx document which lets you examine the templates and export code

It’s now dated, of course, using a much earlier version of Tbx. As a longtime user I don’t find it very hard to mentally “translate” the steps into Tbx.v7 but maybe someone might like to update it for v7?

(And as an aside, it speaks volumes for Tbx’s longterm compatibility that the accompanying file still opens perfectly in the latest version.)

(James Fallows) #7

I had not been aware of that before. Many thanks for the pointer. It’s another illustration that actually provides step-by-step guidance on using the basic features of the program.

(Mark Anderson) #8

Well actually , it was updated:

I’d not done further updates as no one seemed interested. The process does depend on wkhtmltopdf which is open source and a bit flaky at keeping the Mac version up to date.

(Paul Walters) #9

Looking back, @eastgate, @mwra and (no hyperbole) dozens of other volunteers have spent hundreds of hours contributing tutorials and examples to the old forum, the Tinderbox Weekends, and on and on. There are gigabytes of wonderful examples. Mostly written for older versions but as @mrkwr pointed out, much of the material still works today.

(James Fallows) #10

Saw the earlier version of this post, mentioning the actual abundance (vs paucity) of tutorials, explanations, and references that have built up, and was going to say I agreed.

(Mark) #11

I have linked a small tbx file here that I hope will be helpful to those wishing to create a simple website that creates a breadcrumb navbar that maps child parent relationships and also maps inbound and outbound links between notes. I’ve added more notes inside the main home page.

It employs a css stylesheet reference that allows simple tweaks to change the appearance of the html output by altering elements in just one note ( called basic.css)

Hope it helps

Call for Website map examples
Where do you put your reading notes?
(jmm) #12

Your CSS would be interesting, but the link is broken.

(Kanishka Mehta) #13

Yes, the link is broken

(Mark) #14

Sorry about that - here it is again

(Bill Anderson) #15

@mwra I want to thank you for the HTML export tutorial.

I’ve been an avid TB user for some years and read several editions of The Tinderbox Way, but exporting eluded me until last night.

Thank you. Thank you. Thank you.