Offline documentation with Zeal and Sublime Text

Zeal - a documentation browser
Zeal – a documentation browser

Yesterday I came across a really useful application for web development which has already sped up my workflow when needing to look for documentation: Zeal.

The efficiencies come about mostly because instead of having to open up a new browser tab, then either search or navigate to any documentation bookmarks you may have saved, you can instead search (or browse) within the official documentation which has been downloaded to Zeal.

Download documentation sets

Inspired by the Mac-only application Dash, Zeal is a simple offline API documentation browser.

In other words, select the languages you want documentation for, click download and it’s all available in one easy-to-search location.

Select which documentation sets (docsets) you want and click Download
Select which documentation sets (docsets) you want and click download.

You can either browse the documentation, or simply search.

By default searching returns results from all documentation downloaded, but you can also prefix your search terms with the name of a particular language followed by a colon should you wish to limit the search to only that language or framework, e.g. wordpress: get_header.

In order to install it you first have to unzip the application files to your C:\Program Files directory, or C:\Program Files (x86)\ for Windows 64-bit, and create your own shortcut—there isn’t an automatic installer.

Sublime Text integration

Where I’m finding it particularly useful is within my coding editor Sublime Text, using the Zeal Sublime Text package (available for both Sublime Text 2 and 3) which allows you to search the documentation from within Sublime Text, without lifting your fingers from the keyboard.

I found that to configure it I had to first install the package (using Will Bond’s excellent package control), then run it by pressing Shift+F1 which returns an error, and then locate the Zeal.sublime-settings file (via Preferences > Browse Packages…) and update the “zeal_command” parameter to wherever you unzipped the zeal.exe file, which for me looks like:

"zeal_command": "C:\\Program Files (x86)\\Zeal\\zeal.exe",

Then in Sublime Text itself I have two options:

  1. Select something to look up and hit F1.
  2. Or press Shift+F1 to open the Zeal search box to type in my search term.

As an example, I’ve just highlighted padding-left in my CSS code and pressed F1.

Highlight a keyword press F1 and Sublime Text sends that plus its context (a CSS file) to Zeal
Highlight a keyword press F1 and Sublime Text sends that plus its context (a CSS file) to Zeal

You will notice that the Sublime Text plugin has also respected the search term’s context, within a CSS file, and passed that too as an argument.

I’m really impressed and thoroughly recommend you check it out if you are involved in any kind of coding. Both Dash and Zeal share the same documentation sets. There are a lot! And it can also be integrated into a lot of editors, not just Sublime Text, such as Coda, TextMate, Emacs, Vim, Eclipse, and PhpStorm.

Broadband woes /continued

BT Openreach van parked outside our house on Tuesday 18 February
BT Openreach van parked outside our house on Tuesday 18 February

Having had a minor battle to get @BTCare phone us back last week they finally, and I must say apologetically and humbly, arranged for a BT Openreach engineer to visit the house.

He turned up on Wednesday morning (18 February). A lovely chap, cheerful and engaging. What I really respected about him was that he listened to my tales of woe regarding broadband and crackly-line telephone calls before plugging in his equipment and running various tests.

The tests completed successfully: no faults. Hmm… Then he plugged in his phone to our extension and something grabbed his attention.

“Well… something just changed when I plugged in the phone,” he said. He showed me his meter, the display had suddenly leapt from 0 faults to over 1,500.

He moved operations from our living room (where the home hub is plugged into our solitary extension socket) to the master socket near the front door. His meter climbed to over 3,500 faults.

At this point Isaac returned home from playgroup with a friend and I attended to their lunch in the kitchen while the Openreach engineer donned a hi-vis jacket and poked around beneath a manhole in the street to clear the faults.

He suggested that this may solve the issue, if not then we may be looking at an issue with repetitive electrical impulse noise (Rein) when interference from an external power source interferes with the broadband signal.

Since his visit three days ago our connection has dropped out 29 times so far. There seems to be no obvious pattern to it. These are the values recorded in the router logs after the engineer left:

Tuesday 18 February

  • 16:30:59, 18 Feb. (DSL is down after 229 minutes)

Wednesday 19 February

  1. 15:39:18, 19 Feb. (DSL is down after 1387 minutes)
  2. 16:20:14, 19 Feb. (DSL is down after 40 minutes)
  3. 16:21:37, 19 Feb. (DSL is down after 0 minutes)
  4. 17:16:47, 19 Feb. (DSL is down after 54 minutes)
  5. 17:37:38, 19 Feb. (DSL is down after 10 minutes)
  6. 21:00:08, 19 Feb. (DSL is down after 201 minutes)

Thursday 20 February

  1. 02:12:53, 20 Feb. (DSL is down after 311 minutes)
  2. 02:13:48, 20 Feb. (DSL is down after 0 minutes)
  3. 05:56:33, 20 Feb. (DSL is down after 222 minutes)
  4. 10:11:48, 20 Feb. (DSL is down after 254 minutes)
  5. 13:38:08, 20 Feb. (DSL is down after 205 minutes)
  6. 14:22:27, 20 Feb. (DSL is down after 43 minutes)
  7. 16:56:52, 20 Feb (DSL is down after 153 minutes)
  8. 17:05:25, 20 Feb (DSL is down after 7 minutes)
  9. 18:00:14, 20 Feb. (DSL is down after 53 minutes)
  10. 18:53:33, 20 Feb. (DSL is down after 52 minutes)
  11. 18:54:26, 20 Feb. (DSL is down after 0 minutes)
  12. 21:48:25, 20 Feb. (DSL is down after 173 minutes)
  13. 22:32:53, 20 Feb. (DSL is down after 43 minutes)

