Reissued/Updated PDF Manuals and Links

I have an aircraft flight manual that is nearly 3,000 pages long; I have a bit of content highlighted and then I use Apple Notes or a note within DEVONthink to hold my own notes and link back to the content within DT. The manual is re-issued once a year or so with revisions… I would love a way to keep my links relevant over time but I am not sure this would be possible with a changing source document. Any thoughts are appreciated. The only thing I can think of is to just keep old copies alongside the new one so that all links work.

The only option would be to replace the current file with the updated one via the Finder. However, the highlights will of course be gone afterwards but at least the item links should still work.

Splitting the PDF into sections won’t fix the problem, but can ease the burden. That would allow you to just replace the sections that you haven’t annotated, while deciding how to handle the annotations on a case-by-case basis.

For a similar issue in my own work, I use text aliases (Smith2020) rather than direct links. Giving my notes the same alias as the underlying source file lets me find them both, even if the underlying source file is replaced or if there are multiple source files with the same alias. When needed, I can augment this with a Zettelkasten-style note that has links to all the associated files. (I have not tried this with 3,000 page source documents, however!)

Interesting and thanks. I am unfamiliar with text aliases?

In DT’s metadata for a document, you’ll see a field called Aliases. There.

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

Excellent information! I’ll dig in when I get home from my current trip. Yes, aircraft manuals always get longer…

1 Like

So I have started a new note with linked references, and the idea moving forward is to do what NickLowe recommended. However, I cannot edit any of the links I have created. If I convert the markdown file to plain text and perform the edits, then re-save as markdown - I get a sound out of my laptop speaker and nothing else. I must be missing something simple…

Hmm… I think you’re right that it’s something simple, but I’m not sure what; the screenshot looks as if it ought to be perfectly editable. A couple of thoughts:

  1. Is there a reason you’re converting from Markdown to plain text and back again? Your screenshot shows you editing directly in Markdown, which is what I’d have expected. Markdown is already an editable plain-text format; it’s only the .md file suffix that distinguishes it (and thereby allows DT to render the formatting in a split-pane view).

  2. If you click in an item link in a Markdown file to edit it, DT will try to launch it in a browser. To edit it, you need to position your cursor inside the link by dragging from outside the link and/or using arrow keys (or do something like delete the initial x so that DT no longer recognises it as a link).

  1. I must have mis-read something you said earlier.

  2. I see that now - - thanks!!

1 Like

No, it was my unclear wording – edited now! If your notes are already in Markdown, you don’t need to convert anything. Sorry to have unnecessarily muddied the waters…

Is anything logged to Windows > Log? Which version of macOS & DEVONthink do you use?

DT 3.9.4
DTTG 3.8

No messages in Windows > Log

Which macOS version do you use, is there enough disk space and where’s the database located? Did you check the file permissions of the file?

-Sonoma 14.1.1
-Over 200 Gigs remaining of disk space
-Read & Write permissions for my user account
-Database located at:
/Users/stephenpower/Databases/Stephen.dtBase2

Are you able to reproduce this using a fresh database?

I am not. Also, the problem seems to have resolved itself in the original document.

Please choose Help > Report Bug while pressing the Alt modifier key and send the result to cgrunenberg - at - devon-technologies.com - thanks! Maybe there’s a hint in the logs.

Done! and Thanks.