I’ve mentioned from time to time how keeping a blog has shaped not just my ability to write, but also to be a critical thinker. It has raised my awareness of the value of speaking clearly and eloguently.

That point was driven home again today while I was looking into the [geeky protocol I’m playing with] and the [geeky problem] I was having. As a result, I found myself browsing through the Mozilla bug database.

Now, the Mozilla bug database is an interesting beast. It is the focal point for discussion of issues related to any of the numerous Mozilla products and technologies and to date over 400,000 bugs have been filed. Nearly all of these are about fairly mundane and, well, boring topics. But once in a while one of these bugs will sing – become more of a cricket, as it were – and draw insightful commentary that broadens in scope and takes on larger, more meaningful issues.

Which is how I found myself scanning through the comments of bug #307813. In brief, the bug started as a complaint about having to type ‘<svg xmlns="hhtp://">‘ instead of the simpler and more convenient ‘<svg>‘ in a particular file format. And that’s as technical as I’m going to get. Like I said, boring and mundane.

But the dialogue (in the comments section) is interesting – it quickly evolves from the trivial issue to the broader question of policy, and the philosophical beliefs about what users need or want. (e.g. “Trying to teach pigs to sing just annoys ’em.”) And so I found myself not just scanning, but really reading comment #14. There was something about the writing style and the mind behind it that caught my attention. It seemed particularly articulate and insightful. It has interesting references to other writings. It was compelling.

Only after I’d read it, and had that, “Wow, nicely said!”, reaction did I look at who the author was. I guess it’s no coincidence that it turned out to be Brendan Eich, the creator of JavaScript, the programming language that’s been the focus of my career for the last 8 years, and CTO for arguably the most influential OpenSource organization in the industry. You don’t influence people and industry without being articulate.

(And in true Mozilla fashion, the bug is still “NEW” more than two years after it was filed. Ah well, eloquence doesn’t solve everything.)

[Photo by George1652]

Documenting JavaScript – jGrouseDoc

Over the years, I’ve spent a lot of time searching for (and even creating) tools that do automatic documentation of JavaScript. As anyone familiar with this issue can attest to, it’s not an easy problem to solve, and the tools available seem to yield mediocre results at best.

There is, however, a new entry into the field that I’ve been using for month or so now, and that I find myself pleasantly surprised by. The tool is jGrouseDoc (jGD), by Denis Riabtchik. Unlike it’s predecessors, jGD starts with the premise that attempting to parse JavaScript source code is a futile endeavor. The language is not designed to express the high-level concepts and patterns that engineers strive to emulate (and document) in their design.

Instead, the tool looks exlcusively at the information in the comments you author, and provides a rich set of tags for you to annotate your comments with information about the logical structure. This requires a bit more typing, but frees the author and the tool from the shackles of having to figure out how to bolt documentation into the source in awkward ways.

For anyone familiar with JavaDoc, you’ll find the syntax easy to pick up. Here’s what it looks like ..

 * Similar to Prototype's Template object, except the template is a DOM
 * element instead of a string.
 * @class DomTemplate

