Reissued/Updated PDF Manuals and Links

This looks like a job for item link parameters (DT manual, pp. 215–6). You can use DT 3.9’s deep linking functionality to tie your notes to text in the document that you’re fairly confident is unlikely to change between editions, even if its location in the document changes.

Before 3.9, the main way of linking to PDFs was by page. Links would look like this:

x-devonthink-item://8162FF9A-EB9A-48D6-96C3-6D362C37BE8A?page=214

… and would take you to the page of the PDF and leave you there to find the relevant passage on the page by yourself. But 3.9 introduced the “Copy Selection Link” command to the contextual menu for a text selection in a PDF, and also made it the default link format for the “Insert Quote” command in the Annotations inspector. These links look like this:

x-devonthink-item://8162FF9A-EB9A-48D6-96C3-6D362C37BE8A?page=214&start=779&length=62&search=For%20PDFs,%20the%20link%20can%20contain%20a%20reference%20to%20a%20specific%20page.

… and when you click on them they not only take you to the page but now also highlight the linked text on it. This is done by appending three additional link parameters (separated by &) after the page number: a starting character number to begin searching and counting from; the length of the string to be searched; and the actual text string to search for and highlight, with spaces and other special characters encoded MIME-style.

But here’s the trick: the start and length parameters aren’t strictly needed – they’re only there to make the search more efficient, by essentially telling DT to search for a string (and highlight it) within itself. So this version, without those two parameters, will still find and highlight the same passage:

x-devonthink-item://8162FF9A-EB9A-48D6-96C3-6D362C37BE8A?page=213&search=For%20PDFs,%20the%20link%20can%20contain%20a%20reference%20to%20a%20specific%20page.

… as you can verify for yourself if you substitute the address of your own copy of the DT manual for the item address (between the :// and the ?). What this version of the link is telling DT to do is to start on page 214 (PDF page numbering starts at 0), and search until it finds the string in question. It won’t find it on the numbered start page, but it will on the next page, and will highlight it when it does.

So if you have an existing annotation made before DT 3.9, you can add a search parameter to tie the link to something like a section title or other text string in the manual that you know isn’t likely to change between editions. (I’m assuming here that the manual is likely to get longer rather than shorter between editions, so that if your search string moves to a different page in the next edition, it’s likely to be a later one rather than a lower-numbered one.) And if the text string turns out not to be there, it’ll just take you to the specified page number anyway, from which you can probably find and update the required text easily enough, and can do a quick in-document search for it if it’s not obvious.

How you’d add the search parameter and string to existing links depends on their format; editing is easiest if your notes are in a plain-text format such as Markdown, so if you’re using Rich Text or HTML it might be worth using Data => Convert to make a Markdown version that you could then convert back after you’ve updated the links. And you’d need to add the search strings manually, probably by replacing each existing link with a new copied one from the PDF. This might be more trouble than it feels like it’s worth, though with luck you’d only need to do it once and future years’ updates would only need occasional minor tweaking to a handful of links.

Incidentally, you’ll see from the above that the sentence in the manual I’ve been linking to here is technically now out of date: it should now read something like “For PDFs, the link can contain a reference to a specific page and selection.”

5 Likes