Associate Notes with Reference Documents = Richer Functional

Most items in my DB are of one of 4 kinds:
(a) reference documents
(b) RTF notes about these reference docs, many per ref-doc
© projects, which are collections of (a) & (b)
(d) more notes about ©

Groups & tags help me with organizing a, b, c, and d.

However, I do not see any way to associate b with a, in a way which is (i) intuitive in the UI, and (ii) leveraged by the DT AI functions.

For (i):

  • Could the notes be visually shown nested below a reference document?
  • Could the notes be created directly from within the reference document e.g. by picking a reference point and saying “Create Note”?
  • Could the annotation points in the referenced documents be highlighted (potentially without even modifying the original document – by a visual overlay) with links to those notes; & with corresponding reverse links from the notes to the parts of the reference document?

For (ii):

  • Could DT be semantically aware of the (quite special, IMO) relationship from referenced document to its notes (just as it is aware of the relation from groups or tags to contained documents)?
  • Could DT use this knowledge to further improve its AI results e.g. AI results on a reference document includes information gleaned from its notes.

I particularly find the UI for (i) quite awkward. I am trying to use Bill’s (otherwise excellent) suggestions for creating notes linked to the referenced document, but really think DT should make much of this intuitive and transparent for the user.


I’m sorry that no one has continued this discussion. I’ve been thinking about it this past week and can see how displaying files “under” a given file in the GUI would be very useful. The only way I can see of doing this is to create a new group, put the reference doc in it and then add notes and other material associated with it. Not as intuitive from a GUI perspective.

This brings up the whole topic of references. Having a nested “folder” structure (at least in the GUI, it doesn’t matter how it’s implemented underneath) is one way to organize data and the addition of tags adds an extra dimension. I have dabbled with Personal Brain in the past and find a few ideas used there to be intriguing. Things like multiple parent “folders” and lateral links can add richness to one’s organization.

The lateral links (or jumps) provide links to related folders that are not in the parent-child hierarchy. Now, DT provides wiki type links (and another type, as I recall), but these are from words/phrases in one text file to another file. Imagine having a link from any one file to another anywhere else. I can visualize a GUI that lets me click on a file, or even a “folder” and then option-click (or whatever key combination) on another file/group and a link is created. Later, you can right-click on a file/group, get a popup of linked items, choose one and jump right to it. That’s what Personal Brain can do.

The purpose of such a lateral link can be to connect groups of “ideas” or topics that are related, but not in the parent-child sense. There are times when you are searching for something you aren’t sure what phrase to search on - one attempt may give one result, but not the one you want . Other times, you may be searching for an item but don’t even think of some related item until you get a visual reminder (a file/group could have an icon or color to indicate a lateral link). Example: I search for information on Apple TV but forget that I copied some web discussions on using a Mac Mini for a media server months ago. My mind is focused on the ATV and I’d miss the connection to the Mini without visual clues (and support for such jumps).

I’ve gone beyond the OP’s ideas, but I think there’s a bigger picture here than just notes related to a document. There are other ways of creating relationships.

Me too :slight_smile:

All these are great. I’ll use “reference document” as an example below.

Fundamentally, DT should “know” that certain elements (including notes & annotations of a reference document, but also including links within the contents of those notes & annotations), which even though at some primitive implementation level are separate items, semantically (to the user) BELONG to some other item (e.g. the reference document). Then DT can do all kinds of useful things, such as (a) surface links from within notes to the level of the reference document in a column in the list view, or (b) offer doc-to-doc links that it understand and uses in its AI processing.

Absolutely agree.

If DT improves semantic support for such linking, I would LOVE for those links themselves to carry some user-information (e.g. tags), making relations between DT elements themselves more first class in DT (hints of RDF and the like). I don’t think this needs to be restricted to the document level, it could be any part of a document (e.g. using Bill’s smart use of DT’s phrase search ability).

