Tufte

Mon May 6 '19

Introduction

This is an example of applying tufte-css to reST markup.

I don’t have a blog because I never write anything. But maybe I should. I’d like to believe that if I made a blog I would write neat stuff in it. But I probably won’t.

I use sphinx currently and could write stuff in there but I don’t really like how the site looks so I wouldn’t feel good about anything I did there.

I was impressed by lawler.io but found it didn’t work well with reST. So I’ve tried to steal things done there and from tufte-css and hack this together.

A number of things are supported in reST already. Like sections, footnotes1, blockquotes, epigraphs, figures. That’s one of the reasons I like reST. For this website, however, I’ve modified how it writes HTML to use modern elements like <section> and <figure>. This is in part to simplify creating a stylesheet using tufte-css.

1

This is a really long footnote that exists to make sure that it fits within the normal column of text and doesn’t overflow off to the margin on the side.

Epigraphs

Live long and prosper.

—Gandalf, The Lion, The Witch and The Wardrobe

Use the force, Frodo.

—Mal Reynolds, Red Dwarf

The following is just a regular quote.

Many were increasingly of the opinion that they’d all made a big mistake in coming down from the trees in the first place. And some said that even the trees had been a bad move, and that no one should ever have left the oceans.

The Hitchhiker’s Guide to the Galaxy

Sidenotes

Putting content on the side is fun because reading is boring so making page layouts unpredictable can be exciting. You know; mix things up a bit. Maybe put half of the next page at a 90 degree angle like it’s House of Leaves or something.

So in tufte-css, marginnotes are inline content on the margin and sidenotes are footnotes on the margin. In reST we can apply classes to blocks fairly easily. Doing an inline marginnote would be awkward because I think you’d have to use a role and you can’t nest those in reST and they’re used all over for code, emphasis, citations, bold. (This is where I’m referencing2 a side note to illustrate.) The nice thing about it being inline is that it’s easy to float right and have the reference and the sidenote both horizontally aligned. And, probably more importantly, if the footnote isn’t floated (as is the case on narrow displays) it shows up before it’s referenced and looks silly.

The sidenote/.aside footnote is a block element sibling to the paragraph containing its reference. The footnote is placed before the paragraph so that when it floats to the side, its start appears level with the start of the paragraph. Which looks okay.3

Figures

A line chart comparing gifted to non-gifted twitch.tv subscriptions for a channel.
This is a caption for the adjacent figure. It shows some probably mostly accurate numbers for subscriptions per hour to all channels on a popular video streaming website over three days. This caption is in the margin unless your screen size is tiny.

Figures also have legends or something in reST but I can’t be bothered to figure that out right now.

Using ..class:: full-width will make a figure look big. As shown below.

A chart showing twitch.tv channel viewership over time for several channels that occasionally host or receive hosts from other channels.
This figure has a caption that doesn’t fly off the side of the page. It does not take the full width of the page at normal (not tiny) screen sizes.

Random Stuff

This is a code block that pelican should make look cute with highlighting.

The stylesheet I used has really poor contrast. And this first code block has .full-width because the lines are long.

pub fn duration_to_f64<D: Borrow<time::Duration>>(d: D) -> f64 {
    const NANOS_PER_SEC: u32 = 1_000_000_000;
    (d.borrow().as_secs() as f64) + (d.borrow().subsec_nanos() as f64) / (NANOS_PER_SEC as f64)
}

And if your lines aren’t inappropriately wide …

WITH RECURSIVE renames(name) AS (
     VALUES ($1)
  UNION ALL
     SELECT change.new
       FROM renames
          , channel_name_changes change
      WHERE change.old = renames.name)
SELECT name
  FROM renames;

reST also has horizontal rules by doing ---- so here is one now.


Wow. Wasn’t that amazing? Just incredible. What do bullet lists and enumerated lists look like?

  • 8 tablespoons butter, softened (plus butter for the pan)

  • 1 & 1/2 cups all-purpose flour

  • 1/2 cups whole wheat flour

  • 1 teaspoonsalt

  • 1 & 1/2 teaspoons baking powder

  • 3/4 cups sugar

  • 2 eggs

  • 3 bananas very ripe and mashed with a fork until smooth

  • 1 teaspoon vanilla extract

  • 1/2 cups chopped walnuts or pecans

  • 1/2 cups shredded coconut

  1. Heat the oven to 350°F. Grease a 9x5-inch loaf pan with butter.

  2. Mix together the dry ingredients. With a hand mixer, a whisk, or in the food processor, cream the butter and beat in the eggs and bananas. Stir this mixture into the dry ingredients, just enough to combine (it’s okay if there are lumps). Gently stir in the vanilla, nuts, and coconut.

  3. Pour the batter into the loaf pan and bake for 45 to 60 minutes, until nicely browned. A toothpick inserted in the center of the bread will come out fairly clean when done, but because of the bananas this bread will remain moister than most. Do not overcook. Cool on a rack for 15 minutes before removing from the pan.