Anatomy of an action

Espresso actions come in two parts:

1. The XML definition, which tells Espresso the action’s title, what Objective-C class to execute when the action is invoked, and additional information like keyboard shortcuts or tab triggers that should invoke the action.
2. The Objective-C class (or, if using a plugin like TEA or Spice, the script that defines the action’s logic)

Most often, XML action definitions are included with a Sugar (you can make a Sugar for custom text actions simply by adding a .sugar extension to a folder that contains a TextActions folder with the action XML files in it). If you wish, you can also define action XML files outside of a Sugar by enabling TEA custom user actions in the Advanced pane of the Espresso Preferences (more info about TEA custom user actions).

As of Espresso 1.1 there isn’t an in-program GUI for editing actions yet, but hopefully that will come in time.

Spice up your actions

Spice is an Espresso Sugar that I’m currently developing that provides access to the Espresso API using Javascript (thanks to JSCocoa), and additionally provides a selection of utility classes that allow you to interact with the API without needing to know anything about Objective-C or the JSCocoa bridge.

The benefits of this should be fairly obvious, but there’s another reason creating actions with Spice is easier than using TEA or Objective-C; not only are the action scripts not compiled, but you don’t need to relaunch Espresso to see your changes. When I’m coding a Spice action, I usually open the Javascript action in Espresso, and then run the action right there on the Javascript when I need to test it.

Although Spice’s utility classes make creating custom Espresso actions easier, you still need a basic understanding of how the Espresso API works.

Contexts, ranges, recipes, and snippets

When a user invokes an action from the Actions menu, Espresso executes the action’s class and sends it an object representing the text or file context (depending on whether you’re using a text or file action; I’ll be focusing only on text actions because the file action API is currently underwhelming). The text context allows you to access the active file’s text, information about the selection (or selections, since you can select multiple things at once), line information, preferences (like what line ending or indentation is being used), and access to the syntax system.

When you are ready to change some text in the file, your action messages the text context and tells it what to change and how to do it.

As of Espresso 1.1, the easiest actions to create are ones that are invoked by the user, access and change something about the active file’s text, and then immediately exit. It’s possible to do things that are a bit more complicated or on-going, but at the moment Espresso doesn’t make it easy.

When you’re working with text, you’ll mainly be dealing with ranges. A range represents a section of text in the active file and is composed of a location and a length. Internally Espresso keeps track of text by counting all of the characters in the active file starting at zero, so the range location is the index of the starting character and the length is the number of characters contained within the range. Typically you’ll be dealing with selections, so you’ll have ranges like {0, 10} (the first ten characters in the file) or {100, 30} (characters 100 through 130). However, it’s also possible to have ranges like {10, 0}, which represents the cursor location at character index #10 in the file.

A typical text action will fetch the currently selected ranges from Espresso, manipulate the text within them somehow, and then tell Espresso to change the range(s) accordingly. In order to queue up changes like this, you’ll use text recipes.

Text recipes are something that is unique to Espresso, so far as I know. Basically, you create a recipe and tell it things like “delete the text in this range”, “replace the text in this second range”, and “add this text at a third range”. You can compose a multiple step recipe without worrying about tracking how ranges will change; for instance, if you add characters to an early range, you don’t have to adjust the location of later ranges. Instead, the recipe does that for you when you apply it to the document.

Text recipes allow you to make complex changes to multiple ranges in the active file, but you can instead insert text snippets, as well. A text snippet is a specially formatted string that allows Espresso to create tab stops, mirrored segments, and more after you’ve inserted it. Many of the custom actions bundled with Espresso are little more than text snippets; for instance Wrap Selection In Tag merely grabs the selected text and wraps it in a simple snippet that mirrors the HTML element from the opening tag to the closing tag. You can do some pretty magical-seeming things with very simple actions simply through tricky use of text snippets. The one downside to keep in mind for text snippets, however, is that you can only insert one at a time (unlike text recipes, you can’t insert multiple text snippets over discontiguous selections).

Bringing it all together

With an understanding of how the Espresso API works and a quick peek at the Spice docs, setting up an action to delete the current line (to take one example) becomes simple enough:

1. First, we’ll need to define an action in XML, and create a Javascript file with the action logic
2. In the Javascript, we’ll need to query the text context to get the range of the current line, and then create a text recipe to delete that range

The action XML is easy enough; simply create the file Actions.xml and place it either in a Sugar’s TextAction folder or in your Espresso Support folder located here:

~/Library/Application Support/Espresso/Support/TextActions/

The contents of the action XML definition should be this:

<action-recipes>
    <action id="com.onecrayon.DeleteLine" category="actions.text.generic">
        <class>Spice</class>
        <title>Delete Line</title>

        <setup>
            <script>delete_line</script>
            <undo_name>Delete Line</undo_name>
        </setup>
    </action>
</action-recipes>

(If you wish to add a keyboard shortcut, you can do that with the key-equivalent entity; see the Spice action XML docs.)

If you’re using the Support folder option, you’ll need to enable TEA custom user actions in the preferences and restart the program twice. Otherwise you’ll need to make sure the Sugar is installed and restart the program once (action XML definitions are loaded when Espresso boots up; unfortunately as of Espresso 1.1 there isn’t a way to refresh action XML definitions without a relaunch).

Now that you’ve got the action defined (and showing up in the Actions menu) you can create the Javascript file delete_line.js (referenced in the script element of the action XML). If you are using a Sugar, it should be located here:

MySugar.sugar/Support/Scripts/

If you’re using custom user actions in the Espresso Support folder, you’ll save it here:

~/Library/Application Support/Espresso/Support/Scripts/

The simplest way to delete the current line would be this:

// Deletes the current line

// require() allows you easy modular access to Spice's helper classes
var textContext = require('text_action_context').textContext;
var TextRecipe = require('text_recipe').TextRecipe;

// exports.main is your primary function, run automatically by Spice
exports.main = function() {
    // Grab the range of the current line
    var linerange = textContext.rangeForLine();
    // Run the actual removal
    return new TextRecipe().remove(linerange).apply();
}

First, the script uses the universal require() function to include the Spice utility object textContext (which contains methods for interacting with the Espresso text context) and utility class TextRecipe (which allows access to Espresso text recipes).

Spice’s utility classes are provided in a modular system that allows you to only require what you need in order to run your action. Spice modules have the following naming conventions:

• The module is named for the primary class, converted to lowercase and with underscores between words (so primary class TextActionContext becomes module text_action_context)
• Classes are all camel-case with the first letter capitalized (TextActionContext)
• Objects (instantiated versions of a class) are camel-case with the first letter lowercase (textContext is an instantiated version of TextActionContext)

You can see what a given module exports in the Spice docs (along with full references to the object methods available). The text_action_context module is one of the few that exports an object as well as the class, since you’ll never need more than one object for referencing the text context.

Once you’ve saved the Javascript file, you’ve officially created your first Espresso action! You can immediately run the action from the Actions menu, and it will delete the current line. If you test it out, though, you may notice that the action behaves differently when you delete the final line in the document; instead of removing the line completely, it only removes all the text. To fix this, you could modify the action like so:

// Deletes the current line

// require() allows you easy modular access to Spice's helper classes
var textContext = require('text_action_context').textContext;
var TextRecipe = require('text_recipe').TextRecipe;
var Range = require('range').Range;

// exports.main is your primary function, run automatically by Spice
exports.main = function() {
    // Grab the range of the current line
    var linerange = textContext.rangeForLine();
    // If on the last line of the doc, remove the line break prior to the line
    // This isn't strictly necessary, but it's nice to have
    if (textContext.lineNumber() != 1 && textContext.rangeForLine(textContext.lineNumber() + 1) === false) {
        linerange = new Range(linerange.location - 1, linerange.length + 1);
    }
    // Run the actual removal
    return new TextRecipe().remove(linerange).apply();
}

The only addition is some logic to check if we’re on the last line of the document, and if so create a custom Range object that includes the linebreak from the previous line.

Debugging

As you work on your own custom actions, you will of course run into problems and errors. The best way to debug is to keep Console.app open (located in your Applications/Utilities folder), since most errors will be output there. You can also use the globally available system.log('message') to output directly to the console. Many Spice utility classes also include a log() method to quickly log the contents of an object.

When using Spice, keep in mind that it’s still under development (at the time of this writing, it’s at version 1.0 beta 6). If you run into something that seems buggy or a limitation of the utility classes, please let me know.

Parting thoughts

Even if you don’t use Spice, the basic strategy for adding a custom action to Espresso remains the same. TEA offers several alternative methods to creating text actions (from Python scripts with full access to the API to scripts in arbitrary languages like Ruby or PHP that have more limited capabilities). Although the basic editor has a nice interface and some great features, I’ve found that the extensibility of Espresso is what keeps me coming back for more. A modicum of effort is often all that’s required to add a custom text action, so there’s little excuse for not giving it a try if you find yourself missing functionality you’ve grown used to in other editors.

If you do write any great custom actions, please think about sharing them either via a Sugar, GitHub, or the Espresso forums! I’d also love to hear how people are using Spice; I’m still planning out the additions I want to make now that I’ve got most of the basic Espresso API for text actions covered by the utility classes, so your input is extremely valuable.

My first inclination, comparing the film with my Disney favorites Little Mermaid, Beauty and the Beast, and Aladdin was that Princess and the Frog had used those prior movies as a formula and that was what was jarring. Upon further thought, though, I realized that the use of a formula wasn’t the problem; I’d never noticed before Princess and the Frog made me think about it, but Little Mermaid, Beauty and the Beast, and Aladdin follow strict formulas themselves. Heck, they’re practically the same movie:

• The movie opens, and shortly after introducing the main characters our heroine (or hero, but most of them are female for this particular sampling so for simplicity I’ll stick with the feminine) is brought to the villain’s attention. The villain reveals that the heroine has something that makes them uniquely important to the villain’s personal goals (Ariel is the key to Triton’s power, Belle is the only girl worthy of conquest, Aladdin is the only one who can gain the power of the lamp)
• Early on, our heroine reveals their core motivation via song (Part of Your World, Belle’s opening song, One Jump Ahead)
• A spectacular musical number reawakens our interest (Under the Sea, Be Our Guest, Friend Like Me)
• At some point, the villain has a lone musical number, partially spoken or otherwise not as melodic and memorable (Gaston’s song being something of an exception, likely because he’s more of a passive antagonist otherwise so they had to compensate somewhere to make him interesting)
• Various filler songs occur here and there, typically to advance the plot
• A love song occurs at the primary moment one (or both) of the love interests realize their feelings (or otherwise reach a turning point in their relationship)
• A showdown occurs with the villain, the heroine triumphs, and the culmination of their triumph is the marriage to the love interest and achievement of their dreams

You can break the formula down even further past the musical numbers to specific characters (villain’s humorous sidekick, heroine’s non-human helpers, etc.), but you get the idea.

It wasn’t that The Princess and the Frog followed a formula, then, that impaired the movie. In point of fact, the way it nails almost every aspect of the Little Mermaid/etc. formula may well be its greatest strength. Disney obviously brought a lot of budget and creativity to bear to bring the movie to life in the same vein as their old hits (even making the comparison explicitly in their previews, which is what cued me into comparing the two as I was watching it). Yet unlike Little Mermaid or Aladdin I didn’t walk out of the theater wanting to see it again, or utterly captivated by the characters, or excited and eager to tell my friends about the movie. I came out of the theater and thought, “Well, that was fun. Don’t really need to see it again.”

