First look at Sublime Text 2

Once you have opened ST2 you will be presented with a window similar to that shown in Figure 1.

The red numbers on the image are described below:

1. The taskbar. Here you should be able to access all the options for ST2. It is worth noting that all the menus/options are also accessible via the Command Palette which will be introduced later.
2. File tabs. Along this bar will be all the open files in that window/pane. You can either navigate through them by clicking on them or use the keys alt + # to move to the # file (where # is the number of the file from the left).
3. Overview pane (minimap). As you populate your file this will give you a zoomed-out view which can be useful for navigating through large files.
4. File syntax. This shows you what the syntax the file is being displayed in. ST2 will automatically select a syntax based on the file extension (e.g. if the file is .py then ST2 will choose Python). However if you want to change this then you can click on the writing and select your required syntax from the list. This is also achievable through the Command Palette.

There are many useful tools within ST2 and the following sections aim to give you an insight into those we find most valuable.

Built-in Goodies

"Projects" are one of the more useful features of ST2. This feature allows entire folders and their contents to be displayed in the side bar. This gives the user the ability to not only switch quickly between files in a number of directories, but also see what other files exist in the project at all times as in Figure 2. To do this, go to File > Open Folder and select a folder (Advanced Computational Methods Part II students, open ~/comp_mod/blogs). Additional folders can be added to the workspace, and the project can then be saved for another session under the Project tab.

While using ST2, you will notice the smart autocomplete pop-up. This is another handy gadget which works out of the box, and will suggest possible completions for a word you are typing based on similar words in the file, keywords for the file syntax etc.

In addition to these, "Snippets" and "Build Systems" are a powerful way to increase text-editing efficiency, and will be introduced once a few more packages are installed so that we can customise them for our blog entries.

Install Package Control

Package control is the Sublime Text package manager that makes it exceedingly simple to find, install and keep packages up-to-date.

—https://packagecontrol.io

To get package control in ST2, firstly open ST2 and either push the keys ctrl + ' (if you are working on a Virtual Machine, the Keyboard setup may not be the same as your host's - on a MacBook Air, the key ' was actually the § key above tab). Alternatively go to View > Show Console . By doing this a white box at the bottom of your Sublime window should open as shown in Figure 3.

Now follow this link and copy the code provided. Return to the ST2 window and paste the code into the console (i.e. the white box) and then hit return. This will install package control. You may be required to restart ST2 a couple of times depending on what is already installed on your machine.

An easy way to verify if package control is installed is to open the Command Palette with ctrl + shift + p or going to Tools > Command Palette... . The Command Palette is a way to search ST2 for packages, syntax, snippets, ... in other words it is your best friend in ST2! It uses a search method called fuzzy search which allows the user to type keywords only partially and returns the closest matches, making it easy to find tools without needing to remember the exact name and wording. With the Command Palette open, start typing Package Control. This should present you with all options available with regards to Package Control (this is how you will make use of Package Control later).

An alternative method to check if it is fully installed is to go to Preferences and you should see Package Control at the bottom of the list. By clicking on this it will open the Command Palette as described in the above paragraph. However, we thoroughly recommend learning the important key bindings such as ctrl + shift + p to open the Command Palette as removing the need of the mouse to navigate will make your use of ST2 much more efficient.

Installing a Package

We are going to install a package that improves the syntax of reStructuredText in ST2.

