Chad Perrin: SOB

27 February 2010

editors who are wrong

Filed under: inanity,Writing — apotheon @ 08:45

I’d just like to say really quickly that I do in fact know when and how to use a semicolon. It is quite likely that, any time you may see a grammatical error of some sort (or misuse of the UNIX trademark or other such issues that are not strictly technical) in one of my article at TechRepublic, it was an editor altering my article prior to publication who introduced the error, and not me. The same goes for ambiguities of context introduced by formatting, such as when list items get turned into subsection headings (and, thus, the end of the list is no longer a visible end to anything when list items contain multiple paragraphs).

I can’t fucking stand it.

The incident that precipitated this comment from me is in one of my least interesting articles (in my opinion), Avoid ambiguity when referring to account names. The incident in question occurs with these words:

that value is greater than the cost of the added effort involved is difficult to answer in the general case; but for a person whose login information management procedures easily handle this behavior

This article was also a case of a list turning into a series of subsections, so that there’s now no point of differentiation between the last paragraph of the final list item (or subsection) and the first paragraph of the rest of the article. Argh.

Oh, well. It wasn’t really one of my best articles anyway. At least this time it wasn’t a great article turned into a mediocre article by someone else’s meddling.

The last time I tried talking to an editor there about introducing errors into my articles, it was about the UNIX trademark. UNIX is a trademark; Unix is not. Thus, when I say BSD Unix, I’m talking about the BSD branch of the Unix family of operating systems. When a TR editor changes that to BSD UNIX, the sentence now refers to . . . what? Some nonexistent Single UNIX Specification conforming and certified variant of BSD Unix that is called “BSD UNIX” . . . ? Who knows?

When I brought this up, I was basically told to keep my correctness to myself because that’s the way TR does it, has always done it, and will always do it. Since then, I’ve just quietly kept using terms correctly and, when people complained to me about misuse of the term UNIX, I have explained how the term got misused. That’s it. C’est la vie. The lesson I learned from that experience is that I shouldn’t argue about correctness with the editors, because they don’t care.

I won’t bother pointing out to them that “; but” is a sure sign you don’t know how to use a semicolon correctly.

4 February 2010

Documentation Documentation

Filed under: Geek — apotheon @ 01:21

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?

2 February 2010

How I Use XTerm

Filed under: Geek — apotheon @ 05:14

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).

addenda:

If you wish these changes to apply only to UXTerm on FreeBSD, the appropriate file to edit is /usr/local/lib/X11/app-defaults/UXTerm. The proper location for this file may vary among Linux distributions.

Older Posts »

All original content Copyright Chad Perrin: Distributed under the terms of the Open Works License