Have you ever watched the movie Field of Dreams? Don't worry, I haven't either. It's an old movie about a guy who wants to build a baseball field out in the middle of nowhere. Someone tells him the famous line: "If you build it, they will come." And sure enough when he builds the field, the legendary (dead) baseball stars show up to play. A similar thing happened to me (no, not ghosts or voices in my head) as I worked on a project to create hi-quality handouts for my presentation at the 2010 T-Cubed International Conference. I wanted some way of using my favorite editor Emacs, org-mode, and CSS to create the handouts. And sure enough, as I moved forward with the project, solutions seemed to, well, pop out of nowhere.

TI's TrueType Fonts

Since it's a handout on how to use a graphing calculator, I needed someway of entering the calculator keys in Emacs. TI provides these keys via a TrueType font. In Word, adding these to a document is a snap. Just go to Insert Symbol. But is such a thing possible in Emacs?

Maybe. Maybe not. But I figured I could use the following hack: Turn the TrueType file into a bunch of different image files, one picture for each character. These are just regular images that can be added in org-mode as any other picture. This hack works because if you link to an image in org-mode, the image will automagically display in the HTML file. But what about in Emacs? Is there a way to display pictures in Emacs?

The answer is "Yes!" M-x iimage-mode. Image links in org-mode will display as images. You can then press C-l to reload images.

Neat. But I still have the problem of turning that TrueType file into a bunch of picture files. For that I turned to Perl. If I knew how to program Emacs, I'm sure I could have done it in Emacs.

The Gritty Details

Perl's GD::Image's stringFT function creates a picture file from text rendered in a font of your choice. However, there's one hitch—you first create the image file in pixels but stringFT takes as argument the size of the text in points. (Yes, there's a difference. Print materials i.e., fonts, normally measure in points while computer screens are measured in pixels.) The result is text images that aren't aligned correctly.

We need some way of finding how many pixels the character takes up. One solution, which is somewhat backwards, is to first create a "dummy" picture, find out the pixels the character takes up using the given point size, then create the real picture using those dimensions.

The following Perl snippet, loads the truetype file TINspireKeys.ttf, creates a 24-pt version of the "A" character using this font, then saves the picture as A.png.

use GD;

my $font = "./TINspireKeys.ttf"; my $fontheight=24; #in pts

create dummy

my $dummy = new GD::Image(2$fontheight, 2$fontheight); my $dum_col = $dummy->colorAllocate(255,255,255);

get font sizes

my (@bounds)=GD::Image->stringFT($dum_col, $font, $fontheight,0,0,$fontheight, "A");

my $width=abs($bounds[2]-$bounds[0]); my $xoffset=abs($bounds[0]); my $height=abs($bounds[7]-$bounds[1]);

create actual image

my $im = new GD::Image($width, $height); my $white = $im->colorAllocate(255,255,255); my $gray = $im->colorAllocate(0,0,0);

$im->transparent($white); $im->interlaced('true'); $im->stringFT($gray, $font, $fontheight, 0, $xoffset, $height, "A");

Open a file for writing

open(PICTURE, ">A.png") or die("Cannot open file for writing");

Make sure we are writing to a binary stream

binmode PICTURE;

Convert the image to PNG and print it to the file PICTURE

print PICTURE $im->png; close PICTURE;

Unfortunately, if you run this code, you'll find that the image isn't "quite right." The location of the key is wrong. The reason is the TI-Nspire font is low-quality. bounds works properly in higher-quality fonts like Cambria but has the wrong dimensions for TI's fonts. The workaround is to find the right offsets by hand for each character. (Fortunately, the TI-key characters fall into groups with the same offsets, like A…Z and 1…9.)

A Better Alternative

If you read the above solution, you'll notice that only does it have a "hackish" feel to it but the results don't look that good.

The alternative (that I used on a later project) is to use CSS to create your own keys. You can use yasnippet to quickly type these keys (or use keyboard shortcuts if you prefer), and finally, use org-mode's macros to keep the file looking clean. A key can look like this:

+MACRO: add @<span class=calckey>+@</span>

+MACRO: enter @<span class=calckey>enter</span>

To find the sum 1+2, press 1 @<span class=calckey>+@</span> 2 @<span class=calckey>enter</span>.

Quirks With Org-mode

Apparently, org-mode can't handle images nested inside of lists. The following is generated incorrectly:

1. Item 1

+ATTR_HTML class="custom"

[[img/hello.png]] 2. Item 2

The above code exports as two items that are both numbered "1"—not what we intended. The work-around is to put the image in a table and then use CSS to kill the table borders.

While you can apply HTML classes to images and tables directly in the org-mode, for some reason, you can't (yet) do the same thing to lists. For instance, in the above example, ATTR_HTML applies the custom class to the image. The same command works on tables but there is no equivalent command for lists. The workaround is to wrap the list with a div. For example:

@<div class=custom> 1. Item 1 2. Item 2 @</div>

Unfortunately, that produces HTML code that doesn't validate. This is a big deal because you'll get error messages when you try to turn the HTML file into a PDF later on. The good news is that all you have to do is use the longer #+BEGIN_HTML. To keep the code clean, use macros:

+MACRO class #+BEGIN_HTML\n <div class=$1> \n#+END_HTML

+MACRO end #+BEGIN_HTML\n </div> \n#+END_HTML\

{{{class(custom)}}} 1. Item 1 2. Item 2 {{{end}}}

Note the use of \n—each BEGIN/END command needs to live on its own line.

You can use the same technique to get more control of the HTML output. Be aware that org-mode can be very fickle. For instance, if you turn the above list into a paragraph, org-mode produces invalid HTML. What you need to do is add an extra blank line before the {{{end}}}:

{{{class(custom)}}} Paragraph

{{{end}}}

Page Breaks

Use CSS to make the HTML as pretty as you want. For example, you can create boxes with shadows (for Remember notes or calculator keys, for instance). See CSS design sites for tips.

But what about page breaks? Browsers don't support the CSS page-break property. The problem is that since I was creating a handout, I needed better control of page breaks and running headers/footers. Then I stumbled upon a little program called Prince XML—it's high-quality software that turns HTML files into PDFs.

Prince XML supports most of the "good" CSS properties that you use to create pretty web pages. It also supports page breaks and running footers and headers.

The following CSS adds page breaks before H3 headings (these happen to be the main headings in org-mode):

h3 { page-break-before: always; }

The above adds page breaks before every H3 heading, including the first one. To avoid page breaks on a specific H3 heading, use CSS selectors. Using the layout of the org-mode HTML file, the following prevents a page break on the first H3 heading:

div#table-of-contents + div.outline-2 h3 { page-break-before: avoid; }

This tells prince to avoid page breaks on the H3 heading that's contained in a div.outline-2 that is adjacent to a div#table-of-contents.

Lastly, before I forget, when exporting an HTML file to PDF with prince, make sure to use physical units of measurement (inches and centimeters, not pixels).

The End

You can check out the end result here. Not bad for a first attempt but I'll admit that it doesn't really showcase what you can do with CSS. But there are two obvious advantages: (1) You've effectively separated the content from the design. The result is that you're free to focus on what matters—the content. (2) By working in Emacs, you get all the productivity gains of using this powerful editor.