Edit Documents in DEVONthink

Editing most documents is straightforward, but I must mention something up front that could confuse you if you aren’t expecting it: the fact that you can view a document in DEVONthink doesn’t necessarily mean you can edit it—or, in some cases, select text in it.

Because DEVONthink uses the Mac’s Quick Look technology, it can index and display any kind of media the Finder can—including graphics, audio, and video files, iWork and Microsoft Office documents, and others for which Apple or a third party has installed an appropriate plugin. However, although some of these files can be manipulated inside DEVONthink, others cannot. The bulleted list just ahead gives an overview of what you can and can’t do in various kinds of documents.

Just as when viewing documents, you can edit a document directly in the view/edit pane, or double-click it to open it in a separate window. Either way, before you can make changes to a document, it must be in a writable (as opposed to read-only) state. If you see a read-only icon on the navigation bar, check the Info inspector to see if the document is locked ; if so, click the lock so it displays the unlocked icon. But keep in mind that some documents can’t be edited, even if they’re unlocked—this is true, for example, of imported email messages.

Here are the types of editing you can do in which types of documents:

• Select text: All document types except graphics, video, and audio (email messages must be in text-only mode—click the Text Alternative icon on the navigation bar or choose View > Document Display > Text Alternative, ⌘-Control-X, to enter this mode)

• Edit: Plain text, rich text, formatted note, Markdown text, HTML page, web archive, sheet, graphics

• Highlight: Rich text, formatted note, PDF, HTML page, and web archive

• Imprint: Graphics and PDF (see Add Imprints, ahead; requires Pro or Server version)

• Annotate: PDF only

You should also know how to access the tools you’ll need when editing certain document types: the editing bar, which replaces the controls on the navigation bar when you click the Show Editing Bar icon, contains context-sensitive formatting controls that vary with the kind of document (see Figure 69). In most cases, there are other ways to perform the associated editing tasks (for example, using commands on the Format menu and its submenus), but it’s often useful to have those controls available in this handy area right above the body of the document.

With those preliminaries out of the way, let’s look at a few of the most common document types you may want to edit.

Edit Text Documents

To edit a plain text or rich text document (or formatted note) in DEVONthink, use the view/edit pane or double-click it to open the file in a separate window (Figure 70), which gives you a custom—and customizable—toolbar. (Choose View > Customize Toolbar to adjust the toolbar’s buttons to your liking.)

When you open a rich text document in a separate window (as in the image above), the editing bar appears automatically, though you can hide it if you prefer by clicking the Hide Editing Bar icon.

Whether or not you’re using a separate window, you can also optionally display another set of tools called the format bar (see Figure 71), which appears right beneath the toolbar and contains font size and style pop-up menus, alignment buttons, and similar controls. To toggle the display of this bar, choose Format > Show Format Bar (or Hide Format Bar), ⌘-Shift-F.

The format bar is theoretically applicable only to documents with styled text, but that doesn’t apply to formatted notes, HTML, or Markdown documents—just rich text documents. On the other hand, oddly enough, it is available with plain text documents, though only when they’re displayed in separate windows. (Keep in mind that, although you can modify the display of the text in plain text documents using these controls, the style changes aren’t saved with the document—it’s still just plain text.)

DEVONthink’s text editing capabilities are almost identical to those in TextEdit (although some commands are found in slightly different locations, or have different keyboard shortcuts), so you should feel at home. All the important formatting commands are on the Format menu or one of its submenus, just as in TextEdit. In short, for plain text and rich text documents (as well as formatted notes), there’s not much to say—it just works.

Edit HTML and Markdown Documents

DEVONthink lets you edit HTML documents, Markdown documents, and web archives (which bundle HTML along with graphics and other resources in a single file) in much the same way as plain text and rich text documents. However, these three web-related formats share a unique characteristic: they are based on human-readable source code. And so, DEVONthink lets you edit these documents either in preview mode (which shows their final, rendered appearance) or in source mode (which shows their underlying tags); and you can even view both at the same time.

To switch modes, use the icons on the right side of the navigation bar or the commands on the View > Document Display submenu:

• Preview: The default mode, preview shows your document as it will appear with all styles, links, graphics, and so on. For preview mode, click the Preview icon or choose View > Document Display > Preview (⌘-Control-P).

• Source: Shows the underlying HTML or Markdown source of the document. For source mode, click the Source icon or choose View > Document Display > Source (⌘-Control-X).

• Side-by-Side: Shows a split view with the source on the left and the corresponding rendered page on the right (Figure 72). For side-by-side mode, click the Side-by-Side icon or choose View > Document Display > Side-by-Side (⌘-Control-Y).

  

  When working in side-by-side mode, keep in mind that changes don’t appear in the rendered pane until you save the source document (⌘-S). In addition, the two panes don’t scroll in sync; you must manually scroll each pane to the same spot.

