Annotation Pane (Annotation with Links, Notes, Tags v3)

[Frederiko]

What is an annotation
An annotation is a separate document containing the highlight text from the source document and any comment you have made on it. The annotation contains a link back to the original document in the URL field of the annotation (that is the clickable link at the top of the document immediately above the text). The source document has a link back to a special group, unique to the individual source document, which contains all the annotations for that document. Clicking the URL field of the source document will open the group to show all the source document’s annotations. Annotations also assist Devonthink’s AI by breaking up documents into smaller more relevant parts.

Installation
Unzip the attached file and put the Script Bundle in the Devonthink Scripts Folder.
On first use the script will create a new directory structure in the Inbox of the current database to store the annotation files, the source document groups and the configuration file
If you use the script on a database that used v2 scripts, it will update the previous directory structure to the new format
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

Usage

• Select text in a pdf or rtf document.
• Select the script from the Devonthink Scripts menu

Explanation of the fields in the Annotation pane* The Annotation Name field will be the name of the new annotation. The default contents of this field can be changed by editing the configuration file.

• The Date field will set the creation date of the new annotation. The default date is the creation date of the source document in ISO order - year, month, day.
• The Label field values correspond to Devonthink’s label colours (in preferences). The label names may be customised in the configuration file for each database.
• The Annotation Tags field will add tags to the top level of Tags. More than one tag can be added at a time by separating the tags with a ‘;’. You can still enter further tags separated by semi-colons but it won’t attempt to auto-complete subsequent tags.
• Below the Annotation tags field, custom tag groups can be assigned. By default there are no custom tag groups. Custom tag group can be created by editing the configuration file.
• Bellow the Custom tag groups are two special tag groups. Each tag group has three entry fields. This allows more than one tag to be added for each tag group, with each tag autocompleted. The names of the two special tag groups can be changed by editing the configuration file.
• 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 location - By default all annotations are stored in a folder called “annotations/text” in the inbox. If you want to bring up the group selector to choose where to store the annotation, this box should be checked.
• Clips PDF Pages - When this box is unchecked, the annotation will be an rtf file with the selected text and the notes from the Annotation field. If this checkbox is ticked the popup box will allow the range of pdf pages to chosen. 0 will clip the current page. 1 will clip the current page and the next page, -1 will clip the current page and the previous page and so on. This does not effect the original pdf. The annotation is simply composed of a copy of the range of pages. This style of annotation is useful when the source document is graphical in nature, the ocr is poor, or the context of the annotation is hard to express.
• Copy notes to comment -Any notes in the Annotation field will be added to the spotlight comment field of the annotation.
  [/:m][] The Annotation field text will be added as a note to the annotation document.[/*:m][/list:u]

Configuration
The script creates a file called config.scpt in Inbox/Annotations/Configurations. This configuration file allows the setting of per database settings for the annotation pane. In addition to the configuration options above, there are several other options which are detailed in the file.
To edit the configuration file, find it in the database, right click on it and select open with->script editor.
The script also creates a file annotation template.rtf in Inbox/Annotations/Configurations. This is a template file for the creation of rtf annotations. In addition to the placeholders in the file it supports all the standard placeholders detailed at p.128 of the Devonthink Manual. You can edit this file with the standard rtf editor to create a customised template for rtf annotations. If you make a mistake editing either of these files, delete them, empty trash and the defaults will be readded to the database the next time the script is run.

Extras
You can produce a spreadsheet of the annotations and source documents or a summary in a DT sheet. Its also possible to do some quite interesting thing with tags groups to make visualising relationships easier.
The Document Review Pane uses the same configuration file and tag groups to assist with the review of document metadata in the source document. It also provides a useful overview of all annotations in a source document

If you want to know how to quickly go through annotations to a document to revise or modify them, then this post (PDF workflows with DT in macOS) has a helpful description of the workflow.

Custom labels can be easily edited without editing configuration.scpt

If you are interested when tagging is useful and when it is not then this this post and the discussion which accompanies it is useful.

Cautions
If you have been using previous versions back up your database first. All changes should be reversible, but it doesn’t hurt to be careful

Problems
If the script bundle is not working for you, its probably best to pm me (using the forum link to the right of this post), rather than clogging up the forum. Please give me as much information as possible. Screenshots are helpful as are copies of problematic documents. I will send you a link to special ‘in progress’ version which produces a text log which you can send back to me to analyse.

[Updates]
20160421 Minor updates to prevent Devonthink losing focus
20160423 Bug fixes and addition of template files for rtf annotations
20160426 Side panel option added and non iso date time format problems fixed
20160502 Big fixes incl. inconsistent page references & excluding classification. Bates number support added.
20160505 Side panel text selection improved
20160511 Annotation field text selection improved + big fixes
20170908 Dropbox link updated

Unfortunately the file is too big to be hosted here. You can try to download it from here:
https://www.dropbox.com/s/putjs9bfqidb2jn/Annotation%20Pane%20v305.scptd.zip?dl=0

Frederiko

[Frederiko]

It is not always obvious how to use annotations efficiently or what benefit they might have. Sometimes an example is more helpful than the abstract depiction of an interface.

[size=150]Using annotations to build a chronology[/size]

Scenario

I am a historian with many source documents which covers the events over the course of a year. Many people feature in the events and there are multiple locations which relate to each event.

Add Extra Tag Groups to config.scpt
I start by creating three additional tag groups “People”, “Events”, “Locations” which are unique to this database by editing ‘/Inbox/annotations/configuration/config.scpt’

Annotate Documents
When I read a passage in a document that is of interest I select the passage and make an annotation of it. I tag my annotation with the name of the event, the people who attended and date the annotation with the date of the event. If the account is particular significant I also give it a coloured label. I may also use the custom label options to label all documents from a particular source a certain colour.

View Chronology
When I have completed the reading and annotation of all the documents, I go to the folder containing all the annotations. I order the folder documents by the creation date column and I have a chronology of all the events spanning multiple documents. If I have coloured the annotation according to source documents I also have an immediate visual reference of the comprehensiveness of each source.

From the chronology I can see where the same event is dealt with by different authors and how the account of the events differ. Each annotation contains a link back to the passage/page in the original source document, so its easy to reread the original account and supplement my annotation notes.

I can also export the chronology and my annotations to a tool like Aeontimeline, a spreadsheet or to a writing tool like Scrivener, Ulysses or Omnioutliner.

Create Smart Groups
In the course of the research I become interested in the travels of one of the participants between locations. I create a smart group using the tag of the name of the person and the group tag ‘Locations’. I have then created a discrete smart folder of the chronology of that person’s travels from location to location.

View Annotations by Tags
Also in the course of the research, I decide that one location deserves its own thematic treatment. Going to the tag of the location shows me a list of all my annotations of the events at the location linked, of course, to the passages in the source documents.

I hope this gives people some ideas of what is possible.

Frederiko.

[Cassady]

Wow.

Many thanks for this. Will give it a go ASAP.
Appreciate the time taken to provide a use example as well - can make all the difference!

[EmilioSpeciale]

Could you please explain step by step how to install? I am not able to make this work… Thanks

[Frederiko]

How to install

• Download ‘Annotation Pane.scptd.zip’ from the link at the top of page. It will almost certainly be downloaded to your ‘Downloads’ folder.
• Open the ‘Download Folders’
• Double-click the file ‘Annotation Pane.scptd.zip’ and it will be unpacked into a file called ‘Annotation Pane.scptd’
• Right click on ‘Annotation Pane.scptd.zip’ and select ‘Copy’ from the popup menu.
• Go to Devonthink
• In the Devonthink Menu Bar there is a small black icon resembling a ‘scroll’ between the ‘Window’ and ‘Help’ menu.
• Click the Scroll.
• The first menu item is ‘Open Scripts Folder’. Click it.
• A finder menu will open with the ‘Scripts’ folder highlighted.
• Within the scripts folders you will see directories which correspond to the menu items in ‘Open Scripts Folder’.
• Select one of the directories such as ‘Tags’.
• Select Edit->Paste from the Finder menu bar to paste ‘Annotation Pane.scptd’ into the Tags directory.

When you want to invoke the script select ‘Annotation Pane’ from the Script->Tags menu

Its also possible to attach a keystroke to activate the script from System Preference->Keyboard

[EmilioSpeciale]

Thanks for taking the time to explain. I followed your instructions but still the script does not work. It creates in my inbox a folder annotations and inside it 3 folders: configuration (with inside a script config.scpt), groups, text (these last two empty). Now I highlight some text in a rtf file or pdf, invoke the script and nothing happens. Sorry.
Thank you

[Frederiko]

Apologies. There is a new version which should fix your problems EmilioSpeciale.

Frederiko

[EmilioSpeciale]

Thank you Frederiko for your efforts, but… it does not work! Now I see the window of the Annotation, but the script does not create any file!
Thank you.

[Frederiko]

@EmilioSpeciale

but the script does not create any file!

How far do you get? If you check ‘set annotation location’, does it bring up the group selector box after you have pressed ok?

Are you clipping to a pdf, by selecting the ‘clip PDF pages box’?

Does the text you are selecting have umlauts or other non ascii characters?

Frederiko

[korm]

I think this is a great contribution, and appreciate how far Frederiko has taken the concept I began years ago when I posted a demo script in versions 1, and later with v2. He’s made the concept his own over the years, and made the tool into one of the most important private-user contributions ever posted here. I have no doubt Frederiko can go to the next level and make this a commercial success – perhaps even independent of the DEVONthink dependency. Perhaps eventually the Pashua dependency built into the tool can be replaced by migrating it to Swift or JXA – version 4 perhaps?

Wonderful work, Frederiko!

[mnvwvnm]

@EmilioSpeciale

but the script does not create any file!
Thank you.

As happened in version v2, a date format problem?

@korm

I think this is a great contribution, and appreciate how far Frederiko has taken the concept I began years ago when I posted a demo script in versions 1, and later with v2.

As a new member in this forum, giving my first steps on DT - a level less than beginner -, I’m really interested in a way to solve my workflow with the hundreds of documents to read and annotate (a PhD student). In a first impression, this is a great tool, trying to solve one of the DT’s limitations.
In this way, I make my own the korm’s words.

[EmilioSpeciale]

Dear Frederiko thanks for your answer.
I get the same window as the one you posted on the first message. It opens another program something like Pashua (?) and if I check «set annotation location» it does not show the group selector.
I am not clipping to a pdf.
And there are no umlauts etc in my text.
Still does not create any new file. Sorry.
E

I am on El Capitain 10.11.4 and Devon 2.8.10

@Frederiko

@EmilioSpeciale

but the script does not create any file!

How far do you get? If you check ‘set annotation location’, does it bring up the group selector box after you have pressed ok?

Are you clipping to a pdf, by selecting the ‘clip PDF pages box’?

Does the text you are selecting have umlauts or other non ascii characters?

Frederiko

[Frederiko]

There is a more comprehensive version of this script in this thread:http://forum.devontechnologies.com/viewtopic.php?f=20&t=21910&p=105388#p105388

This is a bonus script to the Annotation pane.

One of the features in DT I have thought deserved more attention but in practice is hard to use are labels. As it stands in in DT labels are global and apply to all databases.

I like to use label colours to highlight certain classes of document. However after a short while I can never remember what a particular label colour means for a particular database.

To remedy this the Annotation pane allows for custom label names to be configured per database. This works well when making annotation but still leaves the problem of what the label colours mean when I apply them outside of the pane.

To remedy this here is a short script to apply labels to files. The script presents a dialog of the custom label names sourced from the same configuration file as the pane.

Now my labels have much more semantic meaning and are more useful.

Frederiko
Label selection.scpt.zip (8.24 KB)

[jprint714]

This looks awesome! Like everyone here, I’m grateful for your hard work putting this together for us…

One quick question re: Notes… It seems like the original Note portion of the Annotation pane (i.e., that existed in v2) no longer exists. Is that correct? Or does it work differently now, and requires special configuration?

Also, the customizable annotation name setting look great! But can you explain how the “property maxWords” is supposed to work (versus the “nameinTitle” option)?

Thanks so much!

[Frederiko]

@jprint714

One quick question re: Notes… It seems like the original Note portion of the Annotation pane (i.e., that existed in v2) no longer exists. Is that correct? Or does it work differently now, and requires special configuration?

No it no longer exists. The purpose of the original notes pane was to allow editing of the selected text before it was put in the annotation. This seemed superfluous. If the original selected text needs to be edited, the annotation can be opened. (If people would really like the integrated notes textfield back as an option I would consider adding it)

Also, the customizable annotation name setting look great! But can you explain how the “property maxWords” is supposed to work (versus the “nameinTitle” option)?

When nameinTile property is ‘true’ the default name for the annotation is the name of the source document. When nameinTitle is ‘false’ the default name for the annotation is the first few words of the selected text. The number of words of the selected text that are used is given by the maxWords property.

[Allsop]

Unfortunately I cannot get this to work, when I activate the script I get the annotation pane but the date and time are incorrect and if I accept that date I get an error message saying that it is incorrect. If I change the date and time to the correct one I still get the same message. Any ideas?

[Frederiko]

this problem has been solved by subsequent updates

when I activate the script I get the annotation pane but the date and time are incorrect and if I accept that date I get an error message saying that it is incorrect. If I change the date and time to the correct one I still get the same message.

Andrew, I know these setting under System Preferences->Language and Region->Advanced->Dates work:

If you pm me a screenshot of your same settings I can try and see whats going wrong.

Frederiko

[jprint714]

@Frederiko

@jprint714

One quick question re: Notes… It seems like the original Note portion of the Annotation pane (i.e., that existed in v2) no longer exists. Is that correct? Or does it work differently now, and requires special configuration?

No it no longer exists. The purpose of the original notes pane was to allow editing of the selected text before it was put in the annotation. This seemed superfluous. If the original selected text needs to be edited, the annotation can be opened. (If people would really like the integrated notes textfield back as an option I would consider adding it)

Thanks for your answer. I hear you about the notes pane seeming to be superfluous. I did use it, though, as a way of typing follow up notes / questions that related to particular tagged text. Yes, I’d love to have the notes textfield back, but I really don’t want to put you out. You’ve already done a lot for us, Frederiko. I’d be happy to consider a “hack” solution for a notes textfield, if there’s a way for me to achieve what I’m seeking to do (i.e., including follow up notes / questions for the tagged text). Thanks so much…

@Frederiko

@jprint714

Also, the customizable annotation name setting look great! But can you explain how the “property maxWords” is supposed to work (versus the “nameinTitle” option)?

When nameinTile property is ‘true’ the default name for the annotation is the name of the source document. When nameinTitle is ‘false’ the default name for the annotation is the first few words of the selected text. The number of words of the selected text that are used is given by the maxWords property.

Ok, gotcha. I’ll make the changes - switching it to the latter - and will report back if there are any problems. Thanks so much again for including that option. It’ll seriously save me a TON of time and hassle!

Thanks again!

[Frederiko]

@jprint714

Yes, I’d love to have the notes textfield back, !

There is now a configuration property ‘sidePanel’ which if set to ‘true’ will bring up a side panel to edit the selected text. Be aware however that because of the limitations of the textfield the text conversion won’t be as accurate as when the side panel is not used. Certain character such as " and #s will not appear in the side panel

@Allsop

when I activate the script I get the annotation pane but the date and time are incorrect

The date and time shown in the annotation pane are the date and time of the creation date of the source document (not the current time) in the iso order - year, month, date and time.

@Allsop

If I change the date and time to the correct one I still get the same message

v302 should fix the problem you are having and the annotation document’s creation date should be set to the time in the annotation pane.

v302 reloads the default configuration file so you will have to redo any changes you made to the properties.

Frederiko

[mnvwvnm]

@Frederiko

There is now a configuration property ‘sidePanel’ which if set to ‘true’ will bring up a side panel to edit the selected text.

Once again, thank you Frederiko.