Creating documents with embedded diagrams

If you read my recent post about type algebra, you may have wondered how I got all those nice images in there. Surely creating the images and then inserting them into the post by hand would be rather tedious! Indeed, it would be, but that’s not what I did. I’m quite pleased to announce the release of several tools for making this sort of thing not only possible but even convenient.

Behind it all is the recently released diagrams-builder package. Diagrams backends such as diagrams-cairo give you a static way to render diagrams. diagrams-builder makes the process dynamic: it can take arbitrary snippets of Haskell code, merge them intelligently, and call out to hint to render a diagram represented by some Haskell expression.

As a specific application of diagrams-builder, I’ve released BlogLiterately-diagrams, a diagrams plugin for BlogLiterately. This is what I used to produce the type algebra post. The entire post was written in a single Markdown document, with inline diagrams code in specially marked code blocks. BlogLiterately-diagrams handles compiling those code blocks and replacing them with the generated images; BlogLiterately automatically uploads the images to the server. For example, including

{.dia width='200'}
sq = square 1

foo 0 = sq
foo n = ((foo' ||| sq') === (sq' ||| foo')) # centerXY # scale 0.5
where
foo'   = foo (n-1)
sq'    = sq # fc (colors !! n)
colors = [black, red, orange, yellow, green, blue]

dia = foo 5 # lw 0


in the middle of a post results in

being included in the generated HTML.

Another exciting thing to mention is the LaTeX package diagrams-latex.sty, included in the diagrams-builder distribution. It lets you embed diagrams in LaTeX documents in much the same way that BlogLiterately-diagrams lets you embed diagrams in blog posts. Just stick diagrams code between \begin{diagram} and \end{diagram} and compile the document with pdflatex --enable-write18. It probably needs more work to smooth out some rough edges, but it’s quite usable as it is—in fact, I’m currently using it to create the slides for my Haskell Symposium presentation in a few weeks.

Just to give a little perspective, this is essentially why I started building diagrams, over four years ago now—I wanted to produce some illustrations for a blog post, but was unsatisfied with the existing tools I found. With these tools, I can finally say that I’ve fully achieved my vision of four years ago—though don’t worry, my vision has grown much larger in the meantime!

This entry was posted in diagrams, haskell, projects, writing and tagged , , , , , , , , , . Bookmark the permalink.

11 Responses to Creating documents with embedded diagrams

1. Excellent! This would make a great gitit plugin as well.

• Brent says:

Yes! A gitit plugin would be awesome. I’ll probably get around to it eventually if no one else does, but if someone wants to take a crack at it, it doesn’t look like it would be too difficult.

2. pathomas41 says:

Couldn’t someone use unsafePerformIO in an embedded diagram in order to gain access to your machine? The buildDiagram function doesn’t appear to do anything to prevent IO in the code snippets.

• Brent says:

It’s true that buildDiagram does nothing to ensure safety, absence of unsafePerformIO, and so on. But there is no way anyone could use this to gain access to your machine, unless you accept code from someone else and insert it in your blog post or LaTeX document without reading it.

• pathomas41 says:

Maybe not for BlogLiteraly, but using it with gitit (as requested above) would be a different matter.

• Brent says:

Yes, that’s a good point. If someone wanted to be able to embed diagrams in gitit, or something similar where the code may come from an untrusted source, I would recommend doing something based on Dan Frumin’s work: http://paste.hskll.org/ . It would still need some work to make it into a service that others can use, or a package that others can deploy, but he has already done all the hard work with respect to security.

3. Corentin says:

Hi Brent, do you (or someone) plan on making a plugin for Hakyll? That would be awesome!

• Brent says:

Hi Corentin, a Hakyll plugin would be very cool indeed! I haven’t heard of anyone planning such a thing, but I added it to our trello board: https://trello.com/c/MSiT00UE . It shouldn’t be very hard.

• Corentin says:

Hi Brent, do you know any progress on that? I’m looking for a way to embbed diagrams in markdown.

• Brent says:

Hi Corentin, I don’t think anyone has worked on a Hakyll plugin, but if you want to embed diagrams in markdown, you should take a look at https://github.com/diagrams/diagrams-pandoc . I don’t know what the current status is but I know it is being actively worked on.