DEVONthink includes the Prism syntax highlighting framework for Markdown documents. That means the preview pane in DEVONthink can show code examples embedded in your Markdown code with automatic syntax highlighting. To enable it, go to Settings/Preferences > Files > Markdown and check “Prism support” in the Extensions section. Once you’ve done this, open a Markdown document in DEVONthink, insert a line just before the code example, and type three backticks (`) followed by the name of the language your code example is in. For example:

```javascript

Supported languages are AppleScript, AWK, bash, C, C++, C#, Go, Java, JavaScript, Objective-C, Python, Perl, PHP, Ruby, Rust, Swift, and Typescript. An example of how this works with a JavaScript snippet appears in Figure 73.

Similarly, DEVONthink now supports the MathJAX framework, which lets Markdown previews display fully formatted mathematical equations. To enable it, go to Settings/Preferences > Files > Markdown and check “MathJAX support” in the Extensions section. Then use a supported syntax such as LaTeX or MathML in your Markdown document (for example, $$ sqrt[3]{frac xy} $$) and switch to the preview to see the rendered result.

Starting with version 3.7, DEVONthink also supports transclusion, which means including the entire contents of one (Markdown, HTML, RTF, RTFD, formatted note, web archive, sheet, plain text, or SVG) document in another Markdown document via a special link. To transclude a document, type its name inside double curly braces ({{myfile.md}}) or inside double square brackets preceded by an exclamation point ([[myfile.md]]); or, Control-drag the document to be transcluded to the spot in your Markdown document where you want it to appear. The transcluded document is automatically converted to Markdown; you can see this in preview mode or side-by-side view.

Edit Images

When I say you can edit images in DEVONthink, I don’t mean you can do the fancy things you can in Photoshop. What you can do, however, is rotate or flip an image; add line, shape, or text annotations; use the same image-manipulation tools built into Preview for adjusting overall attributes such as contrast, tint, and sharpness; and apply a few simple special effects.

To edit an image, select the document in your database (to edit it in the view/edit pane) or double-click the document (to open it in a separate window). Click the Show Editing Bar icon on the navigation bar to display the editing bar with graphics-specific icons; these controls are also present on the Format menu (or its submenus).

To make adjustments to the image as a whole, double-click the image, or right-click (or Control-click) the image and choose Edit from the contextual menu. The Image Edit panel (Figure 74) appears.

Move the sliders to adjust your image, and explore the Effects and Details tabs for more options. Switching between the Adjust and Effects tabs discards changes made before the switch, so close the panel to apply your changes before switching tabs.

After making any change to an image, be sure to save it (Data > Save or ⌘-S). Switching to another item in DEVONthink also saves your changes. To discard your changes, click Reset All.

Another way you can edit an image is to add an imprint; see Add Imprints, ahead.

Navigate PDFs

One of DEVONthink’s strongest features is its extensive support for PDF documents. Elsewhere in this book, I discuss how DEVONthink can convert scanned documents into searchable PDFs (see Scan Documents). You can also rotate and zoom them just as you would any other graphic. However, you can do considerably more with PDFs.

For the moment, I want to focus on getting around within PDFs and performing a few basic tasks. Then, in Edit PDFs, I cover DEVONthink’s features for basic, high-level editing; in Annotate PDFs, I explain how to add notes, comments, links, and shapes to PDF documents; and in Add Imprints, I tell you about a new, specialized type of annotation.

Edit PDFs

Although DEVONthink doesn’t offer the extensive PDF editing capabilities found in apps such as PDFpen and Acrobat Pro DC, it does include tools that let you insert, delete, rotate, and rearrange pages, or split a PDF into multiple documents.

While viewing a PDF in the view/edit pane or its own window, you can do the following:

• Insert a blank page: Choose Tools > PDF Document > Insert Blank Page, right-click/Control-click the document and choose Insert Blank Page from the contextual menu, or click the Insert Blank Page icon on the editing bar. A blank page is inserted before the currently selected page.

• Delete a page: Choose Tools > PDF Document > Delete Selected Page, right-click/Control-click the document and choose Delete Selected Page from the contextual menu, or click the Delete Selected Pages icon on the editing bar.

• Rotate a page: Choose Tools > Rotate & Flip > Rotate Left, Rotate Right, or Rotate 180 Degrees; right-click/Control-click the document and choose Rotate Left, Rotate Right, or Rotate 180 Degrees from the contextual menu; or click the Rotate Left icon, Rotate Right icon, or Rotate 180 Degrees icon on the editing bar.

• Rearrange pages: On the Thumbnails tab of the Content inspector (Tools > Inspectors > Thumbnails, Control-5), drag a page thumbnail up or down to move it in the document.

• Reverse all the pages in the document: Choose Tools > PDF Document >Reverse Page Order, right-click/Control-click the document and choose Reverse Page Order from the contextual menu, or click the Reverse Page Order icon on the editing bar.

• Split a PDF into chapters: For PDFs that have a table of contents and chapter headings (including Take Control books!), you can choose Tools > Split PDF > into Chapters to create individual documents from each chapter.

• Split a PDF into pages: To split any multipage PDF into a series of one-page files, choose Tools > Split PDF > into Pages.

Annotate PDFs

DEVONthink has the capability to annotate PDFs—that is, to add comments or notes, highlight interesting passages, or even draw shapes on the pages, all without changing any of the underlying text. Annotations can be useful when marking corrections on page proofs, discussing a report or paper with your colleagues, or jotting reminders as you read an ebook.

To annotate a PDF, you can use the commands on the Tools > Annotate submenu or display the editing bar (by clicking the Show Editing Bar icon) and use the icons that appear there. Figure 75 shows a PDF with a variety of annotations.

You can annotate a PDF in any of the following ways:

• Add a shape: To call attention to a portion of the document, click the Oval tool, the Rectangle tool, or the Line/Arrow tool on the editing bar. Then click and drag to draw the selected shape. When you do this, an Annotations panel (Figure 76) appears, with controls to let you select the color, thickness, and other properties of the shape. (The range of options available in the Annotations panel varies depending on which type of annotation you’re entering or editing.)

  

• Add a note: A note is a comment that appears with a small reference icon at the location of your choice on the page; double-click this icon to display the note’s contents in the Annotations panel. (In Catalina or later, if the document is open in its own window, clicking the icon displays the note’s contents in an overlaid “sticky note.”)

  To add a note, click the Note tool on the editing bar and then click where you want the reference icon to go. When the Annotations panel appears, type your note in the Text field at the top and then click the close button in the upper-left corner of the panel.

• Add text: Unlike notes, which normally appear as unobtrusive icons in your document, text annotations appear on top of the text (much like a sticky note). To add text, click the Text Annotation tool on the editing bar, and then drag out a box to hold your annotation. When the Annotations panel appears, type in the Text field at the top and then click the close button in the upper-left corner of the panel.

• Add a link: You can add a link anywhere in the document, either to another location in the document or to an external URL. To do this, click the Link tool on the editing bar and then drag out a box where you want the link to appear. When the Annotations panel opens, do one of the following:

  • To link to a URL, choose URL (the default) from the Link Type pop-up menu, and then type or paste a URL into the URL field at the bottom.

  • To link to another page in the document, choose Link Within PDF from the Link Type pop-up menu. Then move to the location in the PDF to which you want the link to point (by scrolling or clicking a thumbnail, for example) and click Set.

  Click the close button in the corner of the panel when you’re done. Your link will be clickable only when the Text tool or the Select tool is selected. (By the way, the purpose of the Select tool is to let you select annotations—to edit, move, or delete them—not to select contents of the PDF itself.)

• Apply underline or strikethrough: Select any text in a PDF and click the Underline or Strike Through icon on the editing bar, or choose Format > Style > Underline (⌘-U) to underline it or Format > Style > Strike Through (⌘-Control-S) to cross it out. These commands are also found on the Tools > Annotate submenu.

• Highlight text: To apply a highlighter effect, select a range of text and click the Highlight icon on the editing bar, or choose Format > Highlight (⌘-Shift-L). To adjust the highlight color, click and hold the icon and choose a color from the pop-up menu, or choose a color from the Format > Highlight Color submenu. To remove a highlight, select the highlighted text and choose the Highlight command again. These commands are also found on the Tools > Annotate submenu.

  You can also add a note to highlighted text: Select the highlighted text, right-click (or Control-click), and choose Add Note from the contextual menu.

After making any annotations, be sure to save the document.

To remove an annotation, make sure an annotation tool is selected; then select the annotation and press Delete. To edit an annotation, double-click it, again with any of the annotation tools active. You can change the font and color of the selected annotation using the standard Fonts panel (⌘-T); move it using the arrow keys or by clicking and dragging. You can also view all the annotations for a PDF on the Annotations tab of the Document inspector.

Add Imprints

Imprints are present only in the Pro and Server versions of DEVONthink 3. You can think of an imprint as an automated version of a text annotation. An imprint can add text (in your choice of font, size, color, and style; and with an optional shape border and fill) to a PDF or graphics file. But unlike text annotations, imprints can include placeholder text, numbering, and precise positioning; and you can apply them to all pages or only particular pages of a document. Imprints are thus good for watermarks, stamps, page numbering, and other material that you might want to add to images and PDFs in an automated way.

To create an imprint, start by going to Settings/Preferences > Imprinter. Click the plus button, then click the name (“New Imprinter”) under the Configurations heading, type your own name for the imprint, and press Return. The window should then look something like Figure 77.

In the Title field, type the text you want to appear in the imprint. (You’ll notice a Font token in that field; this is a placeholder telling DEVONthink you want to specify the font information for the imprint, which you almost certainly do. You can delete that token, but DEVONthink will put it back automatically. Basically: just ignore it.)

Speaking of placeholders, you can use as many as you like in an imprint. Right-click (or Control-click in the Title field) and choose a placeholder from the Insert Placeholder submenu of the contextual menu. Among the many options (see Using Placeholders for more information) are File Name, Counter, Page Number, various date and time options, Bates Number, and custom metadata.

Use the controls below the Title field to specify the font, size, style, and color you want for your imprint. Use the Style pop-up menu to enclose your imprint in a shape; the choices are rectangle, rounded rectangle, oval, left-pointing arrow, and right-pointing arrow. If you choose one of these borders, you can then use the Border and/or Fill controls to specify whether the shape should have a border, fill, or both—and what the border/fill attributes should be.

To specify where on each page the imprint should go, click the Location tab (Figure 78). Click a square in the Position selector to anchor the imprint to that relative spot on the page; then use the Offset fields to specify the number of pixels by which it should be offset from that location in each axis. To rotate the imprint, enter a number of degrees in the Rotation field. Finally, select an Occurrence radio button to specify which page(s) of a document the imprint should apply to.

Three other imprint options are worth mentioning:

• Duplicate item before imprinting: Because imprints permanently change the document and DEVONthink offers no tools for removing them, you might want to hedge your bets by checking this box, which instructs DEVONthink to make a copy of each item you imprint, and then add the imprint to the copy.

• Preview: Click the Preview button at the bottom of the Configurations list to see what your imprint will look like on an example document page.

• Combined Configurations: What if you want to put multiple imprints on the same document, each with different characteristics? You could manually apply multiple imprints, but an easier way is to create each imprint individually, then create a combined imprint that applies them all at once. To do this, click the actions icon at the bottom of the Configurations list and choose New Combined Configuration from the pop-up menu. Select an imprint from the Configurations list on the right and click the left arrow button to add it to the combined configuration. Repeat as necessary to add more imprints to the combination.

Once you’ve configured an imprint, you can apply it to any image or PDF by selecting the document and then choosing Tools > Imprinter > Imprint Name. DEVONthink adds the imprint, converting placeholders into real text as appropriate.

Convert Document Formats

Earlier I mentioned that scanned PDF documents can be converted to searchable formats (PDF, RTF, Word, and web archive) by choosing commands from the Data > OCR submenu. DEVONthink can perform other conversions too—find the commands on the Data > Convert submenu.

The additional options and the document types they can convert are:

• to Plain Text: Any text-based format, such as rich text, HTML, Markdown, PDF, Pages, Word, web archives, formatted notes, bookmarks, email messages, and EPUB

• to Rich Text: Plain text and most other text-based formats (such as sheets and PDF, but not Pages), plus graphics

• to Formatted Note: Plain text, rich text, and most of the text-based formats (but not PDF or Pages)

• to Markdown: Most text-based formats, such as rich text, HTML, PDF, Pages, Word, web archives, and email messages—but not EPUB

• to HTML: Plain text, rich text, PDF, and most of the text-based formats (but not Pages)

• to Web Archive: Any text-based format, such as rich text, HTML, Markdown, PDF, Pages, Word, email messages, and EPUB

• to PDF (Single Page): Any document type that DEVONthink can edit

• to PDF (Paginated): Any document type that DEVONthink can edit

• to PDF without Annotations: PDF only

• Duplicates to Replicants: Items that have duplicates in your DEVONthink database

Edit Documents in External Apps

For documents that DEVONthink can’t edit itself—or in cases where you need special features found in a different editor—you can open any document in another app of your choice.

To open a document in an external app, select the document and choose Data > Open With > Name of Application. (The Open With submenu also appears on the Actions pop-up menu on the toolbar and on the Control-click contextual menu.) The apps listed there are the ones that advertise themselves as being able to open the file format in question. For example, when you select a Word document, the Open With submenu shows not only Microsoft Word (as the default choice, at the top), but also TextEdit and other applications you may have that can read Word files, such as Pages and Nisus Writer Pro.

If you prefer to not use DEVONthink’s document editing tools, you can also choose to have all files open in their default app when double-clicked. The behavior here depends on what is set in Settings/Preferences > General > “Double-click opens documents externally”:

• If that box is checked, then double-clicking any document—even one DEVONthink can edit intrinsically—opens it in the default app for that document type. If you want to open it in DEVONthink instead, as a read-only preview, instead select the document and choose Data > Open (⌘-O).

• If that box is unchecked, then double-clicking any document opens it within DEVONthink. If it’s a file format DEVONthink can edit, then you get an editing window; if not, you get a preview window. To force the document to open in the default external app, select it and press ⌘-Shift-O.