This is a read-only archive!

Footnotes

Did you ever notice how footnotes make your writing seem more important1 somehow?

Maybe one reason is that "real" books use footnotes. At a glance, it looks like I have references2 backing up everything I say. In reality, I don't, but the connotation carries through somehow3. Now my blog seems scholarly and authoritative.

And if you're like me, you can't resist clicking footnotes to see what they refer to4. According to my estimates, by utilizing footnotes, in one fell swoop I have decreased my readers' average reading efficiency by 73%.

In any case, I've added experimental, rudimentary support for footnotes to cow-blog.

I'm loosely copying the syntax from Markdown Extra for this. Markdown is great, except when it isn't. The standard doesn't have support for some useful extensions. I use Showdown for Markdown support, and I'm probably going to work on adding more features of Markdown Extra to Showdown in the near future.

I just dread actually doing it. Showdown (like Markdown itself) is implemented as a series of hackish regex transformations of blobs of text. It's not a proper grammar. Implementing more of Markdown Extra means more regex blobbing. It's brittle and fragile and even getting incomplete support for footnotes was less than enjoyable. But at the same time I find myself wanting to do things that Markdown can't so, so I may have to bite the bullet.

(If there's a Showdown Extra out there already, drop me a URL. It'd be most appreciated. But I couldn't find one.)

  1. In reality nothing I say is important.

  2. Does my inner dialog count as a reference?

  3. Via telepathy.

  4. See?

July 27, 2010 @ 5:30 AM PDT
Cateogory: Programming

6 Comments

Andres F.
Quoth Andres F. on July 27, 2010 @ 2:15 PM PDT

I personally like maruku, as it pretty much implements everything I want at the moment. The disadvantage is that it'd be an extra step for you, since it's ruby, and that there's no good way to show previews for comments.

You could always just let the comments be parsed with a less advanced, client-side Markdown filter, since it's not like people are going to be putting footnotes here1, right?

  1. Right?

Brian
Quoth Brian on July 27, 2010 @ 2:48 PM PDT

The main issue is that I use the same Javascript previews when I write posts via the admin control panel. So I could disable the fancier bits of Markdown for comments, but I'd still want it to work for myself1.

But yeah, using Maruku or Pandoc or equivalent is an idea I keep considering. I could even use AJAX for the previews instead of Javascript in that case, but it'd be slow.

  1. I probably will disable footnotes for comments, to be honest, because they have the potential to clobber my posts. But they're so much fun...

John
Quoth John on July 28, 2010 @ 11:43 AM PDT

I use Pandoc myself, but that's for static docs... Just curious; are you caching the html generated from the content here? Or is it all rendered as html from stored markdown content every time?

Brian
Quoth Brian on July 28, 2010 @ 1:15 PM PDT

Yes, the HTML is cached. But while you're writing a comment/post, the HTML re-generated from the Markdown after every couple keystrokes, to keep the preview real-time.

John
Quoth John on July 29, 2010 @ 3:02 AM PDT

Do you find that users appreciate the live preview? For myself, I usually don't notice it until I'm done typing and scroll down to hit submit, and then the preview just looks like what I typed anyway (since, of course, the point of Markdown is that it's supposed to already look natural).

I could see wanting a preview if you expected users to type comments in some harder-to-visualize markup, or maybe if you had a less technical readership.

Brian
Quoth Brian on July 29, 2010 @ 6:21 AM PDT

Actually I have no idea if users appreciate it or not. When I first rolled out the feature, some people said "Wow, neato", but other than that, I haven't heard anything.

I do notice that people who post source code tend to end up with it nicely formatted on their first try. That's part of the reason I wanted it this way.

On most blogs, you type some source code into a comment, and then you pray that you didn't need to escape your <'s or \'s or worry about your whitespace. On my blog you know what you're getting. "Click here to preview" means fewer people are going to bother looking at the preview. And honestly it's as easy or easier to code up a live preview with a few lines of JQuery, compared to a "Click here preview" feature.

I do appreciate live previews myself when writing blog posts, because my posts are long and syntax-heavy.