This article describes how to make use of the website exported from aTbRef v8 in a local environment, for instance just on your Mac or on a netwerk with no public Web access.
This document was last revised using Tinderbox v8.6.2 on macOS 10.14.6.
Author: Mark Anderson (a Tinderbox user since 2004).
1. What you will need
In order to make a local HTML copy of aTbRef you will need to download two ZIP files from the aTbRef website:
- The TBX source of aTbRef: https://www.acrobatfaq.com/atbref8/aTbRef8.zip. The archive unpacks a single TBX file which can be moved anywhere and opening in Tinderbox.
- A Zip archive of the images to be used by the local website: https://www.acrobatfaq.com/atbref8/images.zip. The archive unpacks a single folder called 'images' containing all the images needed.
2. Set up the export location
Decide where you wish to create the website—even if you may subsequently move it. As the TBX file will remember the location after first use it makes sense to use the final location, if you know it. Create a new empty folder there. The exact name of the export folder doesn't matter—though you need to remember where it is for the export step in Tinderbox.
Uncompress the 'images.zip' file and place the resulting 'images' folder inside your intended export folder, so it is ready for use once the HTML content has been exported.
3. Open the TBX
Find your downloaded aTbRef.tbx file and double click it to open it.
Decide whether you want :
- the full export - the default such as is used publicly online. You may want this in order so see how some of the non-content features like RSS or the version checker actually work. As the TBX is already configured for this, jump to the step: 'Export to HTML - 1' further below.
- an alternate export designed for use without web access, with various export features disabled. All the normal HTML content is still exported.
4. Configure for Local use export
Scroll the main outline and find the note close to the bottom, which is called 'EXPORT SET UP FOR WEB'. Open its text window.
5. Setting the export toggle
For local use, alter the two tick-boxes indicated. The note's text describes what the toggle actually controls.
N.B. the note's title is actually 'EXPORT SET UP'; the remainder of the screen name—as seen in the title bar and view pane —is supplied via a display expression.
6. Outline rest for local use
Note the changes in the outline, to remind you you are now in 'local' export mode. You are ready to export the local HTML version.
7. Export to HTML - 1
Ready to export in either mode? Open the File menu and select Export → as HTML
8. Export to HTML - 2
Use the chooser dialog to navigate your desired export folder, created above in step #2, and select it.
Click Export to start the export process.
9. Data is exported
A progress bar is shown during export.
10. Output as seen in Finder
This shows the local output. A number of items created for the full website are not created, such as a RSS feed file. If not needed for local server use, the 'robots.txt' and 'sitemap.xml' may also safely be deleted.
Note the 'images' folder, indicated, is not created by the export—this is the folder you need to add from the downloaded Zip file.
11. Web page content missing in local mode
The local option leaves out from the exported HTML:
- the Google Translate widget (below the quicklinks) as this loads direct from the web.
- the search function panel (towards the bottom) as this returns results from the Google and DuckDuckGo websites.
The other omissions for local use are unseen code in the page source.
12. Further export tweaks
The TBX offers a few more easy controls for customising what is exported, albeit not controlled by the switch in the 'EXPORT SET UP' note.
12.1 Excluding 'similar to' links
Expand the 'TEMPLATES' container and select the export template note '5-basic_all'.
12.2 The 5-basic_all template
UseGoogleTracking. This allows inclusion of Google Tracking code for analytic purposes. If used for your own website, remember to set your own Google Analytics account number in the note at $Path '/Boilerplate/google-tracking'.
UseGoogleTranslate. This allows inclusion of a Google Translate panel assisting non-English speakers to translate the page. Note, it is machine-translation and may be a variable quality depending on the traget language.
UseSimilarTo. Do not use! The feature is currently not fully supported and may cause export problems. The option is still retained in case the feature becomes usable again.
UseGoogleSearch. This allows inclusion of a search panel with Google and DuckDuckGo web searches aimed at site on the aTbRef8 website.
12.3 The Site Map exports
These notes aren't controlled by the web/local toggle and both export an outline of the whole content site.
The first is an HTML page with a link to each page in the main content, laid out in outline form. It is far too big a page for general real-world use but shows the power of just 2 templates (envelope & letter method) being used to include pretty much every content note in the document. This page does export by default, not least as each normal HTML page includes a link to it in their navigation bar. To stop it being exported, open its text window and see the next step. The page can also be used as a form of proxy index by doing a Web Browser find in the page's text for a desired term.
The second export is an experiment in making a 'sitemap.xml' file such Google can use to fine tune indexing of a website. As the XML is verbose, it makes an 8MB (!) file; it does export by default. To toggle creation of this XML file on or off, look at the Key Attributes in its source note as shown in the next step.
12.4 aTbRef XML Sitemap
Tick the box to stop export, un-tick to allow export.
13. Moving the output
Can the website be moved once exported? Yes, absolutely. Either in web or local form, the site is self-contained and all in-site links are relative. To move the site around on your Mac, or to a different location on your LAN or web server, simply move the folder (to which you exported) with all of its contents to the new location.
14. Creative Commons Licence
The CC licence was added with regard to the content of the HTML site. Feel free to learn from and use the design and export mechanisms of the TBX without restriction.
The TBX contains, and exports, a Creative Commons Licence to help anyone who wants to re-use the resource in a private organisational setting, e.g. a university LAN or such. You are free to:
- Share: to copy, distribute and transmit the work
- Remix: to adapt the work
…under the following conditions:
- Attribution. You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work). Please use this Attribution.
- Non-commercial. You may not use this work for commercial purposes. The following Waivers are already granted.
- Share Alike. If you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.
Please note that any of the above conditions can be waived if you get permission from the copyright holder.
Nothing in this license impairs or restricts the author's moral rights.
Feel free to experiment. If you really mess up the TBX, simply download a fresh copy. The file's exports are basically a series of exercises exploring what Tinderbox can do with (HTML) export. Note that you don't have to export HTML. Indeed, the 'zipper' pages don't export a page at all - they just call the command line to make the desired zip files. The no-exporting notes have some information about them in their $Text as well as some coverage in the 'About aTbRef' section in the main content.
Should you delete the root note 'A Tinderbox Reference File' and its descendants, you've effectively got a blank vessel for experiment, albeit with some templates looking at user attributes created for the existing content. Generally such template content will result in no export code if the target attributes are not used so they can be left in situ for simple experimenting.
The zipper feature is set to work on the author's system but these customisations are exposed as key attributes in the relevant notes. So, these features too, can be altered for your own use.