As web developers we write a lot of code, we also take the time to properly select the most semantically appropriate HTML elements for our content. When writing tutorials and articles with code, why don’t we also take the time to properly mark up our code samples in HTML?

Most developers take the route of using a Javascript syntax highlighter or using a server side solution, like Pygments. These aren’t bad solutions, in fact they are pretty great, but they just use a bunch of <span> elements with classes to syntax highlight. We can do better, semantically.

The Elements

We still need to use the trusty <pre><code> as used by the above mentioned scripts. But for the code inside, we can do so much better than meaningless <span>s.

Looking at the HTML specification we have a bunch of elements that make sense within our code blocks:

• <var>: variables
• <b>: keywords; like built in functions and properties
• <i>: taxonomy, technical term, designation; like properties, methods, attributes
• <small>: fine print or comments
• <del>: code that is removed
• <ins>: code that is added
• <mark>: important, highlighted code
• <samp>: computer output
• <kbd>: user input

And we still use the <span>, but only for things that have no meaning in the context, like a regular old string.

Some Examples

Lets walk through some samples to see how to use these elements in our code samples.

HTML

What you want to see:
(view source to see it in practice)

<div class="group">
<h1>Sample HTML</h1>
<p>Some super awesome content!</p>
</div><!-- end group -->

What HTML you would write:

&lt;<b>div</b> <i>class</i>=<span>"group"</span>&gt;
&lt;<b>h1</b>&gt;Sample HTML&lt;/<b>h1</b>&gt;
&lt;<b>p</b>&gt;Some super awesome content!&lt;/<b>p</b>&gt;
&lt;/<b>div</b>&gt;<small>&lt;!-- end group --&gt;</small>

So, from a semantics point of view, I believe the above code is more appropriate. The notable additions are:

• <b> for wrapping around the HTML elements; semantically the elements are keywords, in their context.
• <i> for wrapping attributes on the HTML elements; I suppose that attributes are a taxonomies or designations.
• <span> for wrapping around strings in code, since the string really doesn’t have any meaning.
• <small> for wrapping around comments.

CSS

What you want to see:
(view source to see it in practice)

/* Sectioning Elements */
.group {
  background-image: url("pattern.png");
  border: 1px solid #000;
}

What HTML you would write:

<small>/* Sectioning Elements */</small>
<i>.group</i> {
  <b>background-image</b>: url(<span>"pattern.png"</span>);
  <b>border</b>: 1px <b>solid</b> #000;
}

The same sorta rules apply for CSS, <b> for keywords, aka properties; <i> for selectors; <span> for strings; and, of course, <small> for comments.

Javascript

Let’s look at something a little more complex for Javascript, including additions and deletions and important parts.

What you want to see:
(view source to see it in practice)

document.getElementById('foo').addEventListener('click', function(evt)
{
var myMessage = 'Hello World!';

alert(myMessage)
console.log(myMessage)
}, false)

What HTML you would write:

<b>document</b>.<i>getElementById</i>(<span>'foo'</span>).<i>addEventListener</i>(<span>'click'</span>, <b>function</b>(<var>evt</var>)
{
<b>var</b> <var>myMessage</var> = <span>'Hello World!'</span>;

<del><b>alert</b>(<var>myMessage</var>)</del>
<ins><mark><b>console</b>.<i>log</i>(<var>myMessage</var>)</mark></ins>
}, <b>false</b>)

A few notable additions are the use of <var> for wrapping around variables and arguments. The example uses <b> around Javascript keywords; for document and console, it may be more technically correct to wrap them in <var> elements, but I like to reserve <var> for variables and arguments I have created.

When marking up objects and their properties, I feel that it’s more appropriate to mark up the parent as a <b> or <var> and all the child properties/functions as <i> elements, as in document.getElementById().

Since the above code example is kinda like a tutorial, I decided to show that <del> and <ins> can be used to demonstrate code that should be deleted and code that should be inserted.

Using the <mark> element we can highlight as passage of code that is important to the current step in the tutorial.

PHP

What about going even further by integrating documentation with our code samples by linking to further resources.

What you want to see:
(view source to see it in practice)

<?php

$db = new PDO('mysql:dbname=mydb;host=localhost', 'root', '');
$db->exec('DELETE FROM mytable');

What HTML you would write:

<small>&lt;?php<small>

<var>$db</var> = <b>new</b> <a href="http://php.net/pdo"><b>PDO</b></a>(<span>'mysql:dbname=mydb;host=localhost'</span>, <span>'root'</span>, <span>''</span>);
<var>$db</var>-&gt;<a href="http://php.net/pdo.exec"><i>exec</i></a>(<span>'DELETE FROM mytable'</span>);

Since the above sample is teaching about PDO and exec(), why not link those functions to the PHP documentation, then readers can jump into deeper material at their discretion.

Terminal

I’m not going to cover using <samp> and <kbd> because the HTML spec has some great examples.

Defining the Language

There is a great question on Stack Overflow about what is the most semantically appropriate way to define the programming language for the code. I’m a fan of using @class, like so:

<pre><code class="language-html">…</code></pre>

Why Bother?

Well, I recognize many developers are lazy. And I recognize that the automated solutions have extra benefits such as copy-friendly versions and line numbers, etc. But code seems to be one of those places in online content and documentation where markup can be improved. It seems that web developers spend time choosing appropriate elements for general content, then just dump the code onto the page. True craftsmen would sweat all the details.

Am I over-the-top semantic crazy? Likely. But semantics and code are what we do, lets spend a little more time on our documentation samples.

