If you regularly export a changing TBX to HTML (or other formats) there are some pointers to bear in mind:
- If you change export template code but a note using it is unchanged, the note will not be re-exported. When exporting HTML files, Tinderbox compares the contents of any existing file with the source it is about to export. If both match no export occurs. This means Tinderbox checks for changes in any attribute being exported (not just $Text) and in the template code, e.g. where the note is unchanged but the template has been modified or swapped for a different one. Changes occurring in includes will be detected.
- If a note's exported filename changes (e.g. as a result of a change of note tile) the newly exported file does not result in the previous, differently-named file, being deleted. You will need to tidy up the old files in Finder. If hierarchical links are used consider the link from the parent as well as immediate siblings when working out the files affected. Roadmap view helpfully indicates incoming links allowing you to asses files elsewhere in the export that might be affected.
- Also consider the effects of $HTMLDontExport and $HTMLExportChildren; special attention is needed for notes only ever used as includes.
- The degree to which Tinderbox encodes or 'entifies' characters in the text is controlled by three primary attributes: $HTMLEntities, $HTMLMarkupText and $HTMLQuoteHTML. $AutomaticIndent allows suppression of just the mark up of quick lists (both note indenting and on export).
- Consider the effects of Tinderbox quick lists, font size auto-headings, etc. See more…
- If you change all or a significant number of notes' export template(s) it is advisable to do a full export, especially if the changes alter how navigational links set up.
- Notes with no $Text, or if $Text contains only whitespace, are considered empty and no exported file is generated, even if the note is set to export.
It is thus often a good idea to trash an existing exported set of pages before doing a full export. The export process is pretty speedy so, especially if on a local or LAN location, the loss of pages is very short-lived. If the final location is online, it can be useful to do a local export and then use FTP synching to update the online version to reflect the new output.
When exporting a single page via HTML view, also consider:
- If exporting a page that has includes, only the 'host' note's data is updated to the latest change. It is necessary to explicitly click the 'Update' button to re-compile included content from other notes.
- If exporting a single note whose exported filename has changed, see bullet point 2 above.
- If exporting a single note with exportable aliases, the aliases are not exported. A full HTML export is required to achieve this.
- an alias' HTML view exports the alias to the alias' context, including appropriate basic links and template related previous/next HTML links.
Tinderbox will export embedded images (suspended since v5, but intended to return). These are exported as JPG or PNG (set via HTML Preferences, 'Link images as'), using the host note's exported filename. If more than one image is in the note, the second image uses the filename suffix '-1' (before the extension), image #3 uses the suffix' '-2', etc. The images export to the the same folder as the host note. If the host note is an include, the images are placed in the including note's exported folder but the image filenames are unchanged. See also.
If the document uses a lot of images it can be useful to store them outside the TBX and link to them via the export template (or possibly) inline code). This can help reduce TBX file size and allow for better quality web images. Do bear in mind that if images are stored externally they cannot be seen directly in Tinderbox, though they could be added as file attribute links (harder to do if there is more than one image per note).
All attribute values allow for non-ASCII Unicode characters.
Aliases
Aliases export as separate files in their own outline-based place in the overall export. As such, they use their own basic links (in/out) and their original's text links (as $Text is the same). If an alias has no outbound basic links, it uses those of its original.
Aliases can be exported via HTML view, as with full HTML export, the aliases location/links are reflected in the output page.
Whilst aliases within Tinderbox cannot have children, aliases assume their original's children during export either for inclusion or separate export at the alias' location. (in effect as implied aliases themselves). This can effect recursing templates as output from an agent's aliases may recurse the original's descendants. In such conditions, it may be necessary to ad an alias detection argument. Originally a template might have the condition:
^if($ChildCount)^…
But, it may (depending on the user's intent) need to be altered to:
^if(!$IsAlias & $ChildCount)^
The new clause ensures the inclusion of child notes (and, if recursing, thus all descendants) does not occur if the current item is an alias.