Δαφνη Ευτυχια Αρθουρος

"It should be pointed out that when many, many people actively promote the assassination of a person, as was the case with Dr. Martin Luther King, Jr, and then one person does it, that is not considered a conspiracy. Just a lone gunman.

"We don't have conspiracies in the US. Just those, crazy, crazy conspiracy theorists.

"And an abundance of lone gunmen."

-- Rain Monkey, commenter at The Stranger, 2009-09-29

It turns out that the unmistakable sound of a dying bearing in a computer power-supply fan ... is mistakable after all. I heard it as I was getting ready to leave the house yesterday afternoon, and had that paralyzing moment of wondering which machine was about to die. Then I realized it was actually the sound of a circular saw being used in the house across the street (with the sound being funneled through an open basement door).

Whew.

Yesterday was a day when things kept going wrong but the day somehow worked out after all. Getting ready to go out, it was one of those everything-takes-longer-than-it-should days; I took a wrong turn and somehow ended up in Odenton instead of Laurel and had to backtrack; my ears were acting up enough to make me nervous about going to a concert (but fortunately not badly enough to make it obviously a bad idea); and somebody at Montpelier Arts Center seriously underestimated how popular a free Sunday afternoon concert by The Montpelier Jazz All-Stars would be.

But after a while of listening to the concert from a corridor outside the gallery the music was in, someone wheeled in another stack of chairs and more of the folks leaning against the walls outside got in (then the person who brought more chairs pointed out that there were a couple of open seats in the front row, so Sheepie and I spent the first half of the concert listening from the corridor and the second half with our knees brushing the drape on the front edge of the stage).

I hadn't known what kind of jazz to expect, and I'm not really sure how to classify what they played, but fortunately it wasn't the "difficult listening" all-theory-but-is-there-a-melody type of jazz, nor was it lukewarm ah, "cool" jazz[*]; it was accessible jazz with some fire in it, a little bit done Dixieland style, a little straight-up blues, all of it enjoyable. Piano, vibes, upright bass, two tenor saxophones (one saxophonist also played flute), and for a few tunes, a singer (where we were sitting, I had a great view of her nifty shoes; had to lean back a bit to see her face). The bassist was making sure we didn't feel the lack of a drummer -- he was pretty much filling two roles at once, and his right hand was really, really busy the whole show. (I was taking notes. I think I understand part of what I saw that I need to practice to see whether I can copy it, but there were a couple of right-hand moves that went by so quickly I couldn't figure out what he'd done.)

The volume was probably about right for the room, and good for normal-hearing folks present, but I would have been more comfortable toward the back. (As it was, with how my ears were doing at the time it wasn't really bad, just a little too loud; the way my ears are acting today -- and late last night -- it would've been downright painful.)

Pastries and punch afterward in another gallery, cool art to look at, then off to a kabob place for curry, while my ears got more sensitive and the echoes in the kabob joint started to hurt, then I went home. OT1H, today I feel like I'm recovering from my weekend; OTOH, yay for live music and actually getting out to do something social!

Yay jazz.

I'm having a lot of trouble concentrating today, which is especially annoying since I'm trying to wrap my head around somebody else's code (or wrap the code around my head, I'm not sure -- it's a library: "abcp"). This is my third attempt to avoid finishing writing my own ABC parser from scratch[**], and since it's a library explicitly intended to save other programmers from that task (as opposed to my trying to rip a not-general parser out of somebody else's standalone app), it's the most promising. But alas, even though the author wrote a lot of words about it -- about the general theory of the design, and the names of the token types returned (and for some of them the information fields included ... but not for all), it's still not quite library-documented, if that phrasing makes any sense ...

That is, yay for useful comments in the code, and the diagram of the state machine the library implements, and an overview of the structure, but ideally I shouldn't still need to go tease apart the C code to figure out how to use the library if it's intended as a library for random other programmers to use. I don't want to complain too loudly, because I do want to applaud the documentation that is there (way more than I usually find), but it's kind of like if, say, printf() were described in terms of how the implementation of it figures out what to do next, instead of the 'man' page actually explaining the syntax of a format string and how to zero-fill a %d field. If I had to go read through the source code for the library printf() is contained in to figure out what "%*s" means in a format string, or how to specify the number of decimal places to use on a float (e.g. "%.2f" for two decimal places) instead of just reading the documentation, printf() would be a lot less useful than it is. Yeah, there are always a few questions for which the answer is RTFS, but I'd like RTFM to be enough most of the time.

I know this is asking folks who do an open-source library project to do a second whole project that is the proper documentation, but it spells the difference between a library that is excellent code but never used by anyone else, and a library that becomes a new standard tool. (Open-source developers: become really good friend with tech writers who can be bribed with pizza and beer and/or are huge fans of OSS themselves, okay?) Make the learning curve a speed bump instead of a detour through mountains; make somebody else's decision to try using your library a matter of looking up the function calls, not yet another exercise in yak-shaving.

That said, I'm currently compiling wee test programs to suss out the quirks and answer questions about the library's behaviour not spelled out in the docs. Replacing the main switch() statement in one of the sample programs that came with the library has been a good start (and yay for sample code like that!). It seems to do a few things differently than what would be most convenient for me, but it looks like it'll save me a lot of time if I don't have to squint at its .h and .c files so closely for much longer. (I did have to #ifdef out a chunk of inline assembly in the utility library that this library calls, and fix a dozen makefiles that needed a space inserted between two macros on a bunch of lines, but I have gotten it all to compile, so that part of the yak is shaved, at least.)

So: yay for documentation, but seriously, more of the right kinds of documentation, please?

Unlikely to make it to 3LF tonight (big surprise, I know, considering how long it's been since I did manage to show up), since I'm still feeling the effects of going out yesterday. Possible, but not likely.

[*] "Cool jazz": jazz for people who don't like jazz but are ashamed to admit it. I'm so glad that's not what this concert was. (There are cool real-jazz tunes, but that's not the same as what radio calls "cool jazz".)

[**] I've got a handful of small projects in the works that do various things to ABC files to generate intermediate files to pass to end-product tools like abcm2ps, abctab2ps, and abc2midi. A couple of these need to "understand" enough of the ABC syntax in order to do the right things, that I needed a parser.