A little history’ll do ya good

The Ottawa Dog Park Finder was originally created for the Ottawa Open Data movement to show to the city what is possible. Read more about the original process in the Open Data blog post.) But, it was also created to help Ottawa dog owners find the best parks in the city.

There was one feature that I felt was missing from Park Finder since it launched: a mobile version. When the City of Ottawa decided to host an application contest for Open Data apps I decided to enter Park Finder, but first make it mobile ready.

The open web platform

I’m a web developer at heart and don’t have much interest in doing native applications, so the only logical choice was to make a mobile web app. The concept of Mobile First is exactly the solution I wanted. The idea behind Mobile First, a concept envisioned by Luke Wroblewski, was to design for mobile—first—then design for other platforms. Forcing designers to determine what features are really important.

Though, we shouldn’t stop at design with Mobile First; when creating web sites and web applications, the same ideas can be applied to code. Why not default to mobile, then if conditions are right, expand to desktop versions. That’s exactly what I did when re-developing Park Finder in December.

The supported devices

My goal from the start was to make the app browser agnostic (the goal of any real web developer). So, using my mobile testing suite, I set out to make Park Finder work on all those devices.

The project was a success, I was able to support all the browsers listed in my mobile testing suite (forget BB OS 4, it sucks!) and all the major desktop browsers.

In the spirit of Mobile First, and mobile in general, I simplified the application on mobile to just the essentials:

• displaying the parks nearest you (geo-location, please);
• searching for a park;
• and rating parks.

The only major feature that was removed was park filtering.

The original application was a one page app, clicking on parks just displayed them on the Google Map. Since I needed to support mobiles without Google Maps, the app turned into a multi-page app (as it should have been from the beginning) and used Google Static Maps for the geo-location functionality.

Device classification

I segregated devices into a few classifications: basic, enhanced and enhanced wide. Basic includes all mobile phones and IE 6. Enhanced includes tablet size devices and screens with widths less than 1000 px. Enhanced wide includes all larger screens.

I had originally planned to put Google Maps onto the mobile phones that supported it (Android, iPhone, BB OS 6, Bada), but the usability just wasn’t as great as I had hoped, so Google Maps got relegated to enhanced and enhanced wide only devices (tablets and desktops).

Technical set up

The general idea was to send the basic version of the site to all browsers to minimize download time (and because I am not the biggest fan of browser sniffing). Then using Modernizr and a few other techniques, dynamically load the other resources as required.

The loading process

1. Basic

• HTML, basic.css, basic.js, Modernizr, Geo.js
• No Javascript frameworks for basic, too heavy.

2. Enhanced

• Only executed if the browser supports Google Maps
• Dynamically include enhanced.css and enhanced-wide.css (with @media min-width: 1000px)
• Dynamically include Google Maps
• Dynamically include enhanced.min.js, a bunch of Javascript files minified together to preserve loading order jQuery, Marker Manager, LatLng, enhanced.js)

3. Enhanced wide

• Enhanced wide does not have any feature differences than enhanced, it only looks different: parks are listed beside the map instead of below.

Some code bits

There were a couple other things I needed to detect to fully support my Mobile First idea.

Modernizr.xhr

A Modernizr test to check for XMLHttpRequest support. Used to distinguish between desktop IE 6 and Windows Mobile 6.5 IE 6.

Modernizr.addTest('xhr', function () {
  return !(typeof XMLHttpRequest == 'undefined');
});

Modernizr.mediaqueries

A Modernizr test to check for very basic media query support. As of Modernizr version 2, similar code is already included.

Modernizr.addTest('mediaqueries', function () {
  var ret = false
    , test = document.createElement('div')
    , styles = document.createElement('style')
    , styledef = document.createTextNode('#modernizr-mq-tester{top:-999em;position:absolute;display:none;} @media screen and (min-width:5px){#modernizr-mq-tester{display:block;}}')
    , head = document.getElementsByTagName['head'](0)
  ;

  test.id = 'modernizr-mq-tester';
  test.innerHTML = ' ';
  styles.id = 'modernizr-mq-styles';

  try {
    styles.appendChild(styledef);
    head.appendChild(styles);
    document.documentElement.appendChild(test);
    ret = getComputedStyle(test, null).getPropertyValue('display') == 'block';
    head.removeChild(styles);
    document.documentElement.removeChild(test);
  } catch (e) {}

  return ret;
});

Modernizr.googlemaps

Though not completely accurate, used to detect Google Map support on devices. The code below doesn’t detect mobile phones because it’s looking for a minimum width of 660 px; just change that to 320 px for phone support.

Modernizr.addTest('googlemaps', function () {
  var cw = document.documentElement.clientWidth
    , isIE7 = document.documentElement.className.indexOf('ie7') > -1
    , isIE8 = document.documentElement.className.indexOf('ie8') > -1
    , isIEMobile = document.documentElement.className.indexOf('ie7mobile') > -1
  ;

  if (cw < 600 || !Modernizr.xhr || isIEMobile) return false;

  if (
    (cw < 780 && Modernizr.touch && Modernizr.mediaqueries)
    || (cw >= 780 && (Modernizr.mediaqueries || isIE8 || isIE7))
  ) return true;

  return false;
});

The final app

I’m very happy with the final application, it turned out amazing. I’m super excited because I won bronze in my category in the Apps4Ottawa competition!

A couple niggles

I’m not the biggest fan of the flash that happens just before the enhanced wide layout displays. I think the solution is to detect enhanced wide using media queries inside basic.css and hide the whole application, then after enhanced-wide.css is loaded, fade the application back in.

