Author Archive

Four steps to better LaTeX documents

June 30th, 2008  |  Published in Computing

Here are some simple things you can do to make your LaTeX documents more attractive and functional. (Updated May 2009; now there are more than four suggestions.)

Use pdflatex

The target of your document is either a printer or a file. In either case, you will probably want some way to turn your TeX source into a PDF document. You can do this in several ways: using dvipdf, using Adobe Distiller, or using a fake printer driver. Each of these, though, is sort of a pain. If you use the pdflatex TeX driver, which is a standard part of modern TeX distributions, you’ll get much better results.

pdflatex is almost completely compatible with documents that are acceptable to standard latex, with one important exception: all of your included graphics will need to be PDF files. This isn’t really a drawback, though, since a PDF is much more likely to be free of the sort of bounding-box and font drama that can often plague EPS figures.

You can use the ifpdf package to conditionally execute code when running under pdflatex or otherwise:


\usepackage{ifpdf}

\ifpdf
\usepackage[pdftex]{graphicx}
\else
\usepackage{graphicx}
\fi

Use the microtype package for better typography

Now that you’re using pdfTeX, you have access to better typography. pdfTeX provides features to help ensure that optical margins appear straight, that the typographic color of your text is more uniform, and that unattractive “rivers” are kept to a minimum. The microtype package, which you may already have installed, provides a convenient interface to these features. These options are suitable for set-it-and-forget-it use:


\usepackage[protrusion=true,expansion=true]{microtype}

Even using the defaults buys you a great deal. As a small example of one feature, see the following detail from a document that uses microtype:

Example of character protrusion

Note how the commas and periods extend somewhat into the right margin. This actually helps to make the margin look less ragged than if they were aligned strictly to the left of the right margin. The microtype package can give you a great deal more control over micro-typographic features; see its copious documentation for details.

Use otfinst.py to take advantage of your OpenType faces

As a longtime LaTeX user and as a longer-time reader of technical literature, I approach the Computer Modern Roman fonts with fond nostalgia — it’s hard for me to see them without recalling classics like The Little Schemer or EOPL.

There are faces that are rather nicer, if you’re not targeting an audience with a similar nostalgia profile to mine. Unfortunately, many of them aren’t immediately usable with LaTeX. In particular, it’s not immediately apparent how to use OpenType fonts in your LaTeX documents — and reading about how to do convert and install one’s OpenType fonts will likely give even experienced LaTeX hackers nightmares about strange creatures like “.fd,” “.tfm,” and the dreaded “kpathsea.”

John Owens at UC Davis has a very nice script called otfinst.py that automates the whole process of converting PostScript-flavored OpenType fonts to metric and outline files that LaTeX can use and then installing these and other support files. It’s very easy to use — to install Minion Pro, for example, you’d need only to type:


otfinst.py Minion*.otf

in a shell window and then include the following line in your document:


\usepackage{minion}

I’ve used it successfully to convert many Adobe faces, including Minion, Myriad, Cronos, Warnock, Kepler, Arno Pro (used in the above example), and Garamond Premier Pro. It also works out-of-the-box with some FF typefaces. I haven’t licensed any for-pay FF faces, but I did successfully convert FF Mt to use as a small-caps logo face.

(If you don’t have any decent OpenType faces, you might poke around and see if you prefer the standard garamond or palatino packages to CMR. These aren’t as nice as a “real” Palatino or Garamond, but they’re rather nicer than CMR.)

Use svn-multi for a LaTeX interface to Subversion keywords

You should keep your documents under version control.

If you do, and you use Subversion, then you should install the svn-multi package, which provides a nice interface to access svn keywords from LaTeX documents that span multiple files. Mark Eli Kalderon at University College London wrote a nice article showing how to use svn-multi.

When I’m drafting a document and getting external feedback, I find it especially convenient to be able to include revision numbers with file names in page footers. This way, I can see what revision a hardcopy comes from — and then use latexdiff-svn to compare its contents to those of the current version.

Use vc with other version control systems

If you don’t use Subversion, you won’t be able to use svn-multi. However, you still might want to include version control information in your documents. The vc package is more flexible than svn-multi but is a little more difficult to set up: you’ll have to incorporate a preprocessing step into a makefile or invoke a script from within your documents. vc allows including version control metadata in documents controlled in bzr, Subversion, and git, which is the system that I currently prefer. git support is especially notable because git does not support keyword expansion.

