Dash User Guide - Kapeli 4/17/16, 6:00 AM

Dash for OS X (/dash) Dash for iOS (/dash_ios)

Blog (//blog.kapeli.com) Twitter (https://twitter.com/kapeli)

Contact (/contact)

Dash User Guide

Welcome to Dash's User Guide. The sections below will help you get the
most out of Dash. As always, feel free to contact me (/contact) about
anything if you need further help.

1. Documentation Sets
1.1. Downloading Docsets
1.1.1. Downloading Dash Docsets
1.1.2. Downloading Xcode Docsets
1.2. Generating Docsets
1.3. Managing and Searching Docsets
1.3.1. Search Profiles
1.3.2. Docset Keywords
1.4. Current Page's Table of Contents
2. Integration with Other Apps
2.1. Integration Plugins
2.2. Global Search Shortcut
2.3. The "Look Up in Dash" System Service (uses selected text)
2.4. The "dash://" Custom URL Scheme
3. In-Page Search
4. Snippets
4.1. Tips and Best Practices
4.2. Creating and Editing Snippets
4.3. Searching Snippets
4.4. Syncing Snippets

https://kapeli.com/dash_guide#downloadingDocsets Page 1 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

4.5. Disabling Snippet Expansion

5. Troubleshooting
5.1. "Dash complains that I haven't purchased it, but I did"
5.2. "Can't purchase or can't restore purchases"
5.3. "Duplicate docsets are shown in Dash's Preferences"
5.4. "Snippet expansion is not working"

1. Documentation Sets #

Documentation sets, or docsets, consist of collections of HTML files. Dash uses these
docsets to store the docs you need. This section describes the various features Dash has
to help you acquire and manange docsets.

1.1. Downloading Docsets #

Docsets can be downloaded from a lot of places, the most popular being Dash itself and
Xcode. Regardless of where you get a docset, you can double click it in Finder to let Dash
know about it.

1.1.1. Downloading Dash Docsets #

Downloading Dash docsets is easy, just open Preferences > Downloads.

1.1.2. Downloading Xcode Docsets #

Xcode docsets can be downloaded from Xcode's Preferences > Downloads >
Documentation. After the download finishes, open Dash's Preferences > Docsets and
click the Rescan button at the bottom right. Dash will then find the new docsets that
Xcode installed.

https://kapeli.com/dash_guide#downloadingDocsets Page 2 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

Please note that Xcode leaves around a lot of empty/corrupt docsets. If Dash shows
duplicate docsets in Preferences > Docsets, you should right click each of them, choose
"Show in Finder" and then manually delete them all. Afterwards, redownload the
docsets using Xcode. This will ensure that you'll get rid of all the docsets left around by
previous versions of Xcode and save some disk space.

1.2. Generating Docsets #

Instructions on generating docsets can be found in the Docset Generation Guide

(/docsets).

1.3. Managing and Searching Docsets #

You can manage the docsets you have installed from within Preferences > Docsets. You
can drag and drop docsets to change the order in which results appear. If you're looking
for more advanced ways of managing docsets and easier switching between them, see
the sections below about Search Profiles and Docset Keywords.

If you're looking for a way to download/install docsets, see the Downloading Docsets
section.

1.3.2. Search Profiles #

You can set up collections of docsets and easily switch between them using search
profiles. For example, let's say you do both OS X and Web development, you could set
up a "OS X" search profile which automatically gets activated when Xcode launches and
a "Web" search profile which automatically gets activated when Coda launches.

Search profiles persist between Dash launches and searches. If you explicitly do not
need persistence, use Docset Keywords.

https://kapeli.com/dash_guide#downloadingDocsets Page 3 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

You can find the search profile settings by clicking on the loupe icon of the main
search field:

Trigger Types:

Search Keywords
Search keywords are typed inside of Dash's main search field and activate a profile. In
the screenshot above, whenever the user types "web:" in the search field, the Web
search profile is activated. Search keywords can also be used with the dash:// URL
scheme, which makes it very easy to integrate them into plugins and extensions. For
more details, see the dash:// custom URL scheme section.

App Activation
App Activation triggers activate a search profile whenever a given app becomes active.
In the example in the screenshot above, whenever Coda becomes active, it also
activates the "Web" search profile.

Global Keyboard Shortcut

Whenever you press a combination of keys in any app, the profile gets activated and
Dash is shown.

https://kapeli.com/dash_guide#downloadingDocsets Page 4 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

1.3.3. Docset Keywords #

Docset keywords are a very easy way to search a specific docset, regardless if it's
enabled or not. Each docset has a default keyword which can be edited in Preferences
> Docsets. Keywords are typed inside of the main search field.

For example, PHP's default keyword is "php:". Typing "php:printf" would search the PHP
docset for "printf". Note: this assumes you have the PHP docset installed.

Docset keywords can also be used with the dash:// URL scheme, which makes it very
easy to integrate them into plugins and extensions. For more details, see the dash://
custom URL scheme section.

You can assign the same keyword to more than one docset, and Dash will search them
all. However, you might want to consider using Search Profiles instead which provide
more flexibility for activating collections of docsets.

1.4. Current Page's Table of Contents #

Docsets which support the "Table of Contents" feature show a filterable list of entries
inside Dash's table of contents which is located at the bottom left of the Dash window
(when shown). You can easily navigate this table using ALT+Down/Up Arrow.

The screenshot below shows the table of contents in action:

https://kapeli.com/dash_guide#downloadingDocsets Page 5 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

2. Integration with Other Apps #

Dash can integrate with almost any app you use. Once Dash becomes a part of your
workflow, it will always be one key press away.

2.1. Integration Plugins #

Integration plugins for various 3rd party apps, as well as generic integration methods
(e.g. AppleScript or Shell/Terminal scripts) can be found in Preferences > Integration.

All the integration plugins use the dash:// URL scheme behind the scenes, so it might
be worth reading the help section for the dash:// custom URL scheme to gain
understanding of search keywords and how to limit a plugin to search only a specific
docset.

https://kapeli.com/dash_guide#downloadingDocsets Page 6 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

2.2. Global Search Shortcut #

The global search shortcut is an easy way to activate Dash in a similar style as the
Spotlight shortcut. You can assign a search shortcut in Preferences > General and then
use that hotkey in any app when you want to bring up Dash.

You can assign more global search shortcuts using Search Profile activation triggers.
Search Profiles can also automatically switch and enable different collections of docsets.

2.3. The "Look Up in Dash" System Service (uses selected text) #

The "Look Up in Dash" system service can be used to initiate a Dash search using the
currently selected text of any app.

Using the service from the contextual menu

Right click on some text in any app and choose Services > Look Up in Dash from the
contextual menu.

Using the service with a global keyboard shortcut

You can assign a keyboard shortcut for this service in Preferences > General.

Warning! Some apps do not support OS X system services. Most notably, Java-based apps.

2.4. The "dash://" Custom URL Scheme #

The dash:// custom URL scheme can be used to initiate a Dash search from any app
that supports opening a custom URL.

The format is: dash://{query} . Example: dash://string (dash://string).

You can also include an optional keyword: dash://{keyword}:{query} . Example:
dash://php:printf (dash://php:printf) (note: PHP docset must be installed).
Keywords can be used to specify which docsets exactly you wish to search.
Keywords can be either Docset Keywords or Search Profile keyword triggers.

https://kapeli.com/dash_guide#downloadingDocsets Page 7 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

A more advanced dash-plugin:// (/dash_plugins) custom URL scheme is available

for plugin developers.

3. In-Page Search #

While viewing a documentation page or snippet, you can press CMD+F to initiate an in-
page search.

However, please note that in-page search occurs in the same search field as the regular
search. In a nutshell, anything that comes after a whitespace is searched in-page.

This is what the main search field looks like while searching for stringWithFormat
inside the NSString documentation page:

Due to the "anything that comes after a whitespace is searched in-page" functionality,
you might run into problems while trying to search for something that actually contains
a whitespace (e.g. a Guide). To search entries that contain whitespaces, omit the
whitespace. For example, if you'd like to find the String Programming Guide , you can
search for stringprogramming or stringguide or anything like that as long as you
omit the whitespace.

4. Snippets #

Snippets are really simple pieces of text which you reuse often. The idea is to save a
text/code snippet for later and expand it whenever you need to.

A snippet consists of:

Abbreviation
This is what you type in any app to expand snippets. The abbreviation gets replaced

https://kapeli.com/dash_guide#downloadingDocsets Page 8 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

by the snippet body wherever you type it.

It is highly recommended that your snippet's abbreviation should contain a symbol,
in order to avoid expansions by mistake. I personally use a backtick ( ` ).

Body
This is the piece of text/code you'd like to save and reuse.

Variable Placeholders
Placeholders are the parts of the snippet that change on each expansion. For
example, variable names could be placeholders.
Placeholders are defined by wrapping them in __ (double underscores). For
example, __var__ is a placeholder.
Each time you expand a snippet, you are asked to fill in placeholders (if any).
Placeholders can have default values. Just name your placeholder using the default
value you want and when you press Enter while expanding, the default value is
used.
Placeholders can change the case of the first letter (e.g. lowercase to uppercase).
For example, __name__ and __Name__ .
If __ does not suit your needs, you can define your own placeholder delimiter in
Preferences > Snippets.

Special Placeholders
@clipboard - expands into the contents of the clipboard.
@cursor - repositions the cursor after expansion. Warning: this feature does not
work very well with non-accessible apps.
@date - expands into the current date. You can modify the format in Preferences >
Snippets.
@time - expands into the current time. You can modify the format in Preferences >
Snippets.
You can escape (disable) these special placeholders by typing a \ before them.

The following screenshots show a snippet as defined in Dash and the same snippet
while being expanded:

https://kapeli.com/dash_guide#downloadingDocsets Page 9 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

4.1. Tips and Best Practices #

It is highly recommended that your snippet's abbreviation should contain a symbol, in

order to avoid expansions by mistake. I personally use a backtick ( ` ).

https://kapeli.com/dash_guide#downloadingDocsets Page 10 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

4.2. Creating and Editing Snippets #

To create or edit a snippet start typing into the snippet editor. Snippets are
automatically saved.

To manage snippets and show the snippet editor, click one of the highlighted buttons
from the screenshot below:

4.3. Searching Snippets #

You can search snippets by typing in the main search field. However, it might be hard to
find the snippet you want if you have a lot of docsets enabled. To avoid this, you can
create a snippets only Search Profile. For more information about search profiles, see
the Search Profiles help section.

4.4. Syncing Snippets #

Dash can sync snippets between Macs if you save your snippet library into your
Dropbox folder. You can change your snippets library location in Preferences >
Snippets.

4.5. Disabling Snippet Expansion #

To disable snippet expansion, either delete the snippet or add a few symbols (e.g.
whitespaces) at the end of the snippet's abbreviation.

https://kapeli.com/dash_guide#downloadingDocsets Page 11 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

You can also completely disable snippet expansion by disabling Dash's accessibility
support. You can do this in System Preferences > Security & Privacy > Privacy >
Accessibility > Disable Dash.

5. Troubleshooting #

Common issues are listed below. If you notice a bug or have any feedback, please
contact me (/contact).

5.1. "Dash complains that I haven't purchased it, but I did" #

Dash is free on the Mac App Store - you purchase Dash using an In-App Purchase
located in Preferences > Purchase. This is so that you can test Dash out before
purchasing.

If you are sure you have previously purchased Dash using the In-App Purchase located
in Preferences > Purchase, check out the can't purchase or can't restore purchases help
section.

5.2. "Can't purchase or can't restore purchases" #

Unfortunately, the App Store can act funny sometimes and get confused by its own
caches. I have contacted Apple about it and they seem to have no interest in fixing this
bug.

Check out the In-App Store Troubleshooting (/inappfailed) page for step-by-step
instructions on how to attempt to fix this issue.

5.3. "Duplicate docsets are shown in Dash's Preferences" #

https://kapeli.com/dash_guide#downloadingDocsets Page 12 of 13
Dash User Guide - Kapeli 4/17/16, 6:00 AM

Xcode leaves around a lot of empty/corrupt docsets. If Dash shows duplicate docsets in
Preferences > Docsets, you should right click each of them, choose "Show in Finder"
and then manually delete them all. Afterwards, redownload the docsets using Xcode.
This will ensure that you'll get rid of all the docsets left around by previous versions of
Xcode and save some disk space.

5.4. "Snippet expansion is not working" #

There are 2 things that could prevent snippet expansion from working and in both cases
Dash should have warned you about it:

1. Support for assistive devices is turned off. This needs to be turned on for snippet
expansion to work. You can turn this on in System Preferences > Security & Privacy >
Privacy > Accessibility. If it was turned off, restart Dash after turning it on.

2. You have an app running that enables Secure Input but forgets to turn it off, you need
to identify which app is causing this. Usually, web browsers or an extension inside web
browsers is the culprit. To find where the problem is, quit the apps you have running
one by one and try expanding after each one. If expansion starts working after you quit
an app, that was the app that turned on Secure Input and forgot to turn it off.

© 2016 Kapeli (//kapeli.com). Designed with at Zebra Labs (http://zebra-labs.com).

https://kapeli.com/dash_guide#downloadingDocsets Page 13 of 13