Also, since the app is now a many-page application, when you load a specific park’s URL in a desktop browser it should immediately show it in Google Maps, but does not.

The future for Mobile First

This technique works great for many web sites. Where the most important information is sent as a basic package, then detect features client side, and, if required, dynamically load other assets. Think about a site with a heavy sidebar: don’t send the sidebar to mobile, but AJAX it in for desktop clients.

This mobile first idea, coupled with responsive design, is the way forward for many sites and is what I am exploring on all my future projects.

I started by downloading a bunch of emulators including Android, WebOS, BlackBerry and Windows Phone 7. But quickly found limitations to this approach.

The main limitation of the emulators is that they can’t be open at the same time as my virtual versions of IE. Another issue I quickly found was the lack of Nokia emulators and since Nokia is the most popular handset maker in the world, this is a major issue. I did find the Nokia Remote Device Access, but the idea of scheduling a time and waiting wasn’t something I was excited about.

And we all know that emulators are far from perfect, so actual devices are what I needed.

Researching the Phones

I have been reading a lot of articles, watching a lot videos and clicking through a lot of slideshows trying to wrap my head around the extremely complex and fractured mobile web market.

One article that was extremely helpful was ‘A Practical Guide to Nokia Browsers’ which is a great overview and explanation of the different Symbian browser versions and gives a smattering of Nokia phones that would be good for testing.

The rest of the mobile market isn’t as difficult to handle, assuming that you rule out a bunch of feature phones that people don’t likely surf the internet on anyways; but if they do, they are crazy.

I compiled a list of the browsers and operating systems that I wanted to support and from that determined what phones to get. It took a lot of comparing phone specifications and looking around online to find devices for sale (four days to be exact) to find the phones that would fit into my test suite.

I didn’t want to spend too much money, so I was always conscious of the prices. Continued cost was also very important and I didn’t want to have to support multiple mobile data plans. All of the phones I have in my test suite, therefore, are WiFi equipped.

List of Browsers, OSs, Phones

So, without further adieu, here is the final list of phones I have purchased and where I got them from and how much they cost:

Missing Browsers

You’ll Likely notice a few missing from the list. The first is the venerable mobile browser: Opera. I didn’t go looking specifically for Opera because it can be installed on nearly any phone. I also didn’t go looking for a Brew MP phone because Opera is the primary browser. Opera is already installed an a couple of the Nokia phones, I have it on my iPhone and I downloaded it to an Android phone.

I would like to support iPhone 4 with the double pixel ratio and am thinking of getting an iPod Touch to fill that gap. (Or maybe I’ll be bad just upgrade my iPhone.) Also, I’m unsure as to how much testing I should do on older versions of iOS.

Samsung Bada and Nokia Maemo/MeeGo only have one device each so there isn’t a huge market share. I’ll follow them and see where they go, but I’m not too worried since they are both Webkit-based and Gecko-based respectively.

Another Webkit-based browser, BlackBerry OS 6, definitely needs to be supported, but the devices are still new and expensive, so I thought I would wait a while. Similarly, Windows Phone 7 needs to be supported but is very new and very expensive: also a waiter.

I thought about supporting older browsers, but decided it was a waste of my time since nobody in their right mind would surf the web on them anyways. I’m aware of the mobile Internet’s popularity in developing counties, but don’t really know what types of phones are being used and whether they are feature phones, smart phones, or anything about them except the majority are Opera and Symbian.

Unlocking, Debranding, Flashing & Other Frustrations

I was lucky that all the phones I got in Canada worked over WiFi without a SIM card. Unfortunately the two phones I got from the United States did not.

The processes I describe below may seem simple, but it was my first time with all this stuff (and jargon) and it took me more than two frustrating hours, full of swearing, per phone, to get them functional.

Sony Ericsson Xperia X10

When I received the phone it was locked to AT&T and completely locked out. I couldn’t get in to turn on WiFi, it would only allow emergency phone calls. I first tried unlocking the phone but couldn’t get a code. I then looked around and found out about debranding, which yielded the results I wanted.

Debranding is the process of replacing the carrier’s custom firmware, AKA ‘flashing’, with the generic firmware supplied by the manufacturer. And it was the AT&T firmware restricting the phone’s use without a connection to AT&T’s network.

I basically had to download a debranding kit and replace the firmware on the phone with the supplied generic one to remove the restrictions. It was a little scary—and very hacky—but worked.

HTC myTouch (Magic)

The HTC myTouch came a day after the major Xperia X10 frustrations but presented a different set of problems. When turning the phone on I was asked to sign in to my Google Account to set up the phone. I couldn’t skip the account sign in, the phone had no data plan, and there was no way to get WiFi turned on so I couldn’t get past this screen.

After doing some researching I discovered that I should have access to WiFi and should be able to skip the Google Account sign in, but T-Mobile’s firmware was restricting the phone and forcing a mobile data connection over their network.

Since I was successful at debranding the Xperia X10, I thought I would start there. Unfortunately I couldn’t find a straight forward process like I did for the X10, so I went back to unlocking.

Unlocking is the process of allowing the phone to work on other networks. The myTouch was locked to T-Mobile, but I thought that if I unlocked it I could stick in my iPhone’s SIM and use it’s data connection to get past the Google Account screen.

After putting the $15 unlock code in and adding the APN network connection for Fido, I got past the account screen. After taking the SIM out, all’s good.

Next Steps

