Sat 05 March 2016

Calliope - helping you keep a diary - in LaTeX!

Posted by ankur in Research (491 words, approximately a 2 minute read)

  • Share this post:

Quite a few people write personal diaries - researchers tend to also keep research diaries where we note our generally brilliant ideas. I've used Lifeograph for a number of years now. It's a great application with all the right features that a diary needs - chapters, tags, and metrics. It doesn't quite work for a research diary, though - it doesn't support maths notation for a start, and we really do write a lot of very complicated maths from time to time. (The kinds with lots of symbols you see in the films? Think "A beautiful mind".)

The simple solution, of course, is LaTeX. LaTeX is used extensively in academic writing. While it does have a reputation for being complex and complicated (YES! There's a difference in the two words - they're not interchangeable!) at times, it is by far the best tool for academic writing. It has everything a researcher needs - citation support, can be customised to fit multiple format, and if you pair it with Git you even have versioning and change tracking.


I went looking for packages that may provide this functionality in LaTeX but didn't quite find any that had a convenient workflow and so on. I ran into a this Github project instead, which is a set of templates and scripts that does quite a good job. I've forked it and made some improvements. There's now a single script that takes arguments, for example. I've also added support for indexing - which works similar to tagging - it'll generate a nice clickable index at the end of the document. Of course, I've given it a fancy name, Calliope, and put it up on Github.

Usage is quite straightforward:

[asinha@cs-as14aho-2-herts-ac-uk  00_research_diary(master %=)]$ ./ -h
    usage: ./ options

    Master script file that provides functions to maintain a journal using LaTeX.

    -h  Show this message and quit

    -t  Add new entry for today

    -c  Compile today's entry

    -a  <year>
        Year to generate anthology of

    -p  <year>
        Compile all entries in this year

    -s  <entry> (yyyy-mm-dd)
        Compile specific entry

This is what the directory structure looks like:

[asinha@cs-as14aho-2-herts-ac-uk  00_research_diary(master %=)]$ tree
├── diary
   ├── 2016
      ├── 2016-03-04.tex
      ├── 2016-03-05.tex
      ├── images
      ├── research_diary.sty -> ../../templates/research_diary.sty
      └── stdp_connection_symmetric.h
   └── research_diary.sty -> ../templates/research_diary.sty
├── pdfs
   └── 2016
       ├── 2016-03-04.pdf
       └── 2016-03-05.pdf
├── README.rst
└── templates
    ├── entry.tex
    └── research_diary.sty

        6 directories, 11 files

The script generates your source LaTeX files and puts them in the folders in diary/. Then you write up and use the script to compile it - the generated pdfs are collected in the pdfs/ folder. The script can also generate an anthology for a year you pick. The resultant pdf for a daily entry will look like this:

Screenshot showing pdf generated by Calliope

That's pretty much it. Commit your entry to Git and you're done.

So, give it a go and please file issues if you have any suggestions that would improve it.

  • Share this post: