Make an Annotation with Links, Notes, Tags v2

Revised v2 20150601

This had been superseded by later more robust versions. See later in thread

Here is an updated version of Korm’s script which allows for multiple annotations to the same document to be easily referenced.

Clicking the URL field of annotated document will bring up a separate tag view containing all the documents which have annotated the original document. Create a tag called “annotations” in the tags folder before using the script

Its based on Korm’s ideas in this thread:
[url]manually cross-linking & adding rich text notes to items?]


(* Original script by Korm

modified by Frederiko using Korm's ideas for multiple annotations using tags: https://discourse.devontechnologies.com/t/manually-cross-linking-adding-rich-text-notes-to-items/17667/12


Usage:
Create a tag called "annotations" in the tags folder. All the tags will be stored underneath that tag avoiding tag bloat.
*)

property noDecoration : "\" style=\"text-decoration:none;"
property preferRTF : true

tell application id "DNtp"
		
		(*
         Select a single document
      *)
		set thisItem to content record of think window 1
		set thisItemUUID to (uuid of thisItem) as string
		
		(*
         Get selected citation text
      *)
		--set theCitedText to selected text of think window 1
		--if theCitedText is "" then error "Please select some text"
		
		set theCitedText to the (selected text of think window 1 as string)
		if theCitedText is "" then error "Please select some text"
		
		
		
		(*
         Create a prefix for the annotation otherwise use the name of this item
         Use case: create a text annotation in the document with the same text as the prefix
         You will find the prefix on the clipboard so add it immediately after this dialog ends
      *)
		set thePrefix to text returned of (display dialog "Annotation Prefix:" with title "Annotation Prefix" default answer "")
		if thePrefix is not "" then
			set theName to thePrefix & " " & the name of thisItem
			tell application "System Events"
				set the clipboard to (thePrefix as text)
			end tell
		else
			set theName to the name of thisItem
		end if
		
		(*
         Get a note for this clipping
      *)
		set theNote to text returned of (display dialog "Notes for this clipping:" with title "Notes" default answer "[none]")
		
		(*
         Get tags for the annotation document
      *)
		repeat
			set theTagPrompt to display name editor "Add Tags" info "Tags (separated by semicolons):"
			if theTagPrompt is not "" then exit repeat
		end repeat
		
		
		(*
		Adds the uuid of the document and adds it as a tag to the annotation document
		*)
		
		try
			
			set annotationURL to (the reference URL of (the child named thisItemUUID of (the tag group named "annotations" of the current database)))
		on error
			
			set theRecord to (create record with {name:thisItemUUID, type:group} in tag group named "annotations" of current database)
			set annotationURL to the reference URL of theRecord
			
		end try
		
		set theTagPrompt to (theTagPrompt & ";" & thisItemUUID)
		
		(* Get a name for the annotation document
      *)
		set theAnnotationName to text returned of (display dialog "Name for this annotation file" with title "Annotation File Name" default answer (thePrefix & ": " & the name of thisItem))
		
		(*
         Make a text-search link for this citation
      *)
		if number of words of theCitedText is greater than 5 then
			set maxWords to 5
		else
			set maxWords to number of words of theCitedText
		end if
		set thisWord to 1
		set theCitedTextText to ""
		repeat while thisWord is less than or equal to maxWords
			set theCitedTextText to theCitedTextText & word thisWord of theCitedText
			set thisWord to thisWord + 1
			if thisWord is less than or equal to maxWords then
				set theCitedTextText to theCitedTextText & "%20"
			end if
		end repeat
		set searchCitationLink to " (<a href=\"" & (the reference URL of thisItem as string) & "?search=" & theCitedTextText & noDecoration & "\">" & " Text " & "</a>)"
		
		(*
         Make a path link for this document
      *)
		set thePathLink to " (<a href=\"file://" & the path of thisItem & noDecoration & "\">" & " File " & "</a>)"
		
		(*
         Make a page link for this page if the document is a pdf
      *)
		if the current page of think window 1 ≠ -1 then
			set pageNumber to ((the current page of think window 1) as string)
			-- 20110212 adjust page number to +1 for printing purposes
			set printPageNumber to " (Pg. " & (((the current page of think window 1) + 1) as string) & ")"
			set thePage to "?page=" & pageNumber
			-- set clickHere to "(Click here - page " & pageNumber & ")"
			set clickHere to "| Page " & pageNumber & " link"
		else
			set thePage to ""
			set clickHere to "| Page Link "
			set printPageNumber to "<b><i> (no page - source is not PDF)</i></b>"
		end if
		set theURL to (the reference URL of thisItem as string) & thePage
		set thePageLink to " (<a href=\"" & theURL & noDecoration & "\">" & " Page " & "</a>)"
		
		(*
         Compile all these elements and prepare the annotation
      *)
		set theAnnotation to "<p><b>" & thePrefix & "</b> " & thePageLink & searchCitationLink & thePathLink & "</p>" & "<p>" & theCitedText & printPageNumber & "</p>" & "<b><i>Notes:</i></b><br>" & "<p>" & theNote & "</p>" & "<b><i>Tags:</i></b><br>" & "<p>" & theTagPrompt & "</p>"
		
		if preferRTF then
			set o_theAnnotation to (do shell script "echo " & quoted form of theAnnotation & " | textutil -format html -convert rtf -stdin -stdout")
		else
			set o_theAnnotation to theAnnotation
		end if
		
		
		(*
         Create the annotation document
      *)
		set theAnnotationDocument to create record with {URL:theURL, name:theAnnotationName, source:o_theAnnotation, type:rtf} in display group selector
		
		(*
         Add the tags to the annotation document
      *)
		set {od, AppleScript's text item delimiters} to {AppleScript's text item delimiters, ";"}
		set theTags to text items of theTagPrompt
		set tags of theAnnotationDocument to (parents of theAnnotationDocument) & theTags
		set AppleScript's text item delimiters to od
		
		(*
		Sets the URL of the document to the reference URL of the tag. 
		*)
		
		set URL of thisItem to annotationURL
		
		
	on error error_message number error_number
		if the error_number is not -128 then display alert "DEVONthink Pro" message error_message as warning
	end try
	
end tell

[edit] Script now tags all annotations in the “annotations tag” so the tag folder is not burdened by hundreds of pointless tags. You should never have to go to the annotations tag because you would invariably get to the relevant tag when you click the annotated documents URL field
[edit] Removed reliance on having selected item highlighted. This could cause inconsistent results when using the back button. Now the annotated document is always derived from the active windo

Frederiko

Much obliged Frederiko, for the extra work - and as always, korm, for the initial work and effort!

I apologise for being that person - but with the integration and changes to quite a few scripts, I must confess to not being entirely sure if I am implementing this correctly… Could you kindly verify?

1.) Open the PDF you want to have annotations linked to - select text.
2.) Invoke the script, complete all (if desired) the fields [prefix/sufffix/note/tag etc] - select the place where it is to be stored
3.) Find the newly-created file - find the newly created tag with the unique identifier.
4.) Copy that tag - and apply it/copy it, to any other files you want linked/grouped to the master file.
5.) When the master file is opened, clicking on the link - opens up the new window, displaying all the related files?

Is that correct? Very useful – just wanted to be sure I wasn’t missing something!

Revised v2, above

Hello Cassady,

I understand, I am having to go back and rework this modification into about 10 of my scripts because it seems so useful.

Correct

Correct

There is no need for this step. Everytime you make an annotation to a master document with this script that annotation will be added to the correct tag group.

Clicking the annotation URL (at the top of the master document) will bring up the tag view of all the linked annotations. See my answer to your step four, for an easier way to get the relevant identifying tag for the master document.

If you want to add files that are linked to the master document, and they have not been added with this script, I would use the following script to copy the master file’s uuid (which is also the tag). You can then simply paste this into the tag field of any document you want to link to the master file.

tell application id "DNtp"
	if the current page of think window 1 = -1 then
		set the clipboard to (the uuid of (the first item of (selection as list)) as string)
	else
		set thecontentrecord to content record of think window 1
		set the clipboard to (the uuid of thecontentrecord) as string
	end if
	
end tell

[edit code fixed so it works now]

(this copies the uuid from the active window rather than the selection, which invariably is what you want)

Correct

(please all see the modified script that I have posted above since your posting)

Korm’s script is really very modifiable. So for example one variation of the script I use replaces the dialog box requesting a prefix with an automatic prefix of the page number from the master document. It also replaces the dialog box for file name by making the filename the first 10 words of the selection. This works very well with the tag view because you instantly get a pretty good idea if the particular page and cited text has been annotated before. I also don’t have a need to include the tags in the annotation so I can eliminate this step.

Frederiko

Re: Peter100’s request to open the new RTF in order to take additional notes (and add groups/tags), you could look at a slightly different take that I recently asked about on an older thread: New rtf doc from selected text with URL to pdf
Look in particular at korm’s modified code (Aug 19).
That code has you select PDF text (or, I discovered, just a page or part of a page if it’s an image-only PDF), then it creates a new RTF file in the group you assign, pastes the selected text into the RTF and adds a URL link from the RTF back to the PDF page, and then opens the RTF so you can take more notes (side by side with the original if you want). You can add other tweaks as well: add the summary filename to the body for the AI…

That thread’s code doesn’t include the autonumbering and automatic annotation tag that this thread’s code has, just the group assignment. If you prefer the other features of this code, I’d guess you could add them to that code or add something similar to this thread’s code. For example:

  1. set theAnnotationDocument to create record…
  2. open window for record theAnnotationDocument

So many ways to skin a cat. If your analysis requires fine gradations in your notes, a single document needs to be broken up into a lot of separate notes (the venerable “one thought, one note” note-card method).

It’d be nice if Devonthink could include a couple different models (i.e. scripts) for note-taking, or at least offer a variation on the current Annotation model, which only allows one annotation file per PDF. I know lots of historians who would be interested in that functionality, but will never dive into Applescript, or this forum.

@korm & @Frederiko:

I’ve unfortunately been too snowed under of late to even give things a proper go, but will soon.

Regardless, didn’t sit right with me that I popped up, asked a bunch of questions - and had them answered - only to disappear again: so here be a quick thanks for the effort put in above.

@ostwaldj

I agree. It has puzzled me that gts’ fantastic QuoteHighlight&Annotate Script (despite dating back to 2010) ([url]QuoteHighlight&Annotate script]) has never made into the default install. It is just obviously so much of an advance on the default annotation template. Instead it has been buried on the forums where only the most dedicated will find it. At the very least the thread should have been made sticky. I think unfortunately the same will happen to this thread. Korm’s insight into breaking up annotation and attaching multiple annotations to a single document would be of huge benefit to researchers, academics and lawyers (who I suspect are the three heaviest users of DT). It is a significant improvement over what has gone before.

Frederiko

Revised v2 above

I’ve been a long time lurker in these forums, but I made an account just to agree with the above. That annotation script is pretty much why I use Devonthink. Not just for itself, but for the workflow that it helped me create.

Devonthink is an incredibly powerful program, but guiding that power is not easy. That script helped me more than anything else.

Inspired by korm’s work to build a better interface for the annotation template using keyboard maestro, here is an advanced annotation template that doesn’t require km. Like the most recent versions it uses tags to allow multiple annotations to a single document.

Annotation with date.jpg

