Wednesday, July 20, 2016

Bodega Burger Co. set list 2016-07-15

The nice folks at the Bodega Burger Company in Socorro, the best restaurant in the county, took the risk of hiring me to be the dinner entertainment last Friday, despite the fact that I just sing and don't have any instrumental skills or an accompanist. Heck, I figure if the minstrels could do it, why not me? All it takes is some songs that have strong lyrical and musical content: there will be no blazing 32-bar guitar solos, obviously.

I sang from 6:30 to 9:00 with only a few very short breaks. Here's my set list. As you see, I have a real soft spot for top-40 material from ages past, but that's far from all I sang. I've been doing open mic nights in this town for twenty years, I have a lot of material: so far, about 100 songs that are ready for prime time.

Blue Bayou: Roy Orbison, Joe Melson.
In my life: Beatles.
Another you/World of our own: Tom Springfield.
Mega-hits for the Seekers in the 1960s.
Dance the night away: Jack Bruce, Pete Brown.
From Cream's second album, "Disraeli Gears".
Don't think about her (when you're trying to drive): Little Village.
Little Village was a one-album supergroup of John Hiatt, Ry Cooder, Nick Lowe, and Jim Keltner. I sing this one from the toenails because of a recent unpleasant memory.
Tiny Island: Al Gaylor.
Stolen from Leo Kottke. I love stealing his vocal numbers because we have compatible ranges and he has a wonderfully off-kilter taste in material. I didn't do 'Sonora's Death Row' tonight, not exactly dinner music, but another Kottke piece I've done many times at open mics.
Lady Jane: Mick Jagger, Keith Richards.
Not rock and roll in any way, but a song of courtly love.
Then you can tell me goodbye: John D. Loudermilk.
Another repeat offender from the top 40.
Sukiyake: Rokusuke Ei, Hachidai Nakamura
A Japanese crossover hit, the first Asian artist to break the Billboard Hot 100, in June 1963. They called it 'Sukiyaki' because they figured that's the only Japanese word Americans would recognize; it has nothing to do with beef stew. I throw in one verse of English to give the mood:

I'll hold my head up high, looking to the sky

So they won't see all the tears that are in my eyes

No one will know I'm going through

My first lonely night without you

Silence is golden: Bob Gaudio, Bob Crewe
Big hit for The Tremoloes.
Learning the game: Buddy Holly.
Not your typical happy Holly song: deeply sad and cynical. Stolen from Kottke.
The Longest Time: Billy Joel.
A ridiculously upbeat tune to counteract the previous one. I once sang this two days after my heart got put through a shredder. If I sounded upbeat that night, it was pure acting.
Disney Girls (1957): Bruce Johnston.
Yes, it's a Beach Boys song, but a long ways from "Surfer Girl." A hymn to Disney's shiny fantasy world, recalling my own crush on Hayley Mills. Rather difficult due to a pretty wide range.
Catch the wind: Donovan Leitch.
Another perennial in my open mic act, and one of my favorite songs of all time.
Celluloid heroes: Ray Davies.
From the Kinks album of the same name. A deeply felt lyric that, for a change, is not about romantic love. Don't step on Bela Lugosi, he's liable to turn and bite!
Change the world: Tommy Sims, Gordon Kenney, Wayne Kirkpatrick
Eric Clapton is not usually known for his vocals but his version of this convinced me I gotta learn this one. Sloppy sentimental candyfloss, just the way I like it.
Cold Cold Heart: Hank Williams I.
If I needed someone: Beatles.
Pamela Brown: Tom T. Hall.
Just so nobody can argue I never do country. Thanks to Leo Kottke for finding this one. I frequently end it with the line "And I guess I owe it all to Kendra Barrett," and the Hobbs High class of 1966 will know what that means.
Prime Time: The Tubes.
I saw this legendary band twice live. Better showmen I've rarely seen. This was from their "Remote Control" concept album about TV. At some point I want to do a medley starting with "TV is King" (oh, if only your chassis were covered with skin!), then Blondie's TV song "Fade away and radiate", and close with this one.
Supernova: Nate Borofsky.
Title track from my favorite album since the year 2000, and my favorite new group of the millennium, Girlyman. Sadly, they broke up forever in 2013. The harmony on their version is riveting. Heir to a long tradition of fine American vocal harmonists, from the Sons of the Pioneers through the Everly Bros. and Simon and Garfunkel and Crosby Stills and Nash. It's too bad I can only sing one line, but I think the lyrics are strong even without the harmony.
Desperado: Don Henley.
See the changes: Stephen Stills.
From Crosby Stills & Nash's "CSN" album.
Helplessly hoping: Stephen Stills.
Picking the so-called melody line out of the perfect choral tapestry of the album version took a lot of study. Then I heard Stills sing a solo version to confirm that I did it right.
Happy ending: Joe Jackson.
Another of my go-to songwriters; I've done at least ten of his pieces at open mic nights.
Things we said today: Beatles.
Time after time: Richard Hayman, Cyndi Lauper.
I didn't get to my other favorite of hers, "All through the night," but it's in the book and ready to go.
Overkill: Colin Hay.
Be my number two: Joe Jackson.
A post-romantic-apocalypse love song for the shattered.
Conversation/Blue Boy/Chelsea Morning: Joni Mitchell.
A repeat of a set I did for the NM Symphonic Chorus summer fundraiser a week earlier. I think I've done well over half the songs from "Clouds" and "Ladies of the Canyon" in open mic nights.
Don't let it show: Alan Parsons.
A wonderful song for people recovering from romantic disasters. His "I, Robot" album has been a good source of tunes. I've also done "Some other time" and "Day after day (The show must go on)".
You don't have to say you love me: Dusty Springfield.
Hit Single: Joe Jackson.
If I fell: Beatles.
I'll be over you: Steve Lukather, Randy Goodrum.
Yes, Toto was a commercial smash, but that doesn't mean they were bad. I like to sing this one through, modulate up an octave, and sing it again.
I'm an old cowhand: Johnny Mercer.