I’ve been pondering, and come to the conclusion that what the Disney movies of the early 90’s that I remember so fondly had that Princess and the Frog lacks is the spark, the soul, the story that needs desperately to be told. Without that inspiration, the formula falters, the pieces pull slightly apart, and the viewer is left with the realization that there is a formula and that it isn’t quite working.

Great movies happen because creative people get excited, and if they’re lucky they have the budget and direction they’ll need to create something fantastic. I think that people got excited about Princess and the Frog, but I don’t think that it was because of the story that drives the entire project forward. I think they got excited about the spectacle, the fun characters, and the setting. And in the end, that made the difference between a film destined to be a classic and one that is merely diverting.

The more near misses I see in the theater the more I’ve come to believe that story is the driving creative force that must exist for any narrative work to succeed, be it cinema, literature, or otherwise. Certainly, great characters are a part of the puzzle. A well-tested formula can help clarify and ease the story’s delivery. Talented people well directed can breathe a lot of life into any tale. But unless these things are born out of a story that needs to be told the pieces won’t quite snap into place.

The Princess and the Frog is not a story that needed to be told. It’s a decent story, an amusing story, a story that pleasantly reinforces our own delusions about ourself and our culture; but it isn’t a story that needs its telling so badly that it grabs the imaginations of its makers and viewers alike and refuses to let go even once the curtain has closed.

I don’t know where stories come from, or even how crafted and calculated the Disney movies of yore that I loved might have been behind the scenes. All I know is that in Princess and the Frog Disney has produced a film that sparkles, amuses, and tweaks gently at the heartstrings yet fails to achieve the vivid life bequeathed by story.

The specific need I wanted to address was my inability to easily insert some common HTML elements (particularly links) in WriteRoom. I’ve owned WriteRoom for years thanks to a software bundle, but I never had any use for it until I discovered QuickCursor. Now I can’t get enough of it; full screen editing for text fields in Safari is brilliant.

The only thing I haven’t been happy about was needing to type out every blessed character when I needed light HTML. Although WriteRoom’s Applescript support does not apparently provide access to selected text, the new Services menu does.

To add HTML link insertion to WriteRoom (or any other text editor that supports Services, for that matter) first boot up Automator and create a new Service workflow:

By default, Automator will have you processing selected text in any application. Check the “Replaces selected text” checkbox, and if you’re only going to be using the action in WriteRoom (or similar application) make sure to use the dropdown to target that app and avoid cluttering up your Services menu:

Over at the top right, type “Applescript” in the search box to filter the list for the “Run Applescript” action (make sure you have the Library highlighted, or it may not show up). Drag the action into your workflow:

Select everything in the text box, and replace it with this:

on run {input, parameters}
    set linkDefault to (the clipboard as string)
    set linkDefault to my switchText(linkDefault, "\\\"", "\"")
    set targetLink to do shell script "echo \"" & linkDefault & "\"|sed -E \"s/(mailto:)?(.+@.+\\..+)/mailto:\\2/\""
    if targetLink does not start with "mailto:" then
        set targetLink to do shell script "echo \"" & linkDefault & "\"|sed -E \"s/^(([a-zA-Z0-9-]+\\.)*[a-zA-Z0-9-]+\\.[a-zA-Z]{2,4}(\\/.*)?)/http:\\/\\/\\1/\""
        if targetLink does not start with "http" then
            set targetLink to "http://"
        end if
    end if

    return "<a href=\"" & targetLink & "\">" & input & "</a>"
end run

on switchText(fromText, targetText, replaceText)
    set d to text item delimiters
    set text item delimiters to replaceText
    set fromText to fromText's text items
    set text item delimiters to targetText
    tell fromText to set fromText to item 1 & ({""} & rest)
    set text item delimiters to d
    return fromText
end switchText