To install a package we need to open the Command Palette (with ctrl + shift + p ) and type in Package Control: Install Package and select that entry (remember it is a fuzzy search so you don't need to type it all in). Now you are presented with a list of all the packages available to install via Package Control. Start typing RestructuredText Improved and select the entry that has the description: "Improved Syntax Highlighting for RestructuredText." This will download and install the package and should be functional immediately - this may seem strange and wonderful to users of other text editors whereby restarting the editor is the only method of invoking new tools.

To check, click in the bottom right-hand corner where the file syntax is displayed and see if there is one for reStructuredText Improved. If so you have successfully installed the package.

There are many other useful packages available through Package Control but we just wanted to demonstrate how easy it is to install one! If your ideal package/tool does not exist however, then we need to learn to tweak ST2. Below are two ways to personalise ST2 for your own use: snippets and build systems.

New Snippet...

This example builds on what was taught in the "Introduction to Pelican" session. During that session we learnt to write a blog entry in .rst format. However, each time you start a new blog you have to firstly remember all the important metadata attributes and format them correctly. Therefore, to increase our efficiency we will build a snippet to do this for us.

Firstly, it best to have a file with the extension that you want to build the snippet for open in ST2. This allows you to find the scope needed for the snippet and allows you to test it. On the virtual appliance we have supplied for the module, create a directory called my-blog under the path ~/comp_mod/blogs/tools-pelican/content/ then open a new file and save as blog-entry.rst in the my-blog directory so we can use it throughout this workshop. Note: This can be done quickly with ctrl + n , then ctrl + s and use the file-save GUI.

To build a new snippet we need to go to Tools > New Snippet... which will open a new file with the following code pre-entered:

1 <snippet>
2 <content><![CDATA[
3 Hello, ${1:this} is a ${2:snippet}.
4 ]]></content>
5     <!-- Optional: Set a tabTrigger to define how to trigger the snippet -->
6     <!-- <tabTrigger>hello</tabTrigger> -->
7     <!-- Optional: Set a scope to limit where the snippet will trigger -->
8     <!-- <scope>source.python</scope> -->
9 </snippet>

There are three main lines of interest here:

Line 3

This area (between the [ ] opened at the end of line 2 and closed on line 4) is the text that gets pasted into the file when you create the snippet. We will look at the format in a bit.

Line 6

The code <tabTrigger>hello</tabTrigger> is where you define the tab-trigger to use the snippet.

Line 8

The code <scope>source.python</scope> is where you define what file format you can apply the snippet.

We will firstly define the tab-trigger and the scope so that we can use it our file blog-entry.rst. As the snippet will be creating the title and metadata a sensible tab-trigger would be title so replace line 6 with the following (note: to uncomment/comment lines push ctrl + / ):

6     <tabTrigger>title</tabTrigger>

Next, cycle back to the .rst file and push ctrl + shift + alt + p to show the scope in the status bar at the bottom of the window, see Figure 7.

Copy text.restructuredtext into line 8 so that it reads:

8     <scope>text.restructuredtext</scope>

Now we can start looking at the body of the snippet. Currently we have: Hello, ${1:this} is a ${2:snippet}.. This contains two tab key markers which allow you to cycle through the fields that you wish to enter each time you use the snippet. The tab key markers are denoted by the $ sign, and the number that follows it in the curly brace defines the cycle order (i.e. when you press tab ). You can repeat the number if you want to fill in two fields with the same information. The word that follows the colon is the field text that you will replace when you start typing.

For our "blog title" snippet we will input the following for the content:

<snippet>
    <content><![CDATA[
${1:Title}
####${2:#}

:authors: Your Name
:date: ${3:2015-03-01}
:tags: ${4:Tags}
:slug: ${5:slug}

${6:Starting typing content here...}
    ]]></content>
    <!-- Optional: Set a tabTrigger to define how to trigger the snippet -->
    <tabTrigger>title</tabTrigger>
    <!-- Optional: Set a scope to limit where the snippet will trigger -->
    <scope>text.restructuredtext</scope>
</snippet>

Now we just need to save it by selecting File > Save as or by pressing ctrl + shift +s . The snippet needs to be saved under ~ > .config > sublime-text-2 > Packages > User (ST2 should open the "Save" window in this directory by default) and must have the extension .sublime-snippet. We suggest saving it as a sensible name such as rst-blog-title.sublime-snippet .

Now that it is saved it should work straight away. Navigate back to your .rst file and type in title followed by hitting tab . The snippet should paste all the metadata into your file and allow you to tab through each field and let you update them. Fill in all these fields and add some content such as the classic "Hello World!" Finally, save this file for use in the next section.