Typeset better tables

Thanks to Nate Rosenblum for a pointer to the booktabs package. Essentially, this package makes it possible and easy to set tables properly. The documentation includes several standard tables contrasted with the results possible with booktabs as well as a discussion of some of the rules for typesetting tables. As an example, here is a table from my VMCAI 2009 paper:

example table

A blank Keynote theme

March 13th, 2008  |  Published in Mac

I’ve designed a couple of Keynote themes, and the biggest pain is that you can’t start from scratch: you have to begin with an existing theme. The themes that come with Keynote are fine, but they have a lot of extra junk in them (e.g. wacky faux-granite image fills for shapes and charts, etc.) that will be tedious to remove before you can do anything useful.

The last time I made a new theme, I went looking for a “blank theme,” hoping that someone had made one available as a starting point for new themes. No one had, and I was in a rush. Recently, I decided to make one, and I’m now making it available.

Blank.kth works with Keynote ’08, features tasteful blue fills in charts, includes no goofy images, and defaults all text to Helvetica Neue. To install, unarchive the zip file and drag the .kth file to ~/Library/Application Support/iWork/Keynote/Themes/.

You are free to use Blank.kth for any purpose. Please let me know if you find it useful. Finally, I would appreciate — but do not require — that you share any derived themes with me.

Operator precedence in the Java language

February 6th, 2008  |  Published in Programming, Teaching

This handout presents Java’s operator precedence rules: in general terms (for CS1 students and most everyone else) on the front, and in excruciating detail (for language lawyers and compiler frontend implementors) on the back.

Why integer overflow wraps around

February 6th, 2008  |  Published in Teaching

Here’s a fun handout that I made for my CS1 students. Click the image to download a PDF.

Why integer overflow wraps around

Ideas and resources for course materials

February 5th, 2008  |  Published in Teaching

In August 2007, I led a workshop at Wisconsin for other graduate student instructors on making better course materials. I discussed how to use slides, handouts, and dynamic internet resources effectively to serve lectures and learning. I have reproduced here the text of one of my handouts from that talk; I have added hyperlinks and removed some Wisconsin-specific terminology. If you’d like a printable PDF, you can download the version I gave out at the workshop.

Slides

Suggestions on how to use slides

Students often expect a downloadable set of slides to be a standalone artifact that can serve as a substitute for engaging the material in lecture. Making this assumption is bad for them, but molding your slides to meet this assumption is bad for everyone. You can discourage this behavior by making slides that serve your presentation.

Most of the bad slides you’ve seen contain a laughably small amount of content. This is primarily due to two factors. The main factor is that the medium limits the amount of information you can fit on a slide (consider 36 point type on a low-resolution screen). An important auxiliary factor is that lazy speakers will use slides merely to present their own talking points or an outline of their talk. This doesn’t benefit the audience, who can read as well as the speaker can, and it is of dubious benefit to the speaker, who should have practiced before presenting.

You’ll probably want to provide your students with some lasting artifact of your lectures or course presentations, but you shouldn’t do so by making your slides worse. Instead of putting enough “stuff” on your slides so that students don’t need to listen to you teach, start by developing a handout that covers the most important parts of a topic in detail. Then, develop a lecture in conversation with your handout, using the slides to present detailed examples and to reinforce the key points of your lecture.

A good rule of thumb for slides is to use them as much as possible for things you can’t do any other way: to illustrate things that you couldn’t easily draw on the blackboard; to present larger examples; and to present examples with animations or other multimedia content. You can also use slides to underline particular points (e.g. important definitions, which students can benefit from seeing as well as hearing), to give students an idea of what to expect in the rest of the lecture, and to make them laugh. (Don’t underestimate how easy or effective it can be to use humor in class. After twenty minutes of a late-semester lecture, your students will be inclined to laugh at almost anything.)

Technology-specific tips for slides

There are three major options for slide software: you can use Microsoft PowerPoint, you can use Apple Keynote, or you can use a dedicated drawing program like Adobe Illustrator and then present your slides in a PDF viewer. (For the record, I recommend Keynote to Mac users and Illustrator to Windows users.) These tips should apply to all of these options.

First, learn your software. This may seem like an obvious suggestion, but people often don’t do it. Putting in a couple of hours to skim the manual or work through tutorials can dramatically increase your productivity.

