Published: 2011-11-01

To implement bash(1) tab completion for Cakefile task names all you need to do is add this completion function and command to your ~/.bashrc file:

# Task name completion for cake files. function _cake() { local cur tasks cur="${COMP_WORDS[COMP_CWORD]}" tasks=$(cake | awk '{print $2}') if [ $COMP_CWORD -eq 1 ]; then # Task name completion for first argument. COMPREPLY=( $(compgen -W "$tasks" $cur) ) else # File name completion for other arguments. COMPREPLY=( $(compgen -f $cur) ) fi } complete -o default -F _cake cake c

Now it you type cake <Tab> at the bash command prompt you will get a list of tasks from the current Cakefile. As with all bash completion, if you start typing a name and press Tab then bash will complete the name for you.

To cut down key strokes I’ve also added a c alias for cake to ~/.bashrc:

alias c='cake'

Published: 2011-10-25

This blog entry describes how to write functional tests for CoffeeScript web apps using Selenium. By way of example I’ll describe how I added Selenium tests to the Routeless Backbone Contacts tutorial app and automated it’s execution with a Cakefile.

The source is on Github, the tests described in this post are at the 3.0 tag.

Unit testing frameworks such as QUnit work well for testing libraries, APIs and computational logic but fall short when it comes to testing user interface intensive browser applications, this is where Selenium comes in. The Selenium IDE provides an easy way to functionally test an application user interface in a real browser with exactly the same mouse and keyboard input that a user would enter.

At it’s core “Selenium automates browsers” with a macro-like scripting language called Selenese and a Firefox IDE for recording and playing Selenese scripts. Selenium tests the actual user interface so you record your tests after the user interface has been implemented.

The primary purpose of functional user interface tests is to catch future user interface regressions. The likelihood of user interface regressions at each release increases with the size of the application.

