== Beautiful timetables


-- What?

A small Haskell module to generate a LaTeX file with a nicely formatted
timetable using an embedded domain specific language.


-- Why? (Design goals)

Because I wanted a clear and compact way to display the timetable of the tram
nearby.  Also, I wanted something more 'visual' than a list with numbers.  I am
interested in new ways to display information and what's nice about it and why.

I think the result is something that has a bit of a learning curve and is
therefore less suitable for 'one-time' usage.  On the other hand, because it's
more of a picture and not a bunch of numbers I think it's much easier to learn
the timetable by heart for regular users.

For specification I wanted a small and simple language and preferably not start
with writing a parser, so I decided to hitch a ride with Haskell first.

I'd love to hear your opinion, both a first reaction and after experimenting
with it.  You can reach me at <eelco@lempsink.nl>


-- How? (Usage & Features)

Requirements: you'll need to have a Haskell compiler, such as GHC.  Furthermore
you'll need a LaTeX installation including the PGF/TikZ package.  It can also
help if you know a little Haskell and LaTeX, but I hope it's not required ;)

So, how does it work?  First, you'll need to create a (Haskell) file with the
extension '.hs'.  In it you need to say four things.  First, you need to say
you want to use the timetable module:

> import Timetable

Second, you need to define a title for your timetable.

> title = "Your title"

Third, you'll write your timetable, which is a Haskell list.  You need to
start with saying what you're going to specify, namely a list of entries.

> timetable :: [Entry]

Then, you write all the entries, using the name of the day, followed by the
hour and the minute, between parentheses and separated with a comma.  Let me
show it:

> timetable = [ monday (9,0)
>             , monday (12,15)
>             , tuesday (9,0)
>             , tuesday (12,15)
>             , wednesday (12,15)
>             , thursday (12,15)
>             , friday (12,15)
>             , saturday (13,30)
>             , sunday (13,30)

And you can also use some nice shortcuts for specifying groups of days like
weekends, see:

>             , weekend (14,14)
>             , weekdays (15,0)
>             , everyday (18,32)
>             ]

Last but not least you specify that the main purpose of the file is to nicely
format the timetable, using the timetable you specified and of course the
title.

> main = ppTimetable title timetable

(If you know Haskell, you'll already understand all the nice programming
shorthands you can use.  I'm not going to explain them, because this is not a
Haskell tutorial.)

So, after you did that, what will the software do for you?  (And what doesn't
it do?)

* It will calculate the optimal formatting of the hours, by leaving away the
  biggest gap.  So if the last stop is at 1:00 or 2:00, it will be placed at
  the right, where you'd expect it.

* All times that occur on the same days will be given the same color (of gray).
  NOTE that this is limited to a maximum of 5 at the moment.  I think it is
  sufficient and that allowing more days would make the timetable unreadable.

* A small legend will be printed, formatting the days as concisely possible. 

But, a picture will say more than a thousands words, so an example would be
nice wouldn't it?  Actually you can run this file as a program, because all
example code is marked with the '>' signs.  You can do this on the shell:

$ runhaskell README.lhs > example.tex

And then generate the PDF.  The following command will generate an example.pdf
file.

$ pdflatex example.tex

As an extra (and more complete) example I also included the file with the
timetable I wanted and was the reason for this project.  It's called
'tram-cs.hs' and you can run it similarly as you ran this file.

Unfortunately, for this project to be really useful, it would be nice to have
some parsers for common formats.  It's pretty easy to create a timetable by
hand, but it's still more work than 'pushing a button' ;)


-- Who?

Eelco Lempsink <eelco@lempsink.nl> created this toy project on a lazy weekend.


-- When?

2007-11-10