Another potential time-saver is putting in the effort to make your own custom templates or themes for slides. This will save you the tedious work of modifying defaults every time you make a slide presentation, and can help you enforce a consistent personal style.

I’ve had the best luck making figures and diagrams in a dedicated drawing program and pasting them in to my slides. (Typically, the drawing support in slideware is rudimentary at best.) If you do this, though, you may not be able to manipulate individual parts of the diagram independently (e.g. for animating appearances) from within the presentation software. In this case, you’ll need to paste several times, copying each independent part of a diagram in turn.

Handouts

Software suggestions

I find myself making two kinds of handouts: those that are primarily diagrams or pictures, and those that are primarily text. Of course, almost any good handout will combine graphics and prose, but it seems that any particular handout will either demand a large drawing effort or a large writing effort. I use different programs for each kind of handout.

For handouts that involve mostly drawing, I use OmniGraffle, which is published by The Omni Group, and Adobe Illustrator. OmniGraffle is Mac-only; comparable packages are available on Linux (e.g. dia, the free diagram editor), and on Windows (e.g. Microsoft Visio).

For handouts that involve mostly writing, I use Adobe InDesign. (Apple’s Pages is also a good choice.) InDesign and other page layout programs are great because of the degree of control they allow you. On many handouts, controlling the finer points of design and layout is essential: you’ll need to be sure that the text is readable and that it fits well on the page. (For simpler handouts, of course, your favorite word processor is certainly fine.)

Technology-specific tips for handouts

Making templates for handouts can be a great time-saver, just as it is for slides. My Anatomy of a simple handout provides an annotated version of one of my handout templates, explaining the whys and hows of each part.

You can apply the template idea on a finer granularity as well. If you make a lot of similar figures in your handouts, consider saving template graphics to a file so that you can reuse them (some software also supports creating graphics libraries or stencils). This is a very small time investment that you will greatly appreciate when you’re making the thirtieth Hasse diagram, molecule, historical map, or whatever in a given semester. Remember that you can reuse most of the graphics you make in handouts for your slides with only minor effort to remove details that wouldn’t reproduce well in the slide medium.

Many programs let you place a text area containing variables. Variables are dynamically updated to contain the text of some useful value, for example the current document’s file name or the time that a document was printed. I use variables in my handout templates so I can be sure that a hardcopy handout corresponds to the most recent version and (more importantly) so I can find the right file to edit or print when I need a handout in the future!

Dynamic resources

Some of the best course materials you can provide won’t be “materials” in the conventional sense at all: they will be experiences that your students have interacting with dynamic internet and multimedia resources. In this section, we’ll briefly discuss a few possibilities for using technology to teach.

Syndication

There are a few ways to keep your students up-to-date with announcements and assignments: verbal mentions in class, notices on a syllabus, and mass emails to the course list. However, there are a couple of higher-tech ways to help your students stay informed.

Consider keeping a course weblog: it is easier to post announcements than it is to modify a web page, there is a permanent record of announcements (unlike with email or verbal notices), and tech-savvy students may subscribe to your announcements with a feed reader program, receiving updates automatically. (You can also use this technology to automatically update a course web page.) Some weblog systems also allow students to post comments, which allows them to discuss or ask for clarifications. (You can host a weblog for free at blogspot.com or wordpress.com.)

Also consider publishing your course syllabus as an iCalendar, which is a machine-readable calendar format. This will enable students to subscribe to your calendar and download your syllabus into their desktop calendar, mobile phone, or PDA. (Google Calendar and most desktop clients feature this capability.)

Collaboration

There are several dynamic resources you can use to encourage students to collaborate, to learn from and teach one another, and to grow together as a learning community. The simplest is the course email list, which can be a forum for continuing class discussions online. One successful assignment that I’ve given several times has asked students to critique the design of some real-world thing by using principles they’ve learned about the design of programs. The catch is that I encourage them to find funny examples of bad design, and to send their answers to the class list. Students seem to enjoy the opportunity to discuss and entertain one another, and the assignment reinforces and makes concrete the rather abstract material from class. Furthermore, having responses appear in “public” provides an incentive to do the assignment and to take it seriously.

The computer center typically sets up email lists for each course, which your students will be able to post to. If you’d rather use your course email list strictly for course-related announcements, you can create a dedicated mailing list for class discussions using a free service like Google Groups.