I can’t comment deeply on this idea (everyone breaths a sigh of relief), but I’ll revisit it later.

When last I was a steady commenter on this forum, my main topic of ranting was the subject of document metadata. It still is.

One idea that I mentioned during DT’s beta period was the idea of exposing normally hidden document settings through metadata. I believe this to be an excellent way for people who want certain functionality to gain that functionality without unnecessarily cluttering the interface. It is exposed only to the people who want that functionality.

So in regards to your i:

Let’s say you have a PDF document named “Story.” You want to make various notes to it, so you select a phrase and execute an AppleScript. That AppleScript takes the name of the document, the phrase, and any other data that can be gleaned (such as a page number), and then uses a Smart Template to create a new note. Maybe the name of the new document is Story :: Page 37, “He looked up as he entered the room”. Now, this can be done with DEVONthink’s current functionality.

I think metadata as I’ve suggested it would improve the process by additionally adding or modifying a field within the original “Story” document (AssociatedNotes={“ce2ba720-45c7-11df-9879-0800200c9a66”}, where AssociatedNotes is a metadata field containing an AppleScript list of UUIDs for notes associated with the document) and within the newly-created Note (ParentDocument=“00df63a0-45c8-11df-9879-0800200c9a66”, where ParentDocument is a metadata field containing the ID of the document that the note concerns).

This might not seem that useful, but a second AppleScript, perhaps with a hotkey, could open all of your notes for a particular document. So you open “Story,” hit Ctrl+Opt+Cmd+N or whatever, and windows open up for your notes. Or the script could make a temporary smart group that grabs all notes that refer to “Story”. Or the script could create a temporary RTF document from combining the contents of the notes that refer to “Story” and open that instead. Or whatever else you want.

This is why I like the idea of user metadata – properly implemented, it allows us to control our information with mathematical precision.

Your ii is a different matter altogether – I don’t see that being possible without heavy customized lifting from DEVONtechnologies. But DEVONthink does pay attention to how documents are grouped. Perhaps elsewhere in your database, the operations I described above could create replicants of the documents in the same group, so that the relationship between them is preserved?

Another possibility is that DEVONtechnologies could explicitly insert another factor (“Explicitly associated documents”) into the database for each record, and the value of this relationship could then be added to their internal algorithms. This factor could be exposed to users through the metadata field, so that documents and their notes could have their “ExplicitlyAssociatedWith” metadata fields modified by the above AppleScripts. In addition, if you wanted to associate all documents with a particular label as having a specific trait in common (Red = Book the First, or Lemon Yellow means Emails), you could implement this with the metadata field too. The strength of this approach, again, is that the user has the ability to create his or her desired features, with only structural changes by DEVONtechnologies, and no annoying and controversial GUI changes or preferences above those necessary for adding metadata in the first place.

Hmm, this went more in-depth than I intended.

But yes, I agree with your complaints, and think your suggestions are good.

@kalisphoenix, good suggestions. User-defined metadata should (where appropriate) should complement what DT has i.e. if DT tries to guess at “SEE-ALSO” relation, why on earth should a USER not be able to augment that relation?

I think notes “ABOUT” a document are special, though. Once I say this note N1 is about this document D1, then for all AI processing (and many UIs as well) the item N1 and its contents should be treated as a part of D1, no less than the pre-defined contents of D1. N1 should be accorded the same importance (for AI and UI) as, say, user-assigned tags.

If some of this is indeed Apple-Scriptable, perhaps a DT wizard could whip up (or point us at) a couple of such scripts?

I don’t personally see any reason why that would be impossible. I mean, DT stores an index for each document, so why not build in some logic to make the document virtual? Manually exclude the note documents from see also, and make a field available where users can add the UUIDs of documents whose indexes should be merged with that of the main document. Doesn’t clutter the UI, doesn’t impair the usage for people who don’t care, doesn’t add another preference, and gives individual document-level granularity of control.