So, next I just need to figure out how to implement the mobile first approach on my web sites and how to support all the different platforms and screen sizes in a simple way. Off to the drawing board I go…

Helpful Resources

• Nokia Device Specifications
• Google Android Phones
• BlackBerry Product List
• jQuery Mobile Graded Browser Support
• QuirksMode Mobile
• QuirksMode Mobile Browsers
• John Resig: Testing Mobile Javascript
• A List Apart: Smartphone Browser Landscape

Updates

• Nov 30, 2010—Updated the total cost to include some customs fees and taxes.
• Dec 3, 2010—Added the section about unlocking and debranding. Added more customs fees to the total.
• Dec 15, 2010—Added some new links. Added the iPod Touch with iOS 3.
• Dec 20, 2010—Added Webkit versions.

Open Data is an important step for current governments and there has been a lot of discussion around the blog sphere. I won’t cover material that has already been documented elsewhere, but I do want to mention a local initiative, Open Data Ottawa.

The City of Ottawa is very close to declaring the itself ‘open’ and to encourage the city departments to start opening up the data the Open Data Ottawa Hackfest was arranged.

It is Saturday, April 24th, 2010 and tickets to the event are free, go reserve them.

A Few Open Data Ottawa Links

• Open Data Ottawa
• Open Data Ottawa Blog
• Open Data Ottawa App List
• Open Data Ottawa Registration
• Open Data Ottawa on Twitter

Ottawa Parks Data Set

For my contribution to the Open Data Ottawa Hackfest I am creating an application (more on that in a second) but first I needed a data set.

The city’s web site has a list of all the parks in Ottawa and their addresses. It also has a list of all the parks that allow/disallow dogs split over five pages.

For my application I wanted to use that information, but there was no easily available place to get that information except through the city’s HTML tables on their web site (hence the need for open data).

I set out to extract all the information into a format that could be easily used for my application. The whole process probably took me about ten hours to complete. Here is a very general run-down of what I had to do to get the data in a decent, workable state.

Ottawa Parks Data Set Process

Originally I had wanted to do an automated screen scrape of the data, but after looking through it I felt that it was way too inconsistent to allow for anything totally automated.

So, I resorted to a slightly less elegant and slightly more manual method:

1. I started with this list of dog parks: http://ottawa.ca/rec_culture/park_facility/parks/dogs/index_en.html).

2. I opened each of the HTML tables in its print view and saved them to my desktop.

3. I then opened those HTML files in Microsoft Excel, which parsed them into a fairly usable spreadsheet.

4. Some of the tables had the addresses in the neighbouring cell and some had it in the cell below. So, I corrected all the addresses and put them in the neighbouring cell.

5. I then had a list of some of the city parks, but not all. So I browsed, printed and saved the master list: http://ottawa.ca/rec_culture/park_facility/parks/locations/index_en.html (Thankfully the master list had the addresses in the proper orientation.)

6. I then merged the two lists together in my Excel sheet and removed duplicates.

7. Now, I needed to parse the dog related information into something machine readable. I did that sort of manually by reading the dog information and using a series of cells, I entered 1 or 0 for each of the parks.

   I also went through and augmented the information with the generalized info on the city’s web site like: ‘Rideau: Dogs on leash are permitted in parks’. In this case, I found all the Rideau parks and put that dogs were allowed, but required leashes.

8. At this point I had a huge list, but with a few major defects: almost everything was in ALL-CAPS (why would the city do that?) and I didn’t have any geo-location data for the parks, so they couldn’t be mapped easily.

9. To solve the ALL-CAPS, I copied the offending columns into the wonderful TextMate and ran the ‘Convert to Title Case’ action on them (its not perfect, but much better than ALL-CAPS). And then pasted them back into my spreadsheet.

10. Now for geo-location. I did some googling and found this batch geo-coding service, http://www.batchgeo.com/, that coincidentally allows you to past a spreadsheet of addresses and it will geo-code them all for you. Sweet!

11. An Excel spreadsheet is all jim-dandy but not very good for development purposes, so now I had to get my data out of Excel and into something I could use.

    I originally decided I wanted it in a SQLite database, so I exported from Excel to CSV, which I could then import to SQLite. That may have sounded easy, but was far from it. Excel’s CSV output is far from optimal, so it took a bunch of validating and re-importing until the data was ready to go.

12. I am now about six—seven hours in and feeling pretty excited, so I packaged it up into a little repo with a couple Python scripts for extracting the SQLite data into other formats (CSV, XML and JSON) and released the data set into GitHub, tweeted it and went to bed.

13. The next morning I got an e-mail that my data was being used in an Open Data Ottawa app (great!) but at the same time there was an issue opened on GitHub with my data. Apparently a whack load of the latitudes/longitudes all pointed to the same location (what I realized later was city hall).

    So off I go again trying to determine what was up. It turned out that the offending parks had addresses specified with intersections (and often many intersections). So I had to go through all those parks and correct their addresses and re—geo-code all those parks.

14. Upload to GitHub. Done. (Well done isn’t really final because I found an issue tonight with random extra quotes, but anyways.)

So that, in a (very large) nut shell, is my adventure in producing the Ottawa Parks data set, now onto what I am going to use if for.

Ottawa Dog Park Finder

The application idea was actually my wife’s from a couple years ago, you can actually still see the original announcement blog post. We didn’t get very far on it because adding parks in was really time consuming and there weren’t any automated geo-location services at the time, it was all pretty manual.

So, I am restarting this application, but adding in a few new features.