This script has a few advantages over previous scripts:
a) You can edit the cited text at the time of making the annotation
b) You can choose to open the annotation document immediately after doing the annotation.
c) You can set the creation date of the annotation. If the annotation box check box is ticked the default creation date of the annotation is the same as that of the document.
d) The notes field can be copied to the spotlight comment field.
e) It cleans up the cited text by removing any non alpha-numeric text.

(c and d are especially useful for creating chronologies)

Just unzip and drop the script bundle into your devonthink scripts directory (taking note of korm’s advice below if you have a problem).

Credits:
The core of the code is korm’s code used in his keyboard maestro script.
The gui is built with Carsten Blüm’s Pashua (http://www.bluem.net/en/mac/pashua/), and the Pashua runtime is included in the bundle.

[edit]
v1.1 Search link works properly; the document being annotated is the frontmost document rather than the selected document; c & d added.
Quick annotate with group tagging v1.1.scptd.zip (264 KB)

Revised v2 above

Updated

Thanks to everyone for this thread. I (naively?) thought that the ability to take, and sort, and link notes about documents was the main rationale for Devonthink as a research tool. But until I found this thread, I was unable to figure out how to do it. The manual has 238 mentions of “link,” but I could not find a coherent explanation of how to create cross-links among master/related documents. (e.g. a tutorial. See below for a partial answers.)

In any case, I think with these threads I will be able to figure this out, with “only” another hour or two of effort. Since I’m just a trial user of DT, it may make the difference between buying it, and giving up.

Now I suggest, echoing earlier comment, that this information be pulled into a sticky thread, and ultimately into a PDF tutorial. For other newbies, here are the threads I’ve found that are key.
Removed Macro for Keyboard Maestro
QuoteHighlight&Annotate script
posting.php?mode=reply&f=20&t=18885 (this thread)
manually cross-linking & adding rich text notes to items?
Mystified by Annotation - is there a plain-language tutorial A useful tutorial on how to use all this.
Related:
A useful discussion of how to structure documents in a DB and use “see also” to find links. Someone else's use of AI

Finally, the bibliography manager Bookends has some of this capability. Every referenced document can have an unlimited number of “notes” which are tied to that document. The notes can be tagged individually. And when you highlight a passage in a PDF, it automatically creates a note containing the highlighted text. Of course, Bookends is specialized and much less flexible.
(All errors and omissions in this message are mine. I’m just starting to figure this out. If someone who does understand these issues would summarize the essentials, we would all be grateful.)

2 Likes

@ R^2_is_misleading: Stick with it. DT is complex because of its freeform nature. When it all clicks together I haven’t found any other piece of software which remotely compares.

How annotations work

An annotation contains several links to the page in the document that is being annotated. (If its a pdf, otherwise just to the document)
a) In the Url field;
b) In the Hyperlink in the document called Page;
c) In the Hyperlink in the document called Text.

The annotation can also be reached under any of the Tag groups which reference it.

Annotation_Document.jpg

All the annotations to an original document can be reached by clicking on the URL link at the top of the document. This brings up a separate window with a list of all the annotations to the document. (technically its the tag group hidden under the tag group annotations but you should never have to worry or look in that tag group)

linking tag group.jpg

I hope this is helpful.
Fredriko