Well, the main scenario I envisioned would merely consist of modifications to the Annotation smart template. Open a document, then click the Data Menu > New From Template > Annotation. It’ll create an annotation with a link to the main document. I changed my version so that instead of “Click here to go to the main article” or whatever, it prints the name of the main document.

Some of the other features already exist. “get current page of think window 1”, IIRC, will return the page number if you’re viewing a PDF, which I think is the situation for many (if not most) annotations. RTF is trickier because the line number/scroll position/etc depends on the width of the window and the zoom level and other factors. For this reason, Bill DeVille has, in past discussions, advocated the use of a search phrase. Select a meaningful, probably unique phrase, and then execute the AppleScript… the AppleScript would copy that selected text. Then, with that particular phrase handy, it is considerably easier to find that section of the document. It might be possible to scroll the document down to the first occurrence of that phrase programmatically, but I’m not sure. It would be nice if DEVONtechnologies made the behavior possible, since it kinda exists in some form in the advanced search.

The AppleScript to create a smart group for annotations of a particular document and open a new window for that group would be a piece of cake if the metadata properties existed to tie those documents together. As in, it’d take about five minutes to write.

But these scripts are merely accelerations of what you can already do manually.

You can do this right now by mimicking the Annotation’s use of a URL as link-back.

If you put all your notes for a certain document in a group, and then put (ie copy link) the group’s x-devonthink-item://UUID into the document’s URL field, clicking on that field will open a window onto the group with all your notes.

HTH, Charles

And, as Sophie and kalisphoenix suggest, this action could be scripted. (Hint to certain meister-scripters :unamused: )

That’s great to hear.

But isn’t the URL field used to record the source of a web archive? Also these manually created forward / backward links break easily. I just created an Data / New From Template / Annotation of a PDF document. Then deleted the annotation. The link DT inserted into the URL field of the PDF document is now invalid, yet it still sticks around.

The problem is there are (seems to me … maybe I’m too new to this) too many ways of doing these things (URL link, file name, phrase search, internal DT fields, an aggregating RTF “TOC_of_notes”, etc.), all supported by DT primitive functions, but they could be better standardized and abstracted and directly supported by DT functions (script or otherwise) or the UI. Surely annotating reference documents is a common-enough usage of DT that it should be better supported?

I think DT could EASILY directly support:

[]one standardized mechanisms to make RTF notes about a specific document (“the Reference Document”)[/]
[]one standard way of linking from within a note to a specific location within the Reference Document (e.g. Bill’s phrase search link)[/]
[]one standard way of highlighting a location in the Reference Document and creating either a link or a note linked to that location (e.g. via search phrase, and, PLEASE make these behave like links, taking me directly to the target, don’t pop up a search window and ask me to hit Enter, or even select from the search results, unless absolutely unavoidable)[/]
[]one standard way for the UI to show that the Reference Document has associated notes (created via this standard mechanism)[/]
[]one standard UI way to open the notes associated with the Reference Document[/]

Personally, I also think there should be a standard way to expose (when desired) some highlighting-like markup at relevant locations in the Reference Document, each linking directly to the corresponding note. I understand this demands quite a bit more on the UI so will not hold my breath for this. This is what makes Skim so smooth to use: you can see and edit your annotations AS you read the PDF.

Yes, that’s true, but it’s also true of the current Annotation functionality that’s provided in the Template menu. Take a look at the associated Applescript: it puts the link-back in the URL field if it’s empty, and if not, adds it to the Comment field.

And yes they “break” because there’s not a corresponding “Delete Annotation” script that will do the required clean up.

I think that DEVONtechnologies generally tries to stay in step with the functionality provided by Apple in their operating system. It’s a smart strategy because Apple has historically forced developers to “move along” as they evolve the OS. The biggest instance of this AFAIK, is the “no 64-bit Carbon libraries,” which was the signal for everybody to REALLY adopt Cocoa, and stung Adobe pretty badly.