The app is basically going to allow you to find parks in the city and whether they allow dogs on or off leash and other dog related information. It will be integrated with Google Maps and will allow you to enter locations and find parks closest to a specific location. And the app will hopefully allow users to vote on various aspects of the parks.

Wish me luck, because I only have a few days left.

There are a few recent rumblings on the web that are starting to indicate that view source is on it’s way to extinction due to changes in the web including minification and the need for sp(ee)d. We as web developers can’t let that happen!

View Source and Web History

View source has an extremely important history in web development. It has helped the proliferation of HTML through openness and simplicity. I dare to say that we may not be where we are without view source.

In my development, I rely on view source. It is one of the three things I need to do my job, the other two are a text editor and a browser. There isn’t an easier way to learn new things, debug your code or see if your dynamically generated code is written out properly than View Source.

As Alex Russell mentioned on an excellently written, recent blog post,

The only required equipment is a text editor and a web browser, tools that are free and work together instantly. That is to say, there’s no waiting between when you save the file to disk and when you can view the results. It’s just a ctrl-r away. Alex Russell

If you haven’t read Alex’s post yet, you should, it’s a great read.

The web is not about compilers, it is about changing some text in a plain text file and opening it in a browser. The web encourages openness in learning because it is simply text.

The Open Web

The web is about being open. The standards the web is based upon aren’t public domain just because—they are public domain because it’s important that the web is available to everybody, equally. Net Neutrality and View Source are fighting similar battles, the battle to keep the web open.

How many times have you as a web developer used view source? At least once a day? View source is invaluable.

One of the things I constantly remind my web students is that view source is your friend. If you find a web site that does something you like, view source and then you can do it too.

In how many other professions can learning be done so openly and non-destructively. If you want to see how an electronic device is made you have to disassemble it. Imagine if you could view source on the internal mechanical workings your mobile phone.

Some people say that we don’t need view source any more because there are plenty of books and tutorials. I completely disagree. Books and tutorials are outdated, view source is real-time. (Isn’t that the way the web is going anyways?)

Web Standards & Browser Compatibility

Another major argument is, “if the web was compiled it would be less error prone and standards would be more easily followed.” I suppose that would be true. If the web was a compiled language we would get instant deal-breaking errors on any minor issue. Would that make the web easier to develop for? Yes. Would that make the web easier for non-technical users? No. Would that make the web less challenging and fun? Yes.

Even though all web developers complain about browser incompatibility, at the heart of it, isn’t that what draws us to the web. This idea of a vast, challenging wild-west frontier of platforms that we can target instantly with one text file. Being a web developer is about tackling the challenge of getting our few lines of text to work in as many browsers as possible.

Yes, browsers are incompatible and yes, they are inconsistent, but it is that challenge that should draw you to the profession. If you are not up to the browser inconsistency challenge then you have chosen the wrong profession.

Minification and Obfuscation

Minification and obfuscation seem to be the two major reasons why view source is facing extinction. Minification is important to the web—we all love fast internet. Minification also doesn’t change your code other than compacting it down. With tools like Firebug and the Web Inspector the minification is undone. (Now if only view source would do that by itself.)

Obfuscation, on the other hand, is something I completely disagree with. The web is open! If your company feels they need to obfuscate their code on the web to hide how they did something, then they need to reconsider actually putting the content/application on the web. By hiding your code you are insulting the web.

View Source as a Web Service

Since minification is important for internet speed, maybe there should be some web service like standard where users/developers could request un-minified code for a resource.

Gaging Web Developers’ Chops

Another reason I love view source is it’s an instant way for me to gage another web developer’s skills. If I find a web site that I like the first thing I do is view the source. The source of your web site says a lot about you as a developer. (Also I love to laugh at new sites that have table based layouts.)

To view another developer’s source is intimate and shows that you as the viewer care. If the developer also cares, it will be instantly recognisable in their source.

Save View Source

View source needs to be saved! Go to saveviewsource.org to pledge your commitment to the Save View Source movement. View source needs you!

Through my researching travels on the internet I quickly noticed that all the reviews other people wrote were old, usually a couple years old. The reviews also had one common theme through them all:

• Git is more complicated to use/learn and has more features;
• and Mercurial is simpler to use/learn and has less features.

But after much more researching and digging into the systems I realized this isn’t so much the case.

Feature Comparison

I am not going to do a feature comparison here because there isn’t any reason to. Mercurial and Git have the same features. All the features are built in to Git, whereas Mercurial just requires extensions (often built in, but disabled by default).

My favourite comparative review is: Git is MacGyver and Mercurial is James Bond.

The Git Index

People either love it or hate and it is one of the major points of contention. People choose Git because of it. People choose Mercurial because it doesn’t have it. And that reason is enough for many people.

But the truth is Mercurial does have an extension that adds a very similar idea: Mercurial Queues. Though the implementation is different, the same idea is there.

I didn’t even know if this was a reason I would choose Git or not. Yes, I could see the benefit of being able to commit just a few files at a time but also I could see it being a little annoying having to constantly specify the files I wanted to commit.

Local Branches

Another major difference between the two was Git’s local branches. In Git branches are only local (by default). In Mercurial branches aren’t local—of course there is an extension for local branches in Mercurial.

This wasn’t a major issue for me because I would be using the DVCS primarily for my own client projects, on my own development server. So it didn’t really matter whether the branches are local or not.

Built in Python

I have been having a bit of a PHP crisis lately. I am outgrowing PHP and Python is looking pretty awesome. It is kinda weird, but I feel like Python is a perfect fit for the way I work, though I only know a little yet. So the fact that Mercurial is built in Python and can be imported and used natively in Python apps was a really compelling feature.