If you’re teaching a class with substantial lab or project components, you may find it useful to create a wiki, which is a dynamic web site that your students can read and (easily) update. This doesn’t lead to total anarchy (as you might assume), since there are ways to protect individual pages from malicious changes. Most students are familiar with wiki software because of the popularity of the Wikipedia project. There are several web sites that will host a wiki for you for free; wikihost.org and wikia.org seem popular, although I have not personally used either.

Demonstration

The best course materials combine graphics and prose (spoken or written) to elucidate concepts and processes. Sometimes, though, static pictures aren’t as helpful as they could be. Screencasts are short narrated movies of what’s happening on your computer screen, and they can be useful for demonstrating almost anything you can do with a computer: analyzing statistical data in a spreadsheet, maintining an online bibliography, or searching the library catalog, to give just a few examples. Numerous free and commercial screencast software packages are available for the Mac, Linux, and Windows. (I use iShowU on the Mac; Snapz Pro X is also well-regarded.)

For further reading

I can’t recommend Edward Tufte’s The Cognitive Style of PowerPoint (Graphics Press) highly enough. This essay, Tufte’s other books, and his writings at edwardtufte.com have been quite influential to my own presentation style. Tufte expertly diagnoses the problems with typical slide presentations and points to some potential solutions.

While Tufte’s essay focuses on typical slide shortcomings, Cliff Atkinson has written a different kind of book about slides and presentations. His Beyond Bullet Points (Microsoft Press) doesn’t focus on the limitations of the slide medium or typical slide pitfalls; rather, it tells you how to make better presentations by structuring your talks as stories in multiple acts. In my experience, using this approach has really helped me to explain complex technical topics.

There are many web pages and weblogs devoted to developing better presentations; two well-known sites are presentationzen.com and beyondbullets.com. (The latter is written by Cliff Atkinson, and features resources for readers of his book.)

A good general reference on typography (useful for slides and handouts) is Robert Bringhurst’s The Elements of Typographic Style (Hartley & Marks). (The web site
webtypography.net shows how to apply Bringhurst’s ideas to web page design.) If you’re merely interested in getting a quick introduction to typography and fonts, check out Stop Stealing Sheep and Find Out How Type Works, by Erik Spiekermann and E.M. Ginger (Adobe Press).

Finally, Scott McCloud’s book Understanding Comics: The Invisible Art (Harper) is an excellent primer on visual storytelling techniques and much more. It will help you make better slides and handouts, and it is a fun and informative read.

On “dynamic typing”

September 9th, 2005  |  Published in PL

The expression “dynamic typing” is internally incoherent and should be replaced with something more accurate. Instead, we should call “dynamically typed” languages what they are: untyped.

A type is a range of values. A typed language, in Cardelli’s magisterial formulation, is one in which variables can be ascribed nontrivial types. Note that this must be a static property! Perhaps advocates of the term “dynamic typing” mean that the type of a variable may change with assignment. Such a claim, however, is vacuously true for untyped languages — the range of values a variable may hold can always change with assignment. (This does not mean that a variable in an untyped language may be ascribed a type!) It should be clear that if the “type” of a variable may change with assignment, then the variable does not have a type at all.

To talk sensibly about types, we should follow Cardelli’s example and decouple discussion of typing from discussion of safety. I suspect that what most people mean by “dynamically typed” is “untyped but safe” — viz., an untyped language in which operations are checked at runtime to ensure that they are valid for the given operand values.

Developing an Audio Unit effect

December 10th, 2004  |  Published in Mac, Programming

UPDATE (1/2008): Note that is much easier to get started coding up DSP effects now than it was in 2004, since Xcode 3 includes AU effect and synth templates.

Introduction

This fall, I set out to develop a DSP music effect using Apple’s Audio Unit API. This document describes my experiences and provides pointers for other programmers who are interested in developing software using Apple’s technology.

Basics

Audio Units are software components that implement Apple’s plug-in interface and provide digital signal procesing and/or sound synthesis capabilities to a host program (such as a sequencer or an audio editor). An Audio Unit may operate either as a synthesizer, generating sound, or as an effect, processing sound. The API provides for flexible sound routing capabilities, including m to n channel effects and multiple-out instruments. Finally, effect audio units may operate either in real time or offline.

“Pull” model

Audio Units operate with a “pull” model. This means that, instead of a program “pushing” some amount of audio data to a (virtual or physical) audio interface, the host program invokes a callback function on every plugin at fixed intervals, synchronously “pulling” a fixed number of frames from each. I’ve read that the pull model provides better scalability and lower latency; it seems that most current audio APIs (i.e. PortAudio, JACK, and ALSA) require a pull model.

