Skip to main content

The Joy of Code - Generating Tables of Contents

I’m a computer scientist. That means that sometimes I code for fun. Sometimes I code for both fun and for a purpose. Ideally, I write a useful (or perhaps useless) program each day. Today’s essay is on today’s program. I apologize to the non-technical among you, who may not understand all of this. I also apologize to the technical among you, who may find this obvious and boring. If you want, you can look at my code (which is designed primarily for my use) at https://github.com/GlimmerLabs/coa-aoc-canvas.

This semester, I’m teaching an online class with Global Online Academy, which we usually refer to as GOA. (I pronounce it as Gee Oh Eh; I think some other people pronounce it as go-uh.) GOA uses a Learning Management System (LMS) named Canvas. One of the really nice things about Canvas is that it provides an API (Application Programmer Interface). Why is that nice? Because it allows me to design my own workflows for building and manipulating the course, and then make Canvas fit my workflows, rather than the other way around. (I don’t know why these groups seem to generate so many TLAs (three-letter acronyms), but TLAs do seem to propagate in many situations.)

Over the past few weeks, I’ve been writing a variety of small scripts (aka programs) to make it easier for me to work with Canvas. I wrote programs that would format and upload pages, so that I could write in Markdown rather than using a graphical text editor. (I am significantly faster in Markdown, at least for most tasks.) I wrote something that identified parts of my course that I expected to be there, and made sure that they were there (creating them as necessary). I even wrote a few scripts to delete parts of a course, so that I could clean up the messes that some of my other scripts made.

But most of my programming work was in building programs that let me manage what Canvas calls modules, thematic (and, usually, temporal) groups of work. While Canvas has a relatively convenient module designer, I find it much easier to design my modules in a text editor and then upload them.

Once those programs were built, I could then focus on content and structure, and do so using a workflow that makes sense to me. (Edit lots of text files, type a command, and have the site generated.) And, I have things set up so that when I make a change to my text files, I can easily propagate them to the site. (Perhaps not as easily as I’d like; I just discovered that the default setting for the modules is unpublished, which means that I may have to fix that issue.) Because I am creating pages with a uniform strategy, the structure of the site is clean and consistent. My instructional designer tells me that it looks like the course has been up and running for a few years. (He’s clearly not paying enough attention to the many parts that say Forthcoming.)

Anyway, one of the advantages of working with text files (or with the API), is that it’s much easier to copy information. Each module has an introductory page. As I thought about navigation, I decided that the introductory page should really have a table of contents for the module. (I’d already decided that the introductory page should have a list of work due in the module, but the table of contents provides that information in a different form.) Since each module is described by a simple text file, I whipped up a make table of contents script in about forty-five minutes, and added tables of contents to the dozen modules in about five more minutes. Could I have typed the contents in similar time? Possibly, but I probably would have made some mistakes. And, even more importantly, if I made a change to the module, I would have to remember to make the change to the introductory page. Now, things are automated.

Anyway, today’s script reminds me of a few of the reasons I like to program. First, I like that when I write something, I can see results. In this case, I get to see better navigational support for my students. Second, I like to know that I’m making things more sensible (and perhaps organized). I hate having to keep things in synch. This program helps me automate the process. Third, writing the programs made me think more about how to structure and present information, and will probably help me rethink how I structure and present information. Finally, when I decide to change the format of the tables of contents, it will just be a few minutes of scripting, rather than an hour of editing each toc.

What could be more fun? (Well, maybe writing an essay about it.)


I started using the term TLA some time after reading about TLC or TIC (Three-Letter Corporation or Three-Initial Corporation, I can’t remember which) in Sam Hurt’s Eyebeam. I recommend that strip to you. Maybe I’ll even write an essay about it some day.


I wonder if this is one of those essays that would be better with pictures. Oh well. That’s probably a topic for the future.


Version 1.0 of 2016-09-01.