Command Line Fu

Git is seen as requiring a lot of command line fu and Mercurial is always proud of its simple, intuitive command line interface. Though Git has gotten better/simpler in the more recent versions, there apparently are a few nagging, weird things. Since I am not super amazing at the command line yet (but trying hard), I could see this as a plus for Mercurial. One review I read mentioned that Git is like Linux (wow, that’s a creative comparison): requires a lot of configuration and Mercurial is like Mac: slick and simple to use, with hidden power.

The Popular Kid in Town

Git is the popular kid in town right now. And people love it! Since Git’s popularity is so great, finding help for it should be easy because so many people are talking about/using it. I have always hated the popular kid and that makes me respect Mercurial a little more as the underdog.

GitHub

GitHub is awesome! And the guys behind it really care. GitHub is a major plus for Git. Yes, BitBucket exists, but lacks many of the social aspects that make GitHub what it is. Then I found Hg-Git, a Mercurial plugin to allow Mercurial direct integration with Git (and GitHub)—made by the guys at GitHub. Hg-Git makes me respect the service GitHub offers even more. (Will you marry me GitHub? I love you.)

The GitHub Community

Git has a massive community and recently I read a couple tweets that may, or may not have, influenced my decision.

Positive:

“I’m loving the influx of new contributors to jQuery core since moving to Github.” — @jereisig

And negative:

“Is github now a Single Point of Failure for the whole OSS ecosystem? I love it, but worry a bit.” — @timbray

So, What Did I Choose?

Well, it was a stressful decision and took me about two weeks after all my research to actually make the decision.

And my decision was… Mercurial.

I chose Mercurial for a couple reasons, I think. First I decided that since my command line abilities aren’t as strong as I would like, Mercurial seemed like the simpler choice. I also thought Git may be too complicated and have too many features for my first foray into the command line version control eco-system (previously, with SVN, I used a GUI). Since Mercurial has all the same features, I liked the idea that they were hidden until I was comfortable with the basic features and could unlock them as I needed them. A few other things that influenced my decision were Hg-Git, my support of underdogs and the whole Python thing.

After using if for almost a week I am, so far, happy with my decision. But I admit I have already run into a situation where Git Index would have been very useful.

Updates

Two years after this post, I now switch back and forth between Git and Mercurial. I use both GitHub and BitBucket (BitBucket now supports Git). I’ve even got more proficient with the command line, but I still find Mercurial more user friendly.

I think this site sums the discussion up nicely.

Signature Pad is the first official project posted to my lab section (and there are two more projects in the queue). Getting something posted on labs has been a long time coming, but it’s finally here.

A Little History

Signature Pad started out using Flash and ExternalInterface instead of HTML5 Canvas. It worked, but wasn’t easily configured and—of course—relied on Flash. The signature bits were a little slow on my Mac and saving out the signature as an image wasn’t as reliable as I hoped.

I wanted to make something faster, simpler and more reliable and preferably standards based. So I set out to duplicate the functionality in Javascript/Canvas.

I was surprised at how quickly it came together in canvas, but not without a few IE related hick-ups. After making the first prototype I decided that it would be a great jQuery plugin.

Making a jQuery Plugin

Making a jQuery plugin was a rewarding experience and I found it to be fairly simple. It really helped me understand a few things about Javascript that I had never used before.

Here are a couple resources that helped:

• jQuery Plugin Authoring Docs
• Learning jQuery: A Plugin Development Pattern
• Snook: Developing a jQuery Plugin

I also found it really helpful to look at other jQuery plugins and see how they did things.

The Major Hick-ups

There were a few major hick-ups, related to IE, while developing the plugin.

The first plagued IE7 and IE8 and was related to initially drawing the grey signature line on the canvas. I had it working for a while and then it stopped and I had a long drawn battle to figure out why.

Through my debugging I discovered that only on the first call to the drawSigLine() method, the line wasn’t drawn, but every subsequent time it worked.

I don’t fully remember how I came to the solution, but the solution was just to not draw the line immediately on page load. Instead I created a timeout of 50 milliseconds that would then draw the line when it fired. Problem solved.

The second major issue plagued IE8 only and was related to Explorer Canvas. In IE8 strict mode, I couldn’t draw on the canvas. By couldn’t draw, I mean I could draw, it just wouldn’t display.

Through some online digging I found that excanvas sets overflow: hidden on the VML div that it creates. This prompted me to add a wonderful hack to my code that checks for the div with overflow: hidden and set it’s overflow to visible.

Documentation and Examples

The lab section has complete examples, documentation and tutorials on the Signature Pad.

• Documentation & Tutorials
• Demo of Accepting a Signature
• Demo of Regenerating a Signature

The human mind is powerful at remembering things and one of the ways it helps us remember is through association. Sometimes that association is conscious, like rhyming or song, but many times it is subconscious. One of the strongest associations in my mind is between colours and numbers.

Interchangeable Colours & Numbers

Numbers are colours. When I see numbers in my head I always picture them in a specific colour. If I remove the English symbol of a number and leave just the colour I see the same thing. This subconscious memory trick is especially helpful for remembering a long series of numbers like a phone number or bank account. In my mind’s eye, I see a series of colours and from that the numbers are assigned.

What Does it Look Like?

I am sure you are all interested in what the colours are, so have a gander.

• 0
• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9

This is in no way a perfect representation of the colours. It is really difficult to describe the colours in physical form. When I start to think about what the colours are, I almost have troubles seeing the colours.