Apple plays rough with small companies in this way, and to mention Tinderbox yet again, it’s a perfect example of a product that was beautiful (but pretty non-standard) in OS9. But I imagine Mark Bernstein really sweated to move Tinderbox into an OSX/Intel world, which it only recently did.

So I believe that the answer to your larger question would be: “If Apple provided ways to hyperlink and annotate documents, you’d probably see it in DTPO.”

HTH, Charles

Although without benefit of the neat UI discussed above, I’ve actually been accomplishing the same things discussed above for years. Yes, I can annotate a source document using searchable rich text notes, identify and link to the document(s) to which those notes refer, and find all the notes that are associated with any document. That’s done with searchable Names, links and phrases — using the tools already present in DEVONthink.

It can be argued that my methods are clumsy and perhaps time-consuming.

But I don’t find that they take any time at all. They would, of course, it I were doing nothing else but the mechanical actions required to make or reveal associations. But that’s simply not the case, as I’m multitasking. I’m thinking about the content of documents, it’s relevance to my project and how I’m going to make use of it. Unfortunately, at least for me, thinking takes a lot of time. :slight_smile:

As for user-defined metadata, which includes of course keywords, organizational structure and tags, I think that’s very useful for cataloging properties of items that can be simply and definitively listed, such as cataloging a collection of nuts and bolts by their various dimensions, threading and material composition (a surprisingly large metadata ‘table’ would be required, e.g., dimensions are not merely numerical but the systems of measurement must be identified for the numbers). Beyond that, I’m a confirmed skeptic about the logical consistency and utility of trying to reduce complex information into any simple metadata structure such as tagging. I could spend hours, perhaps days, doing nothing else but trying to reduce the important information in a paper into a set of tags that adequately characterize its information content. And if I repeated that excercise for the same paper at another time, that would produce a different set of tags – consistency is impossible to achieve in practice, as the exercise is subjective. I often capture articles from the M.I.T. Technology Review, which contain pre-assigned tag terms. I almost never find any utility for those tags in the context of my use of those documents in my databases.

Context is important. Among chemists there’s a famous true story about an experimental boat that was built during World War II. The boat was designed for speed and strength, with special metal hull plates. The plates were riveted with standard rivets. On the day scheduled for first trials of the boat, a Navy party went to the dock where it was moored. But it wasn’t visible. It had sunk, because the electrochemical properties of the rivets in the context of the hull plates had resulted in the destruction of the rivets in a salt water environment, and the hull plates separated. The specifications metadata for that boat were incomplete. A lot of time and effort had gone into the boat’s specifications, but it sank. Lesson: when you try something different, don’t assume that a standard set of metadata will be adequate — that assumption can be dangerous.

Hi Bill-

I always enjoy reading your longer contributions to the forum, but I’ve noticed that your characterization of database technology tends to be binary, which vacates a whole range of approaches in the middle. It sort of like there’s DEVONthink, and then there’s CODASYL, but nothing else out there!

XML databases in particular have enabled “adhoc” approaches to attributed data: add some metadata when you need it, and change it around when you have a different idea about the structure. It’s pretty low cost, and right in line with the kinds of approaches you espouse here on the forum. Mark Bernstein calls it “gardening.”

An example I’m working on this week concerns a couple thousand historical documents, about 80-90% of which are dated. The remainder, I can date by historical reference to other sources. I’d like to browse my data by date, but I also need to preserve the distinction between documents that are specifically dated, and ones I’ve “guessed” a date for. Pretty simple to just add an “estimated date” attribute and sort by either actual or estimated date depending on which is available.

I contribute the above because I wrestle with these issues, but that isn’t the same as advocating DEVONthink’s adoption of metadata capabilities. I can’t think of any really outstanding “multi-paradigm” applications out there-- I imagine the effort to do everything dilutes focus. I’d actually rather see DEVONthink make a really great structured database application that tightly integrates like DEVONagent, rather than have you folks take your eyes off the prize of bringing “AI” to heterogenous data collections.

