Giveaway: Dash – Offline access to documentation

As developer you dig through documentation on a daily basis and most of this documentation is only available online these days,  and even if you get them to download the search functionality is gone. But what if you want to develop while you are, for example, in a plane or a train without internet connection?

Offline documentation

I had to travel quit a lot recently and in the train Dash became my best friend. Previously hen I tried to use the time on the train, the lack of internet connection was the biggest problem. With Dash you can download all the documentation you might need straight from within the app. It has a list of more then 130 so called docsets that you can download.

With these docsets you are prepared for your next forced offline time. Compared to a downloaded bunch of html files, Dash keeps the docsets organised and searchable. When you look up, lets say, a parameter of a command line tool on your Mac, you type in the command’s name and Dash will provide you with the man page for it. After the command name, separated by a space, you add a search string that is looked up inside the selected man page.

As these docsets are maintained by the Dash developers, you don’t have to worry about outdated documentation. Whenever a new version is available, Dash will download it for you without disturbing you from your work.

Snippets

As if that’s not enough, Dash provides even more! On top of the worry-free documentation, you have snippets. These are text or code snippets you need to enter again and again. Why not create a template for them and just type a shortcut to get it?

That is exactly what Dash provides. You define an abbreviation for the snippet. For the abbreviation it has proven good advice to add, at least, a very unusual character to it to avoid the snippet kicking in when you don’t want it. The user guide suggests a backtick (`) at the end of the abbreviation string.

When you define your snippet, you have a lot of options to customize them. Dash provides you with predefined placeholders you can use like the @date or @time as well as the option to place the cursor inside the template at any position you like. Additionally you can define placeholders inside the template.

As a PHP developer you write a lot of functions. The complete function structure could be part of the snippet. To show you how easy it is, I created a snippet for a php function. This is how my test snippet looks. It will create a comment block with the date and time when it was generated as well as the function with one parameter. After insertion, the cursor is placed inside the brackets so you can start writing your code immediately.

/**
 * __function-name__
 * created on the @date at @time
 * @param __param1__
**/
function __function-name__ ($__param1__)
{
    @cursor
}

When you type the abbreviation inside the text editor / IDE of your choice, Dash will recognise it. If you have a snippet without any placeholders, Dash just replaces the abbreviation you typed with the snippet, but if the snippet contains placeholders, you will see an overlay window where you can define values for the placeholders before the snippet is inserted.

This is a great feature for often used text snippets. It will work in all text editors as well as in your web-browser. This makes it a great feature for any kind of IDE you are using.

Foreign man pages

If this is still not enough, there is another great feature. Additional to the 80 docsets maintained by the Dash developer, you have the possibility to create your own docsets. Beside others, Dash supports accessing the Mac’s man pages, but when you write shell scripts you might need the man pages from the remote computer, as the command line options from Mac OS X can be quite different from the Linux ones. Dash provides an easy way to access these as well.

The idea is simple. Just download them and let Dash provide the search functionality. It sounds too easy, doesn’t it? But it is simple as that with one little additional point. You wont be know which man page you are looking for as they have the same name. For that all the man pages need to be renamed with a prefix to make it easy to distinguish between them and the Mac OS X ones.

On your remote server

First the man pages need to be copied to the Mac. Connect to your remote computer or server and run the following command to get the directories of your man pages:

$ man -w | tr ":" "\n"
/usr/local/share/man
/usr/share/man/en
/usr/share/man

As you can see in the output (example from a CentOS server) there is a list of directories where man tries to find the requested man page. We now need to copy them over to the Mac. Depending on the server configuration, you might not have access directly to those files. I used “tar” to pack them together into my home directory from where you should be able to transfer them to your Mac:

tar --hard-dereference --dereference -czf ~/usr_local_share_man.tar.gz /usr/local/share/man
tar --hard-dereference --dereference -czf ~/usr_share_man.tar.gz /usr/share/man

As in this case the path “/usr/share/man/en” is a subdirectory of “/usr/share/man”, we do not need to create an archive of both. These archives are now located at your home directory from where you should be able to transfer them to your Mac using scp(1).

On your Mac

Once the archives are transferred to the Mac you can unpack the archives with with the following command. As a result you will get the whole directory structure as we created the archive:

tar -xf usr_local_share_man.tar
tar -xf usr_share_man.tar

The “usr” directory will now contain all the man pages now. Before we can use the new downloaded man pages we need to do a couple more things, but before we continue, place them on your disc where you want them to be. It does not have to be Mac OS X’s man path. It can be literally anywhere on your Mac. When you have moved the directory “usr” there, we can continue with the next step.

Adding the directory to the man page path. This is done by adding a couple of lines to the ~/.profile file. This file configures your shell environment. Within it you can define aliases as well as setting environment variables, and this is exactly what we need to let Dash know where the man pages can be found.

I chose to place the man pages in my home directory under Documents. Add the following lines to the file ~/.profile to configure the man page location:

# additional man pages
export MANPATH=$MANPATH:/Users/USERNAME/Documents/CentOS/usr/local/share/man
export MANPATH=$MANPATH:/Users/USERNAME/Documents/CentOS/usr/share/man/en
export MANPATH=$MANPATH:/Users/USERNAME/Documents/CentOS/usr/share/man

If the ~/.profile file does not yet exist, just create it. Files starting with a “.” (dot) are hidden from the Finder and they are also hidden from the shell if just “ls -l” is used. To see them in the shell execute “ls -la”. Use your favourite editor to edit the file like this: “open -a “TextEdit” ~/.profile” from the shell terminal.

After you have added these lines to the ~/.profile, Dash needs to be restarted to recognise the added man path. With this in place, the man pages can be accessed by Dash.

Unique prefix

Dash will enable you to lookup a specific man page via the search field. At the moment, Dash will show you both man pages with the same name, and without a marking in the man pages you have no way to differentiate the remote from the local man pages.

To rename the man pages easily I created a tiny script that does the work for me. It expects to be called in the directory where you find the “usr/” directory. In the example location mentioned above, that would mean it should be called from “/Users/USERNAME/Documents/CentOS”.

Create a file using your favourite editor with the following content.

#!/bin/bash
version=1.0

if [[ -z $1 ]]; then
	echo "Please specify a prefix for the files."
	exit
fi
PREFIX=$1

FILE_LIST=`find ./usr -type f |grep -v "$PREFIX"`

for FILE in $FILE_LIST; do
	FILEBASE=`basename "$FILE"`
	FILEDIR=`dirname "$FILE"`
	echo "Renaming ... $FILE"
	mv "$FILE" "$FILEDIR/${PREFIX}_$FILEBASE"
done

This script requires one argument: the prefix every file will get. This prefix will be shown in Dash as well. When you search now in Dash, the prefix is shown in the result list and you will have the Mac OS X man page without prefix and a second one with the prefix. So far the basics are also described on the Dash blog. This enables you to read through the man pages and know which man page you are using.

Update inter-page references

Many man pages have references to other man pages. Dash is smart enough to recognise them and create links out of them that you can follow by clicking, but sadly most of them point either to a man page that is one of the Mac OS X man pages or – as Dash can not find the related page – do not have a link. This is because the references do not have the prefix. This is obviously not a problem as long as you do not try to navigate via the reference links.

Each man page file is compressed using gzip. This is not a problem for Dash as this is normal behaviour, but it makes it a little bit more tricky if we want to update the references with our prefix. The following script will update the references.

Create a file using your favourite editor with the following content:

#!/bin/bash
version=1.0

if [[ -z $1 ]]; then
	echo "Please specify a prefix for the files."
	exit
fi
PREFIX=$1

# STEP 1: unzip all zipped files
FILE_LIST=`find ./usr -type f -name *.gz`
for FILE in $FILE_LIST; do
	echo "Unzip file ........ $FILE"
	gunzip "$FILE"
done

# STEP 2: extend all references with the prefix
FILE_LIST=`find ./usr -type f`
for FILE in $FILE_LIST; do
	echo "Add link prefix ... $FILE"
	sed -E "s/([a-z\.\-]+ *\([0-9]\))/${PREFIX}_/g" "$FILE" >"$FILE.relink"
	mv -f "$FILE.relink" "$FILE"
done

# STEP 3: gzip all the man pages again to save space
FILE_LIST=`find ./usr -type f`
for FILE in $FILE_LIST; do
	echo "Zip file .......... $FILE"
	gzip "$FILE"
done

This small script will unpack all the man pages in the first step. Then it will add the prefix to every reference to another man page. As a final step, the script will recompress all the man pages to save disc space.

With this update of the man pages, you have the possibility to use the links Dash created out of these references when showing the man page. By following the links with the prefix, you will stay inside the man pages from the server and not jump between the server’s man pages and the Mac ones.

You might notice some references Dash is not creating links for. This is most likely because the referenced man page is not available because, when you download the man pages from your server, you only download the installed man pages. Man pages get installed with the programs, so you only have the man pages for all the programs you have installed on your server. When a program is not installed, you will not its man page installed either. But most of the time you are probably only interested in the programs you have installed and not in the programs you could have possibly installed.

Giveaway

I am proud that I can announce a giveaway license for this great product. This license is worth USD 19.99 and will be given away on Facebook. To participate in the giveaway, like our facebook page and leave a comment on the post about this article on facebook saying why you would like to have this license.

Tell your friends and colleagues about this giveaway! If enough people participate, the winner will be randomly chosen on the 22.02.2014 and announced on our facebook page.

Read more of my posts on my blog at http://blog.tinned-software.net/.