The only number that isn’t easily described in a static graphic is zero. Zero is actually transparent, like glass. This, I am sure, has some association to the fact that zero represents nothing, therefore my colour is nothing. I should also mention that one is pure white.

Also, like my Year Loop, the numbers in my mind are always in a vast black void.

So, How Does it Work?

Well, it only works in my mind when I think about numbers. If I am looking at numbers on a page, I see them in the colour presented, but when I think about them, they are presented in their associated colour. If the writing on the page is black and it contains an eight, in my mind I will see the black writing with a brown eight in the middle.

It happens so fast, but it seems as though the numbers are stored in my brain as a colour, when I want to remember numbers, I recall a series of colours and my brain instantly translates those into numbers.

The Strongest Association: Time

Though all numbers are colour associated in my mind, time is somehow associated more strongly. I don’t really know how to explain it, maybe the time colours are brighter, as if they are generating their own light, where other numbers are just reflecting the ambient light. Either way, time is especially strongly linked to colour.

• 2
• :
• 5
• 8

When thinking about a time in my mind the colour association is so strong it almost hides the English numeric symbol. But not in a way that blurs the numbers, more that the colours are so bright (like looking into the sun) that you can’t see the shape, just the colour.

When I look at a representation of time, on a clock for instance, unlike the other numbers, the time digits are kind of more visible as their mentally associated colour. I am aware of the colour the time is being presented in, but at the same time aware of the colour association.

What Does it Say About Me?

Do I associate to colours because I have an inclination towards design? Or is it just a simpler, smaller representation to be stored in my brain? Instead of storing the complex lines and shapes of a number, my brain simply stores a colour.

It would be great is someone could explain this working of my mind to me, but until that point I am just going to write it off as another quirk complexity of the human mind.

Related Posts

• Mental Visualizations: The Year Loop

Updates

National Geographic recently published an article titled Why Does Evolution Allow Some People to Taste Words? that mentions synesthesia. Synesthesia sounds very similar to the colour association I’ve described above.

The year is represented as a two-dimensional loop that rotates and scales in three-dimensions with a black void as the backdrop. The months start with January at the top left then proceeds counter-clockwise ending with July at the bottom left. August then connects to July on the bottom right and it’s a straight shot to December, which connects back to January. Have a look at the graphic on the right to get an understanding of how the system is designed.

Three Dimensions of Calendar

The graphic presented on the right is a static version of the what the calendar year would look, if it was zoomed-out. In my mind though, it is never presented zoomed out. It moves around and repositions itself depending on the context—and context is very important. As an example, lets say I am at the tail end of December and am looking forward in time to January. The year loop would go into a perspective mode that presents January top centre and December below. As time passes in January the calendar flies around the January curve towards February. And now I can see February and the next few months ahead of me.

Pictures Are Worth a Thousand Words

Especially when describing something that only I can only—and ever will—see. So I have created a very basic mock-up of the year loop in a three-dimensional Flash movie.

The representation is very basic and only really presents one context: looking ahead in month view. The year loop in my mind is much more dynamic and flexible. Instead of feeling like a solid plastic mass (like in Flash) it is more of a flexible fabric object. The months bend, stretch and adjust based on time and view. Also, in my mental visualization all the days of each month are represented on the loop, not just the weeks.

Context is Important

As I mentioned earlier, the year loop is very context based. In the Flash example we can see only the months. But if I wanted to look at the last week of February the year loop would spin around and put February into a view similar to a standard wall calendar. The view would still have quite a bit of perspective and I can see March starting at the bottom and January fading away at the top. This view also lets me zoom in to specific weeks and days.

Another aspect of the context is when I am looking forward from December. The January that I see is next year. Similarly, when I look back from January I see the previous year’s December.

The Passage of Time

My mental understanding of the passage time is also represented in my year loop. You can see that February to July are actually shorter months compared to the autumn months. This is from my internal clock that always feels those months speed by faster than the fall months.

Calendar Directionality and Holidays

Another interesting aspect is the directionality of the calendar. From January to July, I have the passed months behind me, as though I am looking forward to something. The summer possibly? But when I hit August the calendar turns and I start looking backwards, trying to hide the future behind my field of view. It’s my belief that my mental calendar faces towards the closest holiday or time-off period: in January I am facing the summer, in August I am looking back on the summer and trying to avoid September. Then in October, the calendar starts to turn again, this time looking forward to the winter holidays and the new year.

Interesting Limitations

One interesting quirk is that months always end on the far right of their box, regardless of whether they end on a Saturday or not. And similarly months always start on the far left of their box, whether they start on a Sunday or not. My mental model does not generally recognize mid-week month starts/ends. Instead, when I need to understand, the graphic is replaced by a picture of a calendar, usually the one hanging on my wall showing the mid-week month switch. (This year it is my Chuck Norris Facts calendar.) This somehow is related to my constant forgetfulness of months starting in mid-week.

What Does it All Mean, (Basil)?

Well, I can’t really say. I am sure it says something about my personality, abilities and learned behaviours from a psychological perspective—but what, I don’t know. When talking to Liz about this post, she reminded me of her mental visualization of the calendar year. It is similar than mine, but also different. Her’s travels clockwise and is more circular from January to August. Then in September it is a straight line up to December where it reconnects with January.

It is interesting to me to think about how my mind thinks about things and equally as interesting to see how other people think about things. Or even if they think about how they think about things. Also, it would be interesting to see the similarities and differences between everybody’s mental visualizations. Meta thinking, think about it. (Don’t you love that cheesy final sentence!)