Friday 21 February

  1. 10:01:15, 21 Feb. (DSL is down after 687 minutes)
  2. 11:03:35, 21 Feb. (DSL is down after 61 minutes)
  3. 11:07:53, 21 Feb. (DSL is down after 3 minutes)
  4. 21:13:15, 21 Feb. (DSL is down after 604 minutes)
  5. 21:14:14, 21 Feb. (DSL is down after 0 minutes)
  6. 21:19:43, 21 Feb (DSL is down after 4 minutes)
  7. 21:20:37, 21 Feb. (DSL is down after 0 minutes)
  8. 21:36:52, 21 Feb. (DSL is down after 15 minutes)
  9. 21:37:47, 21 Feb. (DSL is down after 0 minutes)

I’ve started recording the line rate speeds (mostly around 888 Kbps upstream, 9720 Kbps downstream, which is significantly less than we’re used to) and noise margins too (12.00 dB upstream/10.60 dB downstream on Thursday dropping to 7.60 dB upstream/8.90 dB downstream today) in case these are important factors.

We also have an electrician visiting the house tomorrow morning to inspect the wiring to try to rule out that as possible cause of Rein.

Words and Scotland’s future

Scotland's Future - your guide to an independent Scotland
Scotland’s Future is available to download, read online or order a copy.

As I have been thinking about the issues surrounding the question of Scottish independence I keep finding myself thinking about language and words. I keep finding myself wondering what relationship these words have with reality.

Words, words, words.

I hear language that suggests us vs them. I hear words about strength and security. I hear accusations of fear and scaremongering.

As Fr Pip Blackledge also said in a recent blog post, I don’t hear much listening. I hear a lot of broadcasting, and threats and posturing, bordering at times on aggression. I don’t hear much listening.

The Scottish government white paper Scotland’s Future: your guide to an independent Scotland opens with this vision:

With independence we can make Scotland the fairer and more successful country we all know it should be. We can make Scotland’s vast wealth and resources work much better for everyone in our country, creating a society that reflects our hopes and ambition. Being independent means we will have a government that we choose – a government that always puts the people of Scotland first. (page i)

Now is the time we need to be living out the society we want to become, regardless of which side of the argument we find ourselves on. Already we need to be demonstrating the kind of society that puts one another first, that understands fairness and demonstrates respect and care.

Before I was ordained Fr Gian Tellini told me that if I wasn’t a priest when I went up the aisle at the start of the service then I certainly wouldn’t be one when I walked back down the aisle at the end.

If a majority of Scots vote yes in September then it will still be the same people (those who voted yes and those who voted no) living side by side trying to figure out how we adjust and get on with it. We need to be listening now, and building bridges and developing an understanding and caring of one another’s points of view now, because that is the society we’re going to need after the referendum, regardless of the outcome.

There’s lots more I want to say but I’m going to keep this short and end with this short passage from one of my favourite books, Awareness by Anthony de Mello (Zondervan, 1990) which talks about how we identify with words.

Mark Twain put it very nicely when he said, “It was so cold that if the thermometer had been an inch longer, we would have frozen to death.” We do freeze to death on words. It’s not the cold outside that matters, but the thermometer.

It’s not reality that matters, but what you’re saying to yourself about it.

I was told a lovely story about a farmer in Finland. When they were drawing up the Russian-Finnish border, the farmer had to decide whether he wanted to be in Russia or Finland. After a long time he said he wanted to be in Finland, but he didn’t want to offend the Russian officials. These came to him and wanted to know why he wanted to be in Finland. The farmer replied, “It has always been my desire to live in Mother Russia, but at my age I wouldn’t be able to survive another Russian winter.”

Russia and Finland are only words, concepts, but not for human beings, not for crazy human beings. We’re almost never looking at reality.

[…]

Words, words, words, words, how imprisoning they are if they’re not used properly.

That farmer didn’t move! Even if he had decided to label his patch of land ‘Russia’ the winter would not, in reality, have been any more severe than any of the previous he’d experienced there. All that would have changed was the label. But in his mind that label meant harsh winters.

I wonder, what does it really mean to label myself Scottish? Or half-Scottish, half-English (which is what I am)? Or British? Or even northern British? What difference do these labels make to my perception of myself? What difference do these make to how I act and behave? What difference do they make to the reality of who I am: the I, the subjective knower, as opposed to the objective me?

What difference will it actually make whether Scotland is an independent country or remains part of the United Kingdom?

This is a challenge for me, I think, to be careful with my words, to listen more, to understand what others think and feel and fear (and to acknowledge that fear is also a valid response to this situation), and to be on the lookout for the reality behind the labels.

The adventure continues…

I heart maths

Wolfram | Alpha is a very powerful computational search engine. While Google does feature the ability to do some calculations, Wolfram | Alpha takes this a whole new level including the ability to solve and plot equations.

For example, take this mathematical equation:

Equation

which you must enter into Wolfram | Alpha in this format:

x^2+(y-(x^2)^(1/3))^2 = 1

Wolfram | Alpha plots it like this:

This mathematical formula (x squared plus y minus the cube root of x squared squared equals one) plots the shape of a love heart
x squared plus y minus the cube root of x squared squared equals one

There’s something lovely about maths.