I know all the trails in the Big Square States

'Cause I ride the range in my Ford Escape

Hank Williams: I'm so lonesome I could cry.
Cool Water: Bob Nolan.
Gotta do Sons of the Pioneers because as they say at Bob's Country Bunker, Country and Western are two different things. Also known as the Bartender's Friend; guaranteed to spike drink orders.
Complicated Girl: Michael Steele, D. White.
The Bangles really should have been the next Beatles. They had it all: great instrumental skills, fine harmony, good writing right in the group, and they were photogenic.
Ana Ng: John Linnell, John Flansburgh.
These two call themselves They Might Be Giants and they have a goodly cult following among nerds. Lots of lyrics here that go by quickly and leave you wondering, what was that?
Endless Sleep: Nick Lowe.
Another song for the terminally depressed. Stolen from Leo Kottke.
Eternal Flame: S. Hoffs, B. Steinberg, T. Kelly.
Did I mention I adore the Bangles? They visited Elvis's grave once on a rainy day and found that the Eternal Flame was not burning. They complained and the caretaker said, "It's semi-eternal." And that's what inspired this song.
And I love her: Beatles.
It's not my time to go: Dan Hicks/Something: Beatles.
One night many years ago, back when the Socorro Springs Brewery was in their new building and they still did open mics, I had these two songs lined up. Then I suddenly realized that the first song ends with the same word that starts the second, so I made them a musical Siamese twin. By the way, I also love and adore Dan Hicks and his Hot Licks and have done several from him at open mics.
I wanna be sedated: The Ramones.
It would be a sin to ignore the entire punk movement, which so energized popular music after the Disco Disaster Years.

Thursday, February 11, 2016

Is literate programming harmful?

All of my serious work of the last few years has used “lightweight literate programming,”: a program's source code is embedded in a document that describes the internals. See my lightweight literate programming page for an explanation and many examples.

So I feel obliged to respond to a post by my good friend and colleague Daniel Lyons entitled “Literate programming considered harmful”.

The code is important—it’s what makes it go, and we spend all day in there reading it and writing it. We have to be able to understand it to extend it or debug it. But if I’m not able to communicate clearly to a human, it won’t stop the program from entering production—but the “incidental” detail of it being wrong will.

Agreed. It's clearly true that the functioning of the programming is the first priority. And the second sentence above emphasizes the important truth that documented programs are easier to extend or debug.

I put a lot of stock in Brooks’s quote, “Build the first one to throw away, because you will.”...This leads to the second material limitation of literate programming, which is that if you were doing literate first, you have either just written a book about the wrong approach to the problem, which incidentally is also the throwaway program, or you have expended twice the resources to produce a book when what was desired was a program.

Maybe I've led a sheltered life, but I'd guess that in fewer than a third of my projects I threw away the first one and started over. Yes, it's often great to use what you have learned in the first revision. But the last major project I built for the NM Tech Computer Center went into service as soon it was finished, and according to my friend Dylan who is the primary user, has been trouble-free. Of course there lots of changes during the design, but there was less wasted effort because he caught the problems in the specification and not during testing. There are two components to this system: cmsadds: A GUI for CMS course creation, and a database access layer, cmsimport2: Courseware Banner integration tools.

There's another substantive argument here: that literate programming costs “twice the resources” as some unnamed other approach. To what are we comparing? What is the minimal level of documentation for a serious production system? I've been a software professional for fifty years now, and I've spent a goodly slice of that time discussing this very question with my peers. Contra my former coworker Joel Eidsath, I don't really think that zero is the correct level. I think the general consensus among seasoned professionals is that a decently documented program requires a substantial effort to provide comments or other documentation. This is certainly not free.

A third option, which I have seen in practice, is that you have produced a book of negligible value, because although the book-production toolchain was employed and literate code was written, almost no effort went into forming the book-as-literature—that effort went directly into the code anyway.

Writing skills vary among software professionals. I don't know how you judge the literary merit of literate code. My technical writing guru Dr. Jon Price taught me that the first question is, who is your audience, and what assumptions can you safely make about their capabilities? And the second is, what are you trying to accomplish?