Tomorrow, this post will be followed up with another post in the series: Colour Association.

Rich text editors are taking over the web—they are in every application, every CMS, every blog engine and every web site. There are many different rich text editors that you can download and use in your web application. They are all excellently crafted and coded but have one major flaw: they are mimicking Microsoft Word.

Why are all the editors trying to be Microsoft Word? We have all seen the Microsoft Word toolbar madness. But have you noticed the dutiful duplication in online editors. It is time we remind everyone, the web is not Microsoft Word.

What’s Wrong With Rich Text Editors?

Well, nothing, if they are used in the right situation. And that situation is when emulating Microsoft Word is the goal, Google Docs, as an example. When editing content in Google Docs, the goal is not to create valid HTML mark up that means something but rather the goal is to create a document that looks a specific way and contains specific content.

Too Much Concentration on Look and Not Semantics

When editing web content there are many variables that need to be taken into account, including: the limited tag set, search engine optimization, code simplification and of course the idea that we aren’t creating a look we are creating a meaning.

Most of the tools in current rich text editors prompt the user to create a specific look for their content with buttons like bold, italic, underline, strikethrough, alignment, font, colour, background colour, etc. But the look should not be controlled by the content editor. The look is controlled by the web site’s theme and the designer who created the theme. How many designers want content editors to change the colour, font or alignment of text? Oh, and why does underline even exist? Isn’t that only for links?

Too Many Features and Over Generalization

Maybe this is just another Windows (generalized) vs. Unix (specialized) idea but most rich text editors offer too many options and are completely over generalized. All those options dilute what the actual goal is: to create and edit text based content. Not to insert shapes or tables or videos. It even seems like many rich text editors are trying to provide a substitute for Dreamweaver or FrontPage.

Poor or No Education

Many rich text editors try to dumb down the web and allow users to bring their (poor) education of using Microsoft Word to the web. I firmly believe in educating users. Many users don’t understand how and why the web works and by using these rich text editors we are just perpetuating their lack of education. That needs to be changed and it only requires a little bit of education.

My Proposal: A Semantic Text Editor

Instead of using rich text editors in places where they don’t belong we should start using semantic editors with the intent to educate users into thinking about making text that means something and delegate all the look related stuff to the designers.

A semantic text editor would have the same look and be used the same way but the toolbar buttons would be completely different. The toolbar buttons would directly represent HTML tags and not abstract the tags away to fit the Microsoft Word ideology. Users need to learn that they are creating meaning in their text not making it look a certain way.

Proposed Toolbar Buttons

• <a> Create a link. Allow the user to add a URL and an optional title. (Lets not try to abstract away what a link is with globes and chain icons)
• <em> Emphasize the text.
• <strong> Strongly emphasize the text.
• <small> Mark the text as fine print.
• <abbr> Mark the text as an abbreviation and add a definition.
• <sub> Make the text subscript.
• <sup> Make the text superscript.
• <i> Mark the text as being in an alternate voice (e.g. a thought, a technical term, a phrase in another language, etc).
• <b> Mark the text as a keyword.
• <mark> Highlight the text for reference purposes.
• <ins> Mark the text as being newly inserted.
• <del> Mark the text as being deleted.
• <cite> Mark the text as being the title of a work (e.g. a book, a poem, a song, a film, a TV show, a game, etc).
• <time> Mark the text as being a time and get the user to add a date-time.

Each of the above toolbar buttons directly correspond to an HTML element. Paragraphs would be created from breaks in the text.

A couple other buttons could be included for <code> (computer code), <var> (a variable, either computer or math), <samp> (sample output from a computer program) and <kbd> (sample input for a computer program). But those would be for specialized applications, not for the general public.

You may have noticed that none of the buttons are recognizable from their Word counterparts. No more bold, or italic and definitely no more colour changing. Instead the goal is to teach users that they need to think about the meaning of the text, not the visual representation of the text.

Remove the Extra Cruft

The semantic text editor would have one specialized task: editing body content. We should remove all the extra stuff: no more tables, no more graphics, no more videos—these tasks should be relegated to other specialized tools. We need a specialized tool that looks after generating tables. A specialized tool that looks after inserting videos. Even make a specialized tool that creates lists (we could then allow sorting and other modern thingies).

What About Headings and Block Quotes?

Specialization. Headings could easily be integrated into the semantic text editor, but instead think of the semantic text editor as a single piece in a greater content building system (a body builder?). There could be specialized tools for headings, text content (semantic text editor), block quotes, tables, images and other page elements. The tools could be added to the body builder and rearranged more easily than Word would ever allow. Since the tools are specialized they would show only the options needed.

Instead of the users thinking of how the content looks in this kind of system, they should be more concerned about ordering and marking up their content properly—the look is taken care of by the designer.

HTML5 Definitions

One caveat, of course, is that the semantic text editor relies on elements and the definitions of the elements as specified in HTML5.

WYSIWYM

First, let me define WYSIWYM. It very simply means: what you see is what you mean. I can’t say I was clever enough to come up with this myself. There is already a project that is thinking along the same lines that I am, WYMEditor, the only problem is they didn’t take the idea far enough.

The project still maintains visual icons taken from Microsoft Word—not meaning based icons. (What does a globe with the chain do?) And some of the demos show that other semantic elements can be added, but then users are exposed to the code.

The perfect solution would allow addition of all the semantic elements and completely hide the HTML code from the users.

Let’s push ourselves to abandon the current rich text editors and start implementing semantic text editors. We should be training our users for the web not adapting the web to our users.