| Home | Parent | ← Go → | Prior | Next |
In this section, we document the details of the Import and Export processes, seeking to answer such questions as “What happened to Bookmark X?” and “How can I make Y happen to Bookmark Z?”
In general, bookmarks are mapped into the same location in the destination as they were in the source; Bookmarks Bar to Bar, Menu to Menu, etc. However, because Clients, and the BookMacster Bookmarkshelves, have different structures, some of the bookmarks content content copied during an Import or Export have nowhere to go. For example, if bookmarks from a Firefox Client, containing items in its Unsorted Bookmarks Hard Folder are migrated to a Camino Client, which does not have such an Unsorted Bookmarks folder, the subject items must be remapped into a different location.
Using BookMacster, such a migration is performed by an Import + Export, with a BookMacster Bookmarkshelf “in the middle”. Depending on the structure of the Import Client, Bookmarkshelf, and Export Client, remapping may be necessary during Import, Export or both. You can configure some of the remapping rules with the settings described in the next section.
During either an Import or Export, the process of “mapping” computes where a content item should be placed in the destination based on its location in the source. As previously discussed, even with the best of intentions and configurations, an item may not be allowed where it would be directly mapped. For example, loose bookmarks are not allowed into the Root of an export destined for Camino, Chrome, or Firefox.
If directly mapping an item is not allowed, BookMacster then checks to see if it can be remapped to the Default Parent for the destination.
For importing into a Bookmarkshelf, you set a Default Parent in the Import Postprocessing sheet.
For exporting to Clients, you set a Default Parent in the Advanced Settings for that Client.
If the item is not allowed in the Default Parent either, BookMacster tries the other Hard Folders until it finds one where the item is allowed and remaps it to there. (The order in which Hard Folders are tried is a hidden preference.)
For Bookmarkshelf documents that have multiple Import [Clients], when re-importing an item that already exists, if the location of the item in the Client indicates that it has been moved from its current location, the move only occurs if the Client is the first one in your Clients list.
Ignoring moves implied by later Clients is particularly important because of the fact that, when an Import is performed by a BookMacster Agent because it detected changes from a given Client, only the given Client’s content is imported.
As an example of why you want such a move to be ignored, consider a Bookmarkshelf which has two Clients, Safari and Firefox, with Safari first, and has bookmarks in the root. These bookmarks would have been exported to the root in Safari, but, because Firefox does not allow bookmarks in its root, they would have been exported to the Unsorted Bookmarks hard folder in Firefox. If the Simple Agent to Import changes and Export to all Clients was activated, and later a new bookmark was added in Firefox, the Agent would detect the change and import from Firefox only, and BookMacster would move all of those root bookmarks into the Bookmarkshelf’s Reading/Unsorted folder, because that is equivalent to their location in Firefox. Then, when exported to Safari, they would be moved into Safari’s Reading List. Such behavior would be unexpected.
This means that if you purposely move bookmarks from one folder to another in a second or third Client, expecting that such moves will be synced to the Bookmarkshelf and to all other Clients, you will be disappointed. We recommend that, when it’s time to do housecleaning on your bookmarks (moving, renaming, and deleting items, etc.) please open your Bookmarkshelf document, do the work in BookMacster, and, when done, Export to all Clients.
As the result of an Export operation, usually you want the browser or file to which you exported to contain only the items which were exported from BookMacster. Checking on the Delete Unmatched Items option will do this by deleting any destination items which were not be matched to source items during the merge process described above. You should check this box if you want the content of the Client to look as much as possible like the content of your Bookmarkshelf.
Delete Unmatched Items is also available during Import Postprocessing, and is used as part of making your Bookmarkshelf exactly match the content in its Import Clients. Note that there is only one “Delete Unmatched Items” checkbox for a document, not one for each Client in the table. This is because, in this case, there is only one destination (the Bookmarkshelf) from which items can be deleted, and also it cannot be determined whether or not a given item has been matched until after all Import Clients have been imported.
The Safe Limit controls protect your bookmarks from massive changes in the event of some unexpected file corruption. For example, if you accidentally deleted all the bookmarks content in a Bookmarkshelf, and had set an Agent to Export, and Safari was an Export Client, then the next time this Agent was triggered it would wipe out your Safari bookmarks too. To avoid propagating disasters like this, you may set a Safe Limit. If the number of additions + updates + deletions exceeds the applicable Safe Limit in an Import or Export operation, the operation will be aborted and you will be alerted by an Error. (Note that the number of slides is ignored. This is because, for example, adding a single bookmark at the top of a folder of 100 items will cause 100 items to slide down; counting slides would thus make a big deal out of a little deal.)
There are Safe Limit controls for Import Postprocessing, and for exporting to each Client.
Safe Limit controls are OFF (set to infinity) by default.
During an Import or Export, BookMacster will compare bookmarks content items between the Bookmarkshelf and the Client, looking for items that were previously imported or exported. It can do this because it remembers the items’ external identifiers. When a match is found, BookMacster will merge the items by keeping either the item from the Client, or the item from the Bookmarkshelf, as you indicate in the Merge Keep control.
If no previously-imported or exported item is found for a given bookmark, there is another chance for a match if the Merge by URL box is checked. In this case, a second search is done, for a bookmark with the same URL. (Note that BookMacster normalizes URLs.) If found, the items are similarly merged, keeping the item from either the Client or Bookmarkshelf, as indicated by the Keep matched item from control. If more than one such bookmark is found, the source and candidate destination bookmarks’ parents are compared, and if that still does not result in a unique match, the bookmarks’ names are compared, and if that still does not result in a unique match, one is chosen arbitrarily.
For Exporting to a Client which does not accept duplicate items, Merge By URL is forced on and the control is disabled.
When performing an Import or Export operation, BookMacster provides options that allow you to translate between Clients that support folders instead of tags, and Clients that support tags instead of folders. These options are called Fabricate Folders and Fabricate Tags. “Folders” and “Tags” are indicated by little icons…
For browsers that support hierarchy but not tags, during an Import you may Fabricate Tags, and during an Export you may Fabricate Folders. For browsers that support tags but not hierarchy, it’s just the opposite – during an Import you may Fabricate Folders, and during an Export you may Fabricate Tags.
If the Fabricate Tags box is checked on, the names of a bookmark’s parent, grandparent, etc. folders which are not presently among the bookmark’s tags will be added to bookmark’s tags. Only names of soft folders are added, of course. Names of hard folders such as Bookmarks Bar or Bookmarks Menu are not informational and therefore are not added as tags. This is useful if your goal is to use tags instead of folders.
Fabricate Folders s useful if your goal is to use folders instead of tags. If checked ON, any item which has a tag will be placed into a subfolder which has the same name as its first tag, creating the folder if necessary. If in addition the One for each tag setting is checked ON, for items with more than one tag, the same will be done for each additional tag, placing copies of the bookmark into subfolders for each tag, creating additional subfolders if necessary. Note that this can fabricate many duplicate bookmarks.
The number of folders created, however is reduced by the fact that, during Fabricate Folders, only one folder is created to contain multiple bookmarks which require it.
The Fabricate Folders option will not fabricate a folder that would not be allowed at the required location. Currently, there is in practice only one example of this: If Fabricate Folders is checked on, and bookmark(s) at root have tags, but the structure of the destination (either external store or document) does not allow soft folders at the root level, then folders are not created for the tags of these bookmarks.
Bookmarks stored in Clients which are social bookmarking web apps such as Delicious often have an attribute called Shared, or, conversely, “Private”. Bookmarks which are exported as Shared become viewable by other people who visit your bookmarks page.
BookMacster supports a ‘Shared” attribute to its bookmarks, and this attribute is exported to such a Client. So the question arises: When items are imported from a Client such as Safari which does not support the Shared attribute, should the Shared attribute be turned on or off.
You provide the answer by checking Share new items if you want the ‘Shared’ attribute to be turned on in such a case.
To execute an Export, BookMacster first reads in all of the current bookmarks content from the Export Client and compares it to the bookmarks content from the Bookmarkshelf which is proposed to be exported. It determines the number of each type of change which needs to be made. If there are no additions, deletions, moves, or slides, and if none of the items have any updates to a nontrivial attribute, the operation is terminated without writing the file or uploading anything.
During an Import, tags are given a special, conservative treatment. When a bookmark existing in the Bookmarkshelf is matched and merged with one from a Client, any new tags on the bookmark in the Client are added to the bookmark in the Bookmarkshelf, and none are deleted.
During an Export, tags are treated like any other attribute. When a bookmark existing in the Client is matched and merged with one from the Bookmarkshelf, the tags on the bookmark in the Client are completely replaced by the tags on the bookmark in the Bookmarkshelf. Any tags on the Client bookmark not on the Bookmarkshelf bookmark are deleted.
This leaves essentially three alternative methods for deleting tags from bookmarks:
When we speak of changes to separators, we mean adding new separators, moving separators, and/or deleting separators. The behaviors described in this section are the same, with the additional requirement that, in order to delete separators, the relevant Delete Unmatched Items checkbox must be switched ON, and this must be a regular export and not a QuickMerge.
Separators are a structural element which you have usually set to your liking in one Client or another. Therefore, when importing and exporting with multiple Clients, BookMacster filters changes to separators according to special rules which prevent undesired duplications. The underlying idea is that you want separators from source or destination, but not both. Which one you want is determined by the setting of the relevant Merging Keep option, and there is also an option to not export any separators at all. (This may be desirable if you are exporting to Safari and Safari bookmarks will be subsequently synced to the iPhone via iCloud. Separators may be unwanted in the iPhone due to the small screen size.)
The behavior you get with the default settings is probably “what you want” and should “just work”. But for clarity (and our internal quality assurance testing), the rules are detailed in this section, first in words and then in a tabular format.
To be precise, we need to define three classes of separators, imagining that separators are imported from Clients on the Left, to a Bookmarkshelf on the Right.
Left. A separator in a Client which does not exist in the Bookmarkshelf (either because it was never im/exported or was im/exported and subsequently deleted) is called a Left separator. Left separators are imported to the Bookmarkshelf if Merging Keep is set to Client, but not imported if Merging Keep is set to Bkmslf.
Matched. A separator in the Bookmarkshelf which also exists in all Clients (due to prior im/export) is called a matched separator. A matched separator will always remain standing. (Actually, the one in the Bookmarkshelf is either overwritten by a mate imported from a Client, or is untouched, depending on whether Merging Keep is set to Client or Bkmslf. But since separators have no visible attributes, you can’t tell the difference).
Right. A separator in the Bookmarkshelf which is not matched by one in all of the Clients (either because it was never im/exported or was im/exported and subsequently deleted from a Client) is called a Right separator. If the Merging Keep option is set to Client, or if Import Postprocessing Delete Unmatched Items is checked ON (☑), Right separators deleted. Otherwise, Right separators are untouched.
Table. The above rules are summarized in the following table. The settings in the first row are the default settings, which are what you should have if you have never changed any of the Advanced Settings (by clicking one of the “gear” buttons).
| Settings | Behavior of Separators during Import | |||
|---|---|---|---|---|
| ‘Delete Unmatched Items’ in Import Postprocessing (Advanced) Settings | ‘Merging Keep’ in Client Advanced Settings : Import | Left Separators | Matched Separators | Right Separators |
| ON (☑) | Client | Imported | Imported (*) | Deleted |
| OFF (⎕) | Client | Imported | Imported (*) | Deleted |
| ON (☑) | Bkmslf | Not imported | Untouched | Untouched |
| OFF (⎕) | Bkmslf | Not imported | Untouched | Untouched |
(*) Since separators do not have any attributes, the effect of “Imported” in this case is the same as that of “Untouched” – the separator appears to survive unchanged.
For exporting, we redefine the three classes of separators, because Bookmarkshelf and Client are now swapped in our imagined “Left to Right” movement.
Left. A separator in the Bookmarkshelf which does not exist in the Client (either because it was never im/exported or was im/exported and subsequently deleted) is called a Left separator. Action may be affected by the setting of the Export Separators checkbox:
A Left separator is exported only if both this box is checked and and the Merging Keep is set to Bkmslf.
Matched. A separator in the Client which also exists in the Bookmarkshelf (due to a prior im/export) is called a matched separator. A matched separator will always remain standing. (Actually, the one in the Client is either overwritten by its mate exported from the Bookmarkshelf, or is untouched, depending on whether Merging Keep is set to Bkmslf or Client. But since separators have no visible attributes, you can’t tell the difference).
Right. A separator in the Client which is not matched by one in the Bookmarkshelf (either because it was never im/exported or was im/exported and subsequently deleted) is called a Right separator. Right separators are deleted if Merging Keep is set to Bkmslf, but untouched if set to Client.
Table. The above rules are summarized in the following table. The settings in the first row are the default settings, which are what you should have if you have never changed any of the Advanced Settings (by clicking one of the “gear” buttons).
| Client’s Advanced Settings : Export | Behavior of Separators during Export | |||
|---|---|---|---|---|
| Merging Keep Item From |
Export Separators | Left Separators | Matched Separators | Right Separators |
| Bookmarkshelf | ON ☑ | Exported | Exported (*) | Deleted |
| Bookmarkshelf | OFF ⎕ | Not exported | Untouched | Untouched |
| Client | ON ☑ | Not exported | Untouched | Untouched |
| Client | OFF ⎕ | Not exported | Untouched | Untouched |
(*) Since separators do not have any attributes, the effect of “Exported” in this case is the same as that of “Untouched” – the separator appears to survive unchanged.
Note that the Separators’ Behavior does not depend on the Export Client’s Delete Unmatched Items setting. (First of all, only the first two of the above four combinations are possible, since if the Export Client’s Delete Unmatched Items is ON (☑), Merging Keep must be set to Bkmslf. Of these two cases that remain, the separators which would be affected by the Export Client’s Delete Unmatched Items, the Right separators, are deleted due to the action of the Merging Keep = Bkmslf. So, the Export Client’s Delete Unmatched Items does not matter.)
You might create a folder with a certain name, say, News, in, say, the Safari Bookmarks Bar, and then also create a folder with the same name, News in Firefox in the same corresponding location. Then you might import from Safari and Firefox, expecting that the items in your two News folders would be merged into one News folder. BookMacster does indeed do this.
To make this happen, very near the end of an Import or Export operation, BookMacster merges pairs of folders within the same parent, which have the same name, if they come from different sources (either different Clients or Client vs. Bookmarkshelf). Because it does so starting from the root, all such pairs folders will be detected, provided that they have the same lineage. When a pair of folders with the same lineage and name is so discovered, one folder will be kept and the other folder will have its items moved into the first folder and itself be deleted. Also, any external identifiers in the deleted folder not already existing in the kept folder are appended to kept folder.
A more aggressive merging of folders may be performed by executing a Consolidate Folders command.
If during an Import operation, the two folders are from different Clients, the one from the higher-priority Client (higher in the list in Settings ▸ Clients) is kept.
Otherwise, if both folders are new (not previously in the destination), the one with the earlier Date Added is kept. This is important for the following reason. If you are merging from two or more import clients which have similar but not identical hierarchies, for folders which exist in multiple Clients but not in the Bookmarkshelf, if these clients do not themselves provide an Date Added, Date Added is assigned as the time of their import. Therefore, the folder from the client which is first in the Import Clients table will have an older Date Added, typically by a few seconds, and therefore will be the one that is kept.
If both folders were in the Destination before the Import or Export, then the one which has higher item quality is kept.
If one folder is from the source and the other is from the destination, which one is kept depends on the Merging Keep setting: If Merging Keep is set to Client, the folder from the Client is kept. If set to Bookmarkshelf, … Bookmarkshelf. (As stated above, if set to Both, the Merge Folders operation is not even performed.)
In most cases, it does not. A folder with the same lineage and the same name is pretty much the same folder. The only differences might be a couple of BookMacster attributes, such as sorted or not, sort at top/bottom, and the Auto-Click attribute which supported by a couple of browser apps.
Before writing or uploading items, BookMacster removes items which are not allowed or not desirable in the given the Export Client, or won’t work in any Client. Most of these are fairly obvious, but here are a few examples…
Some web browsers have esoteric, proprietary attributes on their bookmarks which are of no interest to BookMacster, you, or other browsers. For example, Opera sports an “ACTIVE” attribute to indicate that an item is selected in Opera’s Manage Bookmarks window, so that if you quit Opera and relaunch, that same item will be selected. OmniWeb also adds several of its own attributes that hardly anyone even knows exist. During an Import operation, BookMacster stores these attributes with the item, marked as applicable to that particular Client. During an Export operation to this Client browser, it writes them back out.
So, yes, BookMacster supports these esoteric, proprietary attributes, even though you don’t see them.
Some local Clients, notably Chrome and Firefox, and in particular the web app Clients (Google Bookmarks, Pinboard, Delicious) apply minor corrections or what we call normalization to the URLs of your bookmarks. For example, launch Firefox Show All Bookmarks, create a new bookmark and type in the URL “http://apple.com”. Notice that when you hit ‘return’, Firefox automatically adds a slash character to the end of the bookmark (signifying an empty “path” portion).
Actually this change can occur in one or more of three places:
What URL you see in the Show All Bookmarks, web page, or similar user interface
What URL they visit when you click the bookmark.
What URL gets returned to BookMacster when it downloads your bookmarks as part of an Import operation.
The last item is the one relevant to BookMacster. This is because BookMacster merges incoming and existing bookmarks during an Import or Export operation. For example, let’s say you that your perform an Export in BookMacster to Google Bookmarks, which uploads a bookmark whose URL is http://UpPpeR.cOM. If you later perform an Import from this Google account, BookMacster will receive a URL which has been normalized to contain only lower-case characters in the host portion, http://upper.com.
To minimize confusion and churning of bookmarks, BookMacster also normalizes any bookmark that you enter into it. There are a couple dozen rules in our algorithm, and our My Eyes Glaze Over Department did not allow us to enter them here. Generally, BookMacster mimics the behavior of Firefox and Chrome, which we have found to be reasonable except for a couple cases. Therefore, since the exported URL is already normalized, the Client will not make any further changes, and churn rarely occurs. One of these rare instances is when the path of a URL ends in ‘index.html’ and it is exported to Google Bookmarks. Google Bookmarks incorrectly, we believe, omits the ‘index.html’, and therefore when you re-import such a bookmark into BookMacster for the first time, an “update” of its URL will be tallied.
In BookMacster, as in most applications, Undo and Redo recall the state of the document (the Bookmarkshelf) before or after an action was performed and simply replace the current state with the the prior state. That is, they reverse the effect of the action on the document but do not, as their title implies, actually undo or redo the action.
This subtle difference is apparent with BookMacster’s Import command. After you Import, the Edit menu’s Undo item will be titled “Undo Import”. If you click this, your Bookmarkshelf’s content will be set back to the way it was before you imported from the browser/file(s).
Then, the Undo item will titled “Redo Import”. Now if you click this, your Bookmarkshelf’s content will be set back to the way it was after you imported from the Import Client(s), reflecting the content in the Client(s) at the time the original import was done. Thus, Redo recalls the content in the Clients at the the time the original import was done. Redo does not import their current contents, which may be different if data was changed within the Client, for example by adding a bookmark, in the meantime.
This concept is even more apparent when performing an Export. BookMacster’s Undo domain does not extend into other apps. And there is no Undo action available after an export; the Unsaved Changes Dot is not affected. (Actually, BookMacster does record the time of the export for considering whether future exports need to be done, but this change is recorded in Local Settings and therefore does not change the Bookmarkshelf. If it did, this would cause Online File Syncing Services to upload this local “change” to the cloud after saving, which would be incorrect.)
There are two ways to restore pre-export content in the Client itself. The first way is to restore the content of a Bookmarkshelf to the way it was before the export in the client, and then export again. The second way, available to advanced users and not applicable to web app Clients, is to quit the Client application, then restore the relevant file(s) from a Time Machine or other backup.
| Home | Parent | ← Go → | Prior | Next |