(There are some interesting posts on the bookend forum on integrating bookends annotations with DT https://www.sonnysoftware.com/phpBB3/viewtopic.php?f=6&t=3465

THIS VERSION HAS BEEN DEPRECATED
There is a later version at http://forum.devontechnologies.com/viewtopic.php?f=20&t=21707

This is a revised and enhanced version of the previous annotation template. This template adds auto-completion for tagging and provision for sub-group tagging.

Annotation tagging with sub issues.jpg

Changes and usage

  • The date fields have now been separated and placed near the top so they can been easily tabbed between. This is the creation date field for the annotation. By default it is the same date as the document being annotated. The date format is year, month, day
  • The annotation prefix field has been removed. The ability to rename the annotation tag name has also been removed. I have never once needed to reach an annotation this way so it appears redundant.
  • The “Annotation Tags” field offers a drop down box and auto-complete suggestion for the first tag. You can still enter further tags separated by semi-colons but it won’t attempt to auto-complete subsequent tags.
  • Two specific tag sub-groups are provided for. In this case “Issues” and “People” but their names can be changed in the first lines of the script. Three auto-complete tag fields are provided for each sub group. These fields will only auto-complete on other tags in the sub group. Sub-group tags do not show up under the “Annotation Tags” field auto-complete. (Look under the “Tags” group to see how these are structured.
  • There are four checkboxes:
    [list][*] Open annotation - This opens the annotation immediately after the dialog for further editing.
  • Notes in comment - Notes will also be placed in the spotlight comment field.
  • Set annotation date - If this is not checked then the creation date of the annotation will be the date the annotation is made. If it is checked the creation date of the annotation date will be that set in the Date boxes.
  • Set annotation location- By default all annotations are stored in a folder called “annotations” in the inbox. If you want to bring up the group selector to choose where to store the annotation, this box should be checked.
    [/*:m][/list:u]
    Just unzip and drop the script bundle into your devonthink scripts directory (The ‘open scripts folder’ menu item).

If you want to produce a spreadsheet of the annotations and source documents then this thread http://forum.devontechnologies.com/viewtopic.php?f=20&t=19534 will be helpful.

There is also a variation on this script which clips whole pages or series of pages as pdfs. Useful for annotating graphical documents. viewtopic.php?f=20&t=19827

Notes on Gatekeeper: If the mac prevents you from running this script bundle, read this http://support.apple.com/kb/HT5290 on how to change your security settings or try Korm’s advice earlier in this thread.

Notes on launch speed: If this script is activated from DT’s script menu I have seen it take up to thirty seconds to launch. I have no idea why. If you are having this problem I recommend placing the script in the user script’s folder and using Fastscripts (http://www.red-sweater.com/fastscripts/) to attach a keystroke to it and launch it instantaneously.

Frederiko

(Note: For me personally this template offers some of the functionality of Lexisnexis Casemap (a windows litigation preparation package) but with the greater flexibility of DT.

[edit v2.1 2014/09/27] Addition of dropdown menu for label and autocomplete tags are now in alphabetical order. Minor change to template to add reference to source document and link to page

[edit 2014/11/3] If the script isnt working for you its because your date/time format is different to that the script was written for. A fix is coming.
Annotation template with specific issue tagging v2.1.scptd.zip (284 KB)

Frederiko - thanks again - this just keeps getting better! :slight_smile:

Could I maybe confirm some things on your usage, since this would make things easier on getting my head around how I could utilise it…

I see, based on the previous screengrabs, that you use the 3 fields under the [Issues] and [People] to generate new tag groups. You then presumably place the relevant pdf’s/rtf’s into these groups - so you’re basically using Tags as Groups (I think that’s the right way of terming it)…

So if you’re working on your master document, you in effect start “building” a folder/group structure around that master document, driving it through the creation of Tags? Is that more-or-less how you do things?

Hello Cassady,

Tags and Folders are different

The annotation file must always be stored in a proper folder and not in a tag group (although its possible to do so, it has unintended consequences). Tag groups should only ever contain replicants (and they are not true replicants because deleting the annotation file will also remove it from all the tags it is associated with). The annotation template takes care of this so you shouldn’t have to worry about this occuring.

The only way you should ever add a tag to a document is by adding the tag to the documents tag list (the strip at the bottom of the document) or in the information panel.

Tags are for metadata and Folders are for documents

The default is to store the annotation file in a folder called ‘annotations’ in the Inbox but you can store it anywhere that works for you. For some types of documents I like to store the annotation in the same folder as the document being annotated.

Folders and tags are two completely different organisational structures. For me folders represent ‘physical bundles’ of document whether they be transcripts of hearings, or documentary evidence received from one of the parties to the litigation. Annotations are also ‘physical’ but more akin to Post-it Notes or note cards. Tags are a way of classifying the information in the ‘physical bundles’ and narrowing it through annotations into more abstract and precise categories. Tags are also a way of pulling related information from different documents into the same logical category. Tags are akin to the index in a book.

The way I use the tags is best illustrated with the following four examples:

a) I want to find all annotations (or source documents) that concern ‘John Smith’ AND the issue of ‘misrepresentation’. I can use advanced search or a smart group to find all annotations that are the intersection of these two tags.

It doesn’t matter where these annotations (or documents with the same tags) are stored in the folder structure. A search on one or more of the tags will find the annotations whereever they are.

In this example I might turn up a passage from an evidence transcript at trial by Mary W about the representations she made to John Smith and an extract from a statement she gave to the police on a different occasion a year earlier about the same thing. These two pieces of information may be hundreds of pages apart and in different folders in documents received from different people. Previously I might have overlooked the linkage.

b) The reason for the tag sub-groups is that I found groups of logically related pieces information (in my case, People & Issues) were being lost in my tag cloud. When I am annotating the 100th document I can no longer remember whether I tagged the person I saw in document 1 as ‘Smith’, ‘J Smith’ or ‘John Smith’. Having separate tag sub groups not only allows for auto-complete just on a subset of the tags, and thereby aids consistency, but also reminds me constantly that its an important field that I probably should complete. It’s so easy to get lazy when you have thousands of pages to work through and cross-reference.

c) Tags make it easy to extract just a portion of evidence. Before I go to trial I can give John Smith just a subset of the documents that are relevant to him together with a list of pages he should pay specific attention to. In a similar vein I may want an overview of just what evidence I have on the issue of misrepresentation and whether it needs to be bolstered by looking for further evidence. Looking in the tag group ‘Issues’ shows all the issues in the case that I have identified, and burrowing down further to the ‘misrepresentation’ tag shows all the annotations and documents that deal with the question of misrepresentation. I will generally export a summary of these annotations and their source documents to numbers for printing so they can be discussed in a strategy conference.

d) A witness may refer to a particular document. Clicking on the url link brings up a window with all the other annotations I have made to that document which will probably include what other witnesses have said about the same document. Opening an annotation will show me my notes to the cited passage and the tags at the bottom of the document can take me to the tag groups containing all the other related referenced people and issues.

The examples I have given are quite specific to what I do, but I hope it will stimulate people to think about how they use DT and modify the workflow to suit them.

I hope this provides some clarity.

Frederiko

Many thanks Frederiko, it does!

I’ve been playing around with it over the course of the past few weeks - and the possibilities are almost endless! :smiley:

This looks like a great script! It’s seriously impressive (esp. to those of us who has no real knowledge of scripting), and we’re very grateful for @korm for first creating the original script! Once again, amazing work and the DTP community is thankful for your generous help…

I’m having some problems operating this new function, and I’d be grateful for any help… I downloaded and installed the latest script version that @Frederiko created (i.e., Annotation template with specific issue tagging v2.1.scptd.zip), and have tried to run it, using the steps outlined above. The very first time I selected text from a PDF document and ran the script it seemed like the script worked, but only partly…

For instance, after I filled out all of the information from the dialogue box, the script created an annotation document (as it should), but that document remained stuck inside the same folder as the original document – whenever I clicked on the annotation file (hoping to add on more to it) it just wouldn’t open. So, I tried to start over: I deleted that newly created annotation file in the trash, emptied the trash, and again following the steps outline above. But now, every time I run the script, the new annotated document automatically ends up in the trash – that is, the Mac trash, not the DTP trash. (I followed the steps that @korm suggested to fix Pashua, but it didn’t have any effect.)

I’m sure I’m committing some elementary error here… Anyway, I would appreciate any help you could offer. Thanks!