OPML is an open standard for transferring outline-type data between applications. Scrivener can import OPML, allowing Tinderbox data to be exported to Scrivener.
Format limitations: OPML is a plain text format. Text formatting, i.e. bold, underline, font face/colour, highlighting can't transfer via OPML, nor may Tinderbox links between notes.
This tutorial was made using Tinderbox v5.11.2 and Scrivener v2.3. The built-in templates referred to here were initially added to Tinderbox in v5.11.0. Note:
- Scrivener has supported OPML drag-drop** import since v.1.x (?) and certainly in v2.0+.
- As at Scrivener v2.3, OPML import can be achieved only via drag-drop into the Binder pane.
- The latter can be modified by adding OPML as a Plain Text Import Type (as explain during this tutorial). This was due to made a default preference setting in v2.3 ,but was omitted in error. It should be the case in any post v2.3 release.
Set up Tinderbox as suits your style - there is no one 'correct' way. AS both apps offer some choice in to how the export import occurs, the tutorial will show a basic method and then discuss some variations.
At the Scrivener end, the Tinderbox note title ($Name) becomes a Binder note name, and the note's text ($Text) the text of the Binder note - unless the latter is modified by Scrivener import Preferences (more on this below). Tinderbox $Checked data is imported but it is unclear whether this is used by Scrivener.
Tinderbox set-up: add the necessary export templates
This action only needs doing once (per TBX document) - skip this step if you have already added these templates.
In Tinderbox, open the File menu, Built-in Templates, and then Scrivener from the sub-menu.
What gets added to your Tinderbox document
Two nested templates are added, 'Scrivener' and 'Scrivener item'. If a root-level 'templates' container doesn't exist, tinderbox will add one. As the templates use a built-in prototype 'HTML Template', the latter - and its container- are also added if necessary. In most mature documents, the templates and prototype will likely be added into the existing relevant containers.
Scrivener set-up: some non-default Preferences - 1
Here, 'opml' has been added to the default list. From v2.4 it should be part of the default list.
Until/unless you make this change OPML can only be imported by drag/drop onto the Binder. Once 'opml' has been added here, the Scrivener File menu, Import, Files can used to select and import OPML files.
However, for the rest of this tutorial the status quo (i.e. drag-drop only) will be assumed.
Choose your export container
Arrange your Tinderbox document's content so that:
- all the data to export is within/descended from a single container
- the container note does not contain data needed in the export
The export container may be anywhere in the document - above it is shown at root level but that is not a requirement.
The export process will export all descendant notes from this container. If it is not possible to arrange the desired notes into a single hierarchy containing only the to-be-exported notes, you may need to export the data as several discrete OPML files.
Select the export container and open its HTML view (View menu, New HTML View… or [Cmd]+[Opt]+[H]). Code in the template automatically sets the necessary '.opml' extension for you. However, you may wish to set the export filename, as shown. If left blank the OPML filename with be based on the export container's title.
Click the Export button - and the export is done!
Note: the first time you export either the whole document or just a note, as here, Tinderbox will show a file chooser dialog for you to set the export location. Thereafter that location is used by both export processes; you can't reset the export location via HTML view.
Whole document exports or multiple HTML view based exports are discussed further below after the Scrivener import.
Locate the exported OPML file
Switch to Finder to locate your exported file, which you will now drag into Scrivener's Binder.
Important: Do not use Scrivener's File -> Import menu. You must use drag drop of an OPML file from a Finder window.
Scrivener's manual describes the process thus (pages 493-4):
- When OPML files are dropped into the binder, Scrivener will attempt to con- vert these outlines into Scrivener outlines. This can be useful if you do your initial brainstorming in a dedicated outliner application. Some of these applications support attached notes to each outliner header. If notes exist, Scrivener can be instructed to apply these notes either to the Synopsis alone, the main text, or the document notes for that heading in the outline. Note that in the case of the last two options, the synopsis will still be set automatically to the first few hundred characters of the note.
- If you want dropped OPML structures to be generated inside of a special folder, rather than directly into your existing Binder structure, enable the “Create folder to hold imported OPML items” option.
The last option is described further below
Drop OPML file in Scrivener's Binder - 1
Drop your file onto your Scrivener document's Binder (the left column of the Scrivener app window). If the Binder is not shown, use the Binder button on Scrivener document's toolbar to display it. Dropping the OPML file onto any other part of the document or onto the app's Dock icon will result in incomplete or corrupted input.
Drop OPML file in Scrivener's Binder - 2
Drop your file onto your Scrivener document's Binder. The first time you do this, you will see a warning. Just click Import. As already explained we're only importing plain text so the warning doesn't apply here.
Choose insertion point in the Binder
Scrivener will indicate where insertion will occur. If the dropp occurs with no blue indication showing, the new data will be inserted into the Binder after the Trash and at root level.
Data arrives in Scrivener (default Preferences)
Exactly where the dropped data arrives depends on where you drop the data. If you drop over/between existing content, Scrivener shows a blue cursor indicating whether the drop will occur inside or between items. Worst case, the dropped item(s) can always be moved again by dragging within the Binder.
If you look at the picture for Step 4 above (Choose your export container), you will see you exported 2 notes with text ($Text), one of which had a child note with no text. As can be seen, the note title ($Name) and text ($Text) are transferred.
Notice that the children of the Tinderbox export container are added directly as Binder items. If you prefer they all get added within a single Binder item, change you Tinderbox layout so that the export container contains a single child container holding all the export content. This technique is explained further on in this tutorial.
Setting Scrivener OPML Preferences
OPML settings are stored in Scrivener -> Preferences, Import/Export pane, Import Options tab.
The pop-up settings are:
- Main Text (with Synopsis) --> default setting
- Notes (with Synopsis)
This tutorial only uses the default setting, i.e. for Main Text. Regardless, within the Binder the results are the same, the above simply affects into what part of the new Binder item(s) any Tinderbox data is placed.
The Create folder to hold imported OPML items box (default: un-ticked) is useful if you'd like to add all imported items to a new root folder in the Binder. The next shows the result of repeating the earlier process with this option ticked.
Data arrives in Scrivener
With the altered Preferences, the exported container from Tinderbox becomes a new folder in the Binder (using the Tinderbox container's name and not the OPML file name) as its name. Note however, that the Tinderbox $Text of the exported container is not used for the Binder
Exporting the whole Tinderbox document
It may be that your Tinderbox document is, bar back-of-house stuff like templates, all data for Scrivener. In that case, put all the content inside one export container at root level, as detailed earlier. Now select each other root-level container, e.g. 'Prototypes', etc., and open its HTML view. Un-tick the Export and Export children boxes. These ensure the container and anything in it won't export as part of a whole-document export.
When done, you can simply export the whole file: File menu, Export as HTML…
If you have an export container for Scrivener data nested inside other tinderbox content you don't wish exported, only un-tick the 'children' box and leave the 'Export children' box ticked. Tinderbox will export a Finder folder for each ancestor container of your OPML container but not files for those notes.
It is also perfectly possible to mix OPML export with the default HTML (or other template-derived format) export. In such a case all files would export their normal HTML files. As the OPML export involves a cascade where one note simply reads and includes the content of others, you can even have a note inside the 'opml' content area still generate an HTML file. In such a case the only file not to generate HTML would be the OPML export folder as no note/container can generate more than one export file.
Exporting multiple OPML segments for Scrivener
The above image shows a document where there are two discrete sections of Tinderbox data to export, resulting in two separate OPML files. As before, either container can be placed anywhere in the document. For simplicity here, everything is at root level but in a mature document the layout may be more complex. Badges have been applied to indicate which containers export. Building on idea discussed above, there is no reason why the non-Scrivener data might not be exporting to some other format. Set up the document as you needs dictate - Tinderbox is very flexible.
In this next example, the process is done using Scrivener default preferences (as described above).
Making data arrive in Scrivener in a single set of Notes - 1
As discussed above, by placing everything inside the export container within a single child container, you can create a 'folder' for you imported date in Scrivener - see the next step.
Making data arrive in Scrivener in a single set of Notes - 2
The data here as as at the beginning but now arrives in Scrivener with it all contained inside a single Binder item. It's down to individual style whether this is an help or just more work.
Making data arrive in Scrivener in a single set of Notes - 3
Here the same exercise as the last step is combined with the Scrivener preference to add new data within a new Binder folder.
Location of imported notes in Scrivener when using File -> Import
If OPML is enabled for import via the main menu, the insertion point seems to be decided thus - based on experiment:-
- Nothing selected in Binder, items are added as children of 'Research'.
- Root level folder selected, items are added as children of selected folder'.
- Non-root-level note/folder selected, items are added as siblings of the selected item.
Drag-drop probably gives finer control over placement of imported items.
Which method should I use?
Again, set up Tinderbox as suits your style. One OPML file, several files - there in no one correct way. Different users will have different needs. You might for instance have separate OPML exports for discrete projects. Even if both projects live in the same document in Tinderbox and Scrivener you might still want to be able to transfer data about Project A separately from Project B.