Implementing an Audio Unit plugin

To implement an Audio Unit plugin, one must write a C++ class that extends one of the Audio Unit component classes; I list some notable ones here:

  1. AUEffectBase A basic audio effect
  2. AUMIDIEffectBase An audio effect that can receive MIDI data
  3. MusicDeviceBase A software synthesizer that responds to MIDI note and continuous controller messages

Extending AUEffectBase

The easiest way to start developing a subclass of AUEffectBase is to copy the SampleEffectUnit code from the developer tools. SampleEffectUnit presents a simple effect that passes its input to its output; as such, the simple pass-through mechanism can be replaced with any custom processing code. SampleEffectUnit assumes an n-in, n-out effect with no interactions between channels and uses a subclass of AUKernelBase to do the bulk of the DSP work.

Using AUKernelBase

The class AUKernelBase provides the interface for a monophonic processing unit; it is provided as a convenience for cases in which, like SampleEffectUnit, n inputs are processed independently to produce n outputs. For an effect processing n channels, n objects extending AUKernelBase will be instantiated. Therefore, each channel can have independent audio state.To build an Audio Unit effect based on AUKernelBase, subclass AUEffectBase and AUKernelBase. You will then modify your AUEffectBase subclass. Override the AUEffectBase::NewKernel() method to return a newly-allocated instance of your AUKernelBase subclass. The NewKernel() method is invoked once for each channel in the AUEffectBase::MaintainKernels() method. (This is in contrast to the documentation for NewKernel(), which is ambiguous.)The AUKernelBase subclass does all of the audio processing in the AUKernelBase::Process() method. (Although the documentation for this method claims that it receives a stream of interleaved samples, this is not the case.) Simply read the input samples (as 32-bit floating point values) and write the output samples. Channel state can be stored in data members of an AUKernelBase subclass.

Overriding AUEffectBase::Render()

The AUKernelBase approach is convenient for common cases. However, it is insufficiently flexible to develop an effect that does not process equal numbers of independent input and output channels. (We’ll call the simpler effects one to one effects.) When developing an effect that either has

  1. different numbers of input and output channels, or
  2. interactions between channel states,

one must use a more flexible method.AUEffectBase::Render() is the callback method invoked by host applications. In its default implementation, it calls AUEffectBase::ProcessBufferLists(); in turn, the default implementation of ProcessBufferLists invokes the Process() method for each channel’s effect kernel on that channel’s input. For non-one to one effects, you must override ProcessBufferLists to perform an appropriate mapping from input channels to output channels.

Appendix: Developing effects with state

It’s pretty straightforward to develop a stateless effect—that is, one in which the value of each output sample depends solely on the value of exactly one corresponding input sample. (Of course, there are many useful distortion-type effects that fit into this category, like waveshapers, clippers, bit-depth reducers, and so on.) However, the “pull” model makes it a little more difficult to develop effects that require maintaining state, like filters, reverbs, and frequency-domain effects—even though some of these are straightforward to develop without the “pull” model.For example, if you were doing frequency-domain manipulation offline on an audio file, it would be as simple as reading in a chunk of audio data, performing windowing operations, performing the FFT, manipulating the FFT results, and outputting the FFT to an output buffer. After doing this for all of the samples in the file, you could write the output buffer to a file.In a synchronous, “pull” environment, it’s harder. You can’t choose which samples you get or when you get them. Rather, you get each sample in order, exactly once, and in fixed-size buffers. Making matters worse, you’ll have to output a fixed number of samples at the same time. Therefore, if you want to develop an effect that relies on state, you’ll have to do some buffering yourself. The figure below indicates the input-to-output relationship for an FFT-based effect with 1x overlap (click to download a printable PDF):

Appendix: References

  1. Audio Unit SDK Documentation. (this is a local link and only works on a Mac with developer tools installed)
  2. CoreAudio-API mailing list. A useful source for information.
  3. CoreAudio Wiki at UCSB. A collaborative web site with comments on several topics relating to Audio Units.
  4. OSXAudio.com. Check the “Developer forum” for some helpful tips.
  5. Urs Heckmann’s CAUGUI toolkit for custom interfaces
  6. Airy Andr’s AUGUI framework also for custom interfaces