/** Hash of template id to DomTemplate objects
 * @variable {static Object} _byId

 * Get a dom template by name.  The returned template is cached, so
 * subsequent calls (for the same template) are efficient.
 * @function {static DomTemplate} getTemplate
 * @param {String} id element id

 * Get a DOM element to use for doing DOM manipulations
 * @function {private Element} _getHelper

 * Use DomTemplate.getTemplate()
 * @constructor {private} initialize

 * Similar to evaluate(), except returns a DOM element. Note that for bulk
 * operations, it's more efficient to use evaluate() to create the HTML
 * string and then apply that using innerHTML.
 * @function {Element} evaluateElement
 * @param {Object} data key-value pairs for token replacement

Using a router as a switch/hub

The ability to use a router as a hub is probably common knowledge in some circles, but Google yielded surprisingly little useful information on the topic. So here’s my weekly contribution to the geek knowledge base…

Your average home computer user will eventually find themselves using a router to take better advantage of their broadband connection. These little black boxes add tremendous value compared to their measly -0 price tag. On of the key features is switching – i.e. the ability to support multiple computers on the same connection. Most of these boxes have 4 ports to plug stuff into, which often leads to a problem: What do you do once you’ve plugged in your PVR, desktop computer, network printer, and docking station for the laptop?

There are a couple obvious solutions – you can buy another router with more ports, or you can buy a dedicated switch. But such devices can be a bit pricey, and if you’re like me, you already have an extra router sitting around. So, why not use that and avoid the guilt-trip involved in chucking a perfectly good networking box in the landfill! Here’s how…

The First Router

One of the nice things about this approach is that you get to leave your existing router alone. It’s probably configured more or less as follows, which’ll work fine for what we want:

WAN IP: dynamically assigned
WAN Subnet Mask:
DHCP: Enabled

The 2nd Router

Adding the 2nd router to the network is where things can get confusing. The most common mistake is to set up the 2nd router just like the first, and plug it into one of the LAN ports of the first router. If this works at all (and often it will to a degree) the results are less than desireable. What you’ve actually done here is create a 2nd sub-network, rather than extending the first. Devices on the 2nd network may have access to the internet, but they’ll be walled off from the first network. You’ll be able to browse the web on that new computer you just plugged in, but you won’t be able to share a printer with your first computer, or share files. This is inconvenient and unnecessary.

Instead, the better solution is to dumb down your 2nd router to just it’s essential switch capabilities.

Start by connecting the 2nd router’s “Uplink” port to one of the LAN ports on the first router. (The location of the uplink port varies by manufacturer, and may place restrictions on whether or not you can use the port next to it, so be sure to refer to the manual.) With that done, configure the 2nd router as follows:

WAN Settings (IP, Subnet Mask, DNS Servers, etc.): n/a
LAN IP: Statically assign to an IP on your first router’s LAN. E.g. if your first router’s LAN is 192.168.1.*, give the 2nd router an IP of (making sure you use an address outside the range reserved for DHCP clients on the first router).
DHCP: Disabled

The most important thing here is to disable DHCP – having more than one DHCP server on a network is just never a good thing. Similarly, if both routers are wi-fi enabled, you’ll should disable the wi-fi feature on the second router to keep the two wireless networks from interferring.

Assigning a static LAN IP let’s you access the 2nd router if you need to administer it (not that there’s much left to administer). It also means that if it has print server support, you can access the printer connected to it.

Finally, all the WAN Settings are moot here since there shouldn’t be anything plugged into the WAN port.

That’s pretty much it. Good luck, and if this was useful, feel free to drop a comment.

7/27/07 update: While the above setup worked fine for me, I ran out of ports again. My long(ish) term solution is to install a 16-port switch from SMC. At ~$40 it’s easy on the pocket book, and this particular box is also compact and, more importantly, fanless, so it doesn’t add to the noise in the office – an important consideration since it’s installed about two feet from where I work. It’s only minor drawback is that it’s not a gigabit switch – it won’t maximize the throughput of newer computers with gigabit network cards. But this has little practical impact for me, and shaves ~$150 off the cost.

Oh… and my old hub? I’ll be donating that to a friend of mine who’s signing up for cable broadband.

8/20/07 update: Minor edits to reflect the fact that most of these devices are switches not hubs, as pointed out by Harry, below. (See Hubs, Switches, Routers – A Hands On How To for more info). I also removed the suggestion that the 2nd router might be usable as a wireless relay point. This just isn’t in the scope of this article, and in all likelihood isn’t possible with most routers.)

The Software Paperweight

There, I did it. I’ve set my away message on AIM to, “On Skype (as Broofa)”, and am quietly tucking it into a dusty corner of my desktop. Possibly, hopefully, never to be used again.

Okay, okay, I’m not quite that serious about it. Heck, this’ll probably only last ’til my next reboot, but still. It says something about how marginalized this once must-have service has become. There’s an entire column waiting to be written about why I find myself deprecating the service that most of my buddies are on. But the short explanation is four IM services is three more than one person should have to have running. Skype has been my de-facto IM service, so AIM is getting a gentle heave-ho.

I’d quit out of it altogether, but this away message is important – I need to tell people that I’m not gone, just over on a different service. So I find myself having to keep it running for no purpose other than maintaining my online presence as “On Skype…”. Kind of sad, actually. Especially since it’s a bit of a memory pig (see screenshot) compared to Skype, which is easier to use, has a better UI, and offers more functionality.

In effect, AIM has become a 20-30MB paperweight on my desktop. Oh, how the mighty have fallen.

P.S. Since I probably won’t get around to writing that column about why I’m not using AIM, the least I can do is include the screenshot I’d use. This is AIM circa 1999. Look familiar? It should, because for day-to-day use it’s pretty much exactly what you get in the latest version of AIM. Sad.