HIS389: Maps and History (2020)

This repo contains materials for a one-time course offered at Woodsworth College in Summer 2020, “The Current Plague”. For more information on the course, see the syllabus. The rest of this document contains information about the course structure and is copied without modification from my template course repository. As this course did not have a significant web presence, some of the information below is irrelevant.

Org-mode

All my course materials are written in org-mode markup, a multi-faceted markup format that is similar to markdown, but with a much richer feature set. Unfortunately it is almost entirely restricted to Emacs users, and perhaps because of that will never gain wide acceptance. For me, though, it remains the best way to write both code and text, and I’m likely to stick with it for the foreseeable future.

• My course syllabus is always a stand-alone document in the top-level directory, which also contains
• ./Lectures.org, a single file with all my lectures
• ./Assignments.org, a single file with all my assignments
• ./Grades, a directory with my grading materials (I exclude these from my git repositories to avoid any accidental disclosure of private information)
• ./Readings, a directory with copies of course readings (similarly, I exclude this from my git repo for copyright reasons)
• ./Images ditto

So the whole course structure comprises just a few large files, which I find a convenient way to keep track of everything.

Export

I use org-mode’s native exporter to produce course documents that need to be distributed in other formats (usually .pdf, .docx, and .htm or .md). Org’s exporter is extremely powerful and flexible, and I use a set of configuration variables, set in the document headers, to control its behaviour. At present I still have stray bits of elisp code in my emacs configuration, but I hope to move that to a central location so its easier to reproduce my build environment.

Websites

Most of my courses have simple static websites, built by the Hugo static site generator. Hugo actually supports org-mode files, but not the monolithic files that I prefer to use. So my website build process has a few steps:

1. edit the org-mode source files in this repo
2. export edits to hugo using ox-hugo, check changes in a local browser, and commit
3. generate the static site by running hugo in the website directory
4. upload files to github or other static site host (like https://hackinghistory.ca)

In the past this has required me to maintain 3 repos or at least 3 branches. My new plan is to cut out the intermediate step. TThe static site “source” files (which are themselves genreated by org!) will just live in the website directory. Auto-generated files will have to be added to git, maybe with some kind of a quick script, or just via magit.

website/deploy.sh contains a really helpful, quick deployment script.

.githooks/post-commit calls the deploy script with a commit message argument derived from the current commit.

Hugo Theme requirements

I’ve been liking simple themes with a sidebar that takes care of the limited navigation requirements for the course. Right now the only important extra feature I’ve been needing is support for fully-formed reveal.js slideshows. Most Hugo themes with reveal support do the parsing themselves – so they expect to see .md files. That isn’t great for me because the org-mode reveal exports are fairly opinionated, and I’d have to write a bunch of code to produce the md files in the form i want them to have. And in some cases the md parsers might not produce the right markup anyway. So, instead I use org-reveal to export, but filter the css and js values at the end of the process; this gives me a set of complete html files as output. To work within the website, these files need to be set inside an iframe, or some other way of scoping css instructions. SO I always need to write a couple of layout templates for just that purpose, as well as a menu generation method that opens the slideshows i n the right place.

I’d be happy to have slightly more sophisticated stuff happening here, but I’m not quite there yet.

ACTION insert the GH address of the source files into the commit message, to make it easier to find them on the web?

Auto exporting

These files take advantage of the auto-export functions in ox-hugo. So every time a Hugo source file is saved, the .md file gets exported to the Hugo site and it can be viewed in a pinned tab in a Hugo process which gets started by ~~/bin/starthugo.sh~, which starts up all the course websites at once.

I need to replicate ~ox-hugo-auto-export~ for ~ox-huveal~, which itself is a bit of a disaster and desperately needs rewriting. I have a do-what-i-mean function in my persistent **Scratch** buffer (copied from Kaushal!) for ox-huveal, and that works fine, but I still need to copy the rest of the infrastructure so I can add it as an after-save-hook, and bundle it up as some kind of a package. I’ve copied ox-hugo-auto-export as ox-reveal-auto-export and I am now satisfied that it works well. I’ll pointto a gh repo when I have it up somewhere. See Kaushal’s documentation on auto-exporting for hints on how to work this.

Simplifying the commit process

I’m hoping that the git post-commit hook included in this repo will make committing a one-stop process – I just commit to the right branch, after which the deployment just happens automagically. See this discussion of external git hooks for some manual setup that still needs to be done. Will perhaps be tricky to do this via a dockerfile or whatever, if I eventually manage to dockerize my workflow here, which I hope to do. should be as simple as git config core.hooksPath .githooks but perhaps that belongs in a makefile or an init file of some kind.

Hugo Setup

#!/bin/zsh
# only do this once!

#use this oneliner to get the location of this script
CUR=$PWD
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )"

cd $DIR/public
rm -rf
cd $DIR

### edit this line first! make sure you get the right info!
# also replace `master` with gh-pages if nec
git submodule add -b master git@github.com:<ORGNAME>/<ORGNAME>.github.io.git public
cd $CUR

What’s left to do?

• [ ] finish up huveal stuff to ease that process
• [ ] include some documentation about the reveal.js requirements for Hugo themes – they need to be able to support org-generated reveal content
• [ ] fix citations & include .bibtex files in the template
• [X] collect stray elisp into a single coherent package
• [ ] make some kind of meta-repo with all the dependencies included
• [ ] figure out a safe way to manage Grade files, but maybe also sitll include some of the template code that I use for that sutff.
• [X] add setup.org file
• [X] determine if some kind of Canvas integration is possible.
  • [X] for instance, it looks like it’s possible to download all submissions for an assignment. I’d like to write a cURL script that authenticates against the servers and grabs & unzips the appropriate zip file. Not sure if that’s going to be possible to do or not.