Lyons addresses this: “The market for programs that cannot be executed (or are not primarily to be executed) is precisely the book market.” I can't speak for other practitioners, but my primary audience is me!

When I start a nontrivial project nowadays, the first thing I do is to create a directory and place in it a DocBook-XML document and a rudimentary Makefile. The first section I write is the “Requirements,” which states why the project is being undertaken and what requirements it hopes to fill. Then I flesh out a complete specification of the external surface of the product.

I hardly think this is wasted effort. In my practice, the specification serves two purposes. It communicates the proposed solution to the users so they can evaluate the design before the developer has spent a lot of time building the wrong widget. Regardless of the audience, however, writing the specification is my favorite way to think seriously about how the widget is going to work: not just the feature set, but all the potential unfortunate interactions between features. So I argue that writing a tight specification should not be counted as extra effort.

This leaves us to consider whether the documentation of the actual code is extra work over and above the writing of what would generally be regarded as minimal comments or other internal documentation. Clearly the useability of the toolset is a critical factor on this evaluation. I've been using DocBook for twenty years. I use emacs with nxml-mode for DocBook creation and editing for almost that long. There is definitely a big learning curve to master those tools. But when I started using them for literate programming, the additional learning curve was inconsequential.

One of the biggest advantages DocBook has over other documentation tools is that it has the full CALS table model, so you can build complex tables with row and column spanning. Also, DocBook makes it easy to embed images with multiple formats so the Web version can show a .jpg but the PDF rendering can use a fully vectorized format like .pdf or .svg. ASCII art is clunky and not, to me, a lot less time-consuming than quality figure creation with Inkscape.

I am thrilled by Lyons' vision of the quality literate framework of the future, which he feels is justified for code that justifies careful study:

I picture something like a fractal document. At first, you get a one-sentence summary of the system. You can then zoom in and get one paragraph, then one page. Each section, you can expand, at first from a very high-level English description, to pseudocode elaborated with technical language, finally to the actual source code.

Exactly: someone new to the code wants to see the big picture first, then work their way down a sort of pyramid until they get to the nuts and bolts when necessary. This is exactly how I structure my literate document. The tip of the pyramid is the requirements. Below that is the externals. The next layer is all the high-level design work above the layer of individual modules:

  • Entity-relationship models for databases, XML document schemata, or internal program data structures.
  • Discussion of any algorithms or data structures that are not generally known standard practice.
  • Database schemata, UML diagrams, or other high-level design artifacts.

I argue that a properly documented program of any size needs these things anyway. The literate model gives you a place to put them.

So what remains is the narrative portion, which in my work generally takes about two-thirds or more of the page count. As I write the narrative for a function or method, I am not just describing the code, I am designing the code. As Flannery O'Connor once said, “I write to discover what I know.” If I'm having trouble describing what a module does, it tells me that I haven't really thought it through. This is one of the reasons that I so frequently emphasize writing skills to student programmers: for me writing is central to the craft, not peripheral.

One of the standard complaints about documentation is that it gets out of sync with the actual code. I find that having the narrative adjacent to the code makes it much easier to fix them both when something changes. Another payoff of the literate approach is that it gives you a place to document paths not taken: we tried this and it didn't work, and here's why; or, we didn't try this, and here's why we didn't.

Yes, I admit that it's somewhat more work to write the narrative sections. One of the chores for each document is to come up with a system of unique identifiers for each section, so that you can cross-refer some other point in the document using its section identifier. One of my standards is that if a section of code calls another function in the same system, the narrative for that code section includes a hyperlink to the definition of the called function. This addresses another of Lyons's points:

I don’t know if you could create the same experience in a linear manner. I suppose what you would do is have an introduction which unfolds each layer of the high-level description up to the pseudocode. Then, each major subsystem becomes its own chapter, and you repeat the progression. But the linearity defeats the premise that you could jump around.

The primary difference between literate programming as envisioned by Dr. Don Knuth in his WEB system (no relation to the World Wide Web; he did this work in the 1980s) is that he wanted to order the presentation of the bits of code to optimize the pedagogical value. My system presents the source code in its original order, and uses hyperlinks so you can examine related functions with a mouse click.

So what is the payoff for me? Here's an example. I have been doing data entry for the Institute for Bird Populations since 1988. My data entry system is on its seventh complete rewrite. Sometimes several years go by between change requests from the client. The specification is 34 pages, and the internals about 200 pages. A lot of the code is now obsolete. Yet when I get a change request, I can generally refamiliarize myself with the project structure and jet down to the point of the change and charge the client less than an hour's labor.

In summary, I think Lyons makes a number of good points. Certainly I hope that others may use my literate code as examples (whether good or bad ones is not for me to say!), but my personal justification for what I consider a relative modest expenditure of additional effort is that it makes it easier to work on my own code when I've been away from it for a while.

Sunday, February 7, 2016

The great Socorro snowstorm of 2015-12-27

We got sixteen inches of snow between midday on 12-26 and dusk on 12-27, which ties an all-time single-storm record for Socorro, NM. Photos at my regular web site.