Overview
PDFoo is a Mac OS X app designed to help you quickly locate information in your PDFs.
The concept is simple:
The concept is simple:
- Build a URL to link to a PDF, or to any location within the PDF.
- Write & refer to these URLs anywhere – in your emails, on a web page, or your favorite note-taking app.
- Later, when you click the URL, the PDFoo app opens up PDF to the correct page.
How PDFoo Works
The PDFoo app only responds to URLs that start with “pdfoo://”.
Figure 1 shows the simplest pdfoo:// URL, one that is configured to open the PDFoo Overview help document within the PDFoo app. Notice that the URL contains a keyword “apphelp” that enables PDFoo to identify the PDF the user wants to open. In PDFoo documentation, this keyword is known as a “Prefix”. In essence, when PDFoo is asked to open a pdfoo:// URL, it compares the prefix in the URL against an internal list of prefixes, and opens the matching PDF.
Figure 1 shows the simplest pdfoo:// URL, one that is configured to open the PDFoo Overview help document within the PDFoo app. Notice that the URL contains a keyword “apphelp” that enables PDFoo to identify the PDF the user wants to open. In PDFoo documentation, this keyword is known as a “Prefix”. In essence, when PDFoo is asked to open a pdfoo:// URL, it compares the prefix in the URL against an internal list of prefixes, and opens the matching PDF.
In the simplest form (Figure 1), clicking on the URL will open the PDF to the first page. While this is useful, you will often want to link to a particular page or section in an important PDF. Figure 2 shows other URLs that link to specific pages in the PDF.
The first example links to page 3 in the help document, the second example looks for a Table of Contents (TOC) entry that matches “toolbar”, and the third example looks for a nested TOC entry that matches “automatch” under a TOC entry that matches “pref”. Figure 3 shows the entire TOC for this PDF and how these two URLs map to specific locations within the TOC. When you click on such a URL, the PDFoo app figures out which TOC entry is the best match and opens the PDF to the corresponding page.
In this manner, PDFoo enables you to build readable URLs to specific pages in your PDF. You can either construct these URLs manually, or let PDFoo build these for you quickly and correctly.
In this manner, PDFoo enables you to build readable URLs to specific pages in your PDF. You can either construct these URLs manually, or let PDFoo build these for you quickly and correctly.
Understanding the Prefix
The prefix, such as “apphelp” in Figures 1-3 above, is the most important part of the pdfoo:// URL. The PDFoo app can open the correct PDF only if it recognizes the prefix in the URL. At any point, the complete list of prefixes that PDFoo understands can be seen in the Preferences dialog, under the Prefix tab (Figure 4).
To add a prefix for a particular PDF, do the following: first, open the PDF via File > Open or drag the PDF(s) onto the PDFoo dock icon; second, assign a unique prefix to each PDF via the “Set Prefix” button on the toolbar.
To add a prefix for a particular PDF, do the following: first, open the PDF via File > Open or drag the PDF(s) onto the PDFoo dock icon; second, assign a unique prefix to each PDF via the “Set Prefix” button on the toolbar.
Pair a Prefix to a PDF
To assign a Prefix to a PDF, you must first open the PDF in PDFoo app, via the File menu > Open… command. PDFoo will assign a random prefix to this PDF (Figure 5), and the prefix is shown in a red box on every page of the PDF. To assign your own prefix, click the “Edit Prefix” button on top left of the toolbar. Specify a prefix for this PDF, say “speedupmac” (Figure 6) and thereafter, you can use the pdfoo://speedupmac/ URL to open this PDF on your Mac.
Hand-crafted URLs
There is no magic behind creating pdfoo:// URLs. The URLs are logical and readable, and PDFoo does the work of matching it to the right spot in the PDF.
You can either create a URL to link to a particular page, or to a particular Table of Contents (TOC) item. On each page, a red box shows the page label corresponding to that page, and which can be used to construct a URL. For example, to link to the page shown in Figure 7, the URL should be pdfoo://speedupmac/53.
Let’s now create a URL to the TOC item “Check Your Resource Usage”, also shown in Figure 7. The obvious rules are: no spaces are allowed, and capital case is not required. In addition, PDFoo requires use of dot (“.”) to separate words in the TOC item, words may be truncated at either end, and the order of words is important. According to the rules, all of the following URLs are valid for the TOC item “Check Your Resource Usage”
However, not all of these URLs may uniquely identify the TOC item. For instance, if there is another TOC item titled “Check Memory Usage”, then clearly a URL of the form pdfoo://check.usage/ is ambiguous. In such cases, PDFoo selects the first matching TOC item in the PDF.
Hand-crafting URLs is hard work but useful when PDFoo is not on hand to build the URLs for you. When reviewing a PDF away from your Mac, you can still hand-craft a pdfoo URL for your notes, such as to mark out important chapters in a reference PDF.
You can either create a URL to link to a particular page, or to a particular Table of Contents (TOC) item. On each page, a red box shows the page label corresponding to that page, and which can be used to construct a URL. For example, to link to the page shown in Figure 7, the URL should be pdfoo://speedupmac/53.
Let’s now create a URL to the TOC item “Check Your Resource Usage”, also shown in Figure 7. The obvious rules are: no spaces are allowed, and capital case is not required. In addition, PDFoo requires use of dot (“.”) to separate words in the TOC item, words may be truncated at either end, and the order of words is important. According to the rules, all of the following URLs are valid for the TOC item “Check Your Resource Usage”
- pdfoo://speedupmac/check.your.resource.usage/
- pdfoo://speedupmac/check.resource.usage/
- pdfoo://speedupmac/check.res.usage/
- pdfoo://speedupmac/resource.usage/
However, not all of these URLs may uniquely identify the TOC item. For instance, if there is another TOC item titled “Check Memory Usage”, then clearly a URL of the form pdfoo://check.usage/ is ambiguous. In such cases, PDFoo selects the first matching TOC item in the PDF.
Hand-crafting URLs is hard work but useful when PDFoo is not on hand to build the URLs for you. When reviewing a PDF away from your Mac, you can still hand-craft a pdfoo URL for your notes, such as to mark out important chapters in a reference PDF.
PDFoo Can Build URLs for You
PDFoo makes it easy to create unique URLs for your TOC items. Where necessary, it lengthens the URL to capture nested TOC items uniquely. For example, for the TOC item “Check Your Resource Usage” in Figure 7, PDFoo may come up with pdfoo://speedupmac/diagnose/check.your.resource.usage/ that takes into account the parent TOC entry “Diagnose Common Speed Problems.”
In this manner, PDFoo tries hard to generate unique URLs for you. When it cannot, it will at least provide the equivalent page URL, i.e. pdfoo://speedupmac/53.
PDFoo provides a Scratchpad note-taking pane on the left (Figure 8), where it places all generated URLs. The Scratchpad is a free form writing area, and helps while you’re browsing a PDF making notes along the way. The buttons at the bottom allow you to switch amongst 5 scratchpads. The content in these scratchpads is automatically saved, and these scratchpads are available across all PDFs opened in PDFoo. The content in a scratchpad can be easily copy-pasted into other note-taking apps such as Evernote, OmniOutliner, and Curio that preserve rich-text formatting and pdfoo:// URLs.
You can insert links into the current Scratchpad using the toolbar buttons grouped together as “Insert Link”. The specific form of the URL generated depends on the state of the button marked “Format URL” on the toolbar (Figure 8).
In this manner, PDFoo tries hard to generate unique URLs for you. When it cannot, it will at least provide the equivalent page URL, i.e. pdfoo://speedupmac/53.
PDFoo provides a Scratchpad note-taking pane on the left (Figure 8), where it places all generated URLs. The Scratchpad is a free form writing area, and helps while you’re browsing a PDF making notes along the way. The buttons at the bottom allow you to switch amongst 5 scratchpads. The content in these scratchpads is automatically saved, and these scratchpads are available across all PDFs opened in PDFoo. The content in a scratchpad can be easily copy-pasted into other note-taking apps such as Evernote, OmniOutliner, and Curio that preserve rich-text formatting and pdfoo:// URLs.
You can insert links into the current Scratchpad using the toolbar buttons grouped together as “Insert Link”. The specific form of the URL generated depends on the state of the button marked “Format URL” on the toolbar (Figure 8).
Linking into PDFs using the Toolbar
The toolbar has six buttons for generating URLs, grouped as “Format URL” and “Insert Link.” Figure 9 shows three possible formatting options for a URL generated for the TOC item “Check Your Resource Usage”. The three buttons in the “Format URL” group act as selectors – one and only one of them is active at any point, and it controls the visual display of the URL that is inserted into the scratchpad.
Note that the underlying URL is always the same, with the entire pdfoo:// prefix, and only the visual appearance changes based on the selected “Format URL” button. When the content is copy-pasted from the Scratchpad into a rich text-compatible note-taking app such as Evernote or TextEdit, the pdfoo:// links will continue to work. For scenarios where you wish to copy-paste the content into plain-text apps, it is recommended to generate full-length URLs that start with pdfoo://.
Note that the underlying URL is always the same, with the entire pdfoo:// prefix, and only the visual appearance changes based on the selected “Format URL” button. When the content is copy-pasted from the Scratchpad into a rich text-compatible note-taking app such as Evernote or TextEdit, the pdfoo:// links will continue to work. For scenarios where you wish to copy-paste the content into plain-text apps, it is recommended to generate full-length URLs that start with pdfoo://.
The “Insert Link” group also allows generating links to the current page, and to the entire PDF. Two of the three “Format URL” options are applicable for these links.
Search & Collect
On the right side of the toolbar is a search button, which allows you to search through the PDF – including text, annotations, and TOC items. Use the text, annotation, and TOC filter buttons to restrict the search. Click through the results to browse the PDF, and drag the search results into the Scratchpad to create pdfoo:// URLs to the correct pages.
The search button provides a convenient way to extract your annotations from the PDF, with a pdfoo:// link back to the page on which each annotation occurs.
If you want to extract all annotations in the PDF, select File menu > Export Annotations in PDF command, and all annotations, with corresponding pdfoo:// links back to PDF pages, will be extracted to a new RTF document.
The search button provides a convenient way to extract your annotations from the PDF, with a pdfoo:// link back to the page on which each annotation occurs.
If you want to extract all annotations in the PDF, select File menu > Export Annotations in PDF command, and all annotations, with corresponding pdfoo:// links back to PDF pages, will be extracted to a new RTF document.
PDFoo Preferences
The Preferences window has three tabs: the Prefix tab allows you to manage the list of prefixes recognized by PDFoo; the AutoMatch tab allows you to set up filenames and prefixes that PDFoo should automatically assign when it opens a PDF with a matching filename; and the Behaviors tab allows finer control over PDFoo’s features.
The Prefix Tab in Preferences
The Prefix tab provides a complete list of prefix previously assigned to PDFs. One prefix may be assigned to only one PDF. However, if you so wish, you can assign multiple prefixes to the same PDF.
- Use the add(+) and remove(-) buttons to edit the list of prefixes. The add(+) button shows the File > Open dialog where a new PDF file may be selected. When the PDF is opened, it is assigned a random prefix. You must use the “Edit Prefix” button on the toolbar to explicitly set the prefix. Once this is done, the newly assigned prefix will appear in the Prefix tab.
- You can double-click on any prefix row to open that PDF in PDFoo. You can also CMD double-click on the prefix row to show the PDF location in Finder.
- You can edit the prefix directly in the row, by (1) click on prefix text to highlight the row, (2) pause and click again. However, bear in mind that PDFoo will no longer recognize any incoming pdfoo:// URLs with the old prefix.
- You may encounter red-colored rows in the Prefix tab. This indicates that the link to the underlying PDF is broken – usually because it was deleted, or occasionally because it was moved. Any red-colored rows must be deleted manually, and
- You can select multiple rows and drag out the contents to a text file. The prefix and PDF file path are copied in a ordered format with special markers such as [prefix]. This text file can be dragged into the AutoMatch tab of another instance of PDFoo (say PDFoo on a colleague’s Mac) to quickly & correctly assign prefixes when PDFs with an identical filename are opened on the other Mac.
- You cannot drag text or PDFs into the Prefix tab. The only way to add content is via the File > Open command, or the equivalent add(+) button as described above. This restriction is necessary to conform to Apple Sandboxing guidelines.
PDFoo Preferences: The AutoMatch Tab
The AutoMatch tab aims to make it easier to share your prefix library across Macs.
Consider the following scenario: You keep all important, high-quality PDFs in a Dropbox folder, and set up prefixes on your iMac at home to link into these PDFs. You use Evernote to store your notes and pdfoo:// links, and everything works great on your iMac. Now, you would like to access these PDFs from your Macbook Air, where your Evernote account is already set up and synced. When you click on pdfoo:// links in Evernote, the PDFoo app opens but does not recognize the prefixes. It asks you to open the PDF for each prefix. You would like to migrate the prefix assignments from your iMac to your Macbook Air. And AutoMatch makes it (relatively) easy.
Conceptually, the AutoMatch feature is simple: When a new PDF is opened in PDFoo, if it doesn’t already have a prefix assigned (as listed in the Prefix tab) then before it decides to assign a random prefix, it will pause to check the AutoMatch list – if the AutoMatch list contains a suggested prefix for a PDF bearing that name, it will go ahead and assign that prefix to the newly opened PDF. It bypasses the step of “Edit Prefix” to rename a randomly-assigned prefix.
The AutoMatch tab comes with an OFF-ON switch, and PDFoo ships with AutoMatch turned ON.
Follow these steps to copy your prefix assignments from your iMac to Macbook Air:
You can also use the steps above to copy prefix assignments between colleagues collaborating on a set of PDFs. AutoMatch looks for a match in PDF filenames, and the exact path on disk does not have to match. When a PDF with a recognized name is opened, the correct prefix will be automatically assigned, and pdfoo:// URLs will work seamlessly on all the Macs thereafter.
Consider the following scenario: You keep all important, high-quality PDFs in a Dropbox folder, and set up prefixes on your iMac at home to link into these PDFs. You use Evernote to store your notes and pdfoo:// links, and everything works great on your iMac. Now, you would like to access these PDFs from your Macbook Air, where your Evernote account is already set up and synced. When you click on pdfoo:// links in Evernote, the PDFoo app opens but does not recognize the prefixes. It asks you to open the PDF for each prefix. You would like to migrate the prefix assignments from your iMac to your Macbook Air. And AutoMatch makes it (relatively) easy.
Conceptually, the AutoMatch feature is simple: When a new PDF is opened in PDFoo, if it doesn’t already have a prefix assigned (as listed in the Prefix tab) then before it decides to assign a random prefix, it will pause to check the AutoMatch list – if the AutoMatch list contains a suggested prefix for a PDF bearing that name, it will go ahead and assign that prefix to the newly opened PDF. It bypasses the step of “Edit Prefix” to rename a randomly-assigned prefix.
The AutoMatch tab comes with an OFF-ON switch, and PDFoo ships with AutoMatch turned ON.
Follow these steps to copy your prefix assignments from your iMac to Macbook Air:
- First, on your iMac, export your prefix assignments to a text file. To do so, select all prefix rows in the Prefix tab in the PDFoo Preferences window and drag it out to a text file (or email.) Notice that the text is formatted using special markers such as “[prefix]”.
- Second, on your Macbook Air, open the AutoMatch tab in PDFoo Preferences window. Select the text (or email) containing the special markers and drag it into AutoMatch table. New rows will be created corresponding to the new prefix mappings. Note that PDFoo on your Macbook Air has not assigned any prefixes to PDFs yet – the AutoMatch tab also serves as “hints”. Ensure that AutoMatch switch is ON before the next step.
- Third, on your Macbook Air, drag several PDFs from your synced Dropbox folder to the running PDFoo application icon in the Dock. Each of these PDFs will now be opened, and the correct prefix will be assigned. You can verify the same via the red box displayed as an overlay on each PDF page, and in the list of recognized Prefixes in the Prefix tab of PDFoo Preferences window.
You can also use the steps above to copy prefix assignments between colleagues collaborating on a set of PDFs. AutoMatch looks for a match in PDF filenames, and the exact path on disk does not have to match. When a PDF with a recognized name is opened, the correct prefix will be automatically assigned, and pdfoo:// URLs will work seamlessly on all the Macs thereafter.
PDFoo Preferences: The Behaviors Tab
The Behaviors tab provides a few important configuration options for tweaking PDFoo to your liking. Please write in to onekerato@me.com with suggestions for further customization. Notable settings include:
- Whether PDFoo should open the help document on startup;
- Whether AutoMatch is enabled or not, and this setting is identical to the AutoMatch OFF/ON switch described above;
- Whether the red box overlay should be shown on every PDF page and its size and location on the page – this overlay helps in verifying that the correct Prefix has been assigned to the PDF; and
- Specific annotations that should be included when the File menu → Export Annotations command creates a RTF document with pdfoo:// links back to the original PDF.
View More at onekerato.com
This help document covers the basics of using PDFoo. But, there’s a lot more. Visit www.onekerato.com for video tutorials and tips & tricks to get the most out of your purchase of PDFoo, and discover ways to unlock the valuable information trapped inside your PDFs.
Advanced topics covered at www.onekerato.com includes:
Please also visit the onekerato support page (www.onekerato.com/support.html) to offer feedback and suggestions to guide the development of this app!
Advanced topics covered at www.onekerato.com includes:
- How to share your PDFoo prefix setup with colleagues, using PDFoo’s AutoMatch feature, available via the PDFoo > Preferences window;
- Directly link to a specific word, phrase or title on any page in the PDF;
- Search and export your notes, highlights and other insightful markup from annotated PDFs to RTF with pdfoo:// links back to original PDF;
- How to use PDFoo in real-world business and academic scenarios;
- Upcoming features in PDFoo based on user feedback; and
- Quickly add a Table of Contents (TOC) to your PDF using PDFOutliner.
Please also visit the onekerato support page (www.onekerato.com/support.html) to offer feedback and suggestions to guide the development of this app!