Save your workflow, and you’re basically done! When you select some text in WriteRoom or elsewhere and run the action from the Services menu, it will wrap the text with a link. It also will check the clipboard to see if there’s a recognizable email address or URL on it, and if so will use it for the link (otherwise defaults to http://).

For maximum productivity benefits, of course, you’ll want to visit the System Preferences Keyboard pane and give your new Service action a shortcut; I’m using control-shift-L since that’s what I’m used to from Textmate and Espresso.

Worth noting is the fact that the above Applescript doesn’t display a dialog box to query you for a URL if it can’t detect one on the clipboard, so for maximum effect you’ll want to copy your target URL prior to running the action if possible. The reason for this minor problem is that the dialogs spawned by my Service action never received focus, and for myself mousing over to give the dialog focus is more work than option arrowing a few times to edit the default URL.

You can, of course, add simple Service actions to surround text in other arbitrary HTML tags, as well. Simply use an Applescript similar to this instead:

on run {input, parameters}
	return "<strong>" & input & "</strong>"
end run

The only major downside that I’ve found of using Services this way is that it isn’t as quick as I’d like. I experimented with using shell scripts or Python instead of Applescript, but there were no significant speed boosts; as best I can tell, however Services is harvesting the selected text and then replacing it afterward is simply a slow process.

I’d love to hear how other people are leveraging the new 10.6 Services menu! I have the feeling that I’m just scratching the surface with this script.

Well, here it is: my definitive StoryMill vs. Scrivener review. Although StoryMill is my personal application of choice, there’s a lot to love (and some things to dislike) about both programs.

Quick and dirty

Not everyone wants to wade through my periphrastic meanderings (just discovered that word, and it’s making me really happy; sorry for sounding like a total vocab snob), so here’s the quick and dirty:

• If you primarily write fiction and want a program that will provide you with an easy framework for organizing your writing, you’ll probably prefer StoryMill.
• If you primarily write non-fiction or screenplays or write fiction and want a program that will let you do pretty much whatever the hell you want workflow-wise (with a correspondingly higher level of confusion), you’ll probably prefer Scrivener.

A broader picture

As is often the case, the fast and dirty comparison is a bit misleading: either program can help you write fiction or non-fiction. The reason the fiction/non-fiction comparison is common is because StoryMill is explicitly focused on fiction (and doesn’t support screenplays at all, since that would steal sales from its companion software Montage) while Scrivener provides a general writing metaphor that can apply to either genre equally well (with limited support for screenplay formatting and footnotes).

The truth is that regardless of your genre the deciding factor for which software to use will be a matter of style. StoryMill’s approach is to provide you with a specific framework for writing and organizing, complemented with a focused group of powerful features. In contrast, Scrivener is much more flexible and offers a larger number of features that you can pick and choose from to form your workflow. You can do most of the things in Scrivener that you can in StoryMill (with a few key exceptions), but it will be slightly more effort.

If StoryMill’s framework makes sense to you and you don’t have an urgent need for any of the features that are Scrivener-only, then StoryMill will be the easiest environment to write in. However, for some people the time necessary to set up their own framework in Scrivener is well worth the effort because the program’s flexibility allows them to write most effectively.

To figure out which style, and thus program, is the best choice for you, you’ll need to consider two big questions: what metaphors do you use for writing, and what specific features are most important for you?

StoryMill: a novel framework

The foundation of StoryMill’s approach to writing and organizing is the scene. Scenes in StoryMill are the building blocks which create chapters and ultimately the story itself (it’s worth noting that you can think of scenes and chapters as whatever content blocks make sense for your story; the names don’t really limit the function). Though you’ll track your characters, locations, and so forth elsewhere, the scenes are where you’ll tie them together.

StoryMill offers several other types of items like characters, locations, research, and even submission tracking for when you complete the novel, but the scenes are the core of the program. If working with scenes makes sense to you, and you like the ability to directly relate characters to scenes and organize both in plot order and chronological order (the latter via the timeline feature), then StoryMill will likely appeal.

This scene-centric framework has actually taken a page from Scrivener’s book in recent updates, as well. You can use scenes either as an outline (in the Scenes view) or as the actual text of the story (in the Chapters view). Storing text in scenes can be a little bit confusing (particularly since you can still store text in chapters and use scenes purely for organization if you choose), but this allows you to take advantage of the outline-as-text feature that Scrivener executes with such panache.

StoryMill also has some specific stand-out features that influenced my decision to use it. For me, annotations are one of the biggest. In StoryMill, you annotate text by selecting it and choosing “Annotate”. The text turns the standard link blue with underline, and a little window opens up in which you can type the annotation’s title (defaults to the selected text) and add your annotation. This is great for a number of reasons:

1. Annotated text is clearly marked, yet the annotations themselves are completely invisible unless you want to see them.
2. Annotations are rich text, so they can contain just about anything. This includes images, formatted text, etc.
3. StoryMill handles annotations intelligently: if you open up the annotations window and start moving through the text with your cursor, the displayed annotation will update based on which linked text the cursor is in. You can also open the annotations window for a given annotation with a hotkey (no clicking the link required).

Some people prefer the margin-notes approach to annotations in Pages, Word, etc., but I find those extremely limiting because if you type more than a sentence or two they become unwieldy, it’s not always easy to tell what text the annotation applies to, and you can’t have very many on a page before they get out of control. The only thing they have over StoryMill’s annotations is that you can view all of them at once, but in practice I’ve never found this to matter.

Another big draw for StoryMill is its timeline functionality. Timelines allow you to view and organize scenes in chronological time, even if the flow of the novel is completely different. This can be fantastically helpful for preventing plot holes and other inconsistencies, and getting a general overview of the flow of time through your novel can be useful in its own right. The downside to timeline is that it’s still a young feature; the interface could use a little refinement and it had a bit of a rocky start thanks to some bugs, but there’s still nothing comparable out there (aside from dedicated timeline software).

StoryMill has numerous other small features that I can’t live without, as well: the progress meter is a one that I’ve surprisingly grown to rely on. It visually tracks how far along you are for both your session and project word goals. It also can emit a sound when you hit your session goal, which is really nice feedback if you’re working in full screen. Full screen is of course another great feature, although one that’s available in most writing software these days. The reason I like StoryMill’s better than Scrivener’s is that it’s truly nothing but you and your writing; no annotations, no floating windows, nothing but the text. Tags and smart views, export templates, and the project-wide find and replace dialog are other reasons to love StoryMill.

Scrivener: your digital corkboard

Scrivener takes a slightly different approach to the writing process. Where StoryMill provides a framework with carefully designed parts, Scrivener offers the user a beautifully executed corkboard metaphor and then hangs potentially useful features around it.

Scrivener’s corkboard is where it really shines. The connection between outline, visual organization of “index cards”, and your actual text is simple, sensible, and flexible enough to handle virtually any kind of writing. Want to break things down into beats, then scenes, then chapters, then acts? Go for it. Your only real limit is your creativity. Scrivener’s central metaphor additionally captures in a digital format a way of working that instantly makes sense to most people who have written by hand. This is a definite strength over StoryMill, which takes a more relational database-driven approach to organization and writing that may not be as easy to initially access for some people.

Aside from its elegant central metaphor, Scrivener also offers a slew of useful features. I encourage you to check out the Scrivener website and free trial to figure out which ones you’ll care about, but the primary things of interest to me are snapshots (saving multiple versions of a single piece of text), wiki-style links to internal documents, the vastly flexible exporting system, and the simple script-writing formatting tools.

It’s worth taking a moment to dwell on snapshots. Although StoryMill is planning to implement similar functionality for their next version, this is a key area where Scrivener is clearly the better choice. Organizing multiple revisions of the same text in StoryMill is extremely kludgy at the current time, while Scrivener handles it with ease.

Additionally, you can (with a little bit of work) mimic some of StoryMill’s strengths in Scrivener. For instance, the Document References could be used to associate characters with scenes. You can also mimic StoryMill’s annotations to some extent using wiki-links that open in split views (Scrivener’s built-in annotations are inline with the text, making them only useful for very short notes to yourself that you don’t mind reading every time you go back over things). They’re not as easy to use as StoryMill annotations, sure, but this kind of flexibility is another of Scrivener’s strengths. The menus may be confusing and (to my eye) bloated, but all those disparate features mean that with a little work you can achieve numerous different workflows.

Beyond the software

Of course, there’s more to writing than just the software itself. Both Scrivener and StoryMill have healthy communities and refreshingly responsive developers. Scrivener has a larger community (and one more inclined to chat about whatever the heck is on their minds), but you may get a faster response in StoryMill’s forums simply because there aren’t as many threads. Your mileage will doubtless vary, but I highly suggest dropping by the forums for whichever software you’re leaning toward and asking any questions you have.

An additional concern is interoperability between your writing software and other software on your computer. Both Scrivener and StoryMill store data in proprietary formats but both also offer flexible ways to export that data. Which export system you like better will probably depend a lot on what you need to export, but both allow you to get all of your data out of the program without much fuss. If you’re trying either software’s free trial, definitely play with the export system before purchasing it.

Scrivener additionally allows easy editing of text in external programs, which can be nice if you like editing text in WriteRoom, BBEdit, or similar.

Time to write

Both StoryMill and Scrivener were created because the developers couldn’t find a tool that fit their respective needs as authors, and the bottom line for any potential user is you should use whichever program makes it easiest for you to write.

For myself, that program is StoryMill. Its framework makes sense to me and I’ve become addicted to its overall slimmed-down focus on the features that matter most (not to mention some specific niceties like rich annotations and timelines).

I can certainly appreciate the draw of Scrivener, however. Every time I open it I’m amazed anew at how simple and relevant a metaphor for writing it provides. StoryMill’s niggling issues with the separation between outline and text are nonexistent in Scrivener thanks to its solid basis in the idea of a corkboard. Sure, to get the kind of interconnectivity that StoryMill encourages you have to do a bit more work, but with Scrivener’s large and helpful community figuring out a document layout and workflow shouldn’t be too painful.

Ironically, in a few short years we’ve gone from having no great alternative writing environments to Word and the other word processors to having a difficult choice between two strong contenders (and that’s discounting the scads of similar but less popular software like CopyWrite, Jer’s Novel Writer, Storyist, or Ulysses, the program that started it all); no choice has exploded into too much choice. Hopefully by focusing on which general approach and specific features are most helpful for your workflow you’ll be able to select the best software for you and get on to what’s really important: your writing.

So this year, I’ve decided to finally jump on the National Novel Writing Month (NaNoWriMo) bandwagon in the hopes that the experience will help me settle into some good writing habits, like writing every morning instead of poking around listlessly online. I will, of course, be writing in StoryMill because I can’t fathom writing in any other software (and yes, I’ve tried pretty much all of the ones available for Mac).

But upon opening StoryMill and prepping a new document for the fast upcoming November 1st, I realized that my typical approach to writing in StoryMill simply isn’t going to work for NaNoWriMo. In order to finish 50,000 words in 30 days, on top of a full time job and other distractions, I’m going to need to write, write, write. Outlining, character backstory, notes on locations, research—all of these will be distractions that could well prevent me from reaching the goal, and yet all of these things are tasks that I regularly undertake in StoryMill. In fact, the program encourages it; take a look at its default novel document:

This is no good at all. Keeping track of characters, scenes, etc. is certainly useful, but I’m going for pure word output, and if the option to procrastinate by expanding on my backstory is available, I’ll probably take it. So to start, I decided to axe absolutely everything except the generic Tasks view, which I renamed to Notes (to delete and rename these items right click a view in the sidebar and choose Manage Views; then when you’re done, right click the smart view and choose Remove View):

I can add those views back in when it comes time to clean things up, and in the meantime I can drop any notes on backstory or whatever into the Notes view as I think of them without feeling any pressure to expand on the ideas. Will my story have more plot holes and inconsistencies than if I’d left those views in? Doubtless. But darn it, I want to win NaNoWriMo! I cannot afford distractions.

Next up, I took a look at the chapters view. I definitely am going to want to write my text in Chapters (the chapters editing window, which you can get to by double clicking a chapter title in the list area, offers numerous incentives like highlighting and annotations that aren’t as easy to use in other views). However, worrying about where my chapter breaks fall is going to slow me down and distract me yet again. I suppose I could just write in a single long chapter, but it would get difficult to manage quickly. Instead, I think I’ll add a new chapter every day. That way I can not only see how many words I was able to write in retrospect (which could be useful info), but I’ll have the story broken up into easily skimmable chunks if I need to go back over it to remember someone’s name or whatever.

Just to prevent any temptation, I also right-clicked on the Timeline button in the toolbar and chose “Remove Item”. Sure, it would never have been activated because I don’t have a scenes view, but the temptation to add a scenes view would be there.

Last, but certainly not least, I double clicked the Progress Meter and set my goals appropriately:

And with that, I’m ready to start writing, as distraction-free as I’m likely to get. I’m sure this system won’t work for everyone (heck, it might not even work for me; I’ve yet to test it out), but my hope is that by slimming down StoryMill to the bare essentials I’ll be able to get my first draft in there as part of reaching the NaNoWriMo goal of 50,000 words, and then I’ll be able to add features like the scenes view, characters, and locations back when I get ready to revise so that I can start cleaning up plot holes and putting a little more thought into the novel. Plus, needing to copy and paste all of my text into scenes will be an excellent excuse to read over it all as part of my revision efforts, anyway.

For other NaNoWriMo participants planning to use StoryMill, here’s a few generic tips to help you out:

• Full screen will likely be your best friend. You can enter full screen quickly from just about any part of the program by hitting command-option-F. Exit full screen by hitting escape.
• As I mentioned above, the Chapters window is probably the best editing experience in StoryMill (aside from full screen). Double click a chapter in the list or sidebar to see what I mean.
• If you’re using a slimmed-down project like I will, you’ll probably also want to avoid spending much time adding tags to things. However, if you drop something in the Notes view it would be a good idea to toss a couple quick tags on it to make sorting through things later easier. For instance, a note about a character could get a “character” tag. Then when it comes time to add the characters view back in you can make a smart view based on notes to filter for all character items and hit the ground running.

Good luck to the other NaNoWriMo participants!

I am such crap at networking. I’ve only attended two conferences so far (An Event Apart and EE Roadshow), but at both I came to the conclusion that the presentations aren’t what the thing’s about. Both times only about half of the presentations were remotely worthwhile, while the others were either senseless cruft or so bogged down by the speaker’s fear of public speaking and/or inability to write coherently that by the end I just wanted to bang my head into the nearest wall a few times. Clearly we aren’t here because web developers are charismatic individuals with a flair for speech-writing.

So I can only assume that it’s the times in between, the meal times and parties, that people find the real value. Those times when you’re expected to wander around, get to know your fellow developers, swap business cards, and talk shop.

Sadly for me, I have no interest in approaching complete strangers and introducing myself. I’ve never had this inclination, which is something that puzzles me. Engage me in conversation, and you’ll find I’m not socially awkward: I am, in fact, an intelligent individual with a good sense of humor who loves interacting with people. Observe me with a group of my friends or family, and you may think me highly extroverted. Yet drop me in a room full of strangers, and I clam up instantly. I know these people are passionate about the same things I’m passionate about, but unless one of them seeks me out I find it hard to think of things to talk about.

I was thinking about this on the bus ride home (I left early, having deduced from fifteen minutes standing around alone that I wasn’t going to get anything out of the after-party, particularly since I don’t drink and thus could not take advantage of the free alcohol), and I’ve finally realized the problem: I’m a presenter. A performer. I’m damn good at giving a speech and then talking to people about it afterward, but no good at being just another member of the audience, milling around and networking.

Problem being, of course, that in both the EE community and the web development community as a whole, I’m a nobody. I haven’t written any books, or published any extensions, or been hired by Happy Cog so it’s unlikely anyone is going to invite me to speak anytime soon.

Guess it’s time to either start the difficult personal work necessary to overcome my awkwardness at initiating social encounters or start submitting topic proposals to my favorite web conference organizers.

Despite my love affair with cinnamon rolls, however, I have never had the courage to experiment with them before. In part, it’s because yeast scares me (my early experiences with yeast bakes turned out poorly, to say the least). Mainly, it’s that I’ve never really had homemade cinnamon rolls that consistently turned out well. Mom would make them occasionally, but they were hit and miss; sometimes delicious, other times passable.

Fortunately for me, and unfortunately for my cholesterol levels, I have at last braved the cinnamon roll and discovered something wonderful: I make damn fine cinnamon rolls, and they’re really, really easy.

Like most of my recent excursions into yeast bakes, my cinnamon rolls start with Artisan Bread in Five Minutes a Day (available via Amazon or on Kindle). I cannot recommend this book highly enough; it is a brilliant introduction to bread baking that makes the task not only easy but quick. Like any baking, it takes a couple tries to figure out exactly how things work, but although my first attempts at recipes and doughs typically don’t end up quite like I planned, I’ve only had a single total disaster (my first attempt at naan was carbonized thanks to following the book’s instructions to heat the skillet on high prior to cooking the bread). If you’ve tried and been frustrated with yeast baking before, you’ll understand what an astonishing track record that is for a beginning baker.

If you have any interest in making fresh bread, go buy the book. You’ll need it to make cinnamon rolls my way, anyway, because they rely on the dough recipes and preparation methods that are the core of the book. Specifically, Artisan Bread in Five provides a Caramel Sticky Buns recipe on page 187, which will be your starting point. The key is instead of the rigamarole of coating the bottom of the pan and turning things upside down once you finish baking, etc. you’ll want to use this easy cinnamon filling:

Cinnamon filling
1 cup packed brown sugar
2 1/2 tablespoons ground cinnamon

Mix the brown sugar and the cinnamon together. You’ll have enough for 2-3 batches of cinnamon rolls (depending on how liberal you are with the sugar and how large you make the cinnamon rolls), so store it in a tupperware or similarly air-tight container for later.

After you’ve rolled the dough out into a rectangle as per the sticky bun recipe, spread all of it except for 1/2-1 inch around the edges with softened butter. I’m usually a bit more liberal with the butter if I’m using the master recipe, but particularly if you’re using brioche dough (which makes the richest, most desert-like cinnamon rolls) you’ll want to be a bit conservative with the butter. You just need enough to coat the dough with a thin layer.

Once you’ve spread the butter, sprinkle it liberally with the cinnamon-sugar mixture. You want to have enough cinnamon-sugar that you can’t see any dough or butter peeking through (except for the strip around the edge of the dough, of course). If you’re particularly liberal with the cinnamon-sugar, you’ll likely end up with a sticky goo at the bottom of the rolls similar to the stuff you’d find in a Cinnabon. Use a little less, and you’ll have a more subtly-flavored rolls that’s a bit cleaner to eat.

Roll and cut the dough as per the sticky bun recipe. I usually use a greased 9×9 glass pan, and always end up with nine rolls (counting the two end ones) each about 1-2 inches high. You can, of course, make more or less depending on how much dough you’ve got and the size of your pan. Place the rolls in the pan with a little bit of room between each one (they’ll spread out as they rise), and cover lightly with plastic wrap.

Whether the rolls rise or not will depend on the temperature of your kitchen. I often need to place a second 9×9 pan filled with hot water under the one with the rolls for 20-40 minutes of the rising time, since my kitchen tends to be cooler. Ideally, the rolls should rise upwards and outwards both, so that they are just touching their neighbors.

Bake according to the sticky buns recipe, about 40 minutes. Baking time will fluctuate depending on how large your rolls are, so start peeking around 30 minutes. Serve warm, preferably with some icing (I leave it to you to find a good icing recipe online; we typically just mix some powdered sugar with water and drizzle it over the warm rolls).

I’ve tried using brioche dough and the master recipe both, and the cinnamon rolls turn out great either way. As you would expect, the brioche-based rolls are richer and more buttery, while the dough of the master recipe rolls takes more of a backseat to the filling. I’m itching to try the challah dough because it’s in between the two as far as eggs and butter content goes.

The only downside to this recipe is that it takes roughly two hours from when you decide to make cinnamon rolls and when they’re ready to eat, thanks to the rising and baking time (even if it’s passive time, it still makes it hard to make cinnamon rolls for breakfast before work). If anyone has any ideas for how to prep the rolls in the evening and have them ready to bake in the morning, I would love to hear them.

Even if I never find a way to cut down on the rising and baking time, though, needing to think ahead two hours is a miniscule price to pay considering that the payout is a dish that has warmed, comforted, and delighted me since childhood.

One Crayon now looks several orders of magnitude better than its original design; offers information and documentation for TEA for Espresso, TEA for Coda, and my other projects in a single unified location; and offers numerous other improvements like a news feed for keeping up to date with general One Crayon news and updates to my various software projects.

I’m not actively seeking freelance work thanks to a busy full time schedule, but I’ve been wanting to revitalize One Crayon for a while, not least because I wanted to start migrating some of my sites over to ExpressionEngine and One Crayon seemed like a good place to start.

There are still some rough edges (I’m looking at you, IE 6) and I haven’t added my website or writing portfolios, but I hope you’ll enjoy it anyway!

So just what the heck is TEA for Espresso? Simply this:

1. A selection of my favorite text actions, mostly (but not entirely) copied from Textmate
2. Generic actions that allow you to create variations on TEA’s bundled functionality to suit your workflow by editing simple XML
3. A general framework for coding and running text actions in arbitrary languages without needing to create a Sugar or (for third party Sugars) without needing compiled Objective-C classes

Espresso’s Sugar API was already pretty sweet. TEA makes it that much better by lowering the barrier to creating custom text actions for users and Sugar developers alike.

Documentation for TEA is currently limited to info on creating your own actions, so I’ll walk you through the basic actions included with the plugin.

The vast majority of TEA’s built-in actions focus on making HTML easier to edit, because editing HTML is most often why I need a text editor.

Generic text actions

Spaces To Tabs… and Tabs To Spaces…
As you might expect, these actions convert the type of indentation in your document or (if it exists) your selected text. When you run the actions you’ll be prompted to enter the number of spaces per tabs you wish to use (it defaults to whatever is in your Espresso preferences, so you can just hit enter most of the time).

Trim Line(s)
Trim Line(s) will, when invoked, either trim all of the lines in your selection or the current line the cursor is on (if no selection exists). Unlike some trim lines actions, TEA’s Trim Line(s) attempts to be smart about what whitespace it removes:

• All whitespace at the end of the line will be stripped
• Any whitespace at the beginning of the line that isn’t part of the indentation will be stripped

What the latter means is that if in the Espresso preferences you have the program set to use spaces instead of tabs with four spaces per tab, and the beginning of a line has ten spaces, two of the spaces will be stripped.

Select → Word, Select → Line, Select → Line Contents
As you might expect, these actions select the word under the cursor, the line under the cursor (including leading and trailing whitespace), or the textual contents of the line under the cursor (excluding leading and trailing whitespace), respectively.

Sorting → Sort Lines (Ascending) and Sorting → Sort Lines (Descending)
As you might expect, these actions sort all lines in the selection (or document, if no selection) in ascending and descending order, respectively.

Sorting → Randomize Lines
This randomly sorts all lines in the selection (or document, if no selection).

Sorting → Remove Duplicate Lines
If for some reason you need to strip all duplicate lines from your selection or document, this is the command for you.

Formatting commands

Indent New Line (command-shift-enter)
One of my favorite parts of Textmate is that after creating an HTML tag, I only have to hit enter once to get a perfectly indented tag pair with the cursor in between and bumped in a level. The fact that Espresso doesn’t do this irks me greatly, and so this action allows you to force the issue. Indent New Line will turn this (pipe represents cursor):

<div>|</div>

Into this:

<div>
    |
</div>

If you have any text selected when you run the action, the selected text will be moved to the middle line and indented.

Insert Linebreak(s) (control-enter)
In HTML, Insert Linebreak(s) will insert a break tag (<br />). In some other contexts (like PHP double quoted strings), it will insert \n. In Markdown it will insert two spaces and a linebreak. If you have one or more selections, the tag or textual linebreak will be inserted at the end of each selection.

In case you didn’t quite catch that, Espresso allows you to have multiple selections (hold down command while you select multiple items with your mouse), and this action will affect all of them. This is extremely cool, and one of the features that I’m still learning to use; before now, I’d never come across a text editor that allowed me to so much as select multiple items at once. Of course, it isn’t all that often that you need to append br tags in a whole bunch of places around a document, but what about when you want tags for…

Strong (command-B) and Emphasize (command-shift-I)
These do about what you’d expect. If you have one or more selections, they’re surrounded with strong or em tags. If no selection, you get a tag wrapping your cursor. Incidentally, if you’re working with a single selection (or no selection) you’ll get a text snippet with tab stops, so hit the tab key to edit what’s inside the tag.

A note on Emphasize’s shortcut; command-I by default is used to show and hide the navigator sidebar, hence this somewhat odd shortcut for italics. If you wish to switch the shortcuts, you can do so through the System Preferences Keyboard & Mouse controls.

HTML actions

Entities → Convert To Named Entities (control-&) and Entities → Convert To Numeric Entities
Run one of these actions to have the character immediately to the left of the cursor converted from Unicode into an HTML character entity. If you have one or more selections, all non-ASCII Unicode characters will be converted to entities of the desired variety. If using named entities, Unicode characters without a named entity will still be converted to their numeric equivalent. These actions will also convert ampersands (but will ignore ampersands that are already part of an entity).

Entities → Insert Non-Breaking Space, etc.
Use these actions to quickly insert the named HTML entity for the given character.

Expand Abbreviation (control-,)
This action is much like Textmate’s “Insert Open/Close Tag (With Current Word)” which, when I saw it demoed in a screencast, changed my life. For far too long had I been toiling away, typing out every blessed less than/greater than symbol. With Expand Abbreviation, I merely type the HTML tag, hit the shortcut, and voilà. I have the complete tag ready to go with barely any effort at all.

And the fun doesn’t stop there! The reason for the action’s name change is that Expand Abbreviation is powered by the fantastic zen coding project, so in addition to Textmate’s functionality Expand Abbreviation offers the full range of zen coding abbreviations and CSS-selector style syntax to create complex markup from very simple declarations. Here’s a quick example of zen coding’s awesomeness:

div#stuff.things.booyah

Type that, hit control-, and you’ll end up with this (pipe represents cursor):

<div id="stuff" class="things booyah">|</div>

Or if you want to do something a little more complicated:

div#nav+div#content>p.item$*2

Which leads to this:

<div id="nav">|</div>
<div id="content">
	<p class="item1"></p>
	<p class="item2"></p>
</div>

And that’s just the tip of the iceberg. Zen coding offers numerous other selectors and scads of abbreviations for HTML and CSS. All of them will work with Expand Abbreviation.

You may also, if you need, use the old Textmate-style tag creation where you type out everything in the tag except the carets, highlight it, and run it through Expand Abbreviation to get a full tag. For instance, this:

div style="width:100%;"

Once selected and run through Expand Abbreviation leads to this markup:

<div style="width:100%;">|</div>

If there is no selection, this action will use the current word regardless of where the cursor falls in it (Textmate will only parse to the left of the cursor).

Wrap Selection In Tag (control-shift-W)
As you might expect, if you select some text and invoke Wrap Selection In Tag, the selection will be wrapped in an HTML tag. Just like in Textmate, you can type out tag attributes and they won’t be mirrored to the closing tag, and moving outside the tag is a tab away.

Wrap Selected Lines In Tag (command-control-shift-W)
This one acts just like Wrap Selection In Tag, except that each line in the selection is wrapped.

Wrap Selection In Link (control-shift-L)
Unsurprisingly, selecting some text and invoking this command will wrap it in an HTML link tag. What makes this action more worthwhile than some of the others is that if you have a recognizable link on your clipboard it will be inserted, and there are several tab stops set up to make removing or editing the link’s title extremely easy. Unlike Textmate, this action does not attempt to populate the title from the actual webpage’s title. I’ve had Textmate hang while it waits to retrieve the webpage too many times to want to implement that functionality myself.

If you use this action while editing Markdown or Textile, the selection will be wrapped in a Markdown or Textile link rather than an HTML anchor.

Documentation For Tag (control-H)
If your cursor is inside an HTML tag, you can run Documentation For Tag to have the word under the cursor (or the selection) searched for in HTMLHelp.com’s HTML reference. If the cursor is inside an HTML tag, you’ll be taken straight to the first result (almost always the correct tag page). Otherwise, you’ll get a Google result listing.

TEA Preferences

TEA → Preferences offers a GUI to modify some TEA-related preferences. You’ll need to have a document open in order to access the prefs due to limitations in how Espresso sets up actions.

General Prefs
Checking “use XHTML by default” will cause TEA-based snippets that use the $E_XHTML variable to leave it blank. At some point in the future, TEA will hopefully be more intelligent about detecting whether a document is HTML or XHTML, but for now you’ll need to control it using this preference.

Similar to Textmate, anything entered in the Custom Shell Variables section of the preferences will be available as an environmental variable to any shell scripts you run through TEA. For instance, if you add a variable with the name “MY_CUSTOM_VARIABLE” and the contents “I love TEA!” then wherever you use the shell environmental variable $MY_CUSTOM_VARIABLE you’ll get “I love TEA!”

Actions
If you check “Enable custom user actions” you will be able to create custom actions without needing a custom sugar. This is useful not only for custom TEA-based actions, but for custom actions using third party sugars, as well.

Beyond the bundle

If TEA’s included actions aren’t enough for you, it’s extremely easy to add your own custom actions, port actions from Textmate bundles, and otherwise use TEA to jumpstart your own Espresso customizations. The TEA for Espresso wiki has lots of info on this sort of thing, or you can take a look at the HTMLBundle.sugar’s source for an example of porting Textmate snippets and bundle items (the HTMLBundle.sugar may also be of use to other folks who want Textmate’s HTML tab completions, among other things; download it here).

I’m also usually available in the forums or Espresso IRC channel if you have questions about using TEA, feature requests, bug reports, or other comments. Alternatively if you have a GitHub account, you can file bug reports and feature requests directly into the TEA for Espresso Issues tracker.

I hope you enjoy TEA with your Espresso!

I’ve tried and discarded NewsFire, Vienna, NetNewsWire, NewsLife, Times, and many others which were on my computer such a short time they don’t deserve a mention. None of them fully satisfied my needs.

Most recently, I decided to give Fever a try. Though I highly dislike web apps (I’ve never found a web app that was remotely as good as its desktop counterparts, mainly thanks to speed and usability issues), I love Mint and figured that maybe, just maybe, Shaun Inman would be the one who could write a web app that was actually useable day to day.

Sadly, my hopes were dashed. Fever is too slow to handle the speed that I can skim through feeds, and has some of the same problems that drove me from NewsFire (like refreshing automatically and losing your place in whatever you’re viewing after an update). I find that I never use the “Hot” functionality because it is so useless at actually predicting what I’ll find interesting (partially thanks to my lack of Spark link blogs, but others have had similar issues), and as a result Fever for me has turned out to just be a rather unresponsive generic feed reader.

(Side note: I haven’t been happy with Fever, but I’d still hesitantly recommend it for some people. Simply the fact that its capable of standing up with options like NewsFire and NetNewsWire is a big point in its favor if you don’t mind the Ajaxy slowness.)

Despite my rampant discontent, I still do not want to code a feed reader myself, so on the off chance that someone is trying to make the perfect feed reader, here’s what it needs.

Make sure keyboard navigation is easy to use. This is the part of Fever that I enjoy most. Hit space bar to jump to the next item. Right arrow opens the item in the browser. Enter swaps between excerpt and full text. Left arrow jumps back to the source list to select a different group. Brilliant.

Allow grouping items by source feed. NewsFire does this beautifully, but for some reason none of the other feed readers have even attempted it. I typically want to read or skim items based on which feed they’re in, and grouping items visually by feed makes it very easy for me to do so. Sticking the source website in a column, or under the title, or over the title, or next to the title does not work as well.

Don’t use a three-pane interface. Mail is a brilliant application for reading email. Feeds are not email. Go use Fever, NewsFire, or Times and find out why designing a great, feed reader-specific workflow is a better plan than rehashing the tired old three-pane news reader.

Settings should be possible to apply per feed, per group, or as application defaults. I love that NetNewsWire and Fever both allow me to granularly set behavior preferences for feeds. Setting refresh rates on a per-feed basis is rarely necessary, but when you need it you’ve got to have it. When I was hunting up freelance work, I subscribed to a few Craig’s List feeds. I eventually had enough work that the feeds were just noise, so (thanks to NetNewsWire), I stuck them in a group and turned off refreshing for that group. They were ready for when I needed them in the future, but out of my way for now.

Don’t sacrifice performance for aesthetics. Times, I’m looking at you. Times is a beautiful feed reader, with an innovative approach to feed reading, and a great set of features. I’d be using it right now if it weren’t buggier than an anthill. The somewhat recent 1.1 update fixed a lot of the really annoying bugs, but the program still isn’t usable. Maybe in another few point updates.

Don’t sacrifice aesthetics for performance. Hi, NetNewsWire! To be fair NetNewsWire mitigates this problem somewhat by offering some really top-notch themes, but although the application is certainly solid and obviously has been given a lot of attention to detail, it could still use a bit of the flair of NewsFire, Times, or Fever. I think there’s a middle road here, and on that middle road a talented designer and talented developer are collaborating. Sadly, feed readers appear to be primarily one-man-in-his-basement affairs.

Remember that users will subscribe both to feeds they want to read every word and those they merely want to skim. Times and Fever are both best for feeds that you want to focus on every headline. NewsFire is great for skimming through lots of headlines thanks to its group-by-feed feature. NetNewsWire is actually pretty good at both, as long as you’re careful about how you sort feeds into groups. The problem here is that the needs (and thus best interface) for feeds with lots of signal versus feeds with lots of noise are quite different, yet feed readers invariably only offer a single interface for browsing and accessing feeds (or offer multiple possible interfaces, but you have to switch between them globally for the whole program). I don’t know what the perfect solution is here, but I do know that it can only exist if the program recognizes that I have two very different approaches to feed reading and provides options accordingly.

Perhaps I’ll never see my perfect feed reader, and instead be destined to keep bouncing between substandard options as they release new upgrades and rekindle my hope that maybe this time they’ll have gotten it right. Perhaps Mac OS X feed readers simply aren’t profitable enough to attract the time and care necessary to craft something that does everything I want without being bloated and terrible, and I’ll eventually just have to suck it up and go with a web app.

But I hope that isn’t the case.

My other favorite time estimator is Stuffit, which back when I still used it would tell me that files would be completely unstuffed anywhere from -16,000 to 1,000,000,000 minutes. I never was sure how a file could have been unstuffed in negative minutes. Possibly Stuffit was trying to tell me that it had been unstuffed once before in the past, so why the hell was I opening it again?

If you’d like to get a great feeling for Braid take a moment to read through the Official Braid Walkthrough. I promise, it won’t spoil anything. Quite the contrary.

Early on when I was playing the game, I got frustrated at one of the puzzles and resorted to the internet to find a walkthrough with some pointers. I stumbled across the official one, read it, and rather sheepishly returned to the game without looking further (incidentally solving the puzzles that I’d had trouble with after leaving them alone for a while and coming back).

But the day that I beat the game, I cheated for real. In my defense, one of the puzzles that I sought help-via-walkthrough on was something I probably wouldn’t have figured out without some sort of hint, dumb luck, or an outside opinion.

For the second puzzle whose solution I looked up, though, I was just being lazy. I had one puzzle left, as far as I could tell it was impossible, and I wanted to beat the damn game and go to bed. After reading the solution, I realized that it was far from impossible, that if I had slept on it one more night and come back with a fresh perspective I would doubtless have figured it out for myself, and that I had just cheated myself out of the pleasure of discovering a solution on my own.

Which makes me wonder; when did beating the game become so important to me?

I don’t really know for sure, but I suspect I have beat maybe only 25% of the video games I’ve ever played, and most of those I completed before I entered junior high. This is in part thanks to the fact that my prime game-playing time (high school and college) I spent working for Inside Mac Games where it was more important to play lots of games than to play games to completion. Even for games that I loved and had a compelling reason to finish (like a few of Spiderweb Software’s games) I inevitably got interrupted by something new that needed to be played and written up; a few interrupted games I went back to and finished, but many more I simply let fall to the wayside. The rest of the reason that I have such a rotten record for games that I’ve beaten compared to when I was young is that I can now afford to just buy a new game if something ends up frustrating or annoying me. When I was in elementary school, Riven pissed me off more times than I can count. I constantly came up against impassable obstacles, and there were weeks or more when I would leave the game alone in disgust and frustration. I couldn’t afford to buy any other games, though, thanks to my all but non-existant allowance, so I kept coming back to Riven until I finally beat it.

Given my record, beating a game isn’t high on my list of priorities. Hell, just looking at my Xbox arcade collection proves that; of the twenty-two I own, I’ve only beaten two (one of which was Braid).

Which brings me back to the question: why was beating Braid important enough to cheat myself out of further time with it? I know, both from experience and from the official Braid walkthrough, that the journey is the reward and sometimes all you need is a good night’s sleep for a puzzle to open up to you. And I still ruined it.

My temptation is to blame the internet. The games I remember most fondly are the old LucasArts adventure games (Indiana Jones and the Fate of Atlantis, Sam & Max, Day of the Tentacle, The Dig), and I played them through either before my family had internet, or when walkthroughs were harder to find. In a way, I couldn’t find spoilers, so I couldn’t spoil myself.

That argument, however, is unfair. The problem isn’t that walkthroughs exist and are easy to find. I actually prefer information to be readily available; there’s nothing worse than having something in a game you can’t solve that you’ve been working at for days with no luck, and then being unable to find any information online to help you. The fault lies somewhere else.

I think the real reason that I became so focused on beating Braid, despite knowing better, was because I have become accustomed to games having some worthwhile content that is then expanded with mountains of filler. A game of Braid’s caliber, where every puzzle is lovingly crafted and unique, took me completely by surprise.

And that makes me sad, both because the game industry as a whole is so focused on quantity rather than quality and because I as a gamer have reached a point where I’m so immured to games without redeemable qualities past the bullet points on their boxes that I unintentionally spoil the few gems that I do come across.

If you have not yet come across Braid, I urge you to learn from my mistakes: don’t just beat the game; play it.

Pete Joison’s artwork, in all its forms, makes me so very, very happy.

In the hopes that I could take the RSS feed and remix it easily on my own, I turned to Yahoo Pipes. Yahoo Pipes provides a relatively easy graphical interface to parse, modify, and combine data streams, JSON, and RSS and spit it back out as RSS, JSON, or PHP serialized code. I first discovered Pipes when I found someone’s “lifestream”, a website that displayed a list of their activity across numerous different services using Yahoo Pipes. These kind of RSS feed mashups seem to be the most common use of the service, but the service is quite flexible so it seemed well suited for repurposing Tumblr’s RSS feed to my own uses.

Over the course of creating the feed, I discovered some interesting features that I feel are worth sharing. For those of your who are curious about my specific implementation, here’s the actual pipe that is powering beckbits.

Moving data between elements

Very early on in my exploration of the default Tumblr RSS feed I realized that I was going to need to use the Tumblr API if I wanted to get direct access to the various components that make up Tumblr posts. Of course, the API provides completely different elements than an RSS feed, so one of the main tasks of my pipe is to move data around between elements.

For things with a one-to-one relationship, the “Rename” operator typically does the trick. For instance, using the external site’s URL for the RSS item link on Tumblr link items was as easy as throwing in a Rename with the rule “item.link-url renamed to link“.

But what about when I needed to combine multiple fields into one? Rename certainly wasn’t going to help me there, and I couldn’t find any way to pipe data between operators and string functions.

Fortunately, the Regex operator came to the rescue.

Although I couldn’t find any documentation for this, the regex module offers a couple great features:

• If you reference an element in the first column that doesn’t exist, it will be created.

• You can include the contents of other elements using the “named backreference” syntax (${element-name}). For instance, when I wanted my description element to include both the Tumblr “quote-text” and “quote-source” elements the “replacement” column looked something like this:

  <blockquote>${quote-text}</blockquote><p><cite>${quote-source}</cite></p>

Simple conditionals using regex

Thanks to the fact that everything in a Yahoo pipe is evaluated sequentially, you can use the regex operator to setup simple conditionals. For instance, regular Tumblr posts have an optional title. If the title existed, I wanted to use it as my RSS item’s title; otherwise it should default to a short excerpt of the text. To accomplish this, I setup the following rules:

Rename
item.regular-title copy as title

Regex
In item.title replace (.*) with $1```${excerpt}
In item.title replace ^```(.*)$ with $1
In item.title replace ^(.+?)```.* with $1

The basic idea is to combine two fields into one separated by some delimiter characters that are unlikely to ever show up otherwise. I chose to use three backticks, since it kept things pretty legible and I rarely use backticks. If you’re not comfortable with regex, the rules in order say:

1. Copy regular-title to title (because regular-title might not exist, this may result in an empty title element)
2. Append ``` plus the excerpt element to whatever is in the title element
3. If the title element starts with backticks (^```), replace its contents with whatever follows the backticks (the excerpt)
4. If the title element starts with one or more characters followed by backticks (^(.+?)```), replace everything with that starting content

Replacing your site feed with a pipe

Once I’d created my pipe it was time to replace beckbits’ feed with the pipe, and I discovered that Yahoo Pipes has a serious downside when it comes to using it instead of your default site feed: the pipe’s output always links back to the pipe page as the feed’s homepage. Although this wouldn’t be a huge deal, it has the unfortunate side effect of causing the favicon associated with your feed to be the Yahoo Pipes favicon, which is extremely non-ideal. In order to fix this, you actually have to post-process the pipe output.

For myself, I opted to do this by reading in the pipe as serialized PHP and then constructing my own simple RSS feed. If you’re interested in doing something similar and would like a starting point, here’s the gist of it.

The truth is, I’m a problem-solver. Every day, I sit down at my computer and I solve people’s problems. Perhaps the problem is that Client A wants a site that they can update themselves. Or maybe my coworker needs me to figure out why the heck their code is breaking in some browsers but not others. And sometimes Client C just has to have a rainbow unicorn spring out of the middle of the page and dance on the user’s mouse cursor in a paroxysm of misused Javascript. The problems change day to day and project to project.

I’ve now been solving problems professionally for over a year and a half, and I’ve found that in the course of solving problems I often discover information and tools online that are extremely useful for web work. Up until now, I haven’t done much with these tidbits aside from occasionally bookmarking them.

No longer! I am pleased to announce beckbits, a collection of links, tips, and other tidbits that I discover during my day job and would like to share with other web problem-solvers. Aside from links to useful resources that I’ve discovered, I may occasionally post software or productivity tips, links to my most recently completed sites, and other minor items that relate to my work as a web professional.

Enjoy!

Obtaining numeric HTML/XML entities is easy enough; I found several different ways to do so in a quick Google search, this being the easiest (text is just an example variable):

text = text.encode('ascii', 'xmlcharrefreplace')

However, it is significantly more difficult to find a way to encode text as named character entities, which if you’re ever going to need to look at the markup later is vastly preferable. After a lot of digging, I discovered some basic logic for named HTML entities in the Python Cookbook. After improving on it to make sure that all entities get replaced (even high level ones without named equivalents) I’ve got something that others may find useful in turn. Simply place this code into a file called named_entities.py and stick it somewhere that your script can find it (or just stick the code at the top of your file, if you only need it in one place). Usage info is in the comment at the top of the code.

Please note that this code is for Python 2.x. Python 3 moved codepoint2name into html.entities.codepoint2name, so you’d need to modify the import.

'''
Registers a special handler for named HTML entities

Usage:
import named_entities
text = u'Some string with Unicode characters'
text = text.encode('ascii', 'named_entities')
'''

import codecs
from htmlentitydefs import codepoint2name

def named_entities(text):
    if isinstance(text, (UnicodeEncodeError, UnicodeTranslateError)):
        s = []
        for c in text.object[text.start:text.end]:
            if ord(c) in codepoint2name:
                s.append(u'&%s;' % codepoint2name[ord(c)])
            else:
                s.append(u'&#%s;' % ord(c))
        return ''.join(s), text.end
    else:
        raise TypeError("Can't handle %s" % text.__name__)
codecs.register_error('named_entities', named_entities)

One last thing: whether you use numeric or named entities, you’ll probably want to encode ampersands afterward. Here’s the regex that I’ve been using to do so, and it’s safe to run on the output of either the named or numeric entity creation code (remember to import re before trying this at home):

text = re.sub('&(?!([a-zA-Z0-9]+|#[0-9]+|#x[0-9a-fA-F]+);)', '&', text)

Enjoy!

That said, I have to admit that my feelings about this release are mixed, and I don’t think that most people who live in their text editor (including myself) will be able to switch to Espresso full time just yet. I’m beginning to think that this may just be how text editors work. I was completely underwhelmed by Coda when it first came out, too, but after Coda 1.5 I tried it again and started migrating projects to it, and as of 1.6 I’m using Coda full time. While some people will find Espresso 1.0’s friendly and simple editing just what the doctor ordered, I suspect that its wider appeal will not be truly realized for another few point releases.

None of which, of course, answers the question, “Is Espresso for me?” Obviously, you won’t know until you try it out for yourself, but for those of you who like to have other people do the initial dirty work, here’s what Espresso is, what it is not, and where it’s probably headed in the near future. (Please note that I don’t have any insider info; I have been participating in the betas since slightly before they went public, however, and would like to think that my guesses are fairly educated.)

In many ways, to understand Espresso you first need to understand what it is not.

Espresso is not CSSEdit

Before you so much as think about downloading Espresso, you need to be clear on one thing: Espresso is not CSSEdit. Yes, you can edit CSS files with Espresso, but it does not offer visual CSS editing, and X-ray and the inspector are nowhere to be seen. You can override stylesheets, CSSEdit groups are supported in the code navigator, and the CSS text editing is very similar, but if you are expecting CSSEdit plus the ability to edit HTML you will be sorely disappointed.

I’m going to make a prediction here (and yes, it’s just a prediction; I have no insider knowledge): I think that Espresso will get X-Ray in a point release. I think it will probably get the inspector and the ability to jump straight from the Inspector to a style in the CSS. But I don’t think it will ever get CSSEdit’s visual editors. Why?

Because competing with yourself is stupid.

CSSEdit is the best way to edit CSS (right now, anyway). Espresso is shooting to be the best way to edit code, no matter what the language.

Perhaps someday MacRabbit might want to merge CSSEdit into Espresso and retire their original flagship product, but don’t hold your breath.

All that said, I’m as baffled as the next guy why you can’t right click a CSS file in Espresso and choose “Edit in CSSEdit”.

Espresso is not Coda

Particularly when MacRabbit announced Espresso and showed off screenshots of an integrated FTP editor I think a lot of people assumed that Espresso was setting out to be an all-in-one editor to challenge Coda (albeit much more slimmed-down). “Hooray!” cried the masses. “Perhaps at last we’ll have an all-in-one solution with a decent text editor at its core!”

The masses were a ways off the mark. Coda attempts to give you every tool you’re likely to need to edit code. Espresso tries to give you a fantastic environment for editing web pages with an extensible Sugar architecture to allow you to expand the editor to other languages. Notice how different those two sentences are.

If you love Coda because of the diverse tools that it gives you, you’ll probably be underwhelmed by Espresso. However, if the shortcomings of Coda’s text editor rub you the wrong way and you don’t very often find yourself using SVN, books, the terminal, etc., then Espresso might be a wonderful solution to your needs.

Espresso 1.0 is a foundation

In many ways, Espresso is building off the legacy of Textmate, if you can say that a piece of software that’s still nominally developed and actively used has a legacy. Text snippets with tab stops and mirrored segments directly mimic Textmate’s snippets and the Sugar syntax system is fairly Textmate-y, as well. Where Textmate provides extreme flexibility with a correspondingly steep learning curve, Espresso attempts to provide some of the core aspects of that flexibility but focus on providing users with a more polished, CSSEdit-ish application.

Espresso 1.0 is a foundation, a solid feature-set that shows the core capabilities of the program and through its scope and design may give you a good idea of what directions the application is likely to grow. When I first read MacRabbit’s descriptions of Espresso I immediately began imagining the possibilities, and every time I launch it I find myself imagining possibilities again. It has the potential to grow into an application almost as flexible as Textmate, but easier to extend and with a friendlier interface that also happens to offer the core features needed for web development.

Aside from its potential, Espresso 1.0 is a powerful text editor that’s overly focused on web design with a few rough edges tucked away beneath the overall gleam of its interface. It’s better than most of the web-centric offerings, but may not be quite good enough to lure you away from heavy hitters like Textmate, Coda, or the venerable BBEdit.

If you’re looking for a simple yet powerful web-oriented text editor with a lot of flexibility and promise for growth, I highly recommend giving Espresso a download. As long as you don’t go in expecting CSSEdit, Coda, or something that will turn into a magical unicorn and solve all your problems you should be pretty pleased with what you find, even if, like myself, you’re unlikely to be able to switch to using it full time for your day job until the application is a bit more mature.

That’s nice; what about TEA?

I haven’t been talking about TEA for Espresso much because although I’m ecstatic that it was one of the few Sugars chosen to be included in the application, it frankly wasn’t ready. I still consider it in beta even if Espresso is out, and because I didn’t know that it was going to be bundled in the application until the morning the app was released, some of its better features are broken. Once I’ve got it in a more mature place, I’ll definitely brag about it a bit more and offer some examples of how to use it; for now, please give me a shout in the Espresso forums if you have any feedback, requests, or bug reports.

For those of you who prefer source to exposition, the project that I’ve been working on is TEA for Espresso and you can find the full source code over at the TEA for Espresso project on GitHub. As you may have surmised, it’s a plugin for the upcoming Espresso text editor created because I wanted to play with Espresso but am addicted to Textmate-style HTML actions.

My personal preference for Python is to use four spaces rather than a tab for indentation, so keep that in mind if you’re trying to execute the code samples below and your document is using tabs.

Using py2app to create semi-standalone code

Py2app allows you to work completely in Python without ever needing to boot up Xcode and touch Objective-C. There’s plenty of information around the web about how to setup a basic py2app setup.py file, but one of the things that I had to discover via trial and error was how to make my code semi-standalone.

Semi-standalone is an option you can enable with py2app that makes your code reliant on the version of Python that is installed with the OS. By default, py2app tries to bundle any dependencies for your project into your bundle, but if you’re only distributing the bundle/plugin/app/whatever to people using the same major OS version this makes for about 15 MB minimum of unnecessary junk getting tossed into your bundle.

Turning on semi-standalone is as simple as adding a key to your py2app options dictionary, but what you might not know is that you also need to enable site-packages, as well (which apparently encourages py2app to create the links to Python necessary for getting the bundle up and running, although it’s only supposed to tell it to include the system and user site-packages in the system path). So to get a semi-standalone bundle, your code needs to look something like this:

setup(
    name='My Plugin Bundle',
    plugin = ['MyPluginBundle.py'],
    options=dict(py2app=dict(
        extension='.bundle',
        semi_standalone = True,
        site_packages = True
    )),
)

One of the most frustrating aspects of working with py2app for me was the lack of any decent documentation on the main py2app site. Fortunately, there’s a much more comprehensive page of documentation available in the MacPython py2app SVN repository, which is where I discovered the site-packages option.

Automatically including project data files

Odds are since you’re using Python you’ll need to include some arbitrary data files with your application, be they NIB files, extra Python scripts and classes, or whatever else. However, py2app’s method of declaring what files you want included with your project is to list them explicitly in a data_files array. This is a major pain, since every time you add or remove a file you have to remember to edit setup.py. No thanks.

Fortunately, Python comes with some powerful file system modules that allow you to traipse around your file system, making note of files and folders as you go. The following code snippet, if included in your setup.py script, will automatically parse through a directory of files and add them to your data_files array without you needing to lift a finger (assuming that you configure the first couple variables to fit your project, that is). Files that start with a period (hidden files) will be ignored. If you’re using SVN, you may also need to add some logic to exclude folders that start with a period (TEA for Espresso is using Git, so this hasn’t been an issue for me).

The downside to using this code, of course, is that you’ll need to nest all your files in the directory structure that you want in your final bundle. So, for example, in order to include something in the Resources folder for TEA for Espresso, I have to nest it in src/Contents/Resources/ whereas I otherwise could have placed it in the root project directory. If you’re doing a simple project with very few files, it might be more worth your while to define data_files differently.

import os

# Sets what directory to crawl for files to include
# Relative to location of setup.py; leave off trailing slash
includes_dir = 'src'

# Set the root directory for included files
# Relative to the bundle's Resources folder, so '../../' targets bundle root
includes_target = '../../'

# Initialize an empty list so we can use list.append()
includes = []

# Walk the includes directory and include all the files
for root, dirs, filenames in os.walk(includes_dir):
    if root is includes_dir:
        final = includes_target
    else:
        final = includes_target + root[len(includes_dir)+1:] + '/'
    files = []
    for file in filenames:
        if (file[0] != '.'):
            files.append(os.path.join(root, file))
    includes.append((final, files))

setup(
    name='My Plugin Bundle',
    plugin = ['MyPluginBundle.py'],
    data_files = includes,
    options=dict(py2app=dict(
        extension='.bundle'
    )),
)

Avoid release statements in Python

I’m sure this is extremely obvious for anyone with significant PyObjC experience, but TEA for Espresso lay fallow for over a month after I started it because I couldn’t get the example plugin ported from Objective-C to Python. It turns out that almost everything in Objective-C can be easily ported to Python using the simple conversion rules (colons to underscores, etc.; see the PyObjC intro for more info), except for any calls to release objects. For instance, here’s the code that was breaking my project:

Objective-C
[selectedRanges release];

Ported into Python (don’t do this!)
selectedRanges.release()

PyObjC auto-releases absolutely everything, so don’t port lines like the one above. They will break your project. This is actually described in the PyObjC introduction if you’d like a more technical explanation; apparently I just missed the significance of it when I read the intro the first time.

Handling **NSError arguments

If you’re implementing a bundle that will be loaded into another application, odds are you’ll need to implement an Objective-C protocol in Python, and Objective-C functions occasionally have an **NSError parameter. If you’re not going to be returning any error information, you can safely ignore the **NSError in your Python code. The bridge automatically handles it. If you might return an error, then you may find this thread on the PyObjC-dev mailing list useful.

For example, for TEA for Espresso I needed to implement this Objective-C method in Python:

- (BOOL)performActionWithContext:(id)context error:(NSError **)outError;

Since I’m never returning any error information, in Python this translates to:

def performActionWithContext_error_(self, context):

Although woefully out of date in some respects, one of the most useful and understandable sources of information about using **NSError with PyObjC I found was Apple’s PyObjC for Developing Cocoa Apps page.

Implementing Objective-C interfaces without a protocol

An interesting problem that can arise if your bundle is implementing an Objective-C interface (rather than conforming to a protocol) is that when your code is loaded you may find that Objective-C can’t find your class methods. To solve this, usually all you need to do is explicitly define the type encoding of your class method. For instance, TEA for Espresso’s main bundle class has the following method:

class TEAforEspresso(NSObject):
    @objc.signature('B@:@')
    def canPerformActionWithContext_(self, context):

The @objc.signature() decorator tells PyObjC that this particular method returns a bool (”B”), is an object method (”@” means object, and “:” means method selector), and accepts one argument which should be a generic object (”@” again meaning object). For a full list of available encoding characters, see the Objective-C Runtime Programming Guide.

You can find more information about this bit of weirdness over at Jim Matthews Blog or, to a very limited extent, in the PyObjC class wrapping documentation.

This became particularly aggravating when I recently started using Git. Git, unfortunately, does not have a great GUI client on the Mac that I’ve found, so I was doing all my work on the command line and determining where the prompt ended and output began was getting to be a persistent problem. I also was not happy with the fact that almost any command besides a simple cd or ls was wrapping onto multiple lines; the default Terminal prompt just takes up so much horizontal space.

Fortunately, it is possible to modify your bash prompt, and having trolled the internet and tested various solutions, here’s what I’m currently using to distinguish prompt from output:

Yes, my computer is named Tastefully Delicious. I myself am not entirely certain how this occurred.

My custom prompt isn’t perfect, and it’s certainly a lot more basic than some that you can create, but it does a great job of visually distinguishing between input and output which is exactly what I needed. Fortunately, it’s not terribly difficult to enable something like this; although bash prompt examples around the internet range from gibberish to hundreds of lines of cryptic functions that you have to load into your bash session, understanding the basics of a custom bash prompt in order to make your own peace with Terminal is quite simple.

First off, head over to IBM’s cheat sheet for bash prompt modification. This was by far the best reference I found on modifying the prompt, and offers a complete listing of available bash sequences and colors (as an added bonus, it uses a much simpler syntax for colors than some other sites advise). In my examples below I’ll be using the specific variables for my personal prompt, but you can of course substitute any bash sequence that you like to make the command line your own.

There are two main parts to customizing your prompt: deciding on the right prompt declaration for you, and then writing it to a file so that it’s loaded every time you load bash. The prompt is stored in the PS1 variable in bash, which you can examine like this:

echo $PS1

To temporarily change the variable (for instance, while testing out various prompts), you’ll run something like this:

export PS1="Your prompt here > "

By adding bash sequences to your prompt, you can make it display more interesting information. For instance, if you wanted to use just the second line of my prompt (what folder you’re in, what computer you’re logged into, and what user account you’re using), you could enter this:

export PS1="\W @ \h (\u) \$ "

Which would result in a prompt that reads something like this:

You can, of course, use any of the sequences listed on the IBM reference. For myself, I found that changing the content of the prompt itself wasn’t enough (even when I experimented with multi-line prompts); what was really needed was some color.

Colors in bash are rather offputting, but easy enough to use as long as you’re careful. The basic format is \e[0m — "\e[" starts the color code, 0 is the actual color declaration (0 specifically means "reset to default"), and "m" ends the color. However, in order to make sure bash wraps things right (should they need wrapping) you have to add some backslash-escaped brackets to mark the code as taking up no space on the line:

\[\e[0m\]

Fun, illegible times. In the color chart on IBM’s reference, you can see the various codes associated with different colors. To setup a specific color combination, separate different numeric color codes with semicolons (so far as I know, order doesn’t matter). So if you wanted red text on a black background you would use \[\e[31;40m\] and if you wanted bold green text on a blue background you’d use \[\e[1;32;44m\] (the number 1 makes the text bolder and/or brighter for use on a dark background). You can also leave off any of the color codes (to just set the background color without messing with the default text color, for instance).

For my prompt I wanted something more subtle than most of the bash colors provide for, so I set the background of the whole window to light gray in the Terminal preferences, and then used the code \[\e[1;30;47m\] which set the text to the bright variant of black on a white background. I wasn’t too happy with the bold text, but fortunately Terminal offers a pair of options to disable bold text and make it “bright” which worked perfectly for me:

With colors worked out, the last step was adding a horizontal rule (via underscores) to separate out the prompt even more. My default Terminal window is 80 characters wide, so I just tossed in 80 underscores. I’m certain there are ways to get tricky with functions and only output as many underscores as you need to fill the window, but that seemed like more effort (and processing overhead) than it was worth.

So without further ado, my complete custom bash prompt:

export PS1="\[\e[1m\]________________________________________________________________________________\n\[\e[1;30;47m\]| \W @ \h (\u) \n| => \[\e[0m\]"

There’s additionally a second level prompt that you may need if you’re entering a command over multiple lines. I just duplicated the final line of my original prompt for the secondary one:

export PS2="\[\e[1;30;47m\]| => \[\e[0m\]"

For both of them, note the “return to default” color code at the end; if you don’t enter that, you’ll end up with an entire window the color of your prompt, which will likely defeat the purpose.

Once you’ve found a prompt that you like, you’ll want to save it so that it automatically loads. To do this, just add the export commands to a hidden file in your home folder named either “.bash_profile” or “.bashrc” (I don’t have any idea what the difference is; I’m personally using .bash_profile because it already existed in my home folder).

Once you’ve saved your path to the file, you should forevermore experience a more visually appealing (and possibly informative) bash prompt, hopefully rendering Terminal a less painful program to use.

My girlfriend’s and my first Christmas tree together. Happy!

Sitting on the couch we’ve got a view of the Christmas tree with the Space Needle standing tall in the window next to it. I love this apartment.

There’s lots of information scattered about the interwebs about arm-wrestling forms into submission, but I recently ran across an issue that has not, so far as I know, been adequately discussed. That topic is legends.

No, not like the legend of Jeffrey Zeldman and his big blue ox, although that’s a good one; I’m talking about the legend element that attaches to fieldsets in order to let your visitor know what the heck this group of form controls they’re supposed to fill out pertains to. Legends, it turns out, are some of the most annoying elements to style you can find. Not only do they by default have some bizarre formatting applied to them by every browser out there (usually in slightly different ways), but normal styling rules don’t apply. Display: block, anyone? Yeah, ain’t happening.

Recently I was asked to style a really nicely laid out form; it had everything lined up down the left side, clearly labeled sections, the works. Except that the headings for each section were occasionally long enough to wrap, and were displayed with many of the same rules as the H3’s on the page. Easy enough, I figured, I’ll just stick display: block and some margins on them.

Which is when I discovered that display: block has no effect on legends in any browser (any browser worth testing in, that is, which means IE 6, IE 7, Firefox 2, Firefox 3, and Safari for my company). Legends with lots of text in them tend to stretch themselves or, worse, their parent elements out to keep everything on the same line, and even if they’re supposedly block-level elements with a margin they’re still treated as inline. Not cool. Fortunately, my latent CSS superpowers were activated when I started swearing like a sailor (wish I had a more socially acceptable trigger, but there you go) and I pounded out some CSS that:

1. Forces long legends to wrap in IE, Firefox, and Safari
2. Encourages legends to act like they know what display: block is all about

The code looks like this (or see it in action):

HTML

<fieldset>
    <legend><span>Legend text</span></legend>
</fieldset>

CSS

legend {
    margin: 0 0 15px;
    float: left;
    white-space: normal;
    *margin-left: -7px;
}

legend span {
    width: 400px;
    display: block;
}

Seem weird? That’s because it is. Here’s the reasons for the insanity:

If you’re like me, you’ll want a margin on your block level elements; in order to get your margin recognized in Firefox 2, you have to put it on the legend element. Of course, margins won’t be recognized on inline elements or legends, but since display: block does squat for a legend you have to float the legend left. For the full display: block effect, of course, there should be a width on the legend, but since Firefox will collapse the legend’s width down to its content anyway, I left it off.

Instead, the semantically meaningless span gets the width and display: block. The span not only forces Firefox to bump the legend’s width out the correct amount, but it also is necessary for long legends to wrap in some browsers. I’m using a pixel width mainly because IE 6 requires a different pixel width (more on this later). Although in a perfect world your legends would not have anything in them other than the legend text, we don’t live in a perfect world.

Adding white-space: normal to either the span or the legend will fix the wrapping problems in Firefox 3 (I chose to attach it to the legend in the hopes that in fifty years or so I can rid myself of that span with less effort).

The *margin-left: -7px line is a hack to fix an IE-specific problem. Even with no padding, margin, and left: 0px IE will still indent your legends seven pixels. The star-property hack targets both IE 6 and 7 (while being ignored by sane browsers) and bumps the legend back over where it should be. I’m using the star-property hack here because it makes the source a lot less verbose; however, you should probably migrate that rule into an IE-specific stylesheet behind a conditional comment.

There is also one more IE-specific adjustment that you have to make thanks to the seven pixel indent. When calculating its box model, IE 6 will determine the width of the legend and add the seven pixel indent before shifting the legend to the left. Long and short of it is that the parent element will be bumped out seven pixels wider than it should be, so you’ll need to give the span a width seven pixels less than your target width for IE 6. For instance, to make the code above work in IE 6 I would add an IE 6 conditional comment with legend span { width: 393px; } inside somewhere.

And that’s it! You will, of course, want to be using an intelligent CSS reset (I recommend Eric Meyer’s CSS reset), but otherwise the above CSS should give you a legend element that acts like a block-level element instead of some weird border-loving pseudo-element with wrapping issues.

There are some further gotchas to be aware of if you start playing around with legends. IE by default colors all legends blue, for instance, and if you want the legend to overlay the fieldset border (or not) you’ll need to go about things slightly differently. However, if you’ve been frustrated by the inability to get your legends to behave like display: block means something, hopefully this snippet will help you out.

As is usually the case, I discovered this particular combination of HTML and CSS by taking previous solutions, mixing them into a putrescent green cocktail, and force-feeding it to my browsers, tweaking the constituent ingredients until they were saying “Mmm, tasty!” instead of puking a bunch of crap all over my lovely webpage. Specifically, John Faulds provided some basic concepts and examples for styling legends and Stephanie Sullivan wrote up the strategies for encouraging legend wrapping in Firefox 2 and 3. Thanks, guys; you rock.

If you want to see the code in action with various permutations for More Pretty, check out this page o’ examples.

However, there’s a large number of people out there who prefer Quicksilver (link to Google Code project; also see Blacktree’s site). I don’t know if it’s for the sexier (if more complicated) interface or just because they’ve got Quicksilver embedded in their fingers as badly as I’ve got LaunchBar in mine, but they’re unlikely to switch anytime soon.

And then there’s the folks out there who haven’t discovered the joys of a launcher program and just run Applescripts manually or with something like FastScripts.

All of which adds up to a bit of a conundrum if you want to share your favorite Applescripts with the world. Fortunately, with a bit of Googling and some good old trial and error, I’ve written a simple Applescript template that allows all users, no matter how they like to launch scripts, to use yours. Without further ado, here’s the code:

-- You'll want to rename this function something appropriate
on action_function(someText)
    -- Check to see if we've got text, ask for it if not
    if someText is equal to "" then
        set question to display dialog ("Enter text:") default answer ""
        set someText to text returned of question
    end if
    -- Do whatever your script does here
end action_function

-- Quicksilver tie-in code
using terms from application "Quicksilver"
    on process text qsText
        my action_function(qsText)
    end process text
end using terms from

-- LaunchBar tie-in function
on handle_string(lbText)
    my action_function(lbText)
    open location "x-launchbar:hide"
end handle_string

-- Call the function in case the script was run directly
-- (Don't worry; this line won't execute if called from LB or QS)
my action_function("")

If you’re familiar with Applescript, the code should be pretty self-explanatory. You wrap all of the scripts actions into a function (called action_function in the example), and then call that function using the specific access routines for Quicksilver or LaunchBar (with a normal call to the function included just in case the user directly accesses the script). The code within action_function is merely a fall-back in case it receives a blank string (you’ll likely only need the fallback if they are calling the script directly). I leave any more specific error checking to you.

This template specifically accepts text; if your script needs to process a list of files, for example, you’ll need to change the code for the various programs appropriately (how specifically to do that I leave up to you, but the general template should still serve you well). One caveat is that if you’re compiling the code, you’ll need Quicksilver installed (even if you only use LaunchBar). However, as far as I can tell, if you’re just running the Applescript you don’t need to have either program installed (or you can have just one or the other). The main downside of needing both to compile is that if you rely on your users to adjust config variables in your script, then they will need to install Quicksilver (unless you include instructions to remove Quicksilver’s code if they aren’t using it).

Let me know if you run into any trouble using this code! I haven’t run into any errors with it in my testing, but that certainly doesn’t mean that they don’t exist.

For those who know about TextSoap, version 6.0’s main benefit (at least from my point of view) is a vastly redesigned custom cleaner editor. Cleaners can now run text through sub-routines, there’s a quick regex reference right in the window, and you can attach notes to cleaner actions to remind yourself what the heck that complicated regex pattern is supposed to be doing. There are other improvements, as well, but the custom cleaners interface is where it’s at for me. If you’re curious, check out the release notes for the full scoop.

For those not in the know, TextSoap is a fantastic piece of software that allows you to make changes to plain and rich text both using built-in cleaners or custom cleaners that you define yourself by combining regular expressions and any of the built-in cleaners with familiar Automator-style rules.

Yeah, I know, it doesn’t sound too impressive, does it? But that’s only because you’re used to wasting a lot of your time on mindless repetitive tasks involving text. TextSoap not only provides an easy way to save sets of common text-based find and replace actions, but it allows you access to them from pretty much anywhere on your computer by integrating with popular programs via plugins, offering a system-wide contextual menu, or hanging out in the Services menu.

When I first bought TextSoap, I regretted it because I barely ever used it (this was back in version 4.0, I think). Then one day I was doing something incredibly repetitive with text (I don’t even remember what), and I got fed up, launched TextSoap, and took a look at the custom cleaners. I’ve never looked back. Although the most powerful custom cleaners require knowledge of regular expressions, there are still hundreds of things you can do without ever worrying about regex simply by combining TextSoap’s provided cleaners with the building blocks available in custom cleaners. TextSoap provides an approach to text manipulation that has saved me hundreds of hours of drudgery.

Over time, I’ve found that the custom cleaners I create tend to fall into two categories:

1. Cleaners that address specific problems that either recur or only happen once but require the same actions repeated a bunch in that sitting. For instance, for one client I have to convert a Word document into a newsletter every two weeks, observing their byzantine rules for HTML formatting. The first time I did it, it took a mind-numbing four hours. The second time, I created a custom cleaner while I worked and it took me two. The third time all I had to do was use the custom cleaner, and it took me one. With practice, I’m now down to about forty minutes.
2. Cleaners that address generic recurring actions. These are cleaners that I’ve slowly tweaked over time, and now use primarily as building blocks for my task-specific cleaners.

It’s this last type of cleaner that I would like to share with you.

My XHTML suite of custom cleaners

My main use for TextSoap is manipulating HTML, and because I know a lot of other people out there have to do this on a regular basis I’ve decided to share the basic cleaners that serve as the foundation for my workflow. TextSoap has revolutionized how I perform certain tasks (particularly converting styled text to HTML and converting really hideous HTML into tasty XHTML), and I strongly recommend it to any web junkie who has cursed out a previous developer for their table-filled monstrosity of a website. Before I get into the nitty-gritty details of what’s included, here’s the download:

Download TextSoap XHTML Suite

Included are eight custom cleaners (if you’re only interested in one or two, see the ReadMe for details on which cleaners require one of their brethren):

• Encode Ampersands. This encodes every ampersand that isn’t already part of an HTML entity.
• Escape Single Quotes. Primarily useful for Javascript, PHP, etc., this escapes all single quotes with a backslash.
• HTML Curly Quotes. For those clients who must have curly quotes, this is your solution. It converts every quote outside of HTML tags into a curly. (Please note: only works for English curly quotes.)
• HTML Paragraphs. This converts text blocks separated by double line breaks into paragraphs, and converts single line breaks to <br /> tags.
• Style to HTML. One of my workhorses, this cleaner takes richly formatted text and turns it into simple, paragraph-delineated HTML with appropriately placed strong and em tags.
• URLs to HTML Links. This cleaner finds all of the easily recognizable URLs in a document (starting with http, https, or www) and converts them into HTML anchor links.
• WebHappy. This happy little cleaner simply converts richly styled italics and bold into strong and em tags, straightens all quotes, and converts any problematic characters into HTML entities.
• XHTML Cleaner. This is a pretty hefty cleaner, and I run it by default on any HTML that needs serious love to turn into XHTML. The cleaner performs a laundry list of common tasks (properly escaping self-closing tags, b to strong, lowercased tag and attribute names, etc.) and also attempts to add and remove linebreaks so that you can easily indent the code in your favorite editor (like Textmate). I rarely use XHTML Cleaner directly, but it offers a great starting point for any custom cleaner that needs to deal with poorly written HTML.

Although some of these cleaners are great on their own (I have a special place in my workflow for WebHappy, for instance, even if I never did think of a good descriptive name for it), a lot of them work best as the starting place for your own task-specific custom cleaners. I’ve tried to add notes to all of the regex rules, as well, so they may help you figure out how best to perform your own tasks (keep in mind that some of these cleaners were developed while I was still figuring regex out, so some of those regular expressions are narsty). If you improve or otherwise modify any of the core suite of cleaners, drop me a line because I’d love to see what you’ve done.

Enjoy!

Along with the update to Coda, I’ve updated the TEA for Coda bundle (find the most recent version on the dedicated TEA for Coda page); all of the scripts will now perform their actions in the active document even if multiple windows are open. Additionally Indent New Line should be significantly improved performance-wise. The scripts do now require Coda 1.6, though; if you’re running an old version of Coda expect buggy behavior.

I am unlikely to improve the TEA for Coda scripts anymore; my new goal will be to get the Textmate bundle items that I know and love into Coda using the plugin interface. This will necessitate learning some Cocoa, though (since some of the key actions require user input), so it may be a little bit of time before I’m able to get a working plugin up and running. In the interim (or until someone else does it), TEA for Coda is still the best way that I know to get Coda to behave like a full-blooded HTML editor.

• The HTML Tidy script is now a universal binary! At long last, our PPC friends can run it just as easily as those with newer hardware.
• The Format with Em and Format with Strong scripts now keep your text highlighted rather than moving the cursor to the end. This is not only more congruent with Textmate’s behavior, but I think it makes better sense, particularly if you ever need to wrap the text in more than one tag (or wish to add a class name, or…).

You can get the update from the dedicated TEA for Coda page. Unless you use PathFinder or have some other way of viewing invisible files, you’ll need to replace the entire HTML directory (if you’ve made changes to the scripts, you should copy them into the new directory before replacing the old one). If you are comfortable with invisible files, then you’ll just need to replace the .lib directory and the Format directory.