Selenese Selenese is the Selenium IDE scripting language, it is surprisingly powerful: Variables can be stored and manipulated. You can run JavaScript snippets with the runScript and waitForCondition commands. The Selenese native format is an HTML table but it can also be exported to languages with Selenium binding (Python, Java, C#).

Requisites

To use the Selenium IDE you will need to install:

• The Firefox web browser.
• The Selenium IDE. Once installed you open the IDE with the Firefox Tools→Selenium IDE menu command.
• I also installed the Highlight Elements IDE plugin.

This post is based on Firefox 7.0.1 (Ubuntu) with Selenium IDE 1.3.0.

Creating a test

Creating a Selenese test script is a two step process:

1. Record a sequence of user interface interactions (mouse and keyboard inputs).
2. Add asserts and verifications to the test sequence. This is the step that transforms the browser automation sequence into a test.

The Selenium IDE documentation also explains how to run, save and edit tests.

Here’s the test for the tutorial application.

Mongoose web server The Mongoose web server is a neat little configurationless cross-platform web server that’s ideal for testing web apps. To install Mongoose on Linux: Unpack and make the source distribution: tar -xzf mongoose-3.0.tgz cd mongoose make linux Copy the mongoose executable to somewhere in your PATH. To use: Change to your app directory. Run mongoose: mongoose [-i <index-files>] Open your browser at localhost:8080, if an index file exists it will be displayed else you’ll be presented with a file browser interface.

Running tests from the command-line

There’s no easy way to open the Selenium IDE and get it to execute a test from the command-line (at least I couldn’t find one), but you can export the tests to Python (or Java or C#) and then run them from the command-line. Apparently a JavaScript driver is in the works but not here yet, so I opted for Python.

I like being able to run Python tests from the command-line but I prefer developing the tests using the IDE. Keeping both in sync can be a challenge but being able to copy commands from the Selenium IDE to the Python source is a real help (set the IDE Options→Clipboard Format→Python 2 (WebDriver) option and you will be able to copy-and-paste IDE commands as Python code).

1. In addition to the Selenium IDE you will need to install the Python bindings for Selenium:

   sudo pip install selenium

2. Now export the test from the Selenium IDE to a Python test file using the IDE File→Export Test Case As→Python 2 (WebDriver) menu command.

The exported Python scripts make use of the Python unit testing framework.

Export anomalies and omissions

The export of Selenese to Python is not perfect, here are some of the manual edits I had to do:

• Replace:

  # ERROR: Caught exception [ERROR: Unsupported command [getConfirmation]]

  with this:

  driver.switch_to_alert().accept()

  See also the Selenium FAQ.

• Moved the focus from the search box to fire the search box change event (used click command as focus is not supported by Python WebDriver API):

  driver.find_element_by_css_selector("input.search").send_keys("sm")
  driver.find_element_by_name("name").click()   # Fire search 'change' event.

  See Dynamic UI controls below.

Here’s the Python test for the tutorial.

Dynamic user interface controls

Incremental search boxes and auto-completing drop-down lists typically emit keystroke events (up/down/press) to dynamically update other elements in response to user keyboard entry. The Selenese type command will not work in this situation.

• The typeKeys command is designed for these situations but I was unable to get it to work.
• Nor did the fireEvent command on keyup work.

The only reliable work-around I could find for testing the incremental Search was to add the change event to the search box and use:

driver.find_element_by_css_selector("input.search").send_keys("sm")
driver.find_element_by_name("name").click()

The click command moves the focus from the search box to trigger a search box DOM change event.

Setup and Teardown

At the start of testing you will typically create test fixtures to put the application in a known state. For data oriented apps this means means populating the database with fixed data, the Routeless Backbone Contacts application has built-in Clear All and Import Data commands that serve this purpose.

Built-in data fixture commands are not normally part of an application but there’s no reason not to implement hidden or debug only fixture commands. Alternatively, if you have moved exclusively to Python scripts for Selenium testing then, you could setup and teardown fixtures in the traditional fashion using Python unittest class and module fixtures.

Cakefile automation

The Routeless Backbone Contacts application is written in CoffeeScript so it made sense to automate the tests with a Cakefile. Because cake runs under Node.js you have a wealth of modules available.

The tutorial Cakefile implements two tasks:

cake server

Start the Mongoose server.

cake test

Run the Python Selenium test.

Cakefile

{exec,spawn} = require 'child_process'

task 'server', 'Start mongoose server', ->
    console.log 'starting mongoose web server...'
    server = spawn 'mongoose', [],
        customFds: [process.stdin, process.stdout, process.stderr]
    process.exit()

task 'test', 'Run tests', ->
    console.log 'starting mongoose web server...'
    server = spawn 'mongoose'
    console.log 'starting tests...'
    exec 'python test/test.py', (err, stdout, stderr) ->
        throw err if err
        console.log stdout + stderr
        server.kill()   # and exit cake.

Published: 2011-10-20

You can configure Vim to automatically compile CoffeeScript files when you save them from within Vim, it’s easy, just add an autocmd to run the CoffeeScript compiler to your ~/.vimrc file:

autocmd BufWritePost,FileWritePost *.coffee :silent !coffee -c <afile>

I prefer this to the CoffeeScript compiler --watch option because you get to see any compiler errors in the editor when you save the CoffeeScript source file.

This technique works, but what happens if you want to selectively include CoffeeScript compiler options with some files and not others? I came up against this problem writing QUnit tests using CoffeeScript which must be compiled without the top-level function wrapper using the --bare command-line option.

My solution was to take a cue from Vim’s mode line feature and write a CoffeeScript compiler wrapper shell script which scans the end of the CoffeeScript source file for a comment line starting with # coffee:, it then passes the remainder of the line to the CoffeeScript compiler as command-line options. Here’s a basic CoffeeScript QUnit test file specifying the --bare option in the trailing mode line:

module 'Test'

test 'addition', ->
    equals 1+1, 2, 'one and one is two'

# coffee: --bare

And here’s the coffee.sh wrapper script:

#!/bin/sh
#
# 'Mode line' wrapper for CoffeeScript 'coffee' compiler command.
#
# Executes CoffeeScript compiler and includes compiler options from line at the
# end of the CoffeeScript source file starting with '# coffee:' (c.f. Vim mode
# lines).
#

# Last argument is the source file name.
for srcfile; do true; done

# Search the last 5 lines in the source for a mode line and extract the
# trailing coffee command options.
pat='^#\s*coffee:'
opts=`tail -n5 $srcfile | grep "$pat" | sed "/$pat/s/$pat//"`

coffee $opts $@

You also need to change coffee to coffee.sh in your ~/.vimrc autocmd plus you need to ensure both coffee to coffee.sh are in your shell search PATH:

autocmd BufWritePost,FileWritePost *.coffee :silent !coffee.sh -c <afile>

Published: 2011-10-16

The Backbone.js Model class provides get and set methods to read and write Model attributes which is not a concise or natural as object property access. But it’s not difficult to add a class method to generate Model getter/setter properties so that you can do this in CoffeeScript:

person.name = 'Joe Bloggs'
ph = person.phone

instead of this:

person.set {name: 'Joe Bloggs'}
ph = person.get 'name'

The CoffeeScript example below shows how it’s done using the ECMAScript 5 Object.defineProperty function to define a Model attribute method. I’ve added the attribute class method to a BaseModel class which is inherited by application classes. To create a Model attribute property call the attribute method and pass it the name of the property.

Backbone = require 'backbone'

class BaseModel extends Backbone.Model
    # Create model attribute getter/setter property.
    @attribute = (attr) ->
        Object.defineProperty @prototype, attr,
            get: -> @get attr
            set: (value) ->
                attrs = {}
                attrs[attr] = value
                @set attrs

class Contact extends BaseModel
    @attribute 'name'
    @attribute 'phone'

p = new Contact()
p.name = 'Joe Bloggs'
p.phone = '1234'
console.log p.attributes    # { name: 'Joe Bloggs', phone: '1234' }

Being able to create custom getter/setter properties is a testament to the little known power of JavaScript.

References

• ECMAScript 5 Objects and Properties
• ECMAScript 5 Strict Mode, JSON, and More
• ECMAScript 5 compatibility table

Published: 2011-10-03
Updated: 2011-10-25

This post describes a revamped version 2.0 of my original Routeless Backbone Contacts application. The material covered here builds on the original post.

1. The basic application functionality and the underlying data remains the same.
2. The new user interface is a single two-pane page with a selectable list of contacts on the left and contact details on the right.
3. A Search box has been added to incrementally filter the list of displayed contacts.
4. The application is 100% event driven — there is no direct coupling between the views. Backbone.js events emitted by the underlying contact data collection ensure the views are updated automatically when the state of the underlying data changes.

Routeless Backbone.js Contacts is a totally client-side CRUD tutorial application written using CoffeeScript, Stylus, Backbone.js and jQuery which are a perfect match for writing concise, readable well structured web applications.

• The source is on Github:
  • This release described in this post is at the 2.0 tag.
  • A subsequent release includes Selenium tests and is at the 3.0. tag.
• The contacts data is persisted locally using browser Web Storage.
• Templates are written using Underscore.js templates (included with Backbone.js).
• Refer to the original Routeless Backbone Contacts 1.0 blog post for more information.

User Interface

The single page user interface combines four Backbone.js views. The views subscribe to, and are updated by, events emitted by the contacts collection (add, remove, change, reset, filter, select).

Models and Collections

ContactModel

The same model as version 1.0.

ContactsCollection

The ContactsCollection collection has been enhanced:

1. The Filter class provides functions to filter the collection by contact name. When the filter criteria changes the collection broadcasts a custom filter event to subscribed views.
2. The Cursor class provides a cursor object which represents the currently selected model in the contacts collection. The cursor listens for changes to the collection so that it can automatically ensure the cursor points to a valid contact in the filtered collection. When the cursor changes the contacts collection broadcasts a custom select event to subscribed views.

Views

RibbonView

StatusView

ListView

DetailView

Browser Compatibility

The markup generated by this tutorial is HTML5 with CSS3, no attempt has been made to accommodate legacy browsers.

• Was developed and tested on Google Chrome 14.
• Firefox 6 works fine.
• Requires IE9+ for correct CSS styling (though the header gradient doesn’t work in IE9).
• Requires iOS5+ for the names list to scroll.

Backbone.js Tips

• The use of the fat arrow function definition operator in event handlers is significant. In the following example, when render is called this will be bound to the callee’s this context so the reference to @el will be correct:
  

  @model.bind 'change', @render render: => @el.html @template

• Don’t rely on the execution order of registered events.
• The Model change event bubbles up through related collections.
• It pays to monitor event handler execution during development. If a section of code triggers the execution of the same handler multiple times this may be symptomatic of a non-optimal design. For example, without the silent option the following code would trigger multiple collection remove events (the collection reset is sufficient to ensure listener notification):
  

  contact.destroy {silent: true} for contact in @collection.toArray() @collection.reset()

  On the other hand, it’s not unusual for event handlers to execute common code which can also result in execution redundancy (for example, the renderCursor handler is also called by the render handler in the ListView). In cases like this don’t sweat over eliminating the redundancy unless it impacts performance — code clarity is usually preferable to the convoluted and brittle optimisations generated by a “fix”.

• When Backbone.js Models and Collections emit built-in events they pass associated event information to the event handler arguments. The catalog of Backbone.js events documents the event handler arguments. Currently undocumented is fact that options arguments passed to event triggering methods are passed through to the handlers as the trailing argument. In the following example an object containing a custom option myOption will be the third argument passed to the add event handlers "add"(model, collection, options):
  

  myCollection.add myModel, {myOption: 'foobar'}

• Don’t forget that Backbone.js event handlers are passed arguments (see previous item). For example, the Backbone.js Collection reset event passes the associated collection to the handler in the first argument which will cause the following code to fail:
  

  @_collection.bind 'reset', @set set: (model=null) => :

  If you assumed that the set handler would be called with no arguments you would expect model to be set to null — in fact model is assigned @_collection. The code can be fixed by introducing an anonymous proxy handler that is bound to this and called without any arguments:

  @_collection.bind 'reset', => @set() set: (model=null) -> :

• Use the built-in event argument passing conventions if you have to trigger a built-in event programmatically. For example:
  

  @collection.trigger 'reset', @collection

Published: 2011-09-24
Updated: 2011-10-03

You don’t need a URL router to write client-side applications.

Routeless Backbone.js Contacts is a totally client-side CRUD tutorial application written using CoffeeScript, Stylus, Backbone.js and jQuery which are a perfect match for writing concise, readable well structured web applications.

• The source is on Github.
  

  Note	This release described in this post is at the 1.0 tag.

• Uses DOM events exclusively for UI navigation.
• The contacts data is persisted locally using browser Web Storage.
• Templates are written using Underscore.js templates (included with Backbone.js).

Screenshots

ListContactView

ShowContactView

EditContactView

Going routeless

It’s a mindset thing. If you come from a server-side web applications background your first instinct is to use a router and fragment identifiers to emulate browser page navigation — go down this route you soon find that trying to maintain a consistent back-button browser history is time consuming, messy and ultimately unnecessary. Single page applications don’t need a back-button (or any browser chrome), especially if they are bundled as pseudo-native mobile apps with something like PhoneGap or packaged for the desktop, for example as Google Chrome Packaged Apps.

Routeless Backbone.js Contacts resides at a single unfragmented URL — user interface navigation is managed exclusively by DOM events. Button and link elements deal with the click events client-side (you are not POSTing form data to a server, so form elements and submit buttons are not necessary). If the application were to persist data externally then then the data POSTS and GETS would be handled transparently by a Backbone database adapter.

Running the application

Once you have downloaded the source from Github open the index.html file in your browser. Press the Import Data button to load the example contacts database.

The source

This post should be read side-by-side with the source, it’s very readable (although a basic understanding of CoffeeScript, HTML and jQuery is recommended).

index.html

Application page HTML and view templates.

application.coffee

Application, models and views.

data.js

Canned data (100 fictitious contacts) loaded by the Import Data command.

main.styl

Stylus CSS.

helpers.styl, gradients.styl

CSS helper functions.

HTML5 markup is used throughout. All the logic is confined to application.coffee (around 160 lines of code). The beauty of CoffeeScript is that the code is concise and virtually self-documenting, for example, here’s the event handler in the ListContactView that responds to the Clear All button click:

clear: (e) ->
    return if not confirm 'About to delete all data.'
    contact.destroy() for contact in @collection.toArray()
    @render()

Application structure

The app object

There is a single global instance app of the App class which:

• Initializes and namespaces global data (collections and views).
• Contains a few generic methods to allow programmatic inter-view navigation — this allows views to call one another and not have to share any information about each other.
• Starts the application (with app.start()).

Models and Collections

A single app.contacts collection of Contact models is persisted locally using the Backbone localStorage Adapter. A single store is instantiated and attached to the ContactModel, the same store is referenced by the ContactCollection.

Views

The CRUD user interface is implemented by three Backbone.js views — ListView, ShowView and EditView (the EditView is also used to create new contacts).

• Each view handles the set of DOM events defined by the View’s events property.
• The events property routes DOM events to a handler within the View.
• When a matching DOM event occurs the View handler is called and passed a jQuery event object.

This example (from the ListContactView) uses a custom data attribute (data-id) to pass the contact ID from the anchor element via a click event object.

DOM event registration:

events:
    'click a.show': 'show'

Link click handler:

show: (e) ->
    @model = @collection.get e.target.getAttribute('data-id')
    @render()

Template link markup:

<a class="show" data-id="<%= contact.id %>"><%= contact.getName() %></a>

It would have been nice to have used the HTML5 DOM dataset property to retrieve the data-id attribute (e.target.dataset.id) but it does not currently work in IE9, Safari or Android browsers.

Libraries

The app uses the following JavaScript libraries (in the lib directory):

• Backbone.js
• jQuery
• Underscore.js
• The Backbone localStorage Adapter persists models to the local disk using the browser Web Storage API.

Techniques

Load scripts at the end of the page body

Place script tags last in the page body, just before the closing body tag. This ensures the page elements elements have been parsed and can be referenced when the scripts execute and allows you to safely reference page elements from class property initializers. See this stackoverflow discussion.

Intra-application links do not need href’s

Dropping the href ensures there are no changes to the browser URL or history.

CSS and HTML Tips

• Stylus is to CSS as CoffeeScript is to JavaScript, use it to keep your CSS DRY and to maintain your sanity.
• Use Stylus imports to unclutter your main CSS.
• CSS padding vs margins:
  • Margins define the element’s relationship to other elements (spacing) and are context specific i.e. an element’s margins will change depending on where it is used in the application.
  • Padding styles an elements appearance and isn’t a context sensitive as the element margins.
  • The width property does not include the margins, border or padding.
• Use HTML5’s concise syntax, it may seem wrong after years of XML indoctrination but it’s not, it’s easier to read and your fingers will thank you. Examples:
  • Closing tag omission:
    

    <tr><td>Foo<td>Bar YES <tr><td>Foo</td><td>Bar</td></tr> NO

  • Minimized attributes:
    

    readonly YES readonly="readonly" NO

  • Empty elements don’t need explicit termination:
    

    <img src="me.png"> YES <img src="me.png" /> NO

• Length and size:
  • Use em units to set size properties on elements that display text, it’ll make it much easier to resize your app.
  • To get exact placements you’ll need to use pixels, but this can probably be confined to non-text elements.
  • Use Stylus arithmetic expressions to maintain the size of interdependent page elements so that changing a single size will ensure the depend sizes are adjusted automatically (DRY again).
• Be careful assigning id attributes in templates, do so only if the template will never appear more than once on a page. If in doubt assign class attributes instead of id attributes.
• Tables are not bad, in fact they are very good for laying out application pages (which are quite different to document oriented websites).
• Don’t put CSS style attributes in HTML template markup — this should be obvious.
• Start with a clean slate, reset user-agent (browser) document oriented CSS defaults:
  

  * { font-size: 20px; font-family: sans-serif; margin: 0; padding: 0; }

References

• E. Mathieu Sternberg’s The Backbone Store, version 2.0.

Published: 2011-08-31

My blogs are usually technical in content and try to be objective in character, this blog is a bit different, it has an unashamed subjective bias (you’ve been warned).

Shortly after the iPad 2 was released I went over to the Dark Side and brought one (my first and only Apple computer). I was just fed up waiting for a decent Android tablet. At the time my only requirements were a decent ePub reader and a web browser.

After two months with the iPad I was still hankering for an Android tablet, I know this probably sounds a bit wishy-washy, but although I used it every day I never really bonded with the iPad, it always felt like an appliance, a black box, something that you turn on, use, then turn off. Don’t get me wrong, the iPad 2 is a nice piece hardware, it’s easy to pick up and use and the software does what it was designed to do. The best recommendation I can give the iPad is that it works.

Two weeks ago I bit the Android bullet and tossed up between an Asus Transformer and a Samsung 10.1 tablet. The Transformer won and I brought the 32GB model with keyboard dock. When I say “tossed up” I am being a little flippant — I compared specs, read reviews and got to play with a Transformer (I had been leaning towards the iPad-like Samsung 10.1 but the hands-on convinced me that the Transformer was a nice piece of kit and that the keyboard was going to be very useful). The transformer’s cheaper price was also a plus.

I haven’t touched my iPad since I got the Transformer, the more I use the Transformer it the more I like it (there’s a greater depth in Android vs iOS) so much so that I’ve given the iPad to my wife. It’s not all sunshine and roses though (see the bad parts), but Android is heading in the right direction — all it needs is for Google to keep on polishing the rough edges and not to take their eyes off the ball.

Here are some comparative observations — things that stood out for me (please bear in mind that these are personal observations, this is not a formal product review):

Thumb friendly UI

The user interface is very “thumb friendly” — most of the time I hold the tablet in landscape mode with one hand either side using just my thumbs to execute commands — much more efficient that the iPad’s “hunt and peck” UI. I don’t know if this is serendipity or by design.

Weight and size

This is interesting, the Transformer is marginally heavier than the iPad 2 (680g vs 601g) but it feels lighter, probably because it’s larger and less dense. The Transformer is also thicker (13mm vs 8.8mm), I thought this would be a biggy (most reviewers think it is) — I was wrong, for me there’s no subjective difference.

Batteries included

The Transformer tablet has a built-in HDMI port and a Micro SD Card slot (iPad memory can’t be expanded and you need an external adapter for HDMI connectivity). The first accessories I brought for the Transformer were:

• A 5m HDMI cable so I could play tablet HD video and audio on my TV.
• A 16GB Micro SD card for transferring and storing data.

Cameras

The 5M pixel rear camera produces much higher quality photos and movies than the iPad, there’s just no comparison.

Real keyboard

The Transformer keyboard dock has a real keyboard (plus battery pack plus expansion ports) which turns the Transformer tablet into a Netbook PC and makes it useful for content creation. For me the lack of a real keyboard for the iPad was an increasing source of frustration (I know you can buy keyboards for the iPad but it’s just not the same as having a beautifully integrated keyboard unit)

Note	The tablet lock/unlock slider should be on the left when inserting the tablet (I thought the slider icon meant locked — it actually means unlocked).

Bundled apps

In my opinion all the Asus specific non-Google apps that come loaded on the Transformer are crapware. I just wish manufacturers would ship vanilla operating systems without including other apps, or at the very least make them optional (there doesn’t even seem to be any easy way to delete the bundled apps).

The Android platform is relatively open

The freedom to choose and create software without the platform vendor’s permission is important to me — Apple’s totalitarian control over iPad software installation and distribution is an unpalatable dead end.

What’s missing

At the moment I’m mostly using the Transformer without the keyboard dock and what I miss most is the iPad Smart Cover — wandering around holding the Transformer in one hand with my fingers on the glass screen doesn’t feel right and there’s a constant nagging awareness of always having to be careful to protect the glass screen.

The bad parts

In a word software (my unit is running Android 3.2).

• Number one problem: The browser is appallingly slow on JavaScript heavy sites (try the jQuery mobile demos). I also tried FireFox, Opera and Dolphin — in all three cases the stability and usability was worst than the Android browser. I don’t know if this is specific to the Transformer or not (see Issue 17353: Honeycomb 3.1: Slow web browser performance on websites with a lot of JavaScript. This is frustrating because the tabbed Android browser has a better UI and many more features than the iPad’s browser.
• Your TV HDMI inputs may or may not work with the tablet HDMI output. My Philips 42 inch LCD TV didn’t connect when plugged into the Transformer, it does not support the tablet’s 1280×800 output. I took the Transformer down to a local TV shop tried two 42 inch LCD TVs: it worked on a Sony but not an LG. This post suggest the problem is a software limitation a the moment: “Tegra 2 supports 1080p output over HDMI, but right now the product is limited to 1280 x 800 output over HDMI”.

Published: 2011-08-30
Updated: 2011-09-04

Here is an AsciiDoc configuration file that can be used to create a simple backend plugin for generating Fossil friendly Wiki markup from AsciiDoc source (I wrote it as a proof-of-concept of the new AsciiDoc backend plugins).

Fossil is a wonderful distributed version control system (DVCS) by Richard Hipp, the author of SQLite. It is built on SQLite and shares the same small-is-beautiful single stand-alone executable philosophy.

A Fossil repository doesn’t just manage source, it also supports distributed project bug tracking, wiki and blog — all managed by an integrated Web UI. Fossil really deserves more attention than it currently gets.

fossil.conf backend configuration file

#
# AsciiDoc configuration file for Fossil DVCS wiki HTML generation.
#

include::{asciidoc-confdir}/html4.conf[]

[footer]
</nowiki>

#--------------------------------
# article and book document types
#--------------------------------
ifndef::doctype-manpage[]

[header]
<nowiki>
{notitle%}<h1>{doctitle}</h1>
{doctitle#}<p>
{doctitle#}<strong>{author}</strong><br>
{doctitle#}<tt>&lt;<a href="mailto:{email}">{email}</a>&gt;</tt><br>
{doctitle#}version {revnumber}{revdate?,}
{doctitle#}{revdate}
{doctitle#}<br>{revremark}
{doctitle#}</p>

endif::doctype-manpage[]

#-------------------------
# manpage document type
#-------------------------
ifdef::doctype-manpage[]

[header]
<nowiki>
<hr>
<h1>
    {doctitle} Manual Page
</h1>
<hr>

endif::doctype-manpage[]

To install the plugin save the listing to fossil.conf and put it in a directory named .asciidoc/backends/fossil in your home directory. Or you could create a plugin and install it using the asciidoc(1) --backend option build and install plugin commands.

Use the fossil backend as you would the built-in backends. For example, this command will insert a Wiki page called AsciiDoc into the current Fossil repository:

asciidoc -b fossil -o - asciidoc.txt | fossil wiki commit AsciiDoc

Published: 2011-07-17

How to configure your Android phone to automatically turn off the mobile data connection once your mobile data limit is reached.

Why bother? In New Zealand we have what amounts to a telecommunications duopoly with mobile data charges that make your eyes water — Vodafone charges me $1 NZD (0.84 USD) for every megabyte over my capped limit of 10MB per day (yes you read correctly 10 megabytes!) with no facility to limit overruns.

Here’s how

1. Go to the Android Market and install the 3G Watchdog and APNdroid applications (both are great apps).
2. Configure 3G Watchdog with your data limit and configure it to use APNdroid to turn off.
   

3G Watchdog will now use APNdroid to automatically turn off your mobile data connection when the preset level is reached, What’s nice is that it will automatically reenable data atically at your next data period.

I also set the 3G Watchdog update frequency to the shortest possible (30s) because in 30s you can consume a lot of data (relative to my measly limit).

Lastly, a word of warning: Android phones consume mobile data even when you’re not using them — this is why I manually turn off mobile data (using APNdroid) when I’m not using it (most of the time I’m on WiFi so I don’t need to have mobile data enabled).

Published: 2011-07-16
Updated: 2011-07-26 (added Q&A)

I went from initial scepticism, when I started looking for a usable iPad remote desktop solution for accessing Windows PCs, to (almost) wild enthusiasm.

I evaluated four of the best iPad remote access apps and am delighted to have found one that does exactly what I want. This post outlines why I settled on Jump Desktop along with a few usage tips.

The four apps I evaluated were:

• Remote Desktop Lite – RDP version 2.7.
• iTAP RDP version 1.7.3.
• Desktop Connect version 4.2.

All four have very good RDP (Microsoft Remote Desktop Protocol) clients, the latter two also include VNC clients. Remote Desktop Lite – RDP is a free app the others are non-free.

The hard part: getting back into your office

My principle use case is remote Internet access from a wireless iPad tethered to my mobile phone back into desktops running Microsoft Windows on my (Internet connected) office LAN. The hard part is locating and securely connecting to desktop PCs from an external location on the Internet. This is because most desktop PCs are isolated from the Internet behind a NAT router/firewall with a dynamic IP address, so you can’t use DNS to locate the router or the PC. You have two choices:

1. You can manually reconfigure your router NAT and firewall rules; then configure your desktop PC’s firewall and remote access permissions; then setup dynamic DNS to your router (this web page outlines the process).
2. Or you can install a desktop app which sets up and manages your connections automatically.

Manual configuration is time consuming and fiddly. It can be downright dangerous if you’re not careful or don’t understand what you’re doing. Of the four apps I tried only Desktop Connect and Jump Desktop support the automatic configuration option (both use Google Talk to facilitate the connection) — this is why, for me, the choice was between these two remote access apps.

Why I choose Jump Desktop over Desktop Connect

Both Jump Desktop over Desktop Connect have excellent RDP and VNC iPad clients, but Jump Desktop really shines when it comes to the auto-connect functionality.

• Jump Desktop auto-connect supports both RDP and VNC protocols, Desktop Connect only supports VNC.
• The free Jump Desktop Viewer is a real gem, it gets installed with the PC Jump Desktop and allows you to use a PC in place of an iPad for the remote access client.
• The Jump Desktop PC auto-connect installer is very polished — it handles VNC server and .NET dependency installation (if necessary). Desktop Connects PC auto-connect app (Easy Connect) was still in beta at the time of my evaluation.

The only thing I would like to see added to Jump Desktop would be built-in help with some sort of first time use wizard or guide. The Jump Desktop website has a very good searchable Knowledge Base which you’ll probably need to use while learning the app. I had a more favorable initial experience with Desktop Connect, it has built-in help and a more discoverable and attractive user interface.

But at the end of the day my choice of Jump Desktop over Desktop Connect was clear cut and unequivocal.

I evaluated RDP connections to Windows 7 Pro and Windows XP Pro; VNC on Windows 7 Home.

RDP or VNC?

The target desktop PC must run a remote access server. All current versions of Windows (apart from Windows Home and Starter editions) come with an RDP server and I recommend using RDP over VNC for Windows access:

1. RDP can run the client at different resolution to the host PC, this means you can always view the remote desktop using the iPad’s native 1024×768 resolution, there’s no pixel interpolation and the clarity is greater.
2. I found RDP performed faster and smoother than VNC alongside each other to a Windows 7 desktop (my iPad was connected to the Internet over a fairly slow tethered mobile 3G connection).
3. The RDP server comes preinstalled and supported by Microsoft.

VNC is useful for non-Windows desktops (Linux, OS X) and for Windows Home edition (which does not include an RDP server).

Jump Desktop tips

Unless stated otherwise these comments relate to RDP connections.

• When using RDP the desktop PC user account that you want to log into must have a password (unless you are prepared to change the password policy). You can set the PC’s autologon to get Jump to automatically submit your logon parameters.
• By default the desktop wallpaper is disabled over RDP (see next item) and the solid desktop color will be displayed. The default solid desktop color is black on Windows 7 but you can change it:
  1. Right-click on the desktop and select Personalize.
  2. Click the Desktop background link then select Solid colors from the Picture location drop-down list and choose a color.
  3. Click Save Changes.
  4. Optionally restore your wallpaper for local access.
• You can enable the desktop wallpaper by editing the Jump quality settings (though this will slow performance and increase data traffic).
• Take time out to learn the Jump Desktop gestures and toolbar and experiment with the user interface options to find the ones that suit you best (I disable the cursor and use pinch and zoom when I need pointer accuracy).
• The Jump Desktop Knowledge Base is your friend.

Q & A

What if I don’t have an iPad?

You don’t need an iPad for remote access, for example the free Jump Desktop Viewer allows you to use a Windows PC in place of an iPad for the remote access client — an option if you’re wanting to dip your toes in the water before deciding on buying an iPad.

Don’t I need an iPad with the 3G option to use a mobile data connection?

No, not if you have a mobile phone that supports WiFi tethering. WiFi tethering turns your phone into your own private wireless hotspot, in most new Android phones turning tethering on is a simple one-click option.

How can I keep a lid on mobile data costs?

Remote access typically uses less data than Web browsing but mobile data is expensive in New Zealand, so only use it when you have to and if, for example, you’re at home connect the iPad to the Internet over your home WiFi connection. I blogged about this recently.

Is it true that remote access won’t work on a PC running Windows Home edition?

Microsoft does not bundle an RDP server with Windows Home editions so you need to install an alternative. Jump Desktop will optionally install a VNC server on Windows Home PCs, but a version of Windows with built-in RDP is preferable.

What happens if my desktop PC is powered off?

Your desktop PC has to be powered on to access it remotely so you do need to leave your PC on and don’t enable the Hibernate or Sleep power options. Most PCs are capable of being turned on by a remote command over the Internet, but getting this configured and working is outside the scope of this post.

So now I’ve got a tablet I don’t need a desktop PC, right?

Not so fast, tablets are content consumers not content creators. The tablet on-screen keyboard and small screen is OK for casual input and browsing but is not suitable for ongoing data entry or document creation.