Best, Charles

Hmmm, maybe I’m not doing it right, but when I:

  • select one of my Web Arhive documents in the list
  • run Data/New From Template/Annotation

I get a new Annotation element, but see no change in either the URL field (which had a pre-existing value) or the Comment field (which was, and still is, empty) of the referenced Web Archive document.

Am I doing something wrong? Or do annotations not work on Web Archives?

Well, I meant something else with my comment: given a model-view-controller paradigm, the Apple approach is to provide Frameworks for the view and controller parts, while you provide the model. Of course, the boundaries between these categories are never precise.

This “convenience” provided by the OS: to make a complex piece of UI software (ie Cocoa) “simple” to write programs for, actually becomes a bit of a straightjacket if your model needs views and control that doesn’t fit in with Apple idea of the UI experience. So you’ve got the choice of presenting your application using Apple’s idea, or getting dirty making enhancements, mods and/or hacks to their code. And when that code changes, you’ve got to keep up.

For a longer discussion of some of this:


I’ll still stand by the comment, or perhaps alter it to “do two things.” I know you’re not a fan of Tinderbox (and there are good reasons not to be), but I haven’t gotten any signal from you that you evaluated it as a paradigm of an attribute-centric information tool. Regardless of whether you want to use it everyday, there’s a lot of thought there about how you can structure data by creating and manipulating metadata.

So, from my perspective, it would be very difficult, if not impossible, to support both the DEVONthink paradigm, and an equally sophisticated metadata paradigm, in the same application.

But as you say, DT could add features that would enable the creation and manipulation of metadata to their existing application. A suggestion I made was a Applescriptable browser window, so you could browse the results of your scripts:

One speculation I had about the relative lack of metadata support in DT concerns data and relationships. In DT data resides in user documents, relations among data reside in DT. User metadata starts to break down this distinction, as users data starts to reside in the DT database. Sound weird? I dunno. What do you do when you want to export your user metadata from DT to file formats that don’t support it?

Anyway, congratulations on the one-month-old! And don’t waste too much of his/her early years staring at this forum…

Best, Charles

Sorry Sophie- I didn’t read the script as carefully as I should have.

There may be an error in it, as it either writes the Annotation URL into the URL field if the URL field is empty, or writes the Original URL into the Spotlight Comments, BUT DOES NOTHING ELSE:

		-- Finally, add the note's item link to the annotated document's URL field if possible
		if URL of theFrontmostDocument ≠ "" then
			set theComment to comment of theFrontmostDocument
			if theComment ≠ "" then set theComment to theComment & return
			set theComment to theComment & my helperLibrary's localizedString("Original URL") & ": " & (URL of theFrontmostDocument)
			set comment of theFrontmostDocument to theComment
			set URL of theFrontmostDocument to ("x-devonthink-item://" & uuid of theRecord) as string
		end if

My guess would be (without actually trying anything) that COPYING the statement:

set URL of theFrontmostDocument to ("x-devonthink-item://" & uuid of theRecord) as string

right above the “else” statement would yield the result that DT is trying to achieve. (That is: if the URL field is already filled, move it to the Comments field, and put the Annotation URL in the URL field.) Try it and see if it gives you what you want. (There are other configurations you could achieve as well.)

Wow. Probably indicative of how many folks actually use these features that something like this wasn’t picked up sooner…

HTH, Charles

Thanks, @cturner.

It confirms to me how important it is for DT to have a way to add rich annotations to any part of any document. Current answers are not standard, smooth, visible, or intuitive, for an important use case for DT.

I sincerely hope DT recognizes this, and consolidates its several mixed pieces (scripts, annotation template, pdf inline annotations, Bill’s phrase search technique, document links, document page links, slide-out See-Also drawer, …) into a top-notch user feature.