Tag Folders User Guide
- 1. Tag Folders User!s Guide Version 2.0
- 2. 2 of 21 © 2008 Jon Christian Stovell This work is licensed under the Creative Commons Attribution-Noncommercial-Share Alike 2.5 Canada Licence. To view a copy of this licence, send a letter to Creative Commons, 171 2nd Street, Suite 300, San Francisco, California, 94105, USA, or visit http://creativecommons.org/licenses/by-nc-sa/2.5/ca/
- 3. 3 of 21 Quick Start Guide" 5 Introduction" 5 Installation and Setup" 6 List of All Files Installed by Tag Folders! 7 Making Tag Folders " 8 Multi-word tags! 8 Spotlight comments! 8 Dropping files onto New Tag! 9 Ways to Access and Use Tag Folders" 9 Customizing a Tag Folder" 9 Basics of Tag Folder criteria! 10 Changing or adding tags and comments to an existing Tag Folder! 11 Keyword criteria! 11 Using other search criteria! 12 Automatically removing unwanted tags! 12 Including “Spotlight Items”! 12 Hierarchical Tag Folders " 13 Applying Extra Tags " 14 Optional settings " 15 Update modification times when tagging files! 15 Growl Notifications " 16 Tag Prompter" 16 Use! 16 Setup! 17
- 4. 4 of 21 What you will be prompted to tag, and what you will not! 17 How it works! 17 What not to do! 18 Comment to Tag Importer" 18 Troubleshooting" 19 Getting Support, Sharing Ideas, Etc." 20 Non-English users" 20 Source code, Licencing, and Modifications" 20
- 5. 5 of 21 Quick Start Guide Run the Tag Folders installer. Answer the setup questions, and then use “New Tag” to create new Tag Folders. Drag-and-drop files onto the icons of your Tag Folders in order to tag them. Open a Tag Folder to see all the files that have that tag. Save a file into a folder that is being watched by Tag Prompter in order to be prompted to tag it. Introduction Tag Folders are Applescript droplets that automatically apply OpenMeta tags (and, optionally, Spotlight comments) to files based on the search criteria of a Smart Folder contained inside each Tag Folder droplet. Opening a Tag Folder displays its Smart Folder, providing quick access to all files that have the associated tags. Thus, Tag Folders provide a simple, straightforward means of using Spotlight and Smart Folders to tag and organize files with minimal effort, using the familiar interface of the Finder. The advantage of Smart Folders over regular folders is clear: they bring together files that match certain conditions even though those files are actually scattered all over the hard drive. This means that one file can appear in any number of Smart Folders, allowing it to be grouped together with other files according to any set of criteria that the user finds meaningful. The same file might appear in a Smart Folder for your trip to Paris in 2004 (but not the return trip in 2007), in another Smart Folder for documents and images related to Gothic architecture, and in another that gathers materials from your previous successful grant proposals. However, Smart Folders take more effort to set up than regular folders, and a simple drag-and-drop does not allow a file to be moved from one group to another. An excellent solution to this limitation is the use of tags—small comments attached to a file—to quickly designate any arbitrary groups that the file should belong to. Tag Folders uses the OpenMeta tagging framework to create a simple, Finder-based, drag-and-drop method to apply tags quickly, easily, and automatically. Thus, Tag Folders are as easy to use as regular folders and as powerful as Smart Folders. They are what Smart Folders should have been.
- 6. 6 of 21 Installation and Setup To install Tag Folders, run the Install Tag Folders application on the Tag Folders disk image. It will place a copy of Tag Folders.app in your Applications folder, and then it will ask you some setup questions. The first question asks where to make the default folder in which new Tag Folders will be created. (The folder does not have to stay here permanently, and can be moved to a new location at any time you like.) A Tag Folder called New Tag will automatically be created inside this folder. The second question asks whether to run Tag Folders in legacy mode or in default mode. Legacy mode allows you to continue using older tagging applications that do not yet support OpenMeta tags. It is only necessary if you plan to keep using one of these older apps in the future. If you are no longer using a legacy tagging app, or if you have never used one, it is recommended that you choose default mode. Default mode provides extra functionality that is not available in Legacy mode. The third question asks what formatting to use with Spotlight Comments. There are several options available: • Spotlight default will simply write each word separated by spaces. • Natural Language separates each comment from the next using a comma and a space, as in normal English usage. • Users who have previously used other tagging applications to tag their files can maintain compatibility by selecting the appropriate formatting style from the list. Some of these options may ask for further information. • You may also choose to create a custom formatting style if the presets do not meet your needs. Custom formatting allows you to specify a custom comment delimiter (that is, the string of text used to separate one comment from the next) and/or a custom prefix and suffix to attach to any comments. You will also be asked whether every word of a phrase should be formatted as a separate comment (e.g. “a”, “new”, “comment”), or if the phrase as a whole should be treated as one comment (e.g. “a new comment”). After you have answered these questions, the installer will update all your existing Tag Folders to the latest version, and install all necessary support files. After this, Tag Prompter will launch and ask you its setup questions. Tag Prompter watches folders for new or changed files, and prompts you to tag them automatically. Click the Add folders button to choose a folder to watch. You may repeat this process to add as many folders as you like. To watch all the subfolders of a folder, or to stop watching a folder, click the Edit folder list button. When you are finished, click Save and Quit. You may change these settings at any time by running the main Tag Folders application from the Applications folder, and choosing “Configure Tag Prompter” from the pop up dialog box.
- 7. 7 of 21 Once you have answered these questions, you will be given the chance to create a new Tag Folder. Select New Tag from the list and click OK. Follow the directions under Making Tag Folders for help on how to make new Tag Folders. Finally, you will be asked to start the Comment to Tag Importer application. First it will ask if you want to import the comments of all files, or only the files in a specific folder. It will then tell you how many files it has found to work on, and ask you how often it should post progress notifications. Once you click the button to start the import, it will ask you for the Spotlight comment format that you have used in the past, and then start importing comments using those settings. You will receive progress notifications as the files are processed, and a notification when the import is complete. If any files encountered errors during the import, they will be listed in an error log file on your desktop. You can manually tag these files yourself at any time. Finally, the Comment to Tag Importer will run a check for illegal characters in the tags on your files, and offer to clean them up if found. List of All Files Installed by Tag Folders When Tag Folders are installed on your computer, the following files and folders are created: 1. /Applications/Tag Folders.app 2. /Library/Spotlight/OpenMeta.mdimporter 3. The default Tag Folders folder at a location you choose 4. A Tag Folder named New Tag inside the default folder 5. ~/Library/Application Support/Tag Folders 6. ~/Library/Application Support/Tag Folders/Settings.plist 7. ~/Library/Application Support/Tag Folders/Tag Folders (an alias to the default folder) 8. ~/Library/Application Support/Tag Folders/Tag Selected Files.app 9. ~/Library/Application Support/Tag Folders/Comment to Tag Importer.app 10. ~/Library/Application Support/Tag Folders/Tag Prompter.app 11. ~/Library/Application Support/Tag Folders/Tag Prompter Settings.plist 12. ~/Library/LaunchAgents/com.vndv.tagfolders.tagprompter.plist In addition, each Tag Folder that you make will create a corresponding Smart Folder inside ~/Library/Saved Searches. If you move a Tag Folder out of the default folder, when that Tag Folder is opened in its new location it will create an alias to itself inside the default folder. If you put the Tag Folder back into the default folder and open it again, the alias will be deleted. NOTE: If Tag Folders is installed by a user without administrator privileges, items 1 and 2 of this list will be installed to ~/Applications/Tag Folders.app and ~/Library/Spotlight/ OpenMeta.mdimporter.
- 8. 8 of 21 Making Tag Folders Making new Tag Folders is very easy. Just double-click on the Tag Folder named New Tag and a small dialog box will pop up asking you to enter the text for the new tags to use for your new Tag Folder. If you want to use more than one tag for this Tag Folder, simply type more words. Once you have created a Tag Folder, you can modify it further. This is especially helpful if you only want it to tag certain kinds of files, or if you want to create a Tag Folder that removes unwanted tags or comments. See Customizing a Tag Folder. Multi-word tags Normally, each word becomes a tag. But sometimes two words really belong together as a single tag (“New York” rather than “New”, “York”). To create a multi-word tag in the New Tag dialog box, enclose the words inside double quotation marks ( " ), like so: This example will create a Tag Folder with three tags: “New York”, “italian”, and “restaurant”. Spotlight comments If you are running Tag Folders in default mode, you will see a button labeled “Add Spotlight Comments…” in the New Tag dialog box. Legacy mode users will not see this button. Click “Add Spotlight Comments…” to display a second dialog box where you may enter some Spotlight Comments that you want this Tag Folder to search for and to apply to files. When entering Spotlight comments into the second dialog box, don’t include a tag prefix or suffix. Just use the plain words themselves. If you have set Tag Folders to use tag prefixes or suffixes, they will be added for you automatically.
- 9. 9 of 21 Dropping files onto New Tag If you have a set of files that you want to make a new Tag Folder for, drag them onto the icon for New Tag. This will create a new Tag Folder as described above, with the added benefit of automatically tagging the dropped files to match it. Ways to Access and Use Tag Folders There are several ways to access and use Tag Folders. By default, Tag Folders are stored inside a regular folder called “Tag Folders”. Opening this folder will give immediate access to all Tag Folders. However, Tag Folders may be kept anywhere you like. Aliases to Tag Folders in other locations will be made automatically in the default folder when the Tag Folders are opened. For example, you can put your favourite Tag Folder on your Desktop for easy access, and the first time you open it from there, an alias to it will be made in the default folder. This allows you to access your Tag Folder from the Desktop and from the default folder. Because of this, adding the default folder to the Finder sidebar or as a Stack in the Dock will give you quick access to all your Tag Folders, no matter where they are actually stored. As an alternative, you can put the Tag Folders application in the Dock, the Finder sidebar, or the Finder toolbar. Running the application will bring up a dialog box listing all your Tag Folders so you can either open them or add files to them. Adding the Tag Folders application to the Finder toolbar makes it easy to tag files even faster than by using drag-and-drop: if you have files selected in the Finder when you run the application, the list will offer to automatically add the selected files to whatever Tag Folders you choose. If you have nothing selected, it will offer to open the chosen Tag Folders instead. Finally, every Tag Folder will also have a corresponding Smart Folder stored in the Saved Searches folder of your user Library folder. This Smart Folder cannot apply tags to files, but it will show all files that appear in the Tag Folder. Any modifications made to the Tag Folder will immediately be reflected in this Smart Folder. Customizing a Tag Folder (Note: it is not recommended that you modify a Tag Folder after you start using it. Changing the criteria of a Tag Folder does not change the tags on the files it contains. The files will merely stop appearing in the Tag Folder because they no longer match its criteria. Instead, make and modify a new Tag Folder, add all the files of your old Tag Folder to the new Tag Folder, and then trash the old one. If you want to remove the old tags from your files, use the trick described in Making a Tag Folder automatically remove unwanted tags below.) Every Tag Folder package contains a Smart Folder whose search criteria are used to determine what tags it uses. Tag Folders may be changed by opening them and then
- 10. 10 of 21 modifying their search criteria. To do this, first make sure the Action menu button is included in the Finder toolbar. (This can be done by control-clicking on the toolbar and selecting “Customize Toolbar….”) Then in the Tag Folder’s window, select Show Search Criteria from the Action menu. This will show the current criteria used by the Tag Folder. Basics of Tag Folder criteria When a new Tag Folder is created, you are asked to provide the text for one or more tags. The Tag Folder then simply looks for files that have those tags attached to them. However, a Tag Folder may be much more complex than that, using many different search criteria. These complex Tag Folders can be created by modifying a newly generated Tag Folder to include these custom criteria. Figure 1 Figure 1 shows an example of a complex Tag Folder. It finds all files that (1) have “example” in their tags or their keywords, (2) are PDFs, (3) either (a) have “urgent” in their Spotlight comments or (b) were created this week and have “testing” in their tags, and (4) do not have “tag to remove” in their tags. If a PDF is dropped onto this Tag Folder’s icon, it will be tagged with the tags “example” and “testing”, and also be given
- 11. 11 of 21 the Spotlight comment “urgent”. If the file has “tag to remove” in its tags, “tag to remove” will be removed from its tags. Changing or adding tags and comments to an existing Tag Folder Tag are defined using Tags criteria. The text box of a Tags criterion contains the text that will be used as the tag. There should be only one tag per criterion. Similarly, Spotlight comments are defined using Spotlight comment criteria. The text box of a Spotlight comment criterion contains the exact text that will be used as the comment. This must include any prefix or suffix used in your comment formatting style. It must not include the comment delimiter from your comment formatting style. Again, there should only be one comment per criterion. To change the tag or the comment that a Tag Folder uses, simply change the text in the Tags criterion or the Spotlight comment criterion and click the Save button. To add a new tag to the Tag Folder, click on the (+) button and then choose “Other…” from the first drop-down menu of the new criterion. After a few moments a dialog box containing a large number of possible search criteria will open. Choose “Tags” and click OK. (It is a good idea to check the “In Menu” checkbox next to “Tags” before clicking OK, so that tags criteria will be more easily available from now on.) To add a new Spotlight comment, follow the same method, but using “Spotlight comment” in place of “Tags”. To make complex search criteria using Any, All, or None, hold down the Option key and click on the (+) button next to an existing line of the search criteria. With the Option key pressed, the (+) button will change to a (…) button, allowing the insertion of Any, All, or None criteria groups. NOTE: When using a Tags criterion, it is best to choose “is” from the second drop-down menu. Using “matches” or “contains” may produce false positives, and the others may fail to find files that actually do have the desired tags. For example, “Tags matches foo” will find all files with the tag “foo” but also all files with the tag “foobar”. On the other hand, for Spotlight comment criteria it is best to use “contains”. The reason for this is that whereas each OpenMeta tag exists as a separate entity, all the Spotlight comments are mushed together into a single string of text. If “is” is used with a Spotlight comment criterion, it will only find files that have that word, and only that word, in their Spotlight comments. Since it is likely that you will have several different words in the comments of your file, it is best to use “contains”. Keyword criteria By default, a Tag Folder always searches for files that match its tags in either their OpenMeta tags or in their keywords. As shown in Figure 1, this is accomplished by including both a Tags criterion and a Keywords criterion in an Any criteria group. It is generally a good idea to follow this method when customizing a Tag Folder.
- 12. 12 of 21 Unlike tags and comments, keywords cannot be written to a file that is dropped onto a Tag Folder!s icon. Keywords are embedded into the file data itself, and cannot be edited without opening and editing the file. Using other search criteria Criteria besides tags, comments, and keywords can also be included in your Tag Folder. In order for a file to be tagged by your Tag Folder, it must meet this other criteria included. The basic rule of thumb here is that any file the Tag Folder could find (assuming it had the right tags, comments, and/or keywords) is a file the Tag Folder can tag. For the example Tag Folder shown in Figure 1, only PDFs can be tagged with this Tag Folder. A text document dropped onto this Tag Folder will be ignored. This is because only PDFs can ever be found by this Tag Folder. On the other hand, even though there is a criterion looking for files created this week, this Tag Folder will tag a PDF of any age that dropped onto it. This is because of where the “Created date is this week” criterion is located in the logical structure of the Tag Folder. Being created this week is part of only one possible way to satisfy the search criteria. Any PDF that had the tag “example” and and the Spotlight comment “urgent” would also satisfy the search criteria, so any PDF can be given the tags and comments to let it do so. Automatically removing unwanted tags If you include a None criterion and put a tag or comment criterion beneath it, qualifying files dropped onto the Tag Folder will have that tag or comment removed from their list of tags.1 For the example Tag Folder shown in Figure 1, any PDF that is dropped onto the Tag Folder’s icon will have the tag “tag to remove” removed from its tags. This feature can be especially helpful if you want to get rid of a certain tag from a large number of files with a minimal amount of work. Including “Spotlight Items” As of version 1.3, Tag Folders include “Spotlight Items” by default. Spotlight Items include human readable representations of iCal events, Address Book contacts, and email messages. Including Spotlight Items in the search criteria of a Tag Folder makes it easy to tag these items and to display them in a Tag Folder when it is opened. To make best use of this feature, you will typically have to do a search in the Spotlight menu for the item you want to tag, and then select Show All in the menu to open a 1However, double negatives are respected in making this decision. If a None criterion contains another None criterion that contains a tags criterion, the tag in that criterion will be applied to files.
- 13. 13 of 21 Finder window displaying the search results.2 You can then drag the desired item onto a Tag Folder to tag them. It will appear in the Tag Folder from then on. Unfortunately it is not possible to drag an email, iCal item, or contact directly from Mail, iCal, or Address Book onto a Tag Folder. However, in Address Book you can right-click on a contact and choose the Spotlight option from the contextual menu to quickly open a Finder search window from which you can tag the contact (and any other files connected with that contact). In combination with keyword search criteria (see above), MailTags can make it easy to add email messages to a Tag Folder without having to leave the Mail.app interface. Just use MailTags to tag an email with a keyword that matches a Tag Folder, and the email will appear in that Tag Folder next time you open it. If you do not want to include Spotlight items in a Tag Folder, you can simply remove the Spotlight Item search criterion from the Tag Folder’s criteria. Hierarchical Tag Folders Tag Folders can contain other Tag Folders, and files added to a child Tag Folder also inherit the tags and comments of the parent Tag Folder. Suppose you have a Tag Folder that searches for the tag “Project 1” and another that searches for the tag “Work”. If you drop the “Project 1” Tag Folder onto the “Work” Tag Folder, it will become a child of “Work” and will appear as an item inside the “Work” Tag Folder. This is very similar to the way regular folders work, with one folder nested inside another to create a hierarchy, except that the Tag Folders can also exist side by side or in entirely different locations. Moreover, a Tag Folder can have more than one parent, allowing it to appear in a number of other Tag Folders. Files added to a child Tag Folder have that Tag Folder’s tags applied to it, as well as the tags of the parent Tag Folder(s). Once “Project 1” has been added to “Work”, any files added to “Project 1” will be tagged with the tags that “Project 1” applies, and also with the tags that “Work” applies. Under normal circumstances, this means that the file will now appear inside both “Project 1” and “Work”. There are some situations in which a file added to a child Tag Folder might not appear in a parent Tag Folder: 1. If you have already begun tagging files with a Tag Folder before you make that Tag Folder the child of another Tag Folder, the files you previously tagged will not be added to the parent Tag Folder automatically. 2 For example, to add Tom Thumb’s contact information to a Tag Folder about a 2008 project proposal, search in the Spotlight menu for “Tom Thumb kind:contact”. To find some key email messages you exchanged with Tom Thumb about the proposal, search for “Tom Thumb 2008 proposal kind:mail”. Note that you do not need to include the “kind:” part of the search, since all kinds are included by default, but doing so will help narrow down the results you get.
- 14. 14 of 21 2. If a file bears a tag that has been excluded from the parent Tag Folder3 but has not been excluded from the child Tag Folder, adding the file to the child Tag Folder will not make it appear in the parent Tag Folder. 3. If the parent Tag Folder includes other kinds of search criteria besides tag, comment, or keyword criteria,4 the file will only appear there if it matches those additional search criteria. The first two of these situations can be addressed by selecting the files of the child Tag Folder and dropping them onto the icon of the parent Tag Folder. Applying Extra Tags Aside from the tags used in a Tag Folder’s search criteria, extra tags may also be applied to files dropped onto a Tag Folder. This is useful if, for example, you want your Tag Folder to show you all files with the tag “French Revolution”, but to tag files with both “French Revolution” and “research”. The mechanism to do this is very simple: apply tags or comments to the Tag Folder itself. To apply extra tags and comments to a Tag Folder, all you need to do is drag your Tag Folder onto New Tag, enter the desired tags and/or comments in the New Tag dialog box, and click OK. This will apply the tags to your existing Tag Folder, and also create a second Tag Folder that searches for those tags. You may safely delete the second Tag Folder if you don!t need it: the original Tag Folder will keep its tags even if the second one is deleted.5 Alternatively, you can apply tags to a Tag Folder using any other OpenMeta tagging application. You can also apply extra Spotlight comments directly to a Tag Folder by selecting it in Finder, choosing Get Info from the File menu, and then typing the comments into the Spotlight comments section of the Info palette. (Note that any text entered in the Spotlight comments of a Tag Folder will be applied without alteration6 to all files dropped onto the Tag Folder’s icon. If you set Tag Folders to attach a prefix or suffix to your comments, make sure to include them in any comments you enter here.) 3 See Automatically removing unwanted tags above. 4 See Using other search criteria above. 5Astute readers will notice that this is the basically same method that is used to create hierarchical Tag Folders, except that you are then throwing away the parent Tag Folder. 6Except in the case of Punakea formatted comments. If the user chooses Punakea compatibility when setting up Tag Folders, any Punakea formatted comments added to a Tag Folder’s Spotlight comments will be parsed and processed in order to properly apply them to files. However, even in this case any Spotlight comments that are not in Punakea format will be passed on to tagged files without alteration.
- 15. 15 of 21 Note that if you have already tagged some files with a Tag Folder, and you then add extra tags or comments to the Tag Folder, those extra tags and comments are not automatically applied to previously tagged files. To update the previously tagged files with the new tags, re-add them to the Tag Folder. Optional settings Update modification times when tagging files Normally, when you tag a file its modification time is not changed. No data inside the file itself has been changed in any way, so OS X does not consider the file to have been modified. In normal use this is the desired behavior. It is not recommended that you update modification times when tagging files unless you really, really need to. Turning on this feature will cause backup software such as Time Machine to make unnecessary backups of your tagged files every time a tag or comment changes on them, and so will end up consuming lots of disk space for no good reason. This is not necessary, because the OpenMeta framework has a transparent tag backup system already in place so that your tags are automatically backed up and restored to your files without having to back up the entire file along with the tags that are attached to it. However, some users may have a situation where they need to change this behavior. For example, some users may use file synchronization applications that do not properly support syncing extended attributes (such as tags and Spotlight comments). Some, but not all, syncing applications may be helped by updating the modification times of tagged files. The best solution is to upgrade to a syncing app that does handle them properly (see below for a list of good ones). But if that is not an option, some users may have success syncing their tags by telling Tag Folders to update the modification time of a file when tagging it. To activate this feature, you will need to edit the file ~/Library/Application Support/Tag Folders/Settings.plist. Depending on your computer, this file might open in TextEdit or in Property List Editor when you double-click on it. In TextEdit, search for the line that says “<key>update_modification_time</key>”, and then change the next line from “<false/>” to “<true/>”. In Property List Editor, click on the triangle next to “Root” to show the list of settings, and then change the value of “update_modification_time” from “No” to “Yes”. Settings.plist also provides an option to update the access time of a file (using the setting called update_access_time). It is unlikely that this option will ever be useful to anyone, but it is there if you need it. Note that some syncing applications do not support extended attributes (such as tags and Spotlight comments) at all. For these apps, updating the modification time of a file will not help in any way. This option is only useful for syncing apps that are able to sync the extended attributes, but do not check the extended attributes when deciding whether or not to sync the file in the first place.
- 16. 16 of 21 A better way to sync your files, including the tags, is to use a syncing app that fully supports extended attributes: • If you are a MobileMe subscriber ($99/yr), your iDisk should handle this effortlessly and just as you would expect. • ChronoSync ($40) does well with synchronizing tags and Spotlight comments along with the files themselves. Just make sure that ChronoSync is configured to preserve extended attributes and to sync invisible files. • The command line tool rsync, which is included with OS X, is able to preserve tags and Spotlight comments properly when used with the -E option.7 Rsync only syncs in one direction, so if you need two-way syncing, consider Unison instead. Many easy-to- use synchronization applications are available that are based on rsync. • Unison (free) does full bidirectional syncing, with full support for extended attributes enabled by default when syncing between OS X clients. It has a GUI and a command line interface. Growl Notifications As of version 1.1, Tag Folders can provide Growl notifications when files are tagged. Progress reports via Growl can also be displayed when tagging a large number of files at once. Growl notifications are configured using the Growl preference pane in System Preferences. Tag Prompter Tag Prompter is a helper application that assists you in keeping the tags on your files up to date. It watches folders for new or modified files and prompts you to tag them automatically. This advancement makes it almost effortless to keep your files properly tagged and organized and to avoid the otherwise inevitable accumulation of forgotten, untagged files. Use Suppose you are working on a new document, and after making some good progress you save the document to your Documents folder. With Tag Prompter watching your Documents folder, a dialog box will appear within a moment or two offering to tag that document by adding it to any Tag Folders you choose. Aside from selecting the appropriate Tag Folder(s) from the list, no further work on your part is needed. 7Type man rsync in Terminal to see the user manual for rsync. The key option for preserving Spotlight comments with the version of rsync included with Leopard is the !E option. For rsync version 3.0 or later, use !X instead of !E
- 17. 17 of 21 Setup Tag Prompter can watch whatever folders you choose. To quickly add folders to the list of folders that Tag Prompter watches, simply drag-and-drop them onto the main Tag Folders application icon (located in your Applications folder by default). You will be asked whether you want to start watching the folders for changes. For more control over the list of watched folders, run the main Tag Folders application and select “Configure Tag Prompter” from the startup dialog. This will start the Tag Prompter configuration applet that allows you to add or remove folders from the watch list. The “Add folders” button allows you to select new folders to watch. Use the “Edit folder list” button to stop watching a folder or to start watching a folder’s subfolders. When you are done choosing what folders you want Tag Prompter to watch for changes, click the “Save and quit” button. You may reconfigure Tag Prompter again at any time to change your settings. The Tag Prompter applet is stored in the Tag Folders application support folder. Do not move it from this location, or it will stop working. What you will be prompted to tag, and what you will not First, Tag Prompter will only prompt you to tag files that do not have anything written in their Spotlight comments. If you have already tagged a file and then make changes to it, Tag Prompter will not bother you about it. Second, Tag Prompter only prompts you to tag files. It will not prompt you to add tags to folders you create. If you want to tag a folder you will have to do so by the usual methods. If you tell Tag Prompter to watch all the subfolders of a folder and then later make a new folder somewhere inside that folder, you will be asked whether you want to start watching the new folder as well. For example, suppose I have a folder called Work that contains three subfolders, Project 1, Project 2, and Project 3, and I tell Tag Prompter to watch Work and all its subfolders. If I then create a new folder called Estimate inside Project 1, Tag Prompter will pop up and ask me if I would like to start watching Estimate for changes. How it works Tag Prompter uses OS X’s built-in technologies to provide its services. The actual watching is done by the operating system itself using a “launch agent.” Launch agents are used by the operating system to perform all sorts of tasks. By using a launch agent, Tag Prompter can run continuously while using almost no resources on your computer at all. The launch agent called com.vndv.tagfolders.tagprompter watches the folders you choose for changes. When a change is detected by the launch agent, one of Tag Prompter’s Applescripts is called to determine whether or not to prompt you to tag the new/changed file(s).
- 18. 18 of 21 However, when a launch agent watches a folder, it only looks down one layer deep: if a file changes in a subfolder of the watched folder, you will not be prompted to tag it. To watch the contents of the subfolder, you must add the subfolder to the list of watched folders. What not to do Do not go crazy watching subfolders! It is a bad idea, for example, to tell Tag Prompter to watch all the subfolders of your home folder. First, you really don’t want to be prompted to tag every little file that ever changes in the bowels of your Library folder. Second, although I worked hard to make Tag Prompter as quick as possible, sorting through thousands upon thousands of unnecessary items will slow it down. It is also a bad idea to tell Tag Prompter to watch your iTunes library, the contents of your iPhoto library, etc. Applications like these already have built-in systems for managing files (including tagging with keywords), and their data should be left alone. I recommend watching your Documents folder, perhaps your Desktop folder, and any other folders that you actively use on a regular basis. Leave those dusty old long-term storage folders off the list; watching them will only slow things down for no real gain. Comment to Tag Importer Tag Folders 2.0 includes an importer applet that can import Spotlight comments into OpenMeta tags. This importer runs once at the end of the installation of Tag Folders, and can be run again at any time by selecting “Import Spotlight comments” from the startup dialog of the main Tag Folders app. You may either import the comments of all files on your computer, or the files in a folder you choose. You will be informed of how many files there are to be imported, and asked how often to display progress notifications. Finally, you will be asked for the formatting system you used on your existing Spotlight comments. Since this may not be the same as what you told Tag Folders to use for formatting your current comments, you have to define it again here. The importer will then copy over all the Spotlight comments of your files into OpenMeta tags. Progress notifications will be displayed at the frequency you specified. When the import is complete, you will be informed if there were any files whose comments could not be imported. If there were any such files, a list of them will be created on your desktop in a file called Spotlight comment import error log.txt. Finally, the importer will double check that there are no illegal characters in the OpenMeta tags, and will clean them up if there are.
- 19. 19 of 21 Troubleshooting If your Tag Folders do not behave as expected, there are a few things you can try. 1. Make sure the file you want to tag meets the criteria of your Tag Folder. If you cannot tag a file with a particular Tag Folder, check whether the Tag Folder has been set to accept only certain files and whether your file meets those criteria. To add your file, you will need to either change it to match the criteria of the Tag Folder, or change the criteria of the Tag Folder to allow the file. 2. Reinstall Tag Folders. This can address a wide variety of problems. 3. If Tag Prompter doesn!t seem to do anything: i. Make sure the files you want to be prompted for do not already have something written in their OpenMeta tags or their Spotlight Comments, and are not folders. Tag Prompter will not prompt you to tag either of these. If you want to add, remove, or change the tags on such a file or folder, drop it onto the icon of a Tag Folder. ii. Use Terminal to make sure Tag Prompter is running. Open Terminal and type launchctl list | grep tagprompter at the command prompt. If Tag Prompter is running properly, the result should say - 0 com.vndv.tagfolders.tagprompter or something like 4895 - com.vndv.tagfolders.tagprompter In the first example, Tag Prompter is running normally, but currently has nothing to work on. If the result contains a 1 instead of a 0 in the second column, Tag Prompter is running, but is encountering an error. In the second example, Tag Prompter is actively processing a file and probably waiting for you to give it an answer to a question. Note that in the second example, the number in the first column will be different every time. If nothing comes back as a result of this command, select “Configure Tag Prompter” from the Tag Folders.app startup dialog in order to restart Tag Prompter. After clicking the Save and Quit button, check again in Terminal again. 4. Rebuild the Spotlight database. Tag Folders and Tag Prompter are highly dependent on the database Spotlight maintains of the files on your computer. If there is any corruption of the Spotlight database, Tag Folders and Tag Prompter may not
- 20. 20 of 21 be able to work as intended. Instructions on how to rebuild the Spotlight database can be found here. 5. If none of the above works, open the script contained inside the application bundle using Script Editor and run it that way to find out what errors might be happening. Control-click on the application in question, choose Show Package Contents from the contextual menu, and then navigate to Contents/Resources/ Scripts. Tag Folders only contain one script. Tag Prompter contains two: main.scpt runs the setup functions, and TagPrompterScript.scpt analyzes files to decide whether to prompt you. Choose the appropriate script to test, open it, and run it using the big green run button in Script Editor. If the script encounters any errors, it will notify you about them. If you know how to fix this yourself, please do so and then contact me by posting on the Tag Folders Google Group so I can update the software for everyone. If not, please post on the Tag Folders Google Group with the error report so I can work on a fix. Getting Support, Sharing Ideas, Etc. Tag Folders is freeware, and I actually do something entirely different from software development with most of my time. So I promise you nothing. That said, I like being helpful, and there are lots of other people in the world who like being helpful too. If you want to talk about Tag Folders, report a bug, get some help, or share an idea, the best way to do that is to go to the Tag Folders Google Group at http://groups.google.com/ group/tag-folders. There you can post messages to me and other readers. Non-English users Tag Folders version 1.2 and higher should work with all language settings on Mac OS X. However, Tag Folders currently only has English dialog box messages. If you would like to help translate the Tag Folders interface into your language, please contact me by posting on the Tag Folders Google Group. In earlier versions of Tag Folders, non-English users sometimes received errors due to English specific terms, and had to modify the Tag Folders source code. This should no longer be the case. Source code, Licencing, and Modifications Tag Folders.app, Tag Prompter.app, and Comment to Tags Importer.app are distributed under the GPL 3.0 licence. A copy of the licence is included inside the application bundle of every Tag Folder, and inside the application bundle of Tag Prompter.app and Comment to Tags Importer.app. The source code for Tag Folders can be accessed by opening Contents/Resources/Scripts/main.scpt inside the application bundle of any Tag Folder. The source code for Tag Prompter can be accessed by opening the .scpt files in Contents/Resources/Scripts/ inside the application bundle of Tag Prompter. The source code for Comment to Tags Importer can be accessed by opening Contents/Resources/ Scripts/main.scpt inside the application bundle of Comment to Tags Importer.app. If you make any improvements to the source code of Tag Folders or Tag Prompter and believe
- 21. 21 of 21 they may be beneficial to others, please consider submitting them to the Tag Folders project by posting on the Tag Folders Google Group. The Tag Folders icon is based on an icon created by Jonathan Hunt at iconaholic.com, and is used by permission, with many thanks.