Chad Perrin: SOB

No, the title of this is not two thirds of a joke about Steve Ballmer's "Developers Developers Developers" dance. I'm talking about documentation for documentation.

The Set-Up

There are at least two types of open source development projects in the world.

1. There's the fakey-type open source development project, where someone writes code in a closed team (perhaps a team of one) and makes that code available to the world under an open source license, but there isn't really any way for anyone to actually contribute to the project.

2. There's the for-realsies type of open source development project, where anyone can contribute — though contributions may of course be rejected if they aren't "good" (by whatever definition the core team uses to use).

The Documentation

It's a pretty generally accepted truism that documentation is important. People argue about whether their pet projects have good documentation, what constitutes good documentation, and so on, but they tend to agree that documentation is important.

A key part of most open source development projects is openness about accepting contributions to documentation. Accepting documentation contributions can help improve documentation without taking time away from actual coding by the core team. This is a good thing.

The Problem

It is often the case that there is a very clear-cut, easy way to contribute code to a project, but someone who wants to contribute documentation is left wondering "What the hell?"

The Solution

If you run a Type 2 ("for-realsies") open source development project, stop right now and look at the documentation your project has for documentation. How well documented is the procedure for contributing improvements to documentation? How easy is it to find?

Seriously, this should be one of your top priorities when running an open source project that actually wants contributions from the user base. If you have a core development team, it is actually more important, most of the time, to encourage documentation contributions from the general public than code contributions. The only time code contributions should take precedence is when you no longer have anybody (competent) on the core team.

If you don't have clear, useful, fairly complete documentation documentation (that is, documentation for the process and standards of creating and contributing acceptable documentation improvements), start working on it now. Please.

Please?

I thought I had already posted something about this to SOB, but I just realized that I had only talked about it on a mailing list.

Basically . . . one of the things I dislike about XTerm is the way it handles multi-click text highlighting by default. Another is the fact that it doesn't do Unicode by default. Of course, XTerm does everything, one way or another — or so it seems. It just takes working around the defaults somehow.

To solve the Unicode problem, just set the "UXTerm" X resource, which includes applying the effects of XTerm's -class and -u8 options. On at least most systems, entering the command uxterm (instead of xerm) should do the trick there. It seems that someone somewhere along the way came up with the brilliant idea of providing a standard UXTerm resource-active wrapper for XTerm.

To solve the multi-click highlighting problem, your XTerm app-defaults file (on FreeBSD, that'd be /usr/local/lib/X11/app-defaults/XTerm) can be edited to include some lines to specify exactly what characters are considered valid highlighting characters for a given number of clicks. Anything up to five clicks can be defined this way.

There are specific terms with specific meanings that can be used here, and the default for two clicks is XTerm's concept of a "word" — which is fine by me. The defaults for three through five clicks, however, don't work so well for me. In fact, by default, three clicks will match a "line", and both four and five clicks have no default at all. Other than "word" and "line", though, none of the options (which are listed in the XTerm manpage under the on5Clicks resource) match any of the things I'd really like to see highlighted on a given number of clicks. Luckily, the XTerm app-defaults file also supports a (limited) regex syntax for the onNClicks resources, where N is the number of clicks.

Keeping the on2Clicks default, the configuration I use to customize multi-click highlighting is:

xterm*on3Clicks:  regex [^ \n]+
xterm*on4Clicks:  regex .*
xterm*on5Clicks:  line

So. That's the long and the short of it. Other than that, all I use that isn't an XTerm default on my FreeBSD systems is a pair of options — specifically, the -r and -sb options (for "reverse video" and "scroll bar", respectively).

I've been running a PRPG campaign via IM chats once a week, using Paizo's Legacy of Fire Adventure Path. We haven't gotten far yet — too much actual roleplaying has gotten in the way of actual progress through the AP (much to the delight of n8, a player who was amongst the recurring members of my gaming group back in the early '90s and has been a friend of mine since the '80s). Um. Right. Onward, to the point.

So, anyway, as I was going through logs from last week's session in preparation for this week's, I found some amusing little exchanges over which I had a chuckle, and one in particular that boggled my mind.

Setting the scene: It took us (no shit) 31 minutes and 49 seconds of fucking around with Pidgin to get a chat session working. Once we finally got one working so everybody could participate in the game, it was apparently too late — I had already lost my tenuous hold on sanity. This is what I said (names changed to protect the guilty):

(21:34:50) n8 entered the room.

(21:34:50) SigO entered the room.

(21:34:50) @ entered the room.

(21:34:56) @: fucking fuckfuck the fuck

(21:35:24) @: Someone on the Pidgin team needs to die by soaking in strong vinegar.

(21:35:31) n8: agreed!!

(21:36:21) @: SigO informs me there's a Pidgin chat bug that might pertain to this problem that has been around for three years without getting any attention from those sea cucumber fuckers.

(21:36:34) @: "The Sea Cucumber: Nature's Pocket Pussy"

(21:37:03) @: I imagine they probably said "That's how it's supposed to work. You're just too stupid to appreciate its beauty and utility."

I got over it in time to run the session, though.

"Nature's Pocket Pussy"? What the hell was I thinking?

How does someone die by soaking in strong vinegar, anyway?

I'm biting my nails in anticipation of the day a decent multiprotocol IM client with a development team that wasn't born with too many chromosomes in its collective rectum actually supports OTR encryption across the board so I can stop using Pidgin. I'm half-expecting the Pidgin team to somehow permanently break compatibility with the OTR plugin first, though. Well . . . I guess that'll be